diff --git a/docs/it/automation/cron-jobs.md b/docs/it/automation/cron-jobs.md index 07b8b018f..d9d3b5e92 100644 --- a/docs/it/automation/cron-jobs.md +++ b/docs/it/automation/cron-jobs.md @@ -2,14 +2,14 @@ read_when: - Pianificazione di processi in background o riattivazioni - Collegamento di trigger esterni (webhook, Gmail) a OpenClaw - - Scegliere tra heartbeat e cron per le attività pianificate + - Decidere tra heartbeat e cron per le attività pianificate summary: Processi pianificati, webhook e trigger Gmail PubSub per lo scheduler del Gateway title: Attività pianificate x-i18n: - generated_at: "2026-04-11T02:44:27Z" + generated_at: "2026-04-12T08:07:59Z" model: gpt-5.4 provider: openai - source_hash: 04d94baa152de17d78515f7d545f099fe4810363ab67e06b465e489737f54665 + source_hash: f42bcaeedd0595d025728d7f236a724a0ebc67b6813c57233f4d739b3088317f source_path: automation/cron-jobs.md workflow: 15 --- @@ -43,107 +43,120 @@ openclaw cron runs --id - I processi vengono mantenuti persistenti in `~/.openclaw/cron/jobs.json`, quindi i riavvii non fanno perdere le pianificazioni. - Tutte le esecuzioni cron creano record di [attività in background](/it/automation/tasks). - I processi una tantum (`--at`) vengono eliminati automaticamente dopo il successo per impostazione predefinita. -- Le esecuzioni cron isolate chiudono, per quanto possibile, le schede/processi del browser tracciati per la loro sessione `cron:` al termine dell'esecuzione, così l'automazione del browser scollegata non lascia processi orfani. +- Le esecuzioni cron isolate chiudono, nel limite del possibile, le schede/processi del browser tracciati per la loro sessione `cron:` al termine dell'esecuzione, così l'automazione del browser scollegata non lascia processi orfani. - Le esecuzioni cron isolate proteggono anche dalle risposte di conferma obsolete. Se il - primo risultato è solo un aggiornamento di stato intermedio (`on it`, `pulling everything -together` e indicazioni simili) e nessuna esecuzione discendente di subagente è ancora - responsabile della risposta finale, OpenClaw ripropone una volta la richiesta per il risultato + primo risultato è solo un aggiornamento di stato provvisorio (`on it`, `pulling everything +together` e indicazioni simili) e nessuna esecuzione di un sottoagente discendente è ancora + responsabile della risposta finale, OpenClaw invia di nuovo il prompt una volta per ottenere il risultato effettivo prima della consegna. -La riconciliazione delle attività per cron è gestita dal runtime: un'attività cron attiva resta tale finché il -runtime cron traccia ancora quel processo come in esecuzione, anche se esiste ancora una vecchia riga di sessione figlia. -Quando il runtime smette di possedere il processo e scade il periodo di tolleranza di 5 minuti, la manutenzione può +La riconciliazione delle attività per cron è gestita dal runtime: un'attività cron attiva rimane attiva finché il +runtime cron continua a tracciare quel processo come in esecuzione, anche se esiste ancora una vecchia riga di sessione figlia. +Una volta che il runtime smette di possedere il processo e la finestra di tolleranza di 5 minuti scade, la manutenzione può contrassegnare l'attività come `lost`. ## Tipi di pianificazione -| Tipo | Flag CLI | Descrizione | -| ------- | --------- | ------------------------------------------------------------ | -| `at` | `--at` | Timestamp una tantum (ISO 8601 o relativo come `20m`) | -| `every` | `--every` | Intervallo fisso | +| Tipo | Flag CLI | Descrizione | +| ------- | --------- | ------------------------------------------------------------- | +| `at` | `--at` | Timestamp una tantum (ISO 8601 o relativo come `20m`) | +| `every` | `--every` | Intervallo fisso | | `cron` | `--cron` | Espressione cron a 5 o 6 campi con `--tz` facoltativo | -I timestamp senza fuso orario vengono trattati come UTC. Aggiungi `--tz America/New_York` per la pianificazione in base all'orario locale. +I timestamp senza fuso orario vengono trattati come UTC. Aggiungi `--tz America/New_York` per una pianificazione in ora locale. -Le espressioni ricorrenti all'inizio dell'ora vengono automaticamente sfalsate fino a 5 minuti per ridurre i picchi di carico. Usa `--exact` per forzare la temporizzazione precisa oppure `--stagger 30s` per una finestra esplicita. +Le espressioni ricorrenti all'inizio dell'ora vengono automaticamente sfalsate fino a 5 minuti per ridurre i picchi di carico. Usa `--exact` per forzare una temporizzazione precisa oppure `--stagger 30s` per una finestra esplicita. + +### Giorno del mese e giorno della settimana usano la logica OR + +Le espressioni cron vengono analizzate da [croner](https://github.com/Hexagon/croner). Quando sia i campi giorno del mese sia giorno della settimana non sono jolly, croner trova una corrispondenza quando **uno dei due** campi corrisponde, non entrambi. Questo è il comportamento standard di Vixie cron. + +``` +# Previsto: "9:00 del 15, solo se è lunedì" +# Reale: "9:00 di ogni 15, E 9:00 di ogni lunedì" +0 9 15 * 1 +``` + +Questo viene eseguito ~5–6 volte al mese invece di 0–1 volte al mese. OpenClaw usa qui il comportamento OR predefinito di Croner. Per richiedere entrambe le condizioni, usa il modificatore giorno della settimana `+` di Croner (`0 9 15 * +1`) oppure pianifica su un solo campo e verifica l'altro nel prompt o nel comando del tuo processo. ## Stili di esecuzione -| Stile | Valore `--session` | Eseguito in | Ideale per | -| --------------- | -------------------- | ------------------------ | ------------------------------- | -| Sessione principale | `main` | Turno heartbeat successivo | Promemoria, eventi di sistema | -| Isolato | `isolated` | `cron:` dedicato | Report, attività in background | -| Sessione corrente | `current` | Vincolato al momento della creazione | Lavoro ricorrente sensibile al contesto | +| Stile | Valore `--session` | Esecuzione in | Ideale per | +| --------------- | -------------------- | ------------------------- | ------------------------------ | +| Sessione main | `main` | Turno heartbeat successivo | Promemoria, eventi di sistema | +| Isolata | `isolated` | `cron:` dedicato | Report, attività in background | +| Sessione corrente | `current` | Associata al momento della creazione | Lavoro ricorrente consapevole del contesto | | Sessione personalizzata | `session:custom-id` | Sessione nominata persistente | Flussi di lavoro che si basano sulla cronologia | -I processi in **sessione principale** accodano un evento di sistema e facoltativamente risvegliano l'heartbeat (`--wake now` o `--wake next-heartbeat`). I processi **isolati** eseguono un turno agente dedicato con una sessione nuova. Le **sessioni personalizzate** (`session:xxx`) mantengono il contesto tra le esecuzioni, abilitando flussi di lavoro come standup giornalieri che si basano sui riepiloghi precedenti. +I processi in **sessione main** accodano un evento di sistema e facoltativamente riattivano l'heartbeat (`--wake now` o `--wake next-heartbeat`). I processi **isolati** eseguono un turno agente dedicato con una sessione nuova. Le **sessioni personalizzate** (`session:xxx`) mantengono il contesto tra le esecuzioni, consentendo flussi di lavoro come standup giornalieri che si basano sui riepiloghi precedenti. -Per i processi isolati, lo smantellamento del runtime ora include la pulizia del browser per quella sessione cron, per quanto possibile. Gli errori di pulizia vengono ignorati in modo che prevalga comunque il risultato cron effettivo. +Per i processi isolati, lo smantellamento del runtime ora include, nel limite del possibile, la pulizia del browser per quella sessione cron. Gli errori di pulizia vengono ignorati, così il risultato cron effettivo resta prioritario. -Quando le esecuzioni cron isolate orchestrano subagenti, la consegna privilegia anche l'output finale -discendente rispetto a testo intermedio obsoleto del padre. Se i discendenti sono ancora in esecuzione, -OpenClaw sopprime quell'aggiornamento parziale del padre invece di annunciarlo. +Quando le esecuzioni cron isolate orchestrano sottoagenti, la consegna preferisce anche l'output finale +discendente rispetto al testo provvisorio obsoleto del genitore. Se i discendenti sono ancora in +esecuzione, OpenClaw sopprime quell'aggiornamento parziale del genitore invece di annunciarlo. -### Opzioni del payload per i processi isolati +### Opzioni di payload per i processi isolati -- `--message`: testo del prompt (obbligatorio per isolato) -- `--model` / `--thinking`: override del modello e del livello di ragionamento -- `--light-context`: salta l'iniezione del file bootstrap del workspace -- `--tools exec,read`: limita quali strumenti il processo può usare +- `--message`: testo del prompt (obbligatorio per l'isolato) +- `--model` / `--thinking`: override del modello e del livello di thinking +- `--light-context`: salta l'iniezione del file bootstrap dello spazio di lavoro +- `--tools exec,read`: limita quali strumenti può usare il processo `--model` usa il modello consentito selezionato per quel processo. Se il modello richiesto non è consentito, cron registra un avviso e torna invece alla selezione del modello -predefinito dell'agente/del processo. Le catene di fallback configurate continuano ad applicarsi, ma un semplice -override del modello senza un elenco di fallback esplicito per processo non aggiunge più il modello primario -dell'agente come destinazione aggiuntiva di nuovo tentativo nascosta. +agente/predefinito del processo. Le catene di fallback configurate continuano ad applicarsi, ma un semplice +override del modello senza un elenco esplicito di fallback per processo non aggiunge più il primario +dell'agente come destinazione nascosta extra di ritentativo. La precedenza di selezione del modello per i processi isolati è: -1. Override del modello del hook Gmail (quando l'esecuzione proviene da Gmail e quell'override è consentito) +1. Override del modello dell'hook Gmail (quando l'esecuzione proviene da Gmail e quell'override è consentito) 2. `model` del payload per processo 3. Override del modello della sessione cron memorizzata -4. Selezione del modello predefinita/dell'agente +4. Selezione del modello agente/predefinito -La modalità rapida segue anch'essa la selezione live risolta. Se la configurazione del modello selezionato -ha `params.fastMode`, cron isolato la usa per impostazione predefinita. Un override `fastMode` -della sessione memorizzata continua comunque ad avere la precedenza in entrambe le direzioni. +Anche la modalità rapida segue la selezione live risolta. Se la configurazione del modello selezionato +ha `params.fastMode`, il cron isolato la usa per impostazione predefinita. Un override `fastMode` +di sessione memorizzato ha comunque la precedenza sulla configurazione in entrambe le direzioni. Se un'esecuzione isolata incontra un passaggio live di cambio modello, cron ritenta con il -provider/modello cambiato e mantiene quella selezione live prima del nuovo tentativo. Quando -il cambio comporta anche un nuovo profilo auth, cron mantiene anche quell'override del profilo auth. -I tentativi sono limitati: dopo il tentativo iniziale più 2 tentativi dovuti al cambio, cron interrompe invece di entrare in un ciclo infinito. +provider/modello cambiato e mantiene quella selezione live prima del ritentativo. Quando +il cambio comporta anche un nuovo profilo di autenticazione, cron mantiene anche l'override +di quel profilo di autenticazione. I ritentativi sono limitati: dopo il tentativo iniziale più 2 +ritentativi di cambio, cron interrompe invece di entrare in un ciclo infinito. ## Consegna e output -| Modalità | Cosa succede | -| ---------- | --------------------------------------------------------- | -| `announce` | Invia un riepilogo al canale di destinazione (predefinito per isolato) | -| `webhook` | Esegue una richiesta POST con il payload dell'evento completato a un URL | -| `none` | Solo interno, nessuna consegna | +| Modalità | Cosa succede | +| ---------- | ----------------------------------------------------------- | +| `announce` | Consegna il riepilogo al canale di destinazione (predefinito per l'isolato) | +| `webhook` | Esegue un POST del payload dell'evento completato a un URL | +| `none` | Solo interno, nessuna consegna | Usa `--announce --channel telegram --to "-1001234567890"` per la consegna al canale. Per gli argomenti del forum Telegram, usa `-1001234567890:topic:123`. Le destinazioni Slack/Discord/Mattermost devono usare prefissi espliciti (`channel:`, `user:`). -Per i processi isolati gestiti da cron, il runner possiede il percorso di consegna finale. All'agente -viene richiesto di restituire un riepilogo in testo semplice, e quel riepilogo viene poi inviato tramite -`announce`, `webhook` oppure mantenuto interno con `none`. `--no-deliver` non restituisce la -consegna all'agente; mantiene l'esecuzione interna. +Per i processi isolati di proprietà di cron, il runner gestisce il percorso di consegna finale. All'agente +viene richiesto di restituire un riepilogo in testo semplice, e quel riepilogo viene poi inviato +tramite `announce`, `webhook` o mantenuto interno per `none`. `--no-deliver` +non restituisce la consegna all'agente; mantiene l'esecuzione interna. -Se l'attività originale indica esplicitamente di inviare un messaggio a un destinatario esterno, -l'agente deve indicare nel suo output a chi/dove quel messaggio deve andare invece di +Se l'attività originale indica esplicitamente di inviare un messaggio a qualche destinatario esterno, +l'agente deve indicare nel proprio output a chi/dove dovrebbe andare quel messaggio invece di provare a inviarlo direttamente. Le notifiche di errore seguono un percorso di destinazione separato: -- `cron.failureDestination` imposta una destinazione predefinita globale per le notifiche di errore. -- `job.delivery.failureDestination` la sovrascrive per singolo processo. -- Se nessuna delle due è impostata e il processo già consegna tramite `announce`, le notifiche di errore ora usano come fallback quella destinazione principale di announce. -- `delivery.failureDestination` è supportato solo sui processi `sessionTarget="isolated"` a meno che la modalità di consegna principale non sia `webhook`. +- `cron.failureDestination` imposta un valore predefinito globale per le notifiche di errore. +- `job.delivery.failureDestination` lo sovrascrive per singolo processo. +- Se nessuno dei due è impostato e il processo consegna già tramite `announce`, le notifiche di errore ora usano come fallback quella destinazione announce primaria. +- `delivery.failureDestination` è supportato solo sui processi `sessionTarget="isolated"` a meno che la modalità di consegna primaria non sia `webhook`. ## Esempi CLI -Promemoria una tantum (sessione principale): +Promemoria una tantum (sessione main): ```bash openclaw cron add \ @@ -168,7 +181,7 @@ openclaw cron add \ --to "channel:C1234567890" ``` -Processo isolato con override di modello e ragionamento: +Processo isolato con override di modello e thinking: ```bash openclaw cron add \ @@ -184,7 +197,7 @@ openclaw cron add \ ## Webhook -Gateway può esporre endpoint webhook HTTP per trigger esterni. Abilita nella configurazione: +Il Gateway può esporre endpoint webhook HTTP per trigger esterni. Abilita nella configurazione: ```json5 { @@ -198,7 +211,7 @@ Gateway può esporre endpoint webhook HTTP per trigger esterni. Abilita nella co ### Autenticazione -Ogni richiesta deve includere il token del hook tramite header: +Ogni richiesta deve includere il token dell'hook tramite header: - `Authorization: Bearer ` (consigliato) - `x-openclaw-token: ` @@ -207,7 +220,7 @@ I token nella query string vengono rifiutati. ### POST /hooks/wake -Accoda un evento di sistema per la sessione principale: +Accoda un evento di sistema per la sessione main: ```bash curl -X POST http://127.0.0.1:18789/hooks/wake \ @@ -217,7 +230,7 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \ ``` - `text` (obbligatorio): descrizione dell'evento -- `mode` (facoltativo): `now` (predefinito) oppure `next-heartbeat` +- `mode` (facoltativo): `now` (predefinito) o `next-heartbeat` ### POST /hooks/agent @@ -238,17 +251,17 @@ I nomi hook personalizzati vengono risolti tramite `hooks.mappings` nella config ### Sicurezza -- Mantieni gli endpoint hook dietro loopback, tailnet o un reverse proxy fidato. -- Usa un token hook dedicato; non riutilizzare i token auth del gateway. +- Mantieni gli endpoint hook dietro loopback, tailnet o un reverse proxy attendibile. +- Usa un token hook dedicato; non riutilizzare i token di autenticazione del gateway. - Mantieni `hooks.path` su un sottopercorso dedicato; `/` viene rifiutato. -- Imposta `hooks.allowedAgentIds` per limitare il routing esplicito `agentId`. +- Imposta `hooks.allowedAgentIds` per limitare l'instradamento esplicito di `agentId`. - Mantieni `hooks.allowRequestSessionKey=false` a meno che tu non richieda sessioni selezionate dal chiamante. -- Se abiliti `hooks.allowRequestSessionKey`, imposta anche `hooks.allowedSessionKeyPrefixes` per vincolare le forme consentite della chiave di sessione. -- I payload hook vengono racchiusi entro limiti di sicurezza per impostazione predefinita. +- Se abiliti `hooks.allowRequestSessionKey`, imposta anche `hooks.allowedSessionKeyPrefixes` per vincolare le forme consentite delle chiavi di sessione. +- I payload hook sono racchiusi in confini di sicurezza per impostazione predefinita. ## Integrazione Gmail PubSub -Collega i trigger della casella Gmail a OpenClaw tramite Google PubSub. +Collega i trigger della posta in arrivo di Gmail a OpenClaw tramite Google PubSub. **Prerequisiti**: CLI `gcloud`, `gog` (gogcli), hook OpenClaw abilitati, Tailscale per l'endpoint HTTPS pubblico. @@ -317,7 +330,7 @@ openclaw cron edit --message "Updated prompt" --model "opus" # Forza l'esecuzione immediata di un processo openclaw cron run -# Esegui solo se è scaduto +# Esegui solo se è il momento previsto openclaw cron run --due # Visualizza la cronologia delle esecuzioni @@ -333,14 +346,10 @@ openclaw cron edit --clear-agent Nota sull'override del modello: -- `openclaw cron add|edit --model ...` cambia il modello selezionato del processo. -- Se il modello è consentito, esattamente quel provider/modello raggiunge l'esecuzione - dell'agente isolato. -- Se non è consentito, cron avvisa e torna alla selezione del modello - predefinita dell'agente/del processo. -- Le catene di fallback configurate continuano ad applicarsi, ma un semplice override `--model` con - nessun elenco di fallback esplicito per processo non passa più al modello - primario dell'agente come destinazione aggiuntiva di nuovo tentativo silenziosa. +- `openclaw cron add|edit --model ...` modifica il modello selezionato del processo. +- Se il modello è consentito, quell'esatto provider/modello viene passato all'esecuzione dell'agente isolato. +- Se non è consentito, cron registra un avviso e torna alla selezione del modello agente/predefinito del processo. +- Le catene di fallback configurate continuano ad applicarsi, ma un semplice override `--model` senza un elenco esplicito di fallback per processo non ripiega più sul primario dell'agente come destinazione aggiuntiva silenziosa di ritentativo. ## Configurazione @@ -355,20 +364,20 @@ Nota sull'override del modello: backoffMs: [60000, 120000, 300000], retryOn: ["rate_limit", "overloaded", "network", "server_error"], }, - webhookToken: "sostituisci-con-token-webhook-dedicato", + webhookToken: "replace-with-dedicated-webhook-token", sessionRetention: "24h", runLog: { maxBytes: "2mb", keepLines: 2000 }, }, } ``` -Disabilita cron: `cron.enabled: false` oppure `OPENCLAW_SKIP_CRON=1`. +Disabilita cron: `cron.enabled: false` o `OPENCLAW_SKIP_CRON=1`. -**Nuovo tentativo per esecuzioni una tantum**: gli errori transitori (limite di frequenza, sovraccarico, rete, errore del server) vengono ritentati fino a 3 volte con backoff esponenziale. Gli errori permanenti disabilitano immediatamente. +**Ritentativo una tantum**: gli errori transitori (limite di frequenza, sovraccarico, rete, errore del server) vengono ritentati fino a 3 volte con backoff esponenziale. Gli errori permanenti disabilitano immediatamente. -**Nuovo tentativo per esecuzioni ricorrenti**: backoff esponenziale (da 30 s a 60 min) tra i tentativi. Il backoff si reimposta dopo l'esecuzione successiva riuscita. +**Ritentativo ricorrente**: backoff esponenziale (da 30s a 60m) tra i ritentativi. Il backoff si azzera dopo l'esecuzione successiva andata a buon fine. -**Manutenzione**: `cron.sessionRetention` (predefinito `24h`) elimina le voci di sessione delle esecuzioni isolate. `cron.runLog.maxBytes` / `cron.runLog.keepLines` eliminano automaticamente i file del log di esecuzione. +**Manutenzione**: `cron.sessionRetention` (predefinito `24h`) elimina le voci della sessione di esecuzione isolata. `cron.runLog.maxBytes` / `cron.runLog.keepLines` eliminano automaticamente le righe dei file di log delle esecuzioni. ## Risoluzione dei problemi @@ -385,26 +394,22 @@ openclaw logs --follow openclaw doctor ``` -### Cron non si attiva +### Cron non si avvia - Controlla `cron.enabled` e la variabile d'ambiente `OPENCLAW_SKIP_CRON`. - Conferma che il Gateway sia in esecuzione continua. - Per le pianificazioni `cron`, verifica il fuso orario (`--tz`) rispetto al fuso orario dell'host. -- `reason: not-due` nell'output di esecuzione significa che l'esecuzione manuale è stata controllata con `openclaw cron run --due` e che il processo non era ancora in scadenza. +- `reason: not-due` nell'output dell'esecuzione significa che l'esecuzione manuale è stata verificata con `openclaw cron run --due` e che il processo non era ancora previsto. -### Cron si è attivato ma non c'è consegna +### Cron è partito ma non c'è consegna - La modalità di consegna `none` significa che non è previsto alcun messaggio esterno. -- Una destinazione di consegna mancante/non valida (`channel`/`to`) significa che l'invio in uscita è stato saltato. +- Destinazione di consegna mancante/non valida (`channel`/`to`) significa che l'invio in uscita è stato saltato. - Gli errori di autenticazione del canale (`unauthorized`, `Forbidden`) significano che la consegna è stata bloccata dalle credenziali. -- Se l'esecuzione isolata restituisce solo il token silenzioso (`NO_REPLY` / `no_reply`), - OpenClaw sopprime la consegna diretta in uscita e sopprime anche il percorso di fallback - del riepilogo accodato, quindi non viene pubblicato nulla nella chat. -- Per i processi isolati gestiti da cron, non aspettarti che l'agente usi lo strumento di messaggistica - come fallback. Il runner gestisce la consegna finale; `--no-deliver` la mantiene - interna invece di consentire un invio diretto. +- Se l'esecuzione isolata restituisce solo il token silenzioso (`NO_REPLY` / `no_reply`), OpenClaw sopprime la consegna diretta in uscita e sopprime anche il percorso di fallback del riepilogo in coda, quindi non viene pubblicato nulla di nuovo in chat. +- Per i processi isolati di proprietà di cron, non aspettarti che l'agente usi lo strumento message come fallback. Il runner gestisce la consegna finale; `--no-deliver` la mantiene interna invece di consentire un invio diretto. -### Insidie del fuso orario +### Problemi comuni con il fuso orario - Cron senza `--tz` usa il fuso orario dell'host del gateway. - Le pianificazioni `at` senza fuso orario vengono trattate come UTC. @@ -414,5 +419,5 @@ openclaw doctor - [Automazione e attività](/it/automation) — tutti i meccanismi di automazione in sintesi - [Attività in background](/it/automation/tasks) — registro delle attività per le esecuzioni cron -- [Heartbeat](/it/gateway/heartbeat) — turni periodici della sessione principale +- [Heartbeat](/it/gateway/heartbeat) — turni periodici della sessione main - [Fuso orario](/it/concepts/timezone) — configurazione del fuso orario diff --git a/docs/it/channels/slack.md b/docs/it/channels/slack.md index df8333315..9522e0fab 100644 --- a/docs/it/channels/slack.md +++ b/docs/it/channels/slack.md @@ -1,30 +1,30 @@ --- read_when: - Configurazione di Slack o debug della modalità socket/HTTP di Slack -summary: Configurazione di Slack e comportamento in fase di esecuzione (Socket Mode + URL di richiesta HTTP) +summary: Configurazione e comportamento in fase di esecuzione di Slack (Socket Mode + URL delle richieste HTTP) title: Slack x-i18n: - generated_at: "2026-04-08T06:02:10Z" + generated_at: "2026-04-12T08:07:55Z" model: gpt-5.4 provider: openai - source_hash: cad132131ddce688517def7c14703ad314441c67aacc4cc2a2a721e1d1c01942 + source_hash: 4b80c1a612b8815c46c675b688639c207a481f367075996dde3858a83637313b source_path: channels/slack.md workflow: 15 --- # Slack -Stato: pronto per la produzione per DM + canali tramite integrazioni dell'app Slack. La modalità predefinita è Socket Mode; sono supportati anche gli URL di richiesta HTTP. +Stato: pronto per la produzione per DM + canali tramite integrazioni dell'app Slack. La modalità predefinita è Socket Mode; sono supportati anche gli URL delle richieste HTTP. - I DM di Slack usano per impostazione predefinita la modalità di associazione. + Le DM di Slack usano per impostazione predefinita la modalità di associazione. Comportamento nativo dei comandi e catalogo dei comandi. - - Diagnostica tra canali e procedure di ripristino. + + Diagnostica cross-channel e procedure di riparazione. @@ -36,10 +36,10 @@ Stato: pronto per la produzione per DM + canali tramite integrazioni dell'app Sl Nelle impostazioni dell'app Slack premi il pulsante **[Create New App](https://api.slack.com/apps/new)**: - - scegli **from a manifest** e seleziona un workspace per la tua app - - incolla il [manifesto di esempio](#manifest-and-scope-checklist) qui sotto e continua per creare l'app + - scegli **from a manifest** e seleziona uno spazio di lavoro per la tua app + - incolla il [manifest di esempio](#manifest-and-scope-checklist) qui sotto e continua con la creazione - genera un **App-Level Token** (`xapp-...`) con `connections:write` - - installa l'app e copia il **Bot Token** (`xoxb-...`) visualizzato + - installa l'app e copia il **Bot Token** (`xoxb-...`) mostrato @@ -57,7 +57,7 @@ Stato: pronto per la produzione per DM + canali tramite integrazioni dell'app Sl } ``` - Fallback env (solo account predefinito): + Fallback tramite variabili d'ambiente (solo account predefinito): ```bash SLACK_APP_TOKEN=xapp-... @@ -77,15 +77,15 @@ openclaw gateway - + Nelle impostazioni dell'app Slack premi il pulsante **[Create New App](https://api.slack.com/apps/new)**: - - scegli **from a manifest** e seleziona un workspace per la tua app - - incolla il [manifesto di esempio](#manifest-and-scope-checklist) e aggiorna gli URL prima della creazione + - scegli **from a manifest** e seleziona uno spazio di lavoro per la tua app + - incolla il [manifest di esempio](#manifest-and-scope-checklist) e aggiorna gli URL prima della creazione - salva il **Signing Secret** per la verifica delle richieste - - installa l'app e copia il **Bot Token** (`xoxb-...`) visualizzato + - installa l'app e copia il **Bot Token** (`xoxb-...`) mostrato @@ -125,7 +125,7 @@ openclaw gateway -## Manifesto ed elenco di controllo degli scope +## Checklist di manifest e ambiti @@ -134,7 +134,7 @@ openclaw gateway { "display_information": { "name": "OpenClaw", - "description": "Slack connector for OpenClaw" + "description": "Connettore Slack per OpenClaw" }, "features": { "bot_user": { @@ -148,7 +148,7 @@ openclaw gateway "slash_commands": [ { "command": "/openclaw", - "description": "Send a message to OpenClaw", + "description": "Invia un messaggio a OpenClaw", "should_escape": false } ] @@ -205,13 +205,13 @@ openclaw gateway - + ```json { "display_information": { "name": "OpenClaw", - "description": "Slack connector for OpenClaw" + "description": "Connettore Slack per OpenClaw" }, "features": { "bot_user": { @@ -225,7 +225,7 @@ openclaw gateway "slash_commands": [ { "command": "/openclaw", - "description": "Send a message to OpenClaw", + "description": "Invia un messaggio a OpenClaw", "should_escape": false, "url": "https://gateway-host.example.com/slack/events" } @@ -289,14 +289,287 @@ openclaw gateway +### Impostazioni aggiuntive del manifest + +Mostra funzionalità diverse che estendono i valori predefiniti sopra. + - - Aggiungi lo scope bot `chat:write.customize` se vuoi che i messaggi in uscita usino l'identità dell'agente attivo (nome utente e icona personalizzati) invece dell'identità predefinita dell'app Slack. + + + È possibile usare più [comandi slash nativi](#commands-and-slash-behavior) al posto di un singolo comando configurato, con alcune particolarità: + + - Usa `/agentstatus` invece di `/status` perché il comando `/status` è riservato. + - Non è possibile rendere disponibili più di 25 comandi slash contemporaneamente. + + Sostituisci la sezione `features.slash_commands` esistente con un sottoinsieme dei [comandi disponibili](/it/tools/slash-commands#command-list): + + + + +```json + "slash_commands": [ + { + "command": "/new", + "description": "Avvia una nuova sessione", + "usage_hint": "[model]" + }, + { + "command": "/reset", + "description": "Reimposta la sessione corrente" + }, + { + "command": "/compact", + "description": "Compatta il contesto della sessione", + "usage_hint": "[instructions]" + }, + { + "command": "/stop", + "description": "Interrompi l'esecuzione corrente" + }, + { + "command": "/session", + "description": "Gestisci la scadenza del binding del thread", + "usage_hint": "idle or max-age " + }, + { + "command": "/think", + "description": "Imposta il livello di ragionamento", + "usage_hint": "" + }, + { + "command": "/verbose", + "description": "Attiva o disattiva l'output dettagliato", + "usage_hint": "on|off|full" + }, + { + "command": "/fast", + "description": "Mostra o imposta la modalità rapida", + "usage_hint": "[status|on|off]" + }, + { + "command": "/reasoning", + "description": "Attiva o disattiva la visibilità del ragionamento", + "usage_hint": "[on|off|stream]" + }, + { + "command": "/elevated", + "description": "Attiva o disattiva la modalità elevata", + "usage_hint": "[on|off|ask|full]" + }, + { + "command": "/exec", + "description": "Mostra o imposta i valori predefiniti di exec", + "usage_hint": "host= security= ask= node=" + }, + { + "command": "/model", + "description": "Mostra o imposta il modello", + "usage_hint": "[name|#|status]" + }, + { + "command": "/models", + "description": "Elenca i provider o i modelli per un provider", + "usage_hint": "[provider] [page] [limit=|size=|all]" + }, + { + "command": "/help", + "description": "Mostra il riepilogo sintetico della guida" + }, + { + "command": "/commands", + "description": "Mostra il catalogo dei comandi generato" + }, + { + "command": "/tools", + "description": "Mostra cosa può usare in questo momento l'agente corrente", + "usage_hint": "[compact|verbose]" + }, + { + "command": "/agentstatus", + "description": "Mostra lo stato di runtime, incluso l'uso/quota del provider quando disponibile" + }, + { + "command": "/tasks", + "description": "Elenca le attività in background attive/recenti per la sessione corrente" + }, + { + "command": "/context", + "description": "Spiega come viene assemblato il contesto", + "usage_hint": "[list|detail|json]" + }, + { + "command": "/whoami", + "description": "Mostra la tua identità mittente" + }, + { + "command": "/skill", + "description": "Esegui una skill per nome", + "usage_hint": " [input]" + }, + { + "command": "/btw", + "description": "Fai una domanda laterale senza modificare il contesto della sessione", + "usage_hint": "" + }, + { + "command": "/usage", + "description": "Controlla il piè di pagina dell'utilizzo o mostra il riepilogo dei costi", + "usage_hint": "off|tokens|full|cost" + } + ] +``` + + + + +```json + "slash_commands": [ + { + "command": "/new", + "description": "Avvia una nuova sessione", + "usage_hint": "[model]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/reset", + "description": "Reimposta la sessione corrente", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/compact", + "description": "Compatta il contesto della sessione", + "usage_hint": "[instructions]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/stop", + "description": "Interrompi l'esecuzione corrente", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/session", + "description": "Gestisci la scadenza del binding del thread", + "usage_hint": "idle or max-age ", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/think", + "description": "Imposta il livello di ragionamento", + "usage_hint": "", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/verbose", + "description": "Attiva o disattiva l'output dettagliato", + "usage_hint": "on|off|full", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/fast", + "description": "Mostra o imposta la modalità rapida", + "usage_hint": "[status|on|off]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/reasoning", + "description": "Attiva o disattiva la visibilità del ragionamento", + "usage_hint": "[on|off|stream]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/elevated", + "description": "Attiva o disattiva la modalità elevata", + "usage_hint": "[on|off|ask|full]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/exec", + "description": "Mostra o imposta i valori predefiniti di exec", + "usage_hint": "host= security= ask= node=", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/model", + "description": "Mostra o imposta il modello", + "usage_hint": "[name|#|status]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/models", + "description": "Elenca i provider o i modelli per un provider", + "usage_hint": "[provider] [page] [limit=|size=|all]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/help", + "description": "Mostra il riepilogo sintetico della guida", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/commands", + "description": "Mostra il catalogo dei comandi generato", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/tools", + "description": "Mostra cosa può usare in questo momento l'agente corrente", + "usage_hint": "[compact|verbose]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/agentstatus", + "description": "Mostra lo stato di runtime, incluso l'uso/quota del provider quando disponibile", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/tasks", + "description": "Elenca le attività in background attive/recenti per la sessione corrente", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/context", + "description": "Spiega come viene assemblato il contesto", + "usage_hint": "[list|detail|json]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/whoami", + "description": "Mostra la tua identità mittente", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/skill", + "description": "Esegui una skill per nome", + "usage_hint": " [input]", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/btw", + "description": "Fai una domanda laterale senza modificare il contesto della sessione", + "usage_hint": "", + "url": "https://gateway-host.example.com/slack/events" + }, + { + "command": "/usage", + "description": "Controlla il piè di pagina dell'utilizzo o mostra il riepilogo dei costi", + "usage_hint": "off|tokens|full|cost", + "url": "https://gateway-host.example.com/slack/events" + } + ] +``` + + + + + + + Aggiungi l'ambito bot `chat:write.customize` se vuoi che i messaggi in uscita usino l'identità dell'agente attivo (nome utente e icona personalizzati) invece dell'identità predefinita dell'app Slack. Se usi un'icona emoji, Slack si aspetta la sintassi `:emoji_name:`. + - - Se configuri `channels.slack.userToken`, gli scope di lettura tipici sono: + + Se configuri `channels.slack.userToken`, gli ambiti di lettura tipici sono: - `channels:history`, `groups:history`, `im:history`, `mpim:history` - `channels:read`, `groups:read`, `im:read`, `mpim:read` @@ -304,49 +577,49 @@ openclaw gateway - `reactions:read` - `pins:read` - `emoji:read` - - `search:read` (se dipendi dalle letture della ricerca di Slack) + - `search:read` (se dipendi dalle letture della ricerca Slack) ## Modello dei token -- `botToken` + `appToken` sono richiesti per Socket Mode. +- `botToken` + `appToken` sono obbligatori per Socket Mode. - La modalità HTTP richiede `botToken` + `signingSecret`. - `botToken`, `appToken`, `signingSecret` e `userToken` accettano stringhe - in chiaro o oggetti SecretRef. -- I token nella configurazione hanno la precedenza sul fallback env. + in chiaro oppure oggetti SecretRef. +- I token di configurazione hanno la precedenza sul fallback env. - Il fallback env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` si applica solo all'account predefinito. -- `userToken` (`xoxp-...`) è solo di configurazione (nessun fallback env) e per impostazione predefinita usa il comportamento di sola lettura (`userTokenReadOnly: true`). +- `userToken` (`xoxp-...`) è solo di configurazione (nessun fallback env) e usa come impostazione predefinita il comportamento di sola lettura (`userTokenReadOnly: true`). Comportamento dell'istantanea di stato: -- L'ispezione dell'account Slack traccia i campi `*Source` e `*Status` - per ogni credenziale (`botToken`, `appToken`, `signingSecret`, `userToken`). -- Lo stato può essere `available`, `configured_unavailable` o `missing`. +- L'ispezione dell'account Slack tiene traccia dei campi `*Source` e `*Status` + per credenziale (`botToken`, `appToken`, `signingSecret`, `userToken`). +- Lo stato è `available`, `configured_unavailable` oppure `missing`. - `configured_unavailable` significa che l'account è configurato tramite SecretRef - o un'altra origine di segreti non inline, ma il percorso di comando/esecuzione corrente + o un'altra origine di segreti non inline, ma il percorso corrente di comando/runtime non è riuscito a risolvere il valore effettivo. -- In modalità HTTP è incluso `signingSecretStatus`; in Socket Mode, la +- In modalità HTTP, è incluso `signingSecretStatus`; in Socket Mode, la coppia richiesta è `botTokenStatus` + `appTokenStatus`. -Per azioni/letture di directory, il user token può essere preferito quando configurato. Per le scritture, il bot token resta preferito; le scritture con user token sono consentite solo quando `userTokenReadOnly: false` e il bot token non è disponibile. +Per le letture di azioni/directory, il token utente può avere la priorità quando configurato. Per le scritture, il token bot resta preferito; le scritture con token utente sono consentite solo quando `userTokenReadOnly: false` e il token bot non è disponibile. -## Azioni e vincoli +## Azioni e gate Le azioni Slack sono controllate da `channels.slack.actions.*`. Gruppi di azioni disponibili negli strumenti Slack correnti: -| Gruppo | Predefinito | -| ---------- | ----------- | -| messages | abilitato | -| reactions | abilitato | -| pins | abilitato | -| memberInfo | abilitato | -| emojiList | abilitato | +| Group | Default | +| ---------- | ------- | +| messages | enabled | +| reactions | enabled | +| pins | enabled | +| memberInfo | enabled | +| emojiList | enabled | Le azioni correnti sui messaggi Slack includono `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` ed `emoji-list`. @@ -354,7 +627,7 @@ Le azioni correnti sui messaggi Slack includono `send`, `upload-file`, `download - `channels.slack.dmPolicy` controlla l'accesso ai DM (legacy: `channels.slack.dm.policy`): + `channels.slack.dmPolicy` controlla l'accesso DM (legacy: `channels.slack.dm.policy`): - `pairing` (predefinito) - `allowlist` @@ -366,16 +639,16 @@ Le azioni correnti sui messaggi Slack includono `send`, `upload-file`, `download - `dm.enabled` (predefinito true) - `channels.slack.allowFrom` (preferito) - `dm.allowFrom` (legacy) - - `dm.groupEnabled` (DM di gruppo predefiniti su false) - - `dm.groupChannels` (allowlist MPIM opzionale) + - `dm.groupEnabled` (DM di gruppo predefinite false) + - `dm.groupChannels` (allowlist MPIM facoltativa) Precedenza multi-account: - `channels.slack.accounts.default.allowFrom` si applica solo all'account `default`. - - Gli account con nome ereditano `channels.slack.allowFrom` quando il loro `allowFrom` non è impostato. + - Gli account con nome ereditano `channels.slack.allowFrom` quando il proprio `allowFrom` non è impostato. - Gli account con nome non ereditano `channels.slack.accounts.default.allowFrom`. - L'associazione nei DM usa `openclaw pairing approve slack `. + L'associazione nelle DM usa `openclaw pairing approve slack `. @@ -386,28 +659,28 @@ Le azioni correnti sui messaggi Slack includono `send`, `upload-file`, `download - `allowlist` - `disabled` - L'allowlist dei canali si trova in `channels.slack.channels` e dovrebbe usare ID di canale stabili. + L'allowlist dei canali si trova sotto `channels.slack.channels` e dovrebbe usare ID canale stabili. - Nota di esecuzione: se `channels.slack` è completamente assente (configurazione solo env), in fase di esecuzione viene usato il fallback `groupPolicy="allowlist"` e viene registrato un avviso (anche se `channels.defaults.groupPolicy` è impostato). + Nota di runtime: se `channels.slack` è completamente assente (configurazione solo env), il runtime usa come fallback `groupPolicy="allowlist"` e registra un avviso (anche se `channels.defaults.groupPolicy` è impostato). Risoluzione nome/ID: - - le voci nell'allowlist dei canali e nell'allowlist DM vengono risolte all'avvio quando l'accesso ai token lo consente - - le voci non risolte per nome di canale vengono mantenute come configurate ma ignorate per l'instradamento per impostazione predefinita - - l'autorizzazione in ingresso e l'instradamento del canale usano gli ID come priorità; la corrispondenza diretta con nome utente/slug richiede `channels.slack.dangerouslyAllowNameMatching: true` + - le voci dell'allowlist dei canali e dell'allowlist DM vengono risolte all'avvio quando l'accesso ai token lo consente + - le voci non risolte del nome canale vengono mantenute come configurate ma ignorate per l'instradamento per impostazione predefinita + - l'autorizzazione in ingresso e l'instradamento dei canali usano per impostazione predefinita prima gli ID; la corrispondenza diretta di username/slug richiede `channels.slack.dangerouslyAllowNameMatching: true` - Per impostazione predefinita, i messaggi nel canale sono vincolati dalle menzioni. + I messaggi del canale sono limitati dalle menzioni per impostazione predefinita. Origini delle menzioni: - menzione esplicita dell'app (`<@botId>`) - pattern regex di menzione (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`) - - comportamento implicito di risposta nei thread al bot (disabilitato quando `thread.requireExplicitMention` è `true`) + - comportamento implicito di risposta nel thread al bot (disabilitato quando `thread.requireExplicitMention` è `true`) - Controlli per canale (`channels.slack.channels.`; i nomi solo tramite risoluzione all'avvio o `dangerouslyAllowNameMatching`): + Controlli per canale (`channels.slack.channels.`; nomi solo tramite risoluzione all'avvio o `dangerouslyAllowNameMatching`): - `requireMention` - `users` (allowlist) @@ -415,7 +688,7 @@ Le azioni correnti sui messaggi Slack includono `send`, `upload-file`, `download - `skills` - `systemPrompt` - `tools`, `toolsBySender` - - formato chiave `toolsBySender`: `id:`, `e164:`, `username:`, `name:` oppure wildcard `"*"` + - formato della chiave `toolsBySender`: `id:`, `e164:`, `username:`, `name:` oppure wildcard `"*"` (le chiavi legacy senza prefisso continuano a essere mappate solo a `id:`) @@ -423,28 +696,28 @@ Le azioni correnti sui messaggi Slack includono `send`, `upload-file`, `download ## Thread, sessioni e tag di risposta -- I DM vengono instradati come `direct`; i canali come `channel`; gli MPIM come `group`. -- Con l'impostazione predefinita `session.dmScope=main`, i DM Slack collassano nella sessione principale dell'agente. +- Le DM vengono instradate come `direct`; i canali come `channel`; gli MPIM come `group`. +- Con il valore predefinito `session.dmScope=main`, le DM di Slack confluiscono nella sessione principale dell'agente. - Sessioni canale: `agent::slack:channel:`. -- Le risposte nei thread possono creare suffissi di sessione thread (`:thread:`) quando applicabile. +- Le risposte nei thread possono creare suffissi di sessione del thread (`:thread:`) quando applicabile. - Il valore predefinito di `channels.slack.thread.historyScope` è `thread`; il valore predefinito di `thread.inheritParent` è `false`. -- `channels.slack.thread.initialHistoryLimit` controlla quanti messaggi esistenti del thread vengono recuperati quando inizia una nuova sessione thread (predefinito `20`; imposta `0` per disabilitare). -- `channels.slack.thread.requireExplicitMention` (predefinito `false`): quando è `true`, sopprime le menzioni implicite nei thread così il bot risponde solo a menzioni `@bot` esplicite all'interno dei thread, anche quando il bot ha già partecipato al thread. Senza questa opzione, le risposte in un thread con partecipazione del bot aggirano il vincolo `requireMention`. +- `channels.slack.thread.initialHistoryLimit` controlla quanti messaggi esistenti del thread vengono recuperati quando inizia una nuova sessione del thread (predefinito `20`; imposta `0` per disabilitare). +- `channels.slack.thread.requireExplicitMention` (predefinito `false`): quando è `true`, sopprime le menzioni implicite del thread in modo che il bot risponda solo a menzioni esplicite `@bot` all'interno dei thread, anche quando il bot ha già partecipato al thread. Senza questa impostazione, le risposte in un thread a cui il bot ha partecipato aggirano il gate `requireMention`. -Controlli del thread di risposta: +Controlli del threading delle risposte: - `channels.slack.replyToMode`: `off|first|all|batched` (predefinito `off`) - `channels.slack.replyToModeByChatType`: per `direct|group|channel` - fallback legacy per chat dirette: `channels.slack.dm.replyToMode` -Sono supportati i tag di risposta manuali: +Sono supportati tag di risposta manuali: - `[[reply_to_current]]` - `[[reply_to:]]` -Nota: `replyToMode="off"` disabilita **tutto** il threading delle risposte in Slack, inclusi i tag espliciti `[[reply_to_*]]`. Questo differisce da Telegram, dove i tag espliciti vengono comunque rispettati in modalità `"off"`. La differenza riflette i modelli di threading delle piattaforme: i thread di Slack nascondono i messaggi dal canale, mentre le risposte di Telegram restano visibili nel flusso principale della chat. +Nota: `replyToMode="off"` disabilita **tutto** il threading delle risposte in Slack, inclusi i tag espliciti `[[reply_to_*]]`. Questo differisce da Telegram, dove i tag espliciti sono comunque rispettati in modalità `"off"`. La differenza riflette i modelli di threading delle piattaforme: i thread di Slack nascondono i messaggi dal canale, mentre le risposte di Telegram restano visibili nel flusso principale della chat. -## Reazioni di ack +## Reazioni di conferma `ackReaction` invia un'emoji di conferma mentre OpenClaw elabora un messaggio in ingresso. @@ -453,28 +726,28 @@ Ordine di risoluzione: - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- fallback all'emoji dell'identità dell'agente (`agents.list[].identity.emoji`, altrimenti "👀") +- fallback dell'emoji dell'identità dell'agente (`agents.list[].identity.emoji`, altrimenti "👀") Note: -- Slack si aspetta shortcodes (per esempio `"eyes"`). -- Usa `""` per disabilitare la reazione per l'account Slack o globalmente. +- Slack si aspetta shortcode (ad esempio `"eyes"`). +- Usa `""` per disabilitare la reazione per l'account Slack o a livello globale. ## Streaming del testo -`channels.slack.streaming` controlla il comportamento dell'anteprima in tempo reale: +`channels.slack.streaming` controlla il comportamento dell'anteprima live: -- `off`: disabilita lo streaming dell'anteprima in tempo reale. -- `partial` (predefinito): sostituisce il testo di anteprima con l'output parziale più recente. +- `off`: disabilita lo streaming dell'anteprima live. +- `partial` (predefinito): sostituisce il testo di anteprima con l'ultimo output parziale. - `block`: aggiunge aggiornamenti di anteprima a blocchi. -- `progress`: mostra testo di stato dell'avanzamento durante la generazione, poi invia il testo finale. +- `progress`: mostra il testo di stato dell'avanzamento durante la generazione, quindi invia il testo finale. `channels.slack.streaming.nativeTransport` controlla lo streaming di testo nativo di Slack quando `channels.slack.streaming.mode` è `partial` (predefinito: `true`). -- Deve essere disponibile un thread di risposta perché compaiano lo streaming di testo nativo e lo stato del thread assistant di Slack. La selezione del thread continua comunque a seguire `replyToMode`. -- Le radici di canale e chat di gruppo possono comunque usare la normale anteprima bozza quando lo streaming nativo non è disponibile. -- I DM Slack di livello superiore restano per impostazione predefinita fuori thread, quindi non mostrano l'anteprima in stile thread; usa risposte nel thread o `typingReaction` se vuoi progressi visibili lì. -- I payload multimediali e non testuali usano il fallback alla consegna normale. +- Per lo streaming di testo nativo devono essere disponibili un thread di risposta e lo stato del thread assistant di Slack. La selezione del thread continua comunque a seguire `replyToMode`. +- Le radici di canali e chat di gruppo possono comunque usare la normale anteprima bozza quando lo streaming nativo non è disponibile. +- Le DM Slack di livello superiore restano fuori thread per impostazione predefinita, quindi non mostrano l'anteprima in stile thread; usa risposte nel thread o `typingReaction` se vuoi un avanzamento visibile in quel caso. +- I media e i payload non testuali usano il fallback alla consegna normale. - Se lo streaming fallisce a metà risposta, OpenClaw usa il fallback alla consegna normale per i payload rimanenti. Usa l'anteprima bozza invece dello streaming di testo nativo di Slack: @@ -495,12 +768,12 @@ Usa l'anteprima bozza invece dello streaming di testo nativo di Slack: Chiavi legacy: - `channels.slack.streamMode` (`replace | status_final | append`) viene migrato automaticamente a `channels.slack.streaming.mode`. -- il booleano `channels.slack.streaming` viene migrato automaticamente a `channels.slack.streaming.mode` e `channels.slack.streaming.nativeTransport`. -- il legacy `channels.slack.nativeStreaming` viene migrato automaticamente a `channels.slack.streaming.nativeTransport`. +- il valore booleano `channels.slack.streaming` viene migrato automaticamente a `channels.slack.streaming.mode` e `channels.slack.streaming.nativeTransport`. +- il valore legacy `channels.slack.nativeStreaming` viene migrato automaticamente a `channels.slack.streaming.nativeTransport`. ## Fallback della reazione di digitazione -`typingReaction` aggiunge una reazione temporanea al messaggio Slack in ingresso mentre OpenClaw elabora una risposta, poi la rimuove quando l'esecuzione termina. È particolarmente utile fuori dalle risposte nei thread, che usano un indicatore di stato predefinito "sta digitando...". +`typingReaction` aggiunge una reazione temporanea al messaggio Slack in ingresso mentre OpenClaw elabora una risposta, quindi la rimuove quando l'esecuzione termina. Questo è particolarmente utile al di fuori delle risposte nei thread, che usano un indicatore di stato predefinito "sta scrivendo...". Ordine di risoluzione: @@ -509,22 +782,22 @@ Ordine di risoluzione: Note: -- Slack si aspetta shortcodes (per esempio `"hourglass_flowing_sand"`). -- La reazione è best-effort e il cleanup viene tentato automaticamente dopo il completamento della risposta o del percorso di errore. +- Slack si aspetta shortcode (ad esempio `"hourglass_flowing_sand"`). +- La reazione è best-effort e la pulizia viene tentata automaticamente al termine della risposta o del percorso di errore. ## Media, suddivisione in blocchi e consegna - Gli allegati file di Slack vengono scaricati da URL privati ospitati da Slack (flusso di richiesta autenticato tramite token) e scritti nell'archivio media quando il recupero riesce e i limiti di dimensione lo consentono. + Gli allegati di file Slack vengono scaricati da URL privati ospitati da Slack (flusso di richiesta autenticato tramite token) e scritti nello store dei media quando il recupero riesce e i limiti di dimensione lo consentono. - Il limite di dimensione in ingresso in fase di esecuzione è per impostazione predefinita `20MB`, salvo override con `channels.slack.mediaMaxMb`. + Il limite predefinito della dimensione in ingresso a runtime è `20MB`, salvo override con `channels.slack.mediaMaxMb`. - i blocchi di testo usano `channels.slack.textChunkLimit` (predefinito 4000) - - `channels.slack.chunkMode="newline"` abilita la suddivisione dando priorità ai paragrafi + - `channels.slack.chunkMode="newline"` abilita la suddivisione con priorità ai paragrafi - gli invii di file usano le API di upload di Slack e possono includere risposte nei thread (`thread_ts`) - il limite dei media in uscita segue `channels.slack.mediaMaxMb` quando configurato; altrimenti gli invii del canale usano i valori predefiniti per tipo MIME dalla pipeline media @@ -532,44 +805,51 @@ Note: Destinazioni esplicite preferite: - - `user:` per i DM + - `user:` per le DM - `channel:` per i canali - I DM Slack vengono aperti tramite le API di conversazione di Slack quando si invia verso destinazioni utente. + Le DM di Slack vengono aperte tramite le API di conversazione di Slack quando si invia a destinazioni utente. ## Comandi e comportamento slash -- La modalità automatica dei comandi nativi è **disattivata** per Slack (`commands.native: "auto"` non abilita i comandi nativi Slack). -- Abilita gli handler dei comandi nativi Slack con `channels.slack.commands.native: true` (o globale `commands.native: true`). -- Quando i comandi nativi sono abilitati, registra in Slack i comandi slash corrispondenti (nomi `/`), con un'eccezione: - - registra `/agentstatus` per il comando di stato (Slack riserva `/status`) -- Se i comandi nativi non sono abilitati, puoi eseguire un singolo comando slash configurato tramite `channels.slack.slashCommand`. -- I menu argomento nativi ora adattano la propria strategia di rendering: - - fino a 5 opzioni: blocchi di pulsanti - - 6-100 opzioni: menu statico di selezione - - più di 100 opzioni: selezione esterna con filtro asincrono delle opzioni quando sono disponibili gli handler delle opzioni di interattività - - se i valori delle opzioni codificati superano i limiti di Slack, il flusso usa il fallback ai pulsanti -- Per payload di opzioni lunghi, i menu degli argomenti dei comandi slash usano una finestra di conferma prima di inviare un valore selezionato. - -Impostazioni predefinite dei comandi slash: +I comandi slash compaiono in Slack come un singolo comando configurato oppure come più comandi nativi. Configura `channels.slack.slashCommand` per modificare i valori predefiniti dei comandi: - `enabled: false` - `name: "openclaw"` - `sessionPrefix: "slack:slash"` - `ephemeral: true` -Le sessioni slash usano chiavi isolate: +```txt +/openclaw /help +``` -- `agent::slack:slash:` +I comandi nativi richiedono [impostazioni aggiuntive del manifest](#additional-manifest-settings) nella tua app Slack e vengono abilitati con `channels.slack.commands.native: true` oppure `commands.native: true` nelle configurazioni globali. -e continuano a instradare l'esecuzione del comando rispetto alla sessione della conversazione di destinazione (`CommandTargetSessionKey`). +- La modalità automatica dei comandi nativi è **disattivata** per Slack, quindi `commands.native: "auto"` non abilita i comandi nativi di Slack. + +```txt +/help +``` + +I menu argomento dei comandi nativi usano una strategia di rendering adattiva che mostra una finestra modale di conferma prima di inviare il valore dell'opzione selezionata: + +- fino a 5 opzioni: blocchi pulsante +- 6-100 opzioni: menu di selezione statico +- più di 100 opzioni: selezione esterna con filtro asincrono delle opzioni quando sono disponibili gestori delle opzioni di interattività +- limiti Slack superati: i valori delle opzioni codificati usano il fallback ai pulsanti + +```txt +/think +``` + +Le sessioni slash usano chiavi isolate come `agent::slack:slash:` e continuano comunque a instradare le esecuzioni dei comandi verso la sessione della conversazione di destinazione usando `CommandTargetSessionKey`. ## Risposte interattive -Slack può eseguire il rendering di controlli interattivi di risposta creati dagli agenti, ma questa funzionalità è disabilitata per impostazione predefinita. +Slack può visualizzare controlli di risposta interattivi creati dall'agente, ma questa funzionalità è disabilitata per impostazione predefinita. Abilitala globalmente: @@ -603,42 +883,42 @@ Oppure abilitala solo per un account Slack: } ``` -Quando è abilitata, gli agenti possono emettere direttive di risposta solo Slack: +Quando è abilitata, gli agenti possono emettere direttive di risposta solo per Slack: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -Queste direttive vengono compilate in Slack Block Kit e instradano clic o selezioni di nuovo attraverso il percorso eventi di interazione Slack esistente. +Queste direttive vengono compilate in Slack Block Kit e instradano clic o selezioni attraverso il percorso esistente degli eventi di interazione Slack. Note: -- Si tratta di UI specifica per Slack. Gli altri canali non traducono le direttive Slack Block Kit nei propri sistemi di pulsanti. -- I valori dei callback interattivi sono token opachi generati da OpenClaw, non valori grezzi creati dall'agente. -- Se i blocchi interattivi generati superano i limiti di Slack Block Kit, OpenClaw usa il fallback alla risposta testuale originale invece di inviare un payload blocks non valido. +- Si tratta di un'interfaccia specifica di Slack. Gli altri canali non traducono le direttive Slack Block Kit nei propri sistemi di pulsanti. +- I valori di callback interattivi sono token opachi generati da OpenClaw, non valori grezzi creati dall'agente. +- Se i blocchi interattivi generati superano i limiti di Slack Block Kit, OpenClaw usa il fallback alla risposta testuale originale invece di inviare un payload `blocks` non valido. ## Approvazioni exec in Slack -Slack può agire come client di approvazione nativo con pulsanti interattivi e interazioni, invece di usare il fallback alla Web UI o al terminale. +Slack può agire come client di approvazione nativo con pulsanti e interazioni interattive, invece di usare il fallback alla Web UI o al terminale. -- Le approvazioni exec usano `channels.slack.execApprovals.*` per l'instradamento nativo in DM/canale. -- Le approvazioni dei plugin possono comunque risolversi tramite la stessa superficie nativa di pulsanti Slack quando la richiesta arriva già in Slack e il tipo di ID approvazione è `plugin:`. -- L'autorizzazione degli approvatori continua a essere applicata: solo gli utenti identificati come approvatori possono approvare o negare richieste tramite Slack. +- Le approvazioni exec usano `channels.slack.execApprovals.*` per l'instradamento nativo DM/canale. +- Anche le approvazioni dei plugin possono risolversi tramite la stessa superficie di pulsanti nativi Slack quando la richiesta arriva già in Slack e il tipo di ID approvazione è `plugin:`. +- L'autorizzazione dell'approvatore continua a essere applicata: solo gli utenti identificati come approvatori possono approvare o rifiutare richieste tramite Slack. -Questo usa la stessa superficie condivisa dei pulsanti di approvazione degli altri canali. Quando `interactivity` è abilitato nelle impostazioni della tua app Slack, le richieste di approvazione vengono renderizzate come pulsanti Block Kit direttamente nella conversazione. -Quando questi pulsanti sono presenti, costituiscono la UX di approvazione primaria; OpenClaw +Questo usa la stessa superficie condivisa dei pulsanti di approvazione degli altri canali. Quando `interactivity` è abilitato nelle impostazioni della tua app Slack, i prompt di approvazione vengono visualizzati come pulsanti Block Kit direttamente nella conversazione. +Quando questi pulsanti sono presenti, rappresentano l'esperienza utente principale per l'approvazione; OpenClaw dovrebbe includere un comando manuale `/approve` solo quando il risultato dello strumento indica che le -approvazioni in chat non sono disponibili o che l'approvazione manuale è l'unico percorso possibile. +approvazioni in chat non sono disponibili o che l'approvazione manuale è l'unico percorso. Percorso di configurazione: - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers` (opzionale; usa il fallback a `commands.ownerAllowFrom` quando possibile) +- `channels.slack.execApprovals.approvers` (facoltativo; usa il fallback a `commands.ownerAllowFrom` quando possibile) - `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, predefinito: `dm`) - `agentFilter`, `sessionFilter` -Slack abilita automaticamente le approvazioni exec native quando `enabled` non è impostato o è `"auto"` e viene risolto almeno un +Slack abilita automaticamente le approvazioni exec native quando `enabled` non è impostato oppure è `"auto"` e viene risolto almeno un approvatore. Imposta `enabled: false` per disabilitare esplicitamente Slack come client di approvazione nativo. -Imposta `enabled: true` per forzare le approvazioni native quando vengono risolti gli approvatori. +Imposta `enabled: true` per forzare l'attivazione delle approvazioni native quando vengono risolti approvatori. Comportamento predefinito senza configurazione esplicita delle approvazioni exec Slack: @@ -651,7 +931,7 @@ Comportamento predefinito senza configurazione esplicita delle approvazioni exec ``` La configurazione nativa esplicita di Slack è necessaria solo quando vuoi sovrascrivere gli approvatori, aggiungere filtri o -scegliere la consegna nella chat di origine: +abilitare la consegna alla chat di origine: ```json5 { @@ -667,36 +947,36 @@ scegliere la consegna nella chat di origine: } ``` -L'inoltro condiviso `approvals.exec` è separato. Usalo solo quando le richieste di approvazione exec devono anche -essere instradate verso altre chat o destinazioni esplicite fuori banda. Anche l'inoltro condiviso `approvals.plugin` è -separato; i pulsanti nativi Slack possono comunque risolvere le approvazioni dei plugin quando tali richieste arrivano già +L'inoltro condiviso `approvals.exec` è separato. Usalo solo quando i prompt di approvazione exec devono essere instradati anche +ad altre chat o a destinazioni esplicite fuori banda. Anche l'inoltro condiviso `approvals.plugin` è +separato; i pulsanti nativi di Slack possono comunque risolvere le approvazioni dei plugin quando tali richieste arrivano già in Slack. -Anche `/approve` nella stessa chat funziona in canali e DM Slack che già supportano i comandi. Vedi [Approvazioni exec](/it/tools/exec-approvals) per il modello completo di inoltro delle approvazioni. +Anche `/approve` nella stessa chat funziona nei canali e nelle DM di Slack che supportano già i comandi. Vedi [Exec approvals](/it/tools/exec-approvals) per il modello completo di inoltro delle approvazioni. ## Eventi e comportamento operativo -- Le modifiche/eliminazioni dei messaggi e i broadcast dei thread vengono mappati in eventi di sistema. -- Gli eventi di aggiunta/rimozione di reazioni vengono mappati in eventi di sistema. +- Le modifiche/eliminazioni dei messaggi e le trasmissioni dei thread vengono mappate in eventi di sistema. +- Gli eventi di aggiunta/rimozione delle reazioni vengono mappati in eventi di sistema. - Gli eventi di ingresso/uscita dei membri, creazione/rinomina dei canali e aggiunta/rimozione dei pin vengono mappati in eventi di sistema. - `channel_id_changed` può migrare le chiavi di configurazione del canale quando `configWrites` è abilitato. -- I metadati di topic/purpose del canale sono trattati come contesto non attendibile e possono essere iniettati nel contesto di instradamento. -- Il seeding del contesto del thread starter e della cronologia iniziale del thread viene filtrato dalle allowlist di mittenti configurate quando applicabile. -- Le block actions e le interazioni con modali emettono eventi di sistema strutturati `Slack interaction: ...` con campi payload ricchi: - - block actions: valori selezionati, etichette, valori picker e metadati `workflow_*` - - eventi modali `view_submission` e `view_closed` con metadati del canale instradati e input del modulo +- I metadati di topic/purpose del canale vengono trattati come contesto non attendibile e possono essere inseriti nel contesto di instradamento. +- Il messaggio iniziale del thread e il seeding iniziale del contesto della cronologia del thread vengono filtrati dalle allowlist dei mittenti configurate quando applicabile. +- Le azioni dei blocchi e le interazioni modali emettono eventi di sistema strutturati `Slack interaction: ...` con campi payload ricchi: + - azioni dei blocchi: valori selezionati, etichette, valori del selettore e metadati `workflow_*` + - eventi modali `view_submission` e `view_closed` con metadati del canale instradato e input del modulo -## Puntatori al riferimento di configurazione +## Riferimenti alla configurazione Riferimento principale: -- [Riferimento di configurazione - Slack](/it/gateway/configuration-reference#slack) +- [Riferimento alla configurazione - Slack](/it/gateway/configuration-reference#slack) Campi Slack ad alto segnale: - - modalità/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` + - modalità/autenticazione: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` - accesso DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` - - interruttore di compatibilità: `dangerouslyAllowNameMatching` (ultima risorsa; lascialo disattivato salvo necessità) - - accesso canale: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` + - interruttore di compatibilità: `dangerouslyAllowNameMatching` (break-glass; lascialo disattivato salvo necessità) + - accesso canali: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` - threading/cronologia: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - consegna: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport` - operazioni/funzionalità: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` @@ -705,7 +985,7 @@ Riferimento principale: - Verifica, in ordine: + Controlla, in ordine: - `groupPolicy` - allowlist dei canali (`channels.slack.channels`) @@ -723,11 +1003,11 @@ openclaw doctor - Verifica: + Controlla: - `channels.slack.dm.enabled` - `channels.slack.dmPolicy` (o legacy `channels.slack.dm.policy`) - - approvazioni di associazione / voci dell'allowlist + - approvazioni di associazione / voci allowlist ```bash openclaw pairing list slack @@ -735,10 +1015,10 @@ openclaw pairing list slack - - Convalida i token bot + app e l'abilitazione di Socket Mode nelle impostazioni dell'app Slack. + + Verifica i token bot + app e l'abilitazione di Socket Mode nelle impostazioni dell'app Slack. - Se `openclaw channels status --probe --json` mostra `botTokenStatus` o + Se `openclaw channels status --probe --json` mostra `botTokenStatus` oppure `appTokenStatus: "configured_unavailable"`, l'account Slack è configurato ma il runtime corrente non è riuscito a risolvere il valore supportato da SecretRef. @@ -746,23 +1026,23 @@ openclaw pairing list slack - Convalida: + Verifica: - signing secret - percorso webhook - - URL di richiesta Slack (Eventi + Interattività + Comandi Slash) + - URL delle richieste Slack (Eventi + Interattività + Slash Commands) - `webhookPath` univoco per ogni account HTTP - Se `signingSecretStatus: "configured_unavailable"` appare nelle - istantanee dell'account, l'account HTTP è configurato ma il runtime corrente non è riuscito - a risolvere il signing secret supportato da SecretRef. + Se `signingSecretStatus: "configured_unavailable"` compare nelle istantanee + dell'account, l'account HTTP è configurato ma il runtime corrente non è + riuscito a risolvere il signing secret supportato da SecretRef. Verifica se intendevi usare: - - modalità di comando nativo (`channels.slack.commands.native: true`) con i corrispondenti comandi slash registrati in Slack + - modalità comandi nativi (`channels.slack.commands.native: true`) con comandi slash corrispondenti registrati in Slack - oppure modalità comando slash singolo (`channels.slack.slashCommand.enabled: true`) Controlla anche `commands.useAccessGroups` e le allowlist di canali/utenti. @@ -775,7 +1055,7 @@ openclaw pairing list slack - [Associazione](/it/channels/pairing) - [Gruppi](/it/channels/groups) - [Sicurezza](/it/gateway/security) -- [Instradamento del canale](/it/channels/channel-routing) +- [Instradamento dei canali](/it/channels/channel-routing) - [Risoluzione dei problemi](/it/channels/troubleshooting) - [Configurazione](/it/gateway/configuration) - [Comandi slash](/it/tools/slash-commands) diff --git a/docs/it/concepts/active-memory.md b/docs/it/concepts/active-memory.md index 36bce94e3..7c3fc7279 100644 --- a/docs/it/concepts/active-memory.md +++ b/docs/it/concepts/active-memory.md @@ -3,34 +3,28 @@ read_when: - Vuoi capire a cosa serve la memoria attiva - Vuoi attivare la memoria attiva per un agente conversazionale - Vuoi regolare il comportamento della memoria attiva senza abilitarla ovunque -summary: Un sotto-agente di memoria bloccante gestito dal plugin che inserisce la memoria pertinente nelle sessioni di chat interattive +summary: Un sotto-agente di memoria di blocco di proprietà del plugin che inserisce memoria pertinente nelle sessioni di chat interattive title: Memoria attiva x-i18n: - generated_at: "2026-04-11T08:00:33Z" + generated_at: "2026-04-12T08:07:56Z" model: gpt-5.4 provider: openai - source_hash: e8b0e6539e09678e9e8def68795f8bcb992f98509423da3da3123eda88ec1dd5 + source_hash: 59456805c28daaab394ba2a7f87e1104a1334a5cf32dbb961d5d232d9c471d84 source_path: concepts/active-memory.md workflow: 15 --- # Memoria attiva -La memoria attiva è un sotto-agente di memoria bloccante opzionale gestito dal plugin che viene eseguito -prima della risposta principale per le sessioni conversazionali idonee. +La memoria attiva è un sotto-agente di memoria di blocco opzionale di proprietà del plugin che viene eseguito prima della risposta principale per le sessioni conversazionali idonee. -Esiste perché la maggior parte dei sistemi di memoria è capace ma reattiva. Si basa -sull'agente principale per decidere quando cercare nella memoria, oppure sull'utente che dica cose -come "ricorda questo" o "cerca nella memoria". A quel punto, il momento in cui la memoria -avrebbe reso la risposta naturale è già passato. +Esiste perché la maggior parte dei sistemi di memoria è capace ma reattiva. Si affida all'agente principale per decidere quando cercare nella memoria, oppure all'utente per dire cose come "ricorda questo" o "cerca nella memoria". A quel punto, il momento in cui la memoria avrebbe reso la risposta naturale è già passato. -La memoria attiva offre al sistema una possibilità limitata di far emergere la memoria pertinente -prima che venga generata la risposta principale. +La memoria attiva offre al sistema un'occasione limitata per far emergere memoria pertinente prima che venga generata la risposta principale. ## Incolla questo nel tuo agente -Incolla questo nel tuo agente se vuoi abilitare la memoria attiva con una -configurazione autonoma e sicura per impostazione predefinita: +Incolla questo nel tuo agente se vuoi abilitare la Memoria attiva con una configurazione autonoma e sicura come impostazione predefinita: ```json5 { @@ -42,7 +36,7 @@ configurazione autonoma e sicura per impostazione predefinita: enabled: true, agents: ["main"], allowedChatTypes: ["direct"], - modelFallbackPolicy: "default-remote", + modelFallback: "google/gemini-3-flash", queryMode: "recent", promptStyle: "balanced", timeoutMs: 15000, @@ -56,28 +50,26 @@ configurazione autonoma e sicura per impostazione predefinita: } ``` -Questo attiva il plugin per l'agente `main`, lo mantiene limitato per impostazione predefinita alle -sessioni in stile messaggio diretto, gli permette prima di ereditare il modello della sessione corrente e -consente comunque il fallback remoto integrato se non è disponibile alcun modello esplicito o ereditato. +Questo attiva il plugin per l'agente `main`, lo mantiene limitato per impostazione predefinita alle sessioni in stile messaggio diretto, gli consente di ereditare prima il modello della sessione corrente e usa il modello di fallback configurato solo se non è disponibile alcun modello esplicito o ereditato. -Dopo, riavvia il gateway: +Dopodiché, riavvia il gateway: ```bash openclaw gateway ``` -Per ispezionarlo dal vivo in una conversazione: +Per ispezionarlo in tempo reale in una conversazione: ```text /verbose on ``` -## Attivare la memoria attiva +## Attiva la memoria attiva La configurazione più sicura è: 1. abilitare il plugin -2. scegliere come target un agente conversazionale +2. scegliere come destinazione un agente conversazionale 3. mantenere il logging attivo solo durante la regolazione Inizia con questo in `openclaw.json`: @@ -91,7 +83,7 @@ Inizia con questo in `openclaw.json`: config: { agents: ["main"], allowedChatTypes: ["direct"], - modelFallbackPolicy: "default-remote", + modelFallback: "google/gemini-3-flash", queryMode: "recent", promptStyle: "balanced", timeoutMs: 15000, @@ -111,25 +103,23 @@ Poi riavvia il gateway: openclaw gateway ``` -Ecco cosa significa: +Cosa significa: - `plugins.entries.active-memory.enabled: true` attiva il plugin - `config.agents: ["main"]` abilita la memoria attiva solo per l'agente `main` -- `config.allowedChatTypes: ["direct"]` mantiene la memoria attiva solo per impostazione predefinita per le sessioni in stile messaggio diretto +- `config.allowedChatTypes: ["direct"]` mantiene la memoria attiva attiva per impostazione predefinita solo per le sessioni in stile messaggio diretto - se `config.model` non è impostato, la memoria attiva eredita prima il modello della sessione corrente -- `config.modelFallbackPolicy: "default-remote"` mantiene il fallback remoto integrato come impostazione predefinita quando non è disponibile alcun modello esplicito o ereditato +- `config.modelFallback` fornisce facoltativamente il tuo provider/modello di fallback per il richiamo - `config.promptStyle: "balanced"` usa lo stile di prompt predefinito per uso generale per la modalità `recent` -- la memoria attiva continua a essere eseguita solo sulle sessioni di chat interattive persistenti idonee +- la memoria attiva viene comunque eseguita solo su sessioni di chat interattive persistenti idonee -## Come visualizzarla +## Come vederla -La memoria attiva inserisce contesto di sistema nascosto per il modello. Non espone -tag grezzi `...` al client. +La memoria attiva inserisce un contesto di sistema nascosto per il modello. Non espone tag grezzi `...` al client. -## Attivazione/disattivazione per sessione +## Interruttore di sessione -Usa il comando del plugin quando vuoi mettere in pausa o riprendere la memoria attiva per la -sessione di chat corrente senza modificare la configurazione: +Usa il comando del plugin quando vuoi mettere in pausa o riprendere la memoria attiva per la sessione di chat corrente senza modificare la configurazione: ```text /active-memory status @@ -137,12 +127,9 @@ sessione di chat corrente senza modificare la configurazione: /active-memory on ``` -Questo vale per la sessione corrente. Non modifica -`plugins.entries.active-memory.enabled`, la selezione dell'agente o altre -configurazioni globali. +Questo è limitato alla sessione. Non modifica `plugins.entries.active-memory.enabled`, la selezione dell'agente o altre configurazioni globali. -Se vuoi che il comando scriva la configurazione e metta in pausa o riprenda la memoria attiva per -tutte le sessioni, usa la forma globale esplicita: +Se vuoi che il comando scriva la configurazione e metta in pausa o riprenda la memoria attiva per tutte le sessioni, usa il formato globale esplicito: ```text /active-memory status --global @@ -150,27 +137,22 @@ tutte le sessioni, usa la forma globale esplicita: /active-memory on --global ``` -La forma globale scrive `plugins.entries.active-memory.config.enabled`. Lascia -`plugins.entries.active-memory.enabled` attivo in modo che il comando resti disponibile per -riattivare la memoria attiva in seguito. +Il formato globale scrive `plugins.entries.active-memory.config.enabled`. Lascia `plugins.entries.active-memory.enabled` attivo in modo che il comando resti disponibile per riattivare la memoria attiva in seguito. -Se vuoi vedere cosa sta facendo la memoria attiva in una sessione dal vivo, attiva la modalità -verbose per quella sessione: +Se vuoi vedere cosa sta facendo la memoria attiva in una sessione in tempo reale, attiva la modalità dettagliata per quella sessione: ```text /verbose on ``` -Con verbose abilitato, OpenClaw può mostrare: +Con la modalità dettagliata abilitata, OpenClaw può mostrare: - una riga di stato della memoria attiva come `Active Memory: ok 842ms recent 34 chars` - un riepilogo di debug leggibile come `Active Memory Debug: Lemon pepper wings with blue cheese.` -Queste righe derivano dallo stesso passaggio di memoria attiva che alimenta il contesto di -sistema nascosto, ma sono formattate per gli esseri umani invece di esporre markup grezzo del prompt. +Queste righe derivano dallo stesso passaggio di memoria attiva che alimenta il contesto di sistema nascosto, ma sono formattate per gli esseri umani invece di esporre markup grezzo del prompt. -Per impostazione predefinita, la trascrizione del sotto-agente di memoria bloccante è temporanea e viene eliminata -dopo il completamento dell'esecuzione. +Per impostazione predefinita, la trascrizione del sotto-agente di memoria di blocco è temporanea e viene eliminata dopo il completamento dell'esecuzione. Esempio di flusso: @@ -179,7 +161,7 @@ Esempio di flusso: what wings should i order? ``` -Forma attesa della risposta visibile: +Forma di risposta visibile prevista: ```text ...normal assistant reply... @@ -192,32 +174,31 @@ Forma attesa della risposta visibile: La memoria attiva usa due controlli: -1. **Consenso esplicito tramite configurazione** - Il plugin deve essere abilitato e l'id dell'agente corrente deve comparire in +1. **Attivazione tramite configurazione** + Il plugin deve essere abilitato e l'ID dell'agente corrente deve comparire in `plugins.entries.active-memory.config.agents`. 2. **Idoneità rigorosa in fase di esecuzione** - Anche se abilitata e selezionata, la memoria attiva viene eseguita solo per le - sessioni di chat interattive persistenti idonee. + Anche quando è abilitata e selezionata, la memoria attiva viene eseguita solo per sessioni di chat interattive persistenti idonee. La regola effettiva è: ```text -plugin enabled +plugin abilitato + -agent id targeted +id agente selezionato + -allowed chat type +tipo di chat consentito + -eligible interactive persistent chat session +sessione di chat interattiva persistente idonea = -active memory runs +la memoria attiva viene eseguita ``` Se uno qualsiasi di questi controlli fallisce, la memoria attiva non viene eseguita. ## Tipi di sessione -`config.allowedChatTypes` controlla quali tipi di conversazioni possono eseguire la memoria attiva. +`config.allowedChatTypes` controlla quali tipi di conversazioni possono eseguire la Memoria attiva. L'impostazione predefinita è: @@ -225,8 +206,7 @@ L'impostazione predefinita è: allowedChatTypes: ["direct"] ``` -Questo significa che la memoria attiva viene eseguita per impostazione predefinita nelle sessioni in stile -messaggio diretto, ma non nelle sessioni di gruppo o canale a meno che tu non le abiliti esplicitamente. +Questo significa che la Memoria attiva viene eseguita per impostazione predefinita nelle sessioni in stile messaggio diretto, ma non nelle sessioni di gruppo o di canale a meno che non le abiliti esplicitamente. Esempi: @@ -244,15 +224,14 @@ allowedChatTypes: ["direct", "group", "channel"] ## Dove viene eseguita -La memoria attiva è una funzionalità di arricchimento conversazionale, non una -funzionalità di inferenza estesa a tutta la piattaforma. +La memoria attiva è una funzionalità di arricchimento conversazionale, non una funzionalità di inferenza valida per l'intera piattaforma. | Surface | La memoria attiva viene eseguita? | | ------------------------------------------------------------------- | ------------------------------------------------------ | -| Sessioni persistenti del Control UI / chat web | Sì, se il plugin è abilitato e l'agente è selezionato | +| Sessioni persistenti di Control UI / chat web | Sì, se il plugin è abilitato e l'agente è selezionato | | Altre sessioni di canale interattive sullo stesso percorso di chat persistente | Sì, se il plugin è abilitato e l'agente è selezionato | -| Esecuzioni headless una tantum | No | -| Esecuzioni heartbeat/background | No | +| Esecuzioni headless one-shot | No | +| Esecuzioni heartbeat/in background | No | | Percorsi interni generici `agent-command` | No | | Esecuzione di sotto-agenti/helper interni | No | @@ -268,51 +247,50 @@ Funziona particolarmente bene per: - preferenze stabili - abitudini ricorrenti -- contesto utente a lungo termine che dovrebbe emergere in modo naturale +- contesto utente a lungo termine che dovrebbe emergere naturalmente È poco adatta per: - automazione - worker interni -- attività API una tantum -- contesti in cui una personalizzazione nascosta sarebbe sorprendente +- attività API one-shot +- situazioni in cui una personalizzazione nascosta sarebbe sorprendente ## Come funziona -La struttura in fase di esecuzione è: +La struttura di runtime è: ```mermaid flowchart LR - U["User Message"] --> Q["Build Memory Query"] - Q --> R["Active Memory Blocking Memory Sub-Agent"] - R -->|NONE or empty| M["Main Reply"] - R -->|relevant summary| I["Append Hidden active_memory_plugin System Context"] - I --> M["Main Reply"] + U["Messaggio utente"] --> Q["Costruisci query di memoria"] + Q --> R["Sotto-agente di memoria di blocco della Memoria attiva"] + R -->|NONE o vuoto| M["Risposta principale"] + R -->|riepilogo pertinente| I["Aggiungi contesto di sistema nascosto active_memory_plugin"] + I --> M["Risposta principale"] ``` -Il sotto-agente di memoria bloccante può usare solo: +Il sotto-agente di memoria di blocco può usare solo: - `memory_search` - `memory_get` -Se la connessione è debole, dovrebbe restituire `NONE`. +Se la connessione è debole, deve restituire `NONE`. ## Modalità di query -`config.queryMode` controlla quanta parte della conversazione vede il sotto-agente di memoria bloccante. +`config.queryMode` controlla quanta parte della conversazione vede il sotto-agente di memoria di blocco. ## Stili di prompt -`config.promptStyle` controlla quanto il sotto-agente di memoria bloccante sia -propenso o rigoroso quando decide se restituire memoria. +`config.promptStyle` controlla quanto il sotto-agente di memoria di blocco sia propenso o rigoroso nel decidere se restituire memoria. Stili disponibili: - `balanced`: impostazione predefinita per uso generale per la modalità `recent` - `strict`: il meno propenso; ideale quando vuoi pochissima contaminazione dal contesto vicino -- `contextual`: il più favorevole alla continuità; ideale quando la cronologia della conversazione dovrebbe contare di più +- `contextual`: il più favorevole alla continuità; ideale quando la cronologia della conversazione deve contare di più - `recall-heavy`: più disposto a far emergere memoria su corrispondenze meno forti ma comunque plausibili -- `precision-heavy`: preferisce in modo aggressivo `NONE` a meno che la corrispondenza non sia ovvia +- `precision-heavy`: preferisce in modo aggressivo `NONE` a meno che la corrispondenza non sia evidente - `preference-only`: ottimizzato per preferiti, abitudini, routine, gusti e fatti personali ricorrenti Mappatura predefinita quando `config.promptStyle` non è impostato: @@ -323,7 +301,7 @@ recent -> balanced full -> contextual ``` -Se imposti esplicitamente `config.promptStyle`, questa sostituzione ha la precedenza. +Se imposti `config.promptStyle` esplicitamente, quell'override ha la precedenza. Esempio: @@ -333,83 +311,72 @@ promptStyle: "preference-only" ## Criterio di fallback del modello -Se `config.model` non è impostato, la memoria attiva prova a risolvere un modello in questo ordine: +Se `config.model` non è impostato, la Memoria attiva prova a risolvere un modello in questo ordine: ```text -explicit plugin model --> current session model --> agent primary model --> optional built-in remote fallback +modello esplicito del plugin +-> modello della sessione corrente +-> modello primario dell'agente +-> modello di fallback configurato facoltativo ``` -`config.modelFallbackPolicy` controlla l'ultimo passaggio. +`config.modelFallback` controlla il passaggio di fallback configurato. -Impostazione predefinita: +Fallback personalizzato facoltativo: ```json5 -modelFallbackPolicy: "default-remote" +modelFallback: "google/gemini-3-flash" ``` -Altra opzione: +Se non viene risolto alcun modello esplicito, ereditato o di fallback configurato, la Memoria attiva salta il richiamo per quel turno. -```json5 -modelFallbackPolicy: "resolved-only" -``` +`config.modelFallbackPolicy` viene mantenuto solo come campo di compatibilità deprecato per configurazioni più vecchie. Non modifica più il comportamento in fase di esecuzione. -Usa `resolved-only` se vuoi che la memoria attiva salti il richiamo invece di fare -fallback al valore remoto integrato predefinito quando non è disponibile alcun modello esplicito o -ereditato. - -## Meccanismi di uscita avanzati +## Escape hatch avanzati Queste opzioni intenzionalmente non fanno parte della configurazione consigliata. -`config.thinking` può sostituire il livello di thinking del sotto-agente di memoria bloccante: +`config.thinking` può sovrascrivere il livello di ragionamento del sotto-agente di memoria di blocco: ```json5 thinking: "medium" ``` -Impostazione predefinita: +Predefinito: ```json5 thinking: "off" ``` -Non abilitarlo per impostazione predefinita. La memoria attiva viene eseguita nel percorso della risposta, quindi il tempo di -thinking aggiuntivo aumenta direttamente la latenza visibile all'utente. +Non abilitarlo per impostazione predefinita. La Memoria attiva viene eseguita nel percorso della risposta, quindi un tempo di ragionamento aggiuntivo aumenta direttamente la latenza visibile all'utente. -`config.promptAppend` aggiunge istruzioni extra dell'operatore dopo il prompt predefinito della memoria attiva -e prima del contesto della conversazione: +`config.promptAppend` aggiunge istruzioni extra dell'operatore dopo il prompt predefinito della Memoria attiva e prima del contesto della conversazione: ```json5 promptAppend: "Prefer stable long-term preferences over one-off events." ``` -`config.promptOverride` sostituisce il prompt predefinito della memoria attiva. OpenClaw -continua comunque ad aggiungere il contesto della conversazione subito dopo: +`config.promptOverride` sostituisce il prompt predefinito della Memoria attiva. OpenClaw aggiunge comunque il contesto della conversazione subito dopo: ```json5 promptOverride: "You are a memory search agent. Return NONE or one compact user fact." ``` -La personalizzazione del prompt non è consigliata a meno che tu non stia deliberatamente testando un -contratto di richiamo diverso. Il prompt predefinito è ottimizzato per restituire `NONE` -oppure un contesto compatto basato su fatti dell'utente per il modello principale. +La personalizzazione del prompt non è consigliata a meno che tu non stia deliberatamente testando un diverso contratto di richiamo. Il prompt predefinito è regolato per restituire `NONE` oppure un contesto compatto di fatti dell'utente per il modello principale. ### `message` Viene inviato solo l'ultimo messaggio dell'utente. ```text -Only the latest user message +Solo l'ultimo messaggio dell'utente ``` Usa questa modalità quando: - vuoi il comportamento più rapido - vuoi il bias più forte verso il richiamo di preferenze stabili -- i turni successivi non richiedono contesto conversazionale +- i turni di follow-up non hanno bisogno del contesto conversazionale Timeout consigliato: @@ -417,22 +384,22 @@ Timeout consigliato: ### `recent` -Vengono inviati l'ultimo messaggio dell'utente più una piccola coda conversazionale recente. +Vengono inviati l'ultimo messaggio dell'utente più una piccola coda recente della conversazione. ```text -Recent conversation tail: +Coda recente della conversazione: user: ... assistant: ... user: ... -Latest user message: +Ultimo messaggio dell'utente: ... ``` Usa questa modalità quando: -- vuoi un miglior equilibrio tra velocità e ancoraggio conversazionale -- le domande di follow-up dipendono spesso dagli ultimi turni +- vuoi un migliore equilibrio tra velocità e radicamento conversazionale +- le domande di follow-up dipendono spesso dagli ultimi pochi turni Timeout consigliato: @@ -440,10 +407,10 @@ Timeout consigliato: ### `full` -L'intera conversazione viene inviata al sotto-agente di memoria bloccante. +L'intera conversazione viene inviata al sotto-agente di memoria di blocco. ```text -Full conversation context: +Contesto completo della conversazione: user: ... assistant: ... user: ... @@ -452,12 +419,12 @@ user: ... Usa questa modalità quando: -- la migliore qualità di richiamo conta più della latenza -- la conversazione contiene impostazioni importanti molto indietro nel thread +- la migliore qualità possibile del richiamo conta più della latenza +- la conversazione contiene un'impostazione importante molto indietro nel thread Timeout consigliato: -- aumentalo in modo sostanziale rispetto a `message` o `recent` +- aumentalo sostanzialmente rispetto a `message` o `recent` - inizia intorno a `15000` ms o più, a seconda della dimensione del thread In generale, il timeout dovrebbe aumentare con la dimensione del contesto: @@ -466,19 +433,17 @@ In generale, il timeout dovrebbe aumentare con la dimensione del contesto: message < recent < full ``` -## Persistenza delle trascrizioni +## Persistenza della trascrizione -Le esecuzioni del sotto-agente di memoria bloccante della memoria attiva creano una vera trascrizione `session.jsonl` -durante la chiamata al sotto-agente di memoria bloccante. +Le esecuzioni del sotto-agente di memoria di blocco della memoria attiva creano una vera trascrizione `session.jsonl` durante la chiamata del sotto-agente di memoria di blocco. -Per impostazione predefinita, quella trascrizione è temporanea: +Per impostazione predefinita, questa trascrizione è temporanea: - viene scritta in una directory temporanea -- viene usata solo per l'esecuzione del sotto-agente di memoria bloccante -- viene eliminata immediatamente al termine dell'esecuzione +- viene usata solo per l'esecuzione del sotto-agente di memoria di blocco +- viene eliminata immediatamente dopo la fine dell'esecuzione -Se vuoi mantenere su disco quelle trascrizioni del sotto-agente di memoria bloccante per debug o -ispezione, attiva esplicitamente la persistenza: +Se vuoi mantenere su disco quelle trascrizioni del sotto-agente di memoria di blocco per il debug o l'ispezione, attiva esplicitamente la persistenza: ```json5 { @@ -497,23 +462,21 @@ ispezione, attiva esplicitamente la persistenza: } ``` -Quando è abilitata, la memoria attiva archivia le trascrizioni in una directory separata sotto la -cartella delle sessioni dell'agente di destinazione, non nel percorso della trascrizione principale -della conversazione dell'utente. +Quando è abilitata, la memoria attiva archivia le trascrizioni in una directory separata sotto la cartella delle sessioni dell'agente di destinazione, non nel percorso principale della trascrizione della conversazione utente. -La struttura predefinita è concettualmente: +La struttura predefinita è, a livello concettuale: ```text agents//sessions/active-memory/.jsonl ``` -Puoi cambiare la sottodirectory relativa con `config.transcriptDir`. +Puoi modificare la sottodirectory relativa con `config.transcriptDir`. -Usa questa opzione con cautela: +Usa questa opzione con attenzione: -- le trascrizioni del sotto-agente di memoria bloccante possono accumularsi rapidamente nelle sessioni molto attive -- la modalità di query `full` può duplicare molto contesto conversazionale -- queste trascrizioni contengono contesto di prompt nascosto e memorie richiamate +- le trascrizioni del sotto-agente di memoria di blocco possono accumularsi rapidamente nelle sessioni attive +- la modalità di query `full` può duplicare molto contesto della conversazione +- queste trascrizioni contengono contesto nascosto del prompt e memorie richiamate ## Configurazione @@ -525,32 +488,32 @@ plugins.entries.active-memory I campi più importanti sono: -| Chiave | Tipo | Significato | -| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `enabled` | `boolean` | Abilita il plugin stesso | -| `config.agents` | `string[]` | ID agente che possono usare la memoria attiva | -| `config.model` | `string` | Riferimento facoltativo al modello del sotto-agente di memoria bloccante; se non impostato, la memoria attiva usa il modello della sessione corrente | -| `config.queryMode` | `"message" \| "recent" \| "full"` | Controlla quanta parte della conversazione vede il sotto-agente di memoria bloccante | -| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controlla quanto il sotto-agente di memoria bloccante sia propenso o rigoroso quando decide se restituire memoria | -| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Sostituzione avanzata del livello di thinking per il sotto-agente di memoria bloccante; impostazione predefinita `off` per maggiore velocità | -| `config.promptOverride` | `string` | Sostituzione avanzata completa del prompt; non consigliata per l'uso normale | -| `config.promptAppend` | `string` | Istruzioni avanzate aggiuntive accodate al prompt predefinito o sostituito | -| `config.timeoutMs` | `number` | Timeout rigido per il sotto-agente di memoria bloccante | -| `config.maxSummaryChars` | `number` | Numero massimo totale di caratteri consentiti nel riepilogo della memoria attiva | -| `config.logging` | `boolean` | Emette log della memoria attiva durante la regolazione | -| `config.persistTranscripts` | `boolean` | Mantiene su disco le trascrizioni del sotto-agente di memoria bloccante invece di eliminare i file temporanei | -| `config.transcriptDir` | `string` | Directory relativa delle trascrizioni del sotto-agente di memoria bloccante sotto la cartella delle sessioni dell'agente | +| Key | Type | Significato | +| --------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `enabled` | `boolean` | Abilita il plugin stesso | +| `config.agents` | `string[]` | ID degli agenti che possono usare la memoria attiva | +| `config.model` | `string` | Riferimento opzionale del modello del sotto-agente di memoria di blocco; se non impostato, la memoria attiva usa il modello della sessione corrente | +| `config.queryMode` | `"message" \| "recent" \| "full"` | Controlla quanta parte della conversazione vede il sotto-agente di memoria di blocco | +| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controlla quanto il sotto-agente di memoria di blocco sia propenso o rigoroso nel decidere se restituire memoria | +| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Override avanzato del livello di ragionamento per il sotto-agente di memoria di blocco; predefinito `off` per velocità | +| `config.promptOverride` | `string` | Sostituzione avanzata dell'intero prompt; non consigliata per l'uso normale | +| `config.promptAppend` | `string` | Istruzioni extra avanzate aggiunte al prompt predefinito o sostituito | +| `config.timeoutMs` | `number` | Timeout rigido per il sotto-agente di memoria di blocco | +| `config.maxSummaryChars` | `number` | Numero massimo totale di caratteri consentiti nel riepilogo di active-memory | +| `config.logging` | `boolean` | Emette log della memoria attiva durante la regolazione | +| `config.persistTranscripts` | `boolean` | Mantiene su disco le trascrizioni del sotto-agente di memoria di blocco invece di eliminare i file temporanei | +| `config.transcriptDir` | `string` | Directory relativa delle trascrizioni del sotto-agente di memoria di blocco sotto la cartella delle sessioni dell'agente | Campi utili per la regolazione: -| Chiave | Tipo | Significato | -| ----------------------------- | -------- | --------------------------------------------------------------- | -| `config.maxSummaryChars` | `number` | Numero massimo totale di caratteri consentiti nel riepilogo della memoria attiva | +| Key | Type | Significato | +| ----------------------------- | -------- | ------------------------------------------------------------- | +| `config.maxSummaryChars` | `number` | Numero massimo totale di caratteri consentiti nel riepilogo di active-memory | | `config.recentUserTurns` | `number` | Turni utente precedenti da includere quando `queryMode` è `recent` | -| `config.recentAssistantTurns` | `number` | Turni assistente precedenti da includere quando `queryMode` è `recent` | -| `config.recentUserChars` | `number` | Numero massimo di caratteri per ogni turno utente recente | -| `config.recentAssistantChars` | `number` | Numero massimo di caratteri per ogni turno assistente recente | -| `config.cacheTtlMs` | `number` | Riutilizzo della cache per query identiche ripetute | +| `config.recentAssistantTurns` | `number` | Turni assistant precedenti da includere quando `queryMode` è `recent` | +| `config.recentUserChars` | `number` | Numero massimo di caratteri per ogni turno utente recente | +| `config.recentAssistantChars` | `number` | Numero massimo di caratteri per ogni turno assistant recente | +| `config.cacheTtlMs` | `number` | Riutilizzo della cache per query identiche ripetute | ## Configurazione consigliata @@ -576,15 +539,14 @@ Inizia con `recent`. } ``` -Se vuoi ispezionare il comportamento dal vivo durante la regolazione, usa `/verbose on` nella -sessione invece di cercare un comando di debug separato per la memoria attiva. +Se vuoi ispezionare il comportamento in tempo reale durante la regolazione, usa `/verbose on` nella sessione invece di cercare un comando di debug separato per active-memory. Poi passa a: -- `message` se vuoi una latenza inferiore -- `full` se decidi che il contesto aggiuntivo vale un sotto-agente di memoria bloccante più lento +- `message` se vuoi una latenza più bassa +- `full` se decidi che il contesto aggiuntivo vale un sotto-agente di memoria di blocco più lento -## Debug +## Debugging Se la memoria attiva non compare dove te l'aspetti: @@ -592,7 +554,7 @@ Se la memoria attiva non compare dove te l'aspetti: 2. Conferma che l'ID dell'agente corrente sia elencato in `config.agents`. 3. Conferma di stare testando tramite una sessione di chat interattiva persistente. 4. Attiva `config.logging: true` e osserva i log del gateway. -5. Verifica che la ricerca nella memoria stessa funzioni con `openclaw memory status --deep`. +5. Verifica che la ricerca nella memoria funzioni con `openclaw memory status --deep`. Se i risultati della memoria sono rumorosi, restringi: @@ -609,4 +571,4 @@ Se la memoria attiva è troppo lenta: - [Ricerca nella memoria](/it/concepts/memory-search) - [Riferimento della configurazione della memoria](/it/reference/memory-config) -- [Configurazione del Plugin SDK](/it/plugins/sdk-setup) +- [Configurazione di Plugin SDK](/it/plugins/sdk-setup) diff --git a/docs/it/concepts/system-prompt.md b/docs/it/concepts/system-prompt.md index e7bcb78fe..09a631679 100644 --- a/docs/it/concepts/system-prompt.md +++ b/docs/it/concepts/system-prompt.md @@ -1,101 +1,96 @@ --- read_when: - - Modifica del testo del system prompt, dell'elenco degli strumenti o delle sezioni ora/heartbeat - - Modifica del bootstrap del workspace o del comportamento di iniezione delle Skills -summary: Cosa contiene il system prompt di OpenClaw e come viene assemblato -title: System Prompt + - Modifica del testo del prompt di sistema, dell'elenco degli strumenti o delle sezioni relative a ora/heartbeat + - Modifica del bootstrap dell'area di lavoro o del comportamento di iniezione delle Skills +summary: Che cosa contiene il prompt di sistema di OpenClaw e come viene assemblato +title: Prompt di sistema x-i18n: - generated_at: "2026-04-08T02:14:25Z" + generated_at: "2026-04-12T08:08:02Z" model: gpt-5.4 provider: openai - source_hash: e55fc886bc8ec47584d07c9e60dfacd964dc69c7db976ea373877dc4fe09a79a + source_hash: 057f01aac51f7737b5223f61f5d55e552d9011232aebb130426e269d8f6c257f source_path: concepts/system-prompt.md workflow: 15 --- -# System Prompt +# Prompt di sistema -OpenClaw crea un system prompt personalizzato per ogni esecuzione dell'agente. Il prompt è **di proprietà di OpenClaw** e non usa il prompt predefinito di pi-coding-agent. +OpenClaw crea un prompt di sistema personalizzato per ogni esecuzione dell'agente. Il prompt è **di proprietà di OpenClaw** e non usa il prompt predefinito di pi-coding-agent. Il prompt viene assemblato da OpenClaw e iniettato in ogni esecuzione dell'agente. -I plugin provider possono contribuire con indicazioni per il prompt consapevoli della cache senza sostituire l'intero prompt di proprietà di OpenClaw. Il runtime del provider può: +I plugin provider possono contribuire con indicazioni sul prompt compatibili con la cache senza sostituire l'intero prompt di proprietà di OpenClaw. Il runtime del provider può: -- sostituire un piccolo insieme di sezioni core denominate (`interaction_style`, +- sostituire un piccolo insieme di sezioni core nominate (`interaction_style`, `tool_call_style`, `execution_bias`) - iniettare un **prefisso stabile** sopra il confine della cache del prompt - iniettare un **suffisso dinamico** sotto il confine della cache del prompt -Usa i contributi di proprietà del provider per la regolazione specifica della famiglia di modelli. Mantieni la mutazione legacy del prompt `before_prompt_build` per compatibilità o per modifiche del prompt realmente globali, non per il normale comportamento del provider. +Usa i contributi di proprietà del provider per la messa a punto specifica della famiglia di modelli. Mantieni la mutazione legacy del prompt `before_prompt_build` per compatibilità o per modifiche del prompt veramente globali, non per il normale comportamento del provider. ## Struttura Il prompt è intenzionalmente compatto e usa sezioni fisse: -- **Tooling**: promemoria della fonte di verità degli strumenti strutturati più indicazioni di runtime sull'uso degli strumenti. -- **Safety**: breve promemoria dei guardrail per evitare comportamenti di ricerca del potere o aggiramento della supervisione. +- **Strumenti**: promemoria della fonte di verità degli strumenti strutturati più indicazioni runtime sull'uso degli strumenti. +- **Sicurezza**: breve promemoria di guardrail per evitare comportamenti orientati alla ricerca di potere o all'elusione della supervisione. - **Skills** (quando disponibili): indica al modello come caricare su richiesta le istruzioni delle skill. -- **OpenClaw Self-Update**: come ispezionare in sicurezza la configurazione con - `config.schema.lookup`, modificare la configurazione con `config.patch`, sostituire l'intera - configurazione con `config.apply` ed eseguire `update.run` solo su esplicita - richiesta dell'utente. Anche lo strumento `gateway`, riservato al proprietario, rifiuta di riscrivere +- **Auto-aggiornamento OpenClaw**: come ispezionare in sicurezza la configurazione con + `config.schema.lookup`, correggere la configurazione con `config.patch`, sostituire l'intera + configurazione con `config.apply` ed eseguire `update.run` solo su richiesta esplicita + dell'utente. Anche lo strumento `gateway`, riservato al proprietario, si rifiuta di riscrivere `tools.exec.ask` / `tools.exec.security`, incluse le alias legacy `tools.bash.*` che vengono normalizzate in quei percorsi exec protetti. -- **Workspace**: directory di lavoro (`agents.defaults.workspace`). -- **Documentation**: percorso locale della documentazione di OpenClaw (repo o pacchetto npm) e quando leggerla. -- **Workspace Files (injected)**: indica che i file bootstrap sono inclusi sotto. -- **Sandbox** (quando abilitato): indica il runtime sandboxed, i percorsi della sandbox e se è disponibile l'exec con privilegi elevati. -- **Current Date & Time**: ora locale dell'utente, fuso orario e formato dell'ora. -- **Reply Tags**: sintassi facoltativa dei tag di risposta per i provider supportati. -- **Heartbeats**: prompt heartbeat e comportamento di ack, quando gli heartbeat sono abilitati per l'agente predefinito. -- **Runtime**: host, OS, node, root del repo (quando rilevata), livello di thinking (una riga). -- **Reasoning**: livello di visibilità corrente + suggerimento per il toggle /reasoning. +- **Area di lavoro**: directory di lavoro (`agents.defaults.workspace`). +- **Documentazione**: percorso locale alla documentazione di OpenClaw (repo o pacchetto npm) e quando leggerla. +- **File dell'area di lavoro (iniettati)**: indica che i file bootstrap sono inclusi qui sotto. +- **Sandbox** (quando abilitata): indica runtime in sandbox, percorsi della sandbox e se è disponibile l'esecuzione con privilegi elevati. +- **Data e ora correnti**: ora locale dell'utente, fuso orario e formato orario. +- **Tag di risposta**: sintassi facoltativa dei tag di risposta per i provider supportati. +- **Heartbeat**: prompt heartbeat e comportamento di ack, quando gli heartbeat sono abilitati per l'agente predefinito. +- **Runtime**: host, OS, node, radice del repo (quando rilevata), livello di ragionamento (una riga). +- **Ragionamento**: livello di visibilità corrente + suggerimento sul toggle /reasoning. -La sezione Tooling include anche indicazioni di runtime per lavori di lunga durata: +La sezione Strumenti include anche indicazioni runtime per lavori di lunga durata: -- usare cron per follow-up futuri (`check back later`, promemoria, lavoro ricorrente) - invece di cicli sleep di `exec`, trucchi di ritardo `yieldMs` o polling ripetuto di `process` -- usare `exec` / `process` solo per comandi che iniziano subito e continuano a essere eseguiti +- usa cron per follow-up futuri (`check back later`, promemoria, lavori ricorrenti) + invece di loop di sleep con `exec`, trucchi di ritardo con `yieldMs` o polling ripetuto di `process` +- usa `exec` / `process` solo per comandi che iniziano ora e continuano a essere eseguiti in background -- quando il risveglio automatico al completamento è abilitato, avviare il comando una sola volta e fare affidamento - sul percorso di risveglio push-based quando emette output o fallisce -- usare `process` per log, stato, input o intervento quando è necessario +- quando è abilitato il risveglio automatico al completamento, avvia il comando una sola volta e fai affidamento sul + percorso di risveglio push-based quando emette output o fallisce +- usa `process` per log, stato, input o intervento quando devi ispezionare un comando in esecuzione -- se l'attività è più grande, preferire `sessions_spawn`; il completamento del sotto-agente è +- se l'attività è più grande, preferisci `sessions_spawn`; il completamento del sotto-agente è push-based e viene annunciato automaticamente al richiedente -- non fare polling di `subagents list` / `sessions_list` in un ciclo solo per attendere +- non fare polling di `subagents list` / `sessions_list` in un loop solo per attendere il completamento -Quando lo strumento sperimentale `update_plan` è abilitato, Tooling indica anche al -modello di usarlo solo per lavori multi-step non banali, mantenere esattamente un passaggio +Quando è abilitato lo strumento sperimentale `update_plan`, Strumenti indica inoltre al +modello di usarlo solo per lavori non banali a più passaggi, mantenere esattamente un passaggio `in_progress` ed evitare di ripetere l'intero piano dopo ogni aggiornamento. -I guardrail di sicurezza nel system prompt sono indicativi. Guidano il comportamento del modello ma non applicano policy. Usa tool policy, approvazioni exec, sandboxing e allowlist dei canali per un'applicazione rigorosa; gli operatori possono disabilitarli intenzionalmente. +I guardrail di sicurezza nel prompt di sistema sono indicativi. Guidano il comportamento del modello ma non applicano policy. Usa policy degli strumenti, approvazioni exec, sandboxing e allowlist dei canali per l'applicazione rigorosa; per design, gli operatori possono disabilitarli. -Sui canali con card/pulsanti di approvazione nativi, il prompt di runtime ora indica all' -agente di fare prima affidamento su quell'interfaccia di approvazione nativa. Dovrebbe includere un comando manuale -`/approve` solo quando il risultato dello strumento indica che le approvazioni in chat non sono disponibili o che -l'approvazione manuale è l'unico percorso. +Sui canali con schede/pulsanti di approvazione nativi, il prompt runtime ora dice all'agente di fare prima affidamento su quell'interfaccia di approvazione nativa. Dovrebbe includere un comando manuale `/approve` solo quando il risultato dello strumento dice che le approvazioni in chat non sono disponibili o che l'approvazione manuale è l'unico percorso. ## Modalità del prompt -OpenClaw può generare system prompt più piccoli per i sotto-agenti. Il runtime imposta una +OpenClaw può generare prompt di sistema più piccoli per i sotto-agenti. Il runtime imposta un `promptMode` per ogni esecuzione (non è una configurazione visibile all'utente): -- `full` (predefinita): include tutte le sezioni sopra. -- `minimal`: usata per i sotto-agenti; omette **Skills**, **Memory Recall**, **OpenClaw - Self-Update**, **Model Aliases**, **User Identity**, **Reply Tags**, - **Messaging**, **Silent Replies** e **Heartbeats**. Tooling, **Safety**, - Workspace, Sandbox, Current Date & Time (quando noto), Runtime e il contesto +- `full` (predefinito): include tutte le sezioni sopra. +- `minimal`: usato per i sotto-agenti; omette **Skills**, **Richiamo della memoria**, **Auto-aggiornamento OpenClaw**, **Alias dei modelli**, **Identità utente**, **Tag di risposta**, + **Messaggistica**, **Risposte silenziose** e **Heartbeat**. Strumenti, **Sicurezza**, + Area di lavoro, Sandbox, Data e ora correnti (quando note), Runtime e contesto iniettato restano disponibili. -- `none`: restituisce solo la riga di identità di base. +- `none`: restituisce solo la riga dell'identità di base. -Quando `promptMode=minimal`, i prompt extra iniettati sono etichettati come **Subagent -Context** invece che **Group Chat Context**. +Quando `promptMode=minimal`, i prompt extra iniettati sono etichettati come **Contesto del sotto-agente** invece di **Contesto della chat di gruppo**. -## Iniezione del bootstrap del workspace +## Iniezione del bootstrap dell'area di lavoro -I file bootstrap vengono tagliati e aggiunti sotto **Project Context** così il modello vede il contesto di identità e profilo senza richiedere letture esplicite: +I file bootstrap vengono tagliati e aggiunti sotto **Contesto del progetto** in modo che il modello veda il contesto di identità e profilo senza bisogno di letture esplicite: - `AGENTS.md` - `SOUL.md` @@ -103,25 +98,27 @@ I file bootstrap vengono tagliati e aggiunti sotto **Project Context** così il - `IDENTITY.md` - `USER.md` - `HEARTBEAT.md` -- `BOOTSTRAP.md` (solo nei workspace appena creati) +- `BOOTSTRAP.md` (solo nelle aree di lavoro completamente nuove) - `MEMORY.md` quando presente, altrimenti `memory.md` come fallback in minuscolo Tutti questi file vengono **iniettati nella finestra di contesto** a ogni turno, a meno che -non si applichi un gate specifico del file. `HEARTBEAT.md` viene omesso nelle esecuzioni normali quando -gli heartbeat sono disabilitati per l'agente predefinito oppure -`agents.defaults.heartbeat.includeSystemPromptSection` è false. Mantieni i file -iniettati concisi, soprattutto `MEMORY.md`, che può crescere nel tempo e portare a +non si applichi un gate specifico per file. `HEARTBEAT.md` viene omesso nelle esecuzioni normali quando +gli heartbeat sono disabilitati per l'agente predefinito o +`agents.defaults.heartbeat.includeSystemPromptSection` è false. Mantieni concisi i file +iniettati, soprattutto `MEMORY.md`, che può crescere nel tempo e portare a un uso del contesto inaspettatamente elevato e a compattazioni più frequenti. -> **Nota:** i file giornalieri `memory/*.md` **non** vengono iniettati automaticamente. Vengono -> accessibili su richiesta tramite gli strumenti `memory_search` e `memory_get`, quindi non -> contano nella finestra di contesto a meno che il modello non li legga esplicitamente. +> **Nota:** i file giornalieri `memory/*.md` **non** fanno parte del normale +> Contesto del progetto bootstrap. Nei turni ordinari vi si accede su richiesta tramite gli +> strumenti `memory_search` e `memory_get`, quindi non contano nella +> finestra di contesto a meno che il modello non li legga esplicitamente. I turni `/new` e `/reset` senza altri contenuti sono l'eccezione: il runtime può anteporre la memoria giornaliera recente +> come blocco di contesto iniziale one-shot per quel primo turno. -I file di grandi dimensioni vengono troncati con un marcatore. La dimensione massima per file è controllata da +I file grandi vengono troncati con un marcatore. La dimensione massima per file è controllata da `agents.defaults.bootstrapMaxChars` (predefinito: 20000). Il contenuto bootstrap totale iniettato -tra i vari file è limitato da `agents.defaults.bootstrapTotalMaxChars` +attraverso i file è limitato da `agents.defaults.bootstrapTotalMaxChars` (predefinito: 150000). I file mancanti iniettano un breve marcatore di file mancante. Quando si verifica il troncamento, -OpenClaw può iniettare un blocco di avviso in Project Context; controllalo con +OpenClaw può iniettare un blocco di avviso in Contesto del progetto; controllalo con `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; predefinito: `once`). @@ -131,38 +128,38 @@ vengono filtrati per mantenere piccolo il contesto del sotto-agente). Gli hook interni possono intercettare questo passaggio tramite `agent:bootstrap` per modificare o sostituire i file bootstrap iniettati (per esempio sostituendo `SOUL.md` con una persona alternativa). -Se vuoi rendere l'agente meno generico, inizia con -[SOUL.md Personality Guide](/it/concepts/soul). +Se vuoi far sembrare l'agente meno generico, inizia da +[Guida alla personalità di SOUL.md](/it/concepts/soul). -Per ispezionare quanto contribuisce ogni file iniettato (grezzo vs iniettato, troncamento, oltre all'overhead dello schema degli strumenti), usa `/context list` o `/context detail`. Vedi [Context](/it/concepts/context). +Per ispezionare quanto contribuisce ogni file iniettato (raw vs iniettato, troncamento, più overhead dello schema degli strumenti), usa `/context list` o `/context detail`. Vedi [Contesto](/it/concepts/context). ## Gestione del tempo -Il system prompt include una sezione dedicata **Current Date & Time** quando il +Il prompt di sistema include una sezione dedicata **Data e ora correnti** quando il fuso orario dell'utente è noto. Per mantenere stabile la cache del prompt, ora include solo il **fuso orario** (nessun orologio dinamico o formato dell'ora). -Usa `session_status` quando l'agente ha bisogno dell'ora corrente; la card di stato -include una riga con timestamp. Lo stesso strumento può facoltativamente impostare un override -del modello per sessione (`model=default` lo cancella). +Usa `session_status` quando l'agente ha bisogno dell'ora corrente; la scheda di stato +include una riga con il timestamp. Lo stesso strumento può facoltativamente impostare un override del modello per sessione +(`model=default` lo cancella). Configura con: - `agents.defaults.userTimezone` - `agents.defaults.timeFormat` (`auto` | `12` | `24`) -Vedi [Date & Time](/it/date-time) per i dettagli completi del comportamento. +Vedi [Data e ora](/it/date-time) per i dettagli completi del comportamento. ## Skills -Quando esistono skill idonee, OpenClaw inietta un elenco compatto delle skill disponibili +Quando esistono skill idonee, OpenClaw inietta un compatto **elenco delle skill disponibili** (`formatSkillsForPrompt`) che include il **percorso del file** per ogni skill. Il -prompt indica al modello di usare `read` per caricare lo SKILL.md nella posizione -elencata (workspace, gestita o inclusa). Se non ci sono skill idonee, la +prompt istruisce il modello a usare `read` per caricare lo SKILL.md nella posizione +elencata (area di lavoro, gestita o inclusa). Se nessuna skill è idonea, la sezione Skills viene omessa. -L'idoneità include gate dei metadati della skill, controlli dell'ambiente/configurazione di runtime -e l'allowlist effettiva delle skill dell'agente quando `agents.defaults.skills` o +L'idoneità include gate dei metadati della skill, controlli dell'ambiente/configurazione runtime +e la allowlist effettiva delle skill dell'agente quando `agents.defaults.skills` o `agents.list[].skills` è configurato. ``` @@ -179,9 +176,9 @@ Questo mantiene piccolo il prompt di base pur consentendo un uso mirato delle sk ## Documentazione -Quando disponibile, il system prompt include una sezione **Documentation** che indica la -directory locale della documentazione di OpenClaw (o `docs/` nel workspace del repo oppure la documentazione del -pacchetto npm incluso) e menziona anche il mirror pubblico, il repo sorgente, la community Discord e -ClawHub ([https://clawhub.ai](https://clawhub.ai)) per la scoperta delle skill. Il prompt indica al modello di consultare prima la documentazione locale -per il comportamento, i comandi, la configurazione o l'architettura di OpenClaw, e di eseguire +Quando disponibile, il prompt di sistema include una sezione **Documentazione** che punta alla +directory locale della documentazione di OpenClaw (o `docs/` nell'area di lavoro del repo o la documentazione inclusa del +pacchetto npm) e indica anche il mirror pubblico, il repo sorgente, il Discord della community e +ClawHub ([https://clawhub.ai](https://clawhub.ai)) per la scoperta delle skill. Il prompt istruisce il modello a consultare prima la documentazione locale +per il comportamento, i comandi, la configurazione o l'architettura di OpenClaw e a eseguire `openclaw status` direttamente quando possibile (chiedendo all'utente solo quando non ha accesso). diff --git a/docs/it/plugins/architecture.md b/docs/it/plugins/architecture.md index 6841acff8..f9229f848 100644 --- a/docs/it/plugins/architecture.md +++ b/docs/it/plugins/architecture.md @@ -1,17 +1,17 @@ --- read_when: - - Creazione o debug dei plugin nativi di OpenClaw - - Comprendere il modello delle capacità dei plugin o i confini di proprietà + - Creazione o debug dei plugin nativi OpenClaw + - Comprendere il modello di capacità dei plugin o i confini di proprietà - Lavorare sulla pipeline di caricamento dei plugin o sul registro - - Implementare gli hook di runtime del provider o i plugin di canale + - Implementare hook di runtime del provider o plugin di canale sidebarTitle: Internals -summary: 'Interni dei plugin: modello delle capacità, proprietà, contratti, pipeline di caricamento e helper di runtime' +summary: 'Interni dei plugin: modello di capacità, proprietà, contratti, pipeline di caricamento e helper di runtime' title: Interni dei plugin x-i18n: - generated_at: "2026-04-11T15:16:04Z" + generated_at: "2026-04-12T08:07:59Z" model: gpt-5.4 provider: openai - source_hash: 7cac67984d0d729c0905bcf5c18372fb0d9b02bbd3a531580b7e2ef483ef40a6 + source_hash: 6165a9da8b40de3bb7334fcb16023da5515deb83c4897ca1df1726f4a97db9e0 source_path: plugins/architecture.md workflow: 15 --- @@ -19,12 +19,12 @@ x-i18n: # Interni dei plugin - Questa è la **riferimento architetturale approfondito**. Per guide pratiche, vedi: - - [Installare e usare i plugin](/it/tools/plugin) — guida per l'utente - - [Per iniziare](/it/plugins/building-plugins) — primo tutorial sui plugin + Questo è il **riferimento di architettura approfondito**. Per guide pratiche, vedi: + - [Installa e usa i plugin](/it/tools/plugin) — guida per l'utente + - [Guida introduttiva](/it/plugins/building-plugins) — primo tutorial sui plugin - [Plugin di canale](/it/plugins/sdk-channel-plugins) — crea un canale di messaggistica - [Plugin provider](/it/plugins/sdk-provider-plugins) — crea un provider di modelli - - [Panoramica dell'SDK](/it/plugins/sdk-overview) — mappa di importazione e API di registrazione + - [Panoramica dell'SDK](/it/plugins/sdk-overview) — mappa degli import e API di registrazione Questa pagina copre l'architettura interna del sistema di plugin di OpenClaw. @@ -32,72 +32,72 @@ Questa pagina copre l'architettura interna del sistema di plugin di OpenClaw. ## Modello pubblico delle capacità Le capacità sono il modello pubblico dei **plugin nativi** all'interno di OpenClaw. Ogni -plugin nativo di OpenClaw si registra rispetto a uno o più tipi di capacità: +plugin nativo OpenClaw si registra in uno o più tipi di capacità: -| Capacità | Metodo di registrazione | Plugin di esempio | -| --------------------- | ------------------------------------------------ | ------------------------------------ | -| Inferenza di testo | `api.registerProvider(...)` | `openai`, `anthropic` | -| Backend di inferenza CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Voce | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Trascrizione in tempo reale | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Voce in tempo reale | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Comprensione dei media | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Generazione di immagini | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Generazione musicale | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Generazione video | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Recupero web | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Ricerca web | `api.registerWebSearchProvider(...)` | `google` | -| Canale / messaggistica | `api.registerChannel(...)` | `msteams`, `matrix` | +| Capacità | Metodo di registrazione | Plugin di esempio | +| ---------------------- | ------------------------------------------------ | ------------------------------------ | +| Inferenza testuale | `api.registerProvider(...)` | `openai`, `anthropic` | +| Backend di inferenza CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Voce | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Trascrizione in tempo reale | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Voce in tempo reale | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Comprensione dei media | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Generazione di immagini | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Generazione musicale | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Generazione video | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Recupero web | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Ricerca web | `api.registerWebSearchProvider(...)` | `google` | +| Canale / messaggistica | `api.registerChannel(...)` | `msteams`, `matrix` | Un plugin che registra zero capacità ma fornisce hook, strumenti o -servizi è un plugin **legacy solo hook**. Questo schema è ancora pienamente supportato. +servizi è un plugin **legacy solo hook**. Questo pattern è ancora pienamente supportato. ### Posizione sulla compatibilità esterna -Il modello delle capacità è integrato nel core e viene usato oggi dai plugin -nativi/inclusi, ma la compatibilità dei plugin esterni richiede ancora un criterio -più rigoroso di "è esportato, quindi è congelato". +Il modello delle capacità è integrato nel core ed è usato oggi dai plugin +bundled/nativi, ma la compatibilità dei plugin esterni richiede ancora un criterio +più rigoroso di “è esportato, quindi è congelato”. -Linee guida attuali: +Indicazioni attuali: -- **plugin esterni esistenti:** mantieni funzionanti le integrazioni basate su hook; trattale - come baseline di compatibilità -- **nuovi plugin nativi/inclusi:** preferisci la registrazione esplicita delle capacità invece di - accessi specifici al vendor o nuovi design solo hook -- **plugin esterni che adottano la registrazione delle capacità:** consentito, ma tratta le - superfici helper specifiche per capacità come in evoluzione, a meno che la documentazione non - contrassegni esplicitamente un contratto come stabile +- **plugin esterni esistenti:** mantenere funzionanti le integrazioni basate su hook; trattare + questo come riferimento di compatibilità +- **nuovi plugin bundled/nativi:** preferire la registrazione esplicita delle capacità invece di + accessi specifici del vendor o nuovi design solo hook +- **plugin esterni che adottano la registrazione delle capacità:** consentito, ma trattare le + superfici helper specifiche per capacità come in evoluzione, a meno che la documentazione non indichi esplicitamente + che un contratto è stabile Regola pratica: - le API di registrazione delle capacità sono la direzione prevista - gli hook legacy restano il percorso più sicuro per evitare rotture nei plugin esterni durante la transizione -- i sottopercorsi helper esportati non sono tutti uguali; preferisci il contratto ristretto - documentato, non esportazioni helper incidentali +- i sottopercorsi helper esportati non sono tutti equivalenti; preferisci il + contratto ristretto documentato, non esportazioni helper incidentali ### Forme dei plugin -OpenClaw classifica ogni plugin caricato in una forma in base al suo effettivo +OpenClaw classifica ogni plugin caricato in una forma in base al suo reale comportamento di registrazione (non solo ai metadati statici): - **plain-capability** -- registra esattamente un tipo di capacità (per esempio un plugin solo provider come `mistral`) - **hybrid-capability** -- registra più tipi di capacità (per esempio - `openai` gestisce inferenza di testo, voce, comprensione dei media e generazione - di immagini) -- **hook-only** -- registra solo hook (tipizzati o personalizzati), senza - capacità, strumenti, comandi o servizi + `openai` possiede inferenza testuale, voce, comprensione dei media e + generazione di immagini) +- **hook-only** -- registra solo hook (tipizzati o personalizzati), nessuna + capacità, strumento, comando o servizio - **non-capability** -- registra strumenti, comandi, servizi o route ma nessuna capacità -Usa `openclaw plugins inspect ` per vedere la forma di un plugin e il dettaglio -delle capacità. Vedi [Riferimento CLI](/cli/plugins#inspect) per i dettagli. +Usa `openclaw plugins inspect ` per vedere la forma di un plugin e la +suddivisione delle capacità. Vedi [Riferimento CLI](/cli/plugins#inspect) per i dettagli. ### Hook legacy L'hook `before_agent_start` resta supportato come percorso di compatibilità per -i plugin solo hook. I plugin legacy del mondo reale dipendono ancora da esso. +i plugin solo hook. Plugin legacy reali continuano a dipenderne. Direzione: @@ -105,7 +105,7 @@ Direzione: - documentarlo come legacy - preferire `before_model_resolve` per il lavoro di override di modello/provider - preferire `before_prompt_build` per il lavoro di modifica del prompt -- rimuoverlo solo dopo che l'uso reale sarà diminuito e la copertura dei fixture dimostrerà la sicurezza della migrazione +- rimuoverlo solo dopo che l'uso reale sarà diminuito e la copertura dei fixture avrà dimostrato la sicurezza della migrazione ### Segnali di compatibilità @@ -115,51 +115,51 @@ una di queste etichette: | Segnale | Significato | | ------------------------- | ------------------------------------------------------------ | | **config valid** | La configurazione viene analizzata correttamente e i plugin vengono risolti | -| **compatibility advisory** | Il plugin usa uno schema supportato ma meno recente (ad es. `hook-only`) | -| **legacy warning** | Il plugin usa `before_agent_start`, che è deprecato | +| **compatibility advisory** | Il plugin usa un pattern supportato ma più vecchio (ad es. `hook-only`) | +| **legacy warning** | Il plugin usa `before_agent_start`, che è deprecato | | **hard error** | La configurazione non è valida o il plugin non è riuscito a caricarsi | Né `hook-only` né `before_agent_start` romperanno il tuo plugin oggi -- `hook-only` è un avviso, e `before_agent_start` genera solo un warning. Questi -segnali appaiono anche in `openclaw status --all` e `openclaw plugins doctor`. +segnali compaiono anche in `openclaw status --all` e `openclaw plugins doctor`. ## Panoramica dell'architettura Il sistema di plugin di OpenClaw ha quattro livelli: -1. **Manifest + rilevamento** - OpenClaw trova i plugin candidati dai percorsi configurati, dalle root del workspace, - dalle root globali delle estensioni e dalle estensioni incluse. Il rilevamento legge prima - i manifest nativi `openclaw.plugin.json` insieme ai manifest dei bundle supportati. +1. **Manifest + individuazione** + OpenClaw trova i plugin candidati dai percorsi configurati, dalle radici del workspace, + dalle radici globali delle estensioni e dalle estensioni bundled. L'individuazione legge prima + i manifest nativi `openclaw.plugin.json` e i manifest bundle supportati. 2. **Abilitazione + validazione** - Il core decide se un plugin rilevato è abilitato, disabilitato, bloccato o + Il core decide se un plugin individuato è abilitato, disabilitato, bloccato o selezionato per uno slot esclusivo come la memoria. 3. **Caricamento di runtime** - I plugin nativi di OpenClaw vengono caricati in-process tramite jiti e registrano + I plugin nativi OpenClaw vengono caricati in-process tramite jiti e registrano capacità in un registro centrale. I bundle compatibili vengono normalizzati in - record di registro senza importare codice di runtime. + record del registro senza importare il codice di runtime. 4. **Consumo della superficie** Il resto di OpenClaw legge il registro per esporre strumenti, canali, configurazione dei provider, hook, route HTTP, comandi CLI e servizi. -Per la CLI dei plugin in particolare, il rilevamento del comando root è diviso in due fasi: +Per la CLI dei plugin in particolare, l'individuazione dei comandi root è suddivisa in due fasi: -- i metadati al momento del parsing provengono da `registerCli(..., { descriptors: [...] })` -- il vero modulo CLI del plugin può restare lazy e registrarsi al primo richiamo +- i metadati in fase di parsing provengono da `registerCli(..., { descriptors: [...] })` +- il vero modulo CLI del plugin può restare lazy e registrarsi alla prima invocazione -Questo mantiene il codice CLI posseduto dal plugin all'interno del plugin, pur consentendo a OpenClaw +Questo mantiene il codice CLI posseduto dal plugin all'interno del plugin, permettendo comunque a OpenClaw di riservare i nomi dei comandi root prima del parsing. -Il confine progettuale importante: +Il confine di progettazione importante: -- il rilevamento + la validazione della configurazione devono funzionare da metadati di **manifest/schema** - senza eseguire codice del plugin +- l'individuazione + la validazione della configurazione dovrebbero funzionare da **metadati di manifest/schema** + senza eseguire il codice del plugin - il comportamento di runtime nativo proviene dal percorso `register(api)` del modulo plugin -Questa separazione consente a OpenClaw di validare la configurazione, spiegare plugin mancanti/disabilitati e +Questa separazione consente a OpenClaw di validare la configurazione, spiegare i plugin mancanti/disabilitati e costruire suggerimenti per UI/schema prima che il runtime completo sia attivo. -### Plugin di canale e strumento di messaggistica condiviso +### Plugin di canale e strumento condiviso dei messaggi I plugin di canale non devono registrare uno strumento separato di invio/modifica/reazione per le normali azioni di chat. OpenClaw mantiene un unico strumento `message` condiviso nel core, e @@ -167,20 +167,20 @@ i plugin di canale possiedono il rilevamento e l'esecuzione specifici del canale Il confine attuale è: -- il core possiede l'host dello strumento `message` condiviso, il collegamento al prompt, la - gestione di sessioni/thread e il dispatch di esecuzione -- i plugin di canale possiedono il rilevamento delle azioni con ambito, il rilevamento delle capacità - e qualsiasi frammento di schema specifico del canale +- il core possiede l'host dello strumento `message` condiviso, il wiring del prompt, la + gestione di sessione/thread e il dispatch dell'esecuzione +- i plugin di canale possiedono il rilevamento di azioni con ambito, il rilevamento delle capacità e qualsiasi + frammento di schema specifico del canale - i plugin di canale possiedono la grammatica di conversazione della sessione specifica del provider, come - il modo in cui gli ID di conversazione codificano gli ID dei thread o vengono ereditati dalle conversazioni padre -- i plugin di canale eseguono l'azione finale tramite il loro adapter di azione + il modo in cui gli ID conversazione codificano gli ID thread o ereditano dalle conversazioni padre +- i plugin di canale eseguono l'azione finale tramite il loro adattatore di azione Per i plugin di canale, la superficie SDK è -`ChannelMessageActionAdapter.describeMessageTool(...)`. Questa chiamata di rilevamento unificata -consente a un plugin di restituire insieme le sue azioni visibili, capacità e contributi allo schema, -in modo che questi elementi non divergano. +`ChannelMessageActionAdapter.describeMessageTool(...)`. Questa chiamata di individuazione unificata +consente a un plugin di restituire insieme le sue azioni visibili, capacità e contributi di schema +così che questi elementi non divergano tra loro. -Il core passa l'ambito di runtime in questo passaggio di rilevamento. I campi importanti includono: +Il core passa l'ambito di runtime a questo passaggio di individuazione. I campi importanti includono: - `accountId` - `currentChannelId` @@ -189,72 +189,76 @@ Il core passa l'ambito di runtime in questo passaggio di rilevamento. I campi im - `sessionKey` - `sessionId` - `agentId` -- `requesterSenderId` in ingresso attendibile +- `requesterSenderId` inbound attendibile Questo è importante per i plugin sensibili al contesto. Un canale può nascondere o esporre -azioni di messaggio in base all'account attivo, alla stanza/thread/messaggio corrente o -all'identità attendibile del richiedente senza codificare branch specifici del canale nello +azioni sui messaggi in base all'account attivo, alla stanza/thread/messaggio corrente o +all'identità attendibile del richiedente, senza codificare rami specifici del canale nello strumento `message` del core. -Per questo motivo le modifiche di instradamento dell'embedded runner sono ancora lavoro del plugin: il runner è -responsabile dell'inoltro dell'identità corrente di chat/sessione nel confine di rilevamento del plugin -in modo che lo strumento `message` condiviso esponga la giusta superficie posseduta dal canale per il turno corrente. +Per questo motivo le modifiche di routing dell'embedded runner restano lavoro del plugin: il runner è +responsabile dell'inoltro dell'identità corrente di chat/sessione al confine di individuazione del plugin +affinché lo strumento `message` condiviso esponga la superficie posseduta dal canale corretta +per il turno corrente. -Per gli helper di esecuzione posseduti dal canale, i plugin inclusi dovrebbero mantenere il runtime di esecuzione -all'interno dei propri moduli di estensione. Il core non possiede più i runtime delle azioni di messaggio di Discord, +Per gli helper di esecuzione posseduti dal canale, i plugin bundled dovrebbero mantenere il runtime di esecuzione +all'interno dei propri moduli di estensione. Il core non possiede più i runtime di azione dei messaggi per Discord, Slack, Telegram o WhatsApp sotto `src/agents/tools`. -Non pubblichiamo sottopercorsi separati `plugin-sdk/*-action-runtime`, e i plugin inclusi -dovrebbero importare direttamente il proprio codice di runtime locale dai loro -moduli posseduti dall'estensione. +Non pubblichiamo sottopercorsi separati `plugin-sdk/*-action-runtime`, e i plugin bundled +dovrebbero importare direttamente il proprio codice di runtime locale dai +loro moduli posseduti dall'estensione. -Lo stesso confine si applica in generale agli SDK seam con nome del provider: il core non dovrebbe +Lo stesso confine si applica in generale alle seam SDK con nome del provider: il core non dovrebbe importare barrel di convenienza specifici del canale per estensioni come Slack, Discord, Signal, -WhatsApp o simili. Se il core ha bisogno di un comportamento, deve consumare il barrel `api.ts` / `runtime-api.ts` -del plugin incluso oppure promuovere la necessità in una capacità generica e ristretta nell'SDK condiviso. +WhatsApp o simili. Se il core ha bisogno di un comportamento, o consuma il barrel `api.ts` / `runtime-api.ts` +del plugin bundled stesso, oppure promuove la necessità in una capacità generica ristretta nell'SDK condiviso. -Per i sondaggi in particolare, esistono due percorsi di esecuzione: +Per i sondaggi in particolare, ci sono due percorsi di esecuzione: -- `outbound.sendPoll` è la baseline condivisa per i canali che rientrano nel modello comune dei sondaggi -- `actions.handleAction("poll")` è il percorso preferito per semantiche di sondaggio specifiche del canale o parametri di sondaggio aggiuntivi +- `outbound.sendPoll` è la base condivisa per i canali che si adattano al modello comune + di sondaggio +- `actions.handleAction("poll")` è il percorso preferito per la semantica dei sondaggi specifica del canale + o per parametri di sondaggio aggiuntivi -Il core ora rimanda l'analisi condivisa dei sondaggi finché il dispatch del sondaggio del plugin non rifiuta +Il core ora rimanda il parsing condiviso dei sondaggi a dopo che il dispatch del sondaggio del plugin ha rifiutato l'azione, così i gestori di sondaggi posseduti dal plugin possono accettare campi di sondaggio specifici del canale -senza essere bloccati prima dal parser generico dei sondaggi. +senza essere prima bloccati dal parser generico dei sondaggi. Vedi [Pipeline di caricamento](#load-pipeline) per la sequenza completa di avvio. ## Modello di proprietà delle capacità -OpenClaw tratta un plugin nativo come confine di proprietà per una **azienda** o una -**funzionalità**, non come un insieme eterogeneo di integrazioni non correlate. +OpenClaw tratta un plugin nativo come confine di proprietà per un'**azienda** o una +**funzionalità**, non come un contenitore di integrazioni non correlate. Questo significa: -- un plugin aziendale dovrebbe di solito possedere tutte le superfici di OpenClaw rivolte a quell'azienda +- un plugin aziendale dovrebbe di solito possedere tutte le superfici OpenClaw-facing di quell'azienda - un plugin di funzionalità dovrebbe di solito possedere l'intera superficie della funzionalità che introduce -- i canali dovrebbero consumare capacità core condivise invece di reimplementare ad hoc il comportamento del provider +- i canali dovrebbero consumare capacità condivise del core invece di reimplementare in modo ad hoc + il comportamento del provider Esempi: -- il plugin incluso `openai` possiede il comportamento del provider di modelli OpenAI e il comportamento OpenAI per +- il plugin bundled `openai` possiede il comportamento del provider di modelli OpenAI e il comportamento OpenAI per voce + voce in tempo reale + comprensione dei media + generazione di immagini -- il plugin incluso `elevenlabs` possiede il comportamento vocale di ElevenLabs -- il plugin incluso `microsoft` possiede il comportamento vocale di Microsoft -- il plugin incluso `google` possiede il comportamento del provider di modelli Google più il comportamento Google per +- il plugin bundled `elevenlabs` possiede il comportamento vocale ElevenLabs +- il plugin bundled `microsoft` possiede il comportamento vocale Microsoft +- il plugin bundled `google` possiede il comportamento del provider di modelli Google più il comportamento Google per comprensione dei media + generazione di immagini + ricerca web -- il plugin incluso `firecrawl` possiede il comportamento di recupero web di Firecrawl -- i plugin inclusi `minimax`, `mistral`, `moonshot` e `zai` possiedono i rispettivi +- il plugin bundled `firecrawl` possiede il comportamento Firecrawl di recupero web +- i plugin bundled `minimax`, `mistral`, `moonshot` e `zai` possiedono i loro backend di comprensione dei media -- il plugin incluso `qwen` possiede il comportamento del provider di testo Qwen più il +- il plugin bundled `qwen` possiede il comportamento di provider testuale Qwen più il comportamento di comprensione dei media e generazione video -- il plugin `voice-call` è un plugin di funzionalità: possiede il trasporto delle chiamate, strumenti, - CLI, route e il bridging dei media stream di Twilio, ma consuma capacità condivise di voce +- il plugin `voice-call` è un plugin di funzionalità: possiede trasporto delle chiamate, strumenti, + CLI, route e bridging del media-stream Twilio, ma consuma le capacità condivise di voce più trascrizione in tempo reale e voce in tempo reale invece di importare direttamente i plugin vendor Lo stato finale previsto è: -- OpenAI vive in un solo plugin anche se copre modelli di testo, voce, immagini e - video futuri +- OpenAI si trova in un unico plugin anche se copre modelli testuali, voce, immagini e + futuro video - un altro vendor può fare lo stesso per la propria area di superficie - i canali non si preoccupano di quale plugin vendor possieda il provider; consumano il contratto di capacità condiviso esposto dal core @@ -265,45 +269,45 @@ Questa è la distinzione chiave: - **capability** = contratto del core che più plugin possono implementare o consumare Quindi, se OpenClaw aggiunge un nuovo dominio come il video, la prima domanda non è -"quale provider dovrebbe codificare rigidamente la gestione del video?" La prima domanda è "qual è -il contratto di capacità video del core?" Una volta che quel contratto esiste, -i plugin vendor possono registrarsi rispetto ad esso e i plugin di canale/funzionalità possono consumarlo. +“quale provider dovrebbe hardcodare la gestione del video?” La prima domanda è “qual è +il contratto di capacità video del core?” Una volta che quel contratto esiste, i plugin vendor +possono registrarsi rispetto a esso e i plugin di canale/funzionalità possono consumarlo. -Se la capacità non esiste ancora, la mossa giusta di solito è: +Se la capacità non esiste ancora, la mossa corretta di solito è: 1. definire la capacità mancante nel core 2. esporla tramite l'API/runtime dei plugin in modo tipizzato 3. collegare canali/funzionalità a quella capacità 4. lasciare che i plugin vendor registrino le implementazioni -Questo mantiene esplicita la proprietà evitando al tempo stesso comportamenti del core che dipendono da un -singolo vendor o da un percorso di codice specifico di un singolo plugin. +Questo mantiene esplicita la proprietà evitando al contempo comportamenti del core che dipendono da un +singolo vendor o da un percorso di codice specifico per un singolo plugin. ### Stratificazione delle capacità Usa questo modello mentale quando decidi dove deve stare il codice: -- **livello delle capacità del core**: orchestrazione condivisa, policy, fallback, regole di - merge della configurazione, semantica di consegna e contratti tipizzati -- **livello dei plugin vendor**: API specifiche del vendor, autenticazione, cataloghi di modelli, sintesi - vocale, generazione di immagini, backend video futuri, endpoint di utilizzo -- **livello dei plugin di canale/funzionalità**: integrazione Slack/Discord/voice-call/ecc. - che consuma le capacità del core e le presenta su una superficie +- **livello di capacità del core**: orchestrazione condivisa, policy, fallback, regole di merge + della configurazione, semantica di consegna e contratti tipizzati +- **livello del plugin vendor**: API specifiche del vendor, autenticazione, cataloghi di modelli, sintesi + vocale, generazione di immagini, futuri backend video, endpoint di utilizzo +- **livello del plugin di canale/funzionalità**: integrazione Slack/Discord/voice-call/ecc. + che consuma capacità del core e le presenta su una superficie -Per esempio, TTS segue questa forma: +Per esempio, la TTS segue questa forma: - il core possiede la policy TTS al momento della risposta, l'ordine di fallback, le preferenze e la consegna sui canali - `openai`, `elevenlabs` e `microsoft` possiedono le implementazioni di sintesi - `voice-call` consuma l'helper di runtime TTS per la telefonia -Lo stesso schema dovrebbe essere preferito per le capacità future. +Lo stesso pattern dovrebbe essere preferito per le capacità future. ### Esempio di plugin aziendale multi-capacità Un plugin aziendale dovrebbe risultare coeso dall'esterno. Se OpenClaw ha contratti condivisi per modelli, voce, trascrizione in tempo reale, voce in tempo reale, comprensione dei media, generazione di immagini, generazione video, recupero web e ricerca web, -un vendor può possedere tutte le sue superfici in un unico posto: +un vendor può possedere tutte le proprie superfici in un unico posto: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -318,12 +322,12 @@ const plugin: OpenClawPluginDefinition = { register(api) { api.registerProvider({ id: "exampleai", - // hook di autenticazione/catalogo modelli/runtime + // auth/model catalog/runtime hooks }); api.registerSpeechProvider({ id: "exampleai", - // configurazione vocale del vendor — implementa direttamente l'interfaccia SpeechProviderPlugin + // vendor speech config — implement the SpeechProviderPlugin interface directly }); api.registerMediaUnderstandingProvider({ @@ -348,7 +352,7 @@ const plugin: OpenClawPluginDefinition = { api.registerWebSearchProvider( createPluginBackedWebSearchProvider({ id: "exampleai-search", - // logica di credenziali + fetch + // credential + fetch logic }), ); }, @@ -359,9 +363,9 @@ export default plugin; Ciò che conta non sono i nomi esatti degli helper. Conta la forma: -- un solo plugin possiede la superficie del vendor +- un plugin possiede la superficie del vendor - il core continua a possedere i contratti di capacità -- i plugin di canale e funzionalità consumano helper `api.runtime.*`, non codice vendor +- i plugin di canale e di funzionalità consumano helper `api.runtime.*`, non codice del vendor - i test di contratto possono verificare che il plugin abbia registrato le capacità che dichiara di possedere @@ -370,20 +374,20 @@ Ciò che conta non sono i nomi esatti degli helper. Conta la forma: OpenClaw tratta già la comprensione di immagini/audio/video come un'unica capacità condivisa. Lo stesso modello di proprietà si applica anche qui: -1. il core definisce il contratto di media-understanding +1. il core definisce il contratto di comprensione dei media 2. i plugin vendor registrano `describeImage`, `transcribeAudio` e - `describeVideo` a seconda dei casi -3. i plugin di canale e funzionalità consumano il comportamento condiviso del core invece di - collegarsi direttamente al codice vendor + `describeVideo` secondo necessità +3. i plugin di canale e di funzionalità consumano il comportamento condiviso del core invece di + collegarsi direttamente al codice del vendor -Questo evita di incorporare nel core le ipotesi video di un singolo provider. Il plugin possiede +Questo evita di incorporare nel core le assunzioni video di un singolo provider. Il plugin possiede la superficie del vendor; il core possiede il contratto di capacità e il comportamento di fallback. La generazione video usa già la stessa sequenza: il core possiede il contratto di capacità tipizzato e l'helper di runtime, e i plugin vendor registrano -implementazioni `api.registerVideoGenerationProvider(...)` rispetto ad esso. +implementazioni `api.registerVideoGenerationProvider(...)` rispetto a esso. -Ti serve una checklist concreta per il rollout? Vedi +Hai bisogno di una checklist concreta di rollout? Vedi [Capability Cookbook](/it/plugins/architecture). ## Contratti e applicazione @@ -392,28 +396,28 @@ La superficie API dei plugin è intenzionalmente tipizzata e centralizzata in `OpenClawPluginApi`. Questo contratto definisce i punti di registrazione supportati e gli helper di runtime su cui un plugin può fare affidamento. -Perché è importante: +Perché questo è importante: - gli autori di plugin ottengono un unico standard interno stabile - il core può rifiutare proprietà duplicate, ad esempio due plugin che registrano lo stesso - id provider -- l'avvio può mostrare diagnostiche utili per registrazioni non valide -- i test di contratto possono applicare la proprietà dei plugin inclusi e prevenire derive silenziose + ID provider +- l'avvio può mostrare diagnostica utile per registrazioni non valide +- i test di contratto possono imporre la proprietà dei plugin bundled e prevenire derive silenziose -Esistono due livelli di applicazione: +Ci sono due livelli di applicazione: 1. **applicazione della registrazione a runtime** - Il registro dei plugin valida le registrazioni durante il caricamento dei plugin. Esempi: - id provider duplicati, id provider vocali duplicati e registrazioni non valide - producono diagnostiche dei plugin invece di comportamento indefinito. + Il registro dei plugin valida le registrazioni mentre i plugin vengono caricati. Esempi: + ID provider duplicati, ID provider vocali duplicati e registrazioni + non valide producono diagnostica dei plugin invece di comportamenti indefiniti. 2. **test di contratto** - I plugin inclusi vengono acquisiti in registri di contratto durante i test, così + I plugin bundled vengono acquisiti nei registri di contratto durante le esecuzioni di test così OpenClaw può verificare esplicitamente la proprietà. Oggi questo viene usato per - provider di modelli, provider vocali, provider di ricerca web e proprietà delle registrazioni incluse. + provider di modelli, provider vocali, provider di ricerca web e proprietà delle registrazioni bundled. -L'effetto pratico è che OpenClaw sa in anticipo quale plugin possiede quale -superficie. Questo permette al core e ai canali di comporsi senza attriti perché la proprietà è -dichiarata, tipizzata e verificabile invece che implicita. +L'effetto pratico è che OpenClaw sa, fin dall'inizio, quale plugin possiede quale +superficie. Questo consente al core e ai canali di comporsi senza attriti perché la proprietà è +dichiarata, tipizzata e verificabile invece di essere implicita. ### Cosa appartiene a un contratto @@ -429,17 +433,17 @@ I buoni contratti dei plugin sono: I cattivi contratti dei plugin sono: - policy specifiche del vendor nascoste nel core -- vie di fuga specifiche di un singolo plugin che bypassano il registro -- codice di canale che accede direttamente a un'implementazione vendor +- vie di fuga specifiche per un singolo plugin che aggirano il registro +- codice di canale che entra direttamente in un'implementazione vendor - oggetti di runtime ad hoc che non fanno parte di `OpenClawPluginApi` o `api.runtime` In caso di dubbio, alza il livello di astrazione: definisci prima la capacità, poi -lascia che i plugin si colleghino ad essa. +lascia che i plugin si colleghino a essa. ## Modello di esecuzione -I plugin nativi di OpenClaw vengono eseguiti **in-process** con il Gateway. Non sono +I plugin nativi OpenClaw vengono eseguiti **in-process** con il Gateway. Non sono sandboxed. Un plugin nativo caricato ha lo stesso confine di fiducia a livello di processo del codice core. @@ -447,25 +451,26 @@ Implicazioni: - un plugin nativo può registrare strumenti, gestori di rete, hook e servizi - un bug in un plugin nativo può mandare in crash o destabilizzare il gateway -- un plugin nativo malevolo equivale a esecuzione arbitraria di codice all'interno del processo OpenClaw +- un plugin nativo malevolo equivale a esecuzione di codice arbitrario all'interno del + processo OpenClaw I bundle compatibili sono più sicuri per impostazione predefinita perché OpenClaw attualmente li tratta come pacchetti di metadati/contenuti. Nelle release attuali, questo significa soprattutto -Skills incluse. +Skills bundled. -Usa allowlist e percorsi espliciti di installazione/caricamento per i plugin non inclusi. Tratta -i plugin del workspace come codice di sviluppo, non come impostazione predefinita di produzione. +Usa allowlist e percorsi espliciti di installazione/caricamento per i plugin non bundled. Tratta +i plugin del workspace come codice di sviluppo, non come impostazioni predefinite di produzione. -Per i nomi dei pacchetti workspace inclusi, mantieni l'id del plugin ancorato al nome npm: +Per i nomi dei pacchetti del workspace bundled, mantieni l'ID del plugin ancorato nel nome npm: `@openclaw/` per impostazione predefinita, oppure un suffisso tipizzato approvato come `-provider`, `-plugin`, `-speech`, `-sandbox` o `-media-understanding` quando -il pacchetto espone intenzionalmente un ruolo plugin più ristretto. +il pacchetto espone intenzionalmente un ruolo di plugin più ristretto. Nota importante sulla fiducia: -- `plugins.allow` considera attendibili gli **id plugin**, non la provenienza della sorgente. -- Un plugin del workspace con lo stesso id di un plugin incluso oscura intenzionalmente - la copia inclusa quando quel plugin del workspace è abilitato/in allowlist. +- `plugins.allow` si fida degli **ID plugin**, non della provenienza della sorgente. +- Un plugin del workspace con lo stesso ID di un plugin bundled oscura intenzionalmente + la copia bundled quando quel plugin del workspace è abilitato/in allowlist. - Questo è normale e utile per sviluppo locale, test di patch e hotfix. ## Confine di esportazione @@ -474,84 +479,88 @@ OpenClaw esporta capacità, non comodità di implementazione. Mantieni pubblica la registrazione delle capacità. Riduci le esportazioni helper non contrattuali: -- sottopercorsi helper specifici del plugin incluso -- sottopercorsi di plumbing runtime non destinati a essere API pubbliche -- helper di convenienza specifici del vendor +- sottopercorsi helper specifici dei plugin bundled +- sottopercorsi di plumbing di runtime non destinati a essere API pubbliche +- helper di comodità specifici del vendor - helper di setup/onboarding che sono dettagli di implementazione -Alcuni sottopercorsi helper dei plugin inclusi restano ancora nella mappa di esportazione generata dell'SDK -per compatibilità e manutenzione dei plugin inclusi. Esempi attuali includono +Alcuni sottopercorsi helper dei plugin bundled restano comunque nella mappa di esportazione SDK generata +per compatibilità e manutenzione dei plugin bundled. Esempi attuali includono `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` e vari seam `plugin-sdk/matrix*`. Trattali come -esportazioni riservate di dettaglio implementativo, non come il pattern SDK consigliato per +`plugin-sdk/zalo-setup` e diverse seam `plugin-sdk/matrix*`. Trattali come +esportazioni riservate a dettagli di implementazione, non come pattern SDK consigliato per nuovi plugin di terze parti. ## Pipeline di caricamento -All'avvio, OpenClaw esegue approssimativamente questi passaggi: +All'avvio, OpenClaw esegue approssimativamente questo: -1. rileva le root dei plugin candidati +1. individua le root candidate dei plugin 2. legge i manifest nativi o dei bundle compatibili e i metadati dei pacchetti 3. rifiuta i candidati non sicuri 4. normalizza la configurazione dei plugin (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. decide l'abilitazione per ciascun candidato +5. decide l'abilitazione per ogni candidato 6. carica i moduli nativi abilitati tramite jiti -7. chiama gli hook nativi `register(api)` (oppure `activate(api)` — un alias legacy) e raccoglie le registrazioni nel registro dei plugin +7. chiama gli hook nativi `register(api)` (o `activate(api)` — un alias legacy) e raccoglie le registrazioni nel registro dei plugin 8. espone il registro alle superfici di comandi/runtime -`activate` è un alias legacy di `register` — il loader risolve qualunque dei due sia presente (`def.register ?? def.activate`) e lo chiama nello stesso punto. Tutti i plugin inclusi usano `register`; per i nuovi plugin, preferisci `register`. +`activate` è un alias legacy di `register` — il loader risolve quello presente (`def.register ?? def.activate`) e lo chiama nello stesso punto. Tutti i plugin bundled usano `register`; per i nuovi plugin preferisci `register`. -I gate di sicurezza avvengono **prima** dell'esecuzione a runtime. I candidati vengono bloccati -quando l'entry esce dalla root del plugin, il percorso è scrivibile da tutti oppure -la proprietà del percorso sembra sospetta per i plugin non inclusi. +I controlli di sicurezza avvengono **prima** dell'esecuzione a runtime. I candidati vengono bloccati +quando l'entry esce dalla root del plugin, il percorso è scrivibile da chiunque, oppure la proprietà del percorso appare sospetta per i plugin non bundled. ### Comportamento manifest-first Il manifest è la fonte di verità del control plane. OpenClaw lo usa per: - identificare il plugin -- rilevare canali/Skills/schema di configurazione dichiarati o capacità del bundle +- individuare canali/Skills/schema di configurazione dichiarati o capacità del bundle - validare `plugins.entries..config` - arricchire etichette/segnaposto della Control UI - mostrare metadati di installazione/catalogo - preservare descrittori economici di attivazione e setup senza caricare il runtime del plugin -Per i plugin nativi, il modulo runtime è la parte di data plane. Registra il -comportamento effettivo come hook, strumenti, comandi o flussi provider. +Per i plugin nativi, il modulo runtime è la parte di data plane. Registra +il comportamento reale come hook, strumenti, comandi o flussi provider. -I blocchi facoltativi del manifest `activation` e `setup` restano nel control plane. -Sono descrittori di soli metadati per la pianificazione dell'attivazione e il rilevamento del setup; +I blocchi facoltativi `activation` e `setup` del manifest restano nel control plane. +Sono descrittori di soli metadati per la pianificazione dell'attivazione e l'individuazione del setup; non sostituiscono la registrazione a runtime, `register(...)` o `setupEntry`. +L'individuazione del setup ora preferisce ID posseduti dal descrittore come `setup.providers` e +`setup.cliBackends` per restringere i plugin candidati prima di ricorrere a +`setup-api` per i plugin che hanno ancora bisogno di hook di runtime al momento del setup. Se più di +un plugin individuato rivendica lo stesso ID normalizzato di provider di setup o backend CLI, la ricerca del setup rifiuta il proprietario ambiguo invece di basarsi sull'ordine di individuazione. + ### Cosa mette in cache il loader OpenClaw mantiene brevi cache in-process per: -- risultati del rilevamento +- risultati di individuazione - dati del registro dei manifest - registri dei plugin caricati -Queste cache riducono gli avvii impulsivi e il sovraccarico dei comandi ripetuti. È sicuro +Queste cache riducono gli avvii a raffica e l'overhead dei comandi ripetuti. È corretto considerarle come cache prestazionali di breve durata, non persistenza. Nota sulle prestazioni: - Imposta `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` o `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1` per disabilitare queste cache. -- Regola le finestre di cache con `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` e +- Regola le finestre della cache con `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` e `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Modello di registro -I plugin caricati non mutano direttamente variabili globali casuali del core. Si registrano in un +I plugin caricati non mutano direttamente globali casuali del core. Si registrano in un registro centrale dei plugin. Il registro tiene traccia di: -- record dei plugin (identità, sorgente, origine, stato, diagnostiche) +- record dei plugin (identità, sorgente, origine, stato, diagnostica) - strumenti - hook legacy e hook tipizzati - canali @@ -562,21 +571,21 @@ Il registro tiene traccia di: - servizi in background - comandi posseduti dal plugin -Le funzionalità del core leggono poi da quel registro invece di parlare direttamente con i moduli plugin. -Questo mantiene il caricamento a senso unico: +Le funzionalità del core leggono poi da quel registro invece di parlare direttamente con i moduli +dei plugin. Questo mantiene il caricamento unidirezionale: -- modulo plugin -> registrazione nel registro +- modulo del plugin -> registrazione nel registro - runtime del core -> consumo del registro Questa separazione è importante per la manutenibilità. Significa che la maggior parte delle superfici del core -ha bisogno di un solo punto di integrazione: "leggere il registro", non "gestire casi speciali per ogni modulo plugin". +ha bisogno di un solo punto di integrazione: “leggere il registro”, non “gestire con casi speciali ogni modulo +di plugin”. ## Callback di binding della conversazione -I plugin che effettuano il binding di una conversazione possono reagire quando un'approvazione viene risolta. +I plugin che associano una conversazione possono reagire quando un'approvazione viene risolta. -Usa `api.onConversationBindingResolved(...)` per ricevere una callback dopo che una richiesta di binding -viene approvata o negata: +Usa `api.onConversationBindingResolved(...)` per ricevere un callback dopo che una richiesta di binding viene approvata o negata: ```ts export default { @@ -584,36 +593,36 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // Ora esiste un binding per questo plugin + conversazione. + // A binding now exists for this plugin + conversation. console.log(event.binding?.conversationId); return; } - // La richiesta è stata negata; cancella qualsiasi stato locale in sospeso. + // The request was denied; clear any local pending state. console.log(event.request.conversation.conversationId); }); }, }; ``` -Campi del payload della callback: +Campi del payload del callback: -- `status`: `"approved"` oppure `"denied"` -- `decision`: `"allow-once"`, `"allow-always"` oppure `"deny"` +- `status`: `"approved"` o `"denied"` +- `decision`: `"allow-once"`, `"allow-always"` o `"deny"` - `binding`: il binding risolto per le richieste approvate -- `request`: il riepilogo della richiesta originale, suggerimento di detach, id del mittente e - metadati della conversazione +- `request`: il riepilogo della richiesta originale, il suggerimento di distacco, l'ID del mittente e + i metadati della conversazione -Questa callback è solo di notifica. Non cambia chi è autorizzato a effettuare il binding di una -conversazione, e viene eseguita dopo che il core ha terminato la gestione dell'approvazione. +Questo callback è solo di notifica. Non cambia chi è autorizzato ad associare una +conversazione, e viene eseguito dopo che la gestione dell'approvazione del core è terminata. ## Hook di runtime del provider I plugin provider ora hanno due livelli: -- metadati del manifest: `providerAuthEnvVars` per una ricerca economica dell'autenticazione del provider via env - prima del caricamento del runtime, `providerAuthAliases` per varianti di provider che condividono - l'autenticazione, `channelEnvVars` per una ricerca economica di env/setup del canale prima del caricamento del runtime, +- metadati del manifest: `providerAuthEnvVars` per un lookup economico dell'autenticazione provider tramite env + prima del caricamento del runtime, `providerAuthAliases` per varianti del provider che condividono + autenticazione, `channelEnvVars` per un lookup economico dell'env/setup del canale prima del caricamento del runtime, più `providerAuthChoices` per etichette economiche di onboarding/scelta di autenticazione e metadati dei flag CLI prima del caricamento del runtime - hook in fase di configurazione: `catalog` / legacy `discovery` più `applyConfigDefaults` @@ -637,85 +646,84 @@ I plugin provider ora hanno due livelli: `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw continua a possedere il loop agente generico, il failover, la gestione delle trascrizioni e la -policy degli strumenti. Questi hook sono la superficie di estensione per il comportamento specifico del provider senza +OpenClaw continua a possedere il loop generico dell'agente, il failover, la gestione della trascrizione e +la policy degli strumenti. Questi hook sono la superficie di estensione per il comportamento specifico del provider senza richiedere un intero trasporto di inferenza personalizzato. Usa il manifest `providerAuthEnvVars` quando il provider ha credenziali basate su env che i percorsi generici di autenticazione/stato/selettore di modelli devono vedere senza caricare il runtime del plugin. -Usa il manifest `providerAuthAliases` quando un id provider deve riutilizzare -le variabili env, i profili di autenticazione, l'autenticazione supportata da config e la scelta di onboarding con chiave API -di un altro id provider. Usa il manifest `providerAuthChoices` quando le superfici CLI di onboarding/scelta di autenticazione -devono conoscere l'id scelta del provider, le etichette di gruppo e il semplice -cablaggio di autenticazione con un solo flag senza caricare il runtime del provider. Mantieni `envVars` del runtime del provider -per suggerimenti rivolti all'operatore come etichette di onboarding o variabili di setup -di client-id/client-secret OAuth. +Usa il manifest `providerAuthAliases` quando un ID provider deve riutilizzare +le variabili env, i profili di autenticazione, l'autenticazione supportata dalla configurazione e la scelta di onboarding della chiave API di un altro ID provider. +Usa il manifest `providerAuthChoices` quando le superfici CLI di onboarding/scelta di autenticazione +devono conoscere l'ID di scelta del provider, le etichette di gruppo e il semplice wiring di autenticazione a flag singolo senza caricare il runtime del provider. Mantieni `envVars` del runtime provider per suggerimenti rivolti all'operatore come etichette di onboarding o variabili di setup per +client-id/client-secret OAuth. Usa il manifest `channelEnvVars` quando un canale ha autenticazione o setup guidati da env che -il fallback generico dell'env della shell, i controlli di config/stato o i prompt di setup devono vedere +i fallback generici di shell-env, i controlli di configurazione/stato o i prompt di setup devono vedere senza caricare il runtime del canale. ### Ordine e uso degli hook -Per i plugin di modello/provider, OpenClaw chiama gli hook approssimativamente in questo ordine. -La colonna "Quando usarlo" è la guida rapida per decidere. +Per i plugin modello/provider, OpenClaw chiama gli hook approssimativamente in questo ordine. +La colonna “Quando usarlo” è la guida rapida per decidere. -| # | Hook | Cosa fa | Quando usarlo | +| # | Hook | Cosa fa | Quando usarlo | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Pubblica la configurazione del provider in `models.providers` durante la generazione di `models.json` | Il provider possiede un catalogo o valori predefiniti di base URL | -| 2 | `applyConfigDefaults` | Applica valori predefiniti globali della configurazione posseduti dal provider durante la materializzazione della configurazione | I valori predefiniti dipendono dalla modalità di autenticazione, dall'env o dalla semantica della famiglia di modelli del provider | -| -- | _(ricerca del modello integrata)_ | OpenClaw prova prima il normale percorso registro/catalogo | _(non è un hook del plugin)_ | -| 3 | `normalizeModelId` | Normalizza alias legacy o preview degli id modello prima della ricerca | Il provider possiede la pulizia degli alias prima della risoluzione del modello canonico | -| 4 | `normalizeTransport` | Normalizza `api` / `baseUrl` della famiglia del provider prima dell'assemblaggio generico del modello | Il provider possiede la pulizia del trasporto per id provider personalizzati nella stessa famiglia di trasporto | -| 5 | `normalizeConfig` | Normalizza `models.providers.` prima della risoluzione del runtime/provider | Il provider ha bisogno di una pulizia della configurazione che dovrebbe stare nel plugin; gli helper inclusi della famiglia Google fanno anche da backstop per le voci di configurazione Google supportate | -| 6 | `applyNativeStreamingUsageCompat` | Applica riscritture di compatibilità dell'uso dello streaming nativo ai provider di configurazione | Il provider ha bisogno di correzioni dei metadati di utilizzo dello streaming nativo guidate dall'endpoint | -| 7 | `resolveConfigApiKey` | Risolve l'autenticazione con marker env per i provider di configurazione prima del caricamento dell'autenticazione di runtime | Il provider ha una risoluzione della chiave API con marker env posseduta dal provider; `amazon-bedrock` ha anche un resolver integrato del marker env AWS qui | -| 8 | `resolveSyntheticAuth` | Espone autenticazione locale/self-hosted o supportata da configurazione senza persistere testo in chiaro | Il provider può operare con un marker di credenziale sintetica/locale | -| 9 | `resolveExternalAuthProfiles` | Sovrappone profili di autenticazione esterni posseduti dal provider; il valore predefinito di `persistence` è `runtime-only` per credenziali possedute da CLI/app | Il provider riutilizza credenziali di autenticazione esterne senza persistere refresh token copiati | -| 10 | `shouldDeferSyntheticProfileAuth` | Riduce la precedenza dei placeholder sintetici dei profili memorizzati rispetto all'autenticazione basata su env/config | Il provider memorizza profili placeholder sintetici che non dovrebbero avere precedenza | -| 11 | `resolveDynamicModel` | Fallback sincrono per id modello posseduti dal provider non ancora presenti nel registro locale | Il provider accetta id modello upstream arbitrari | -| 12 | `prepareDynamicModel` | Warm-up asincrono, poi `resolveDynamicModel` viene eseguito di nuovo | Il provider ha bisogno di metadati di rete prima di risolvere id sconosciuti | -| 13 | `normalizeResolvedModel` | Riscrittura finale prima che l'embedded runner usi il modello risolto | Il provider ha bisogno di riscritture del trasporto ma continua a usare un trasporto core | -| 14 | `contributeResolvedModelCompat` | Contribuisce con flag di compatibilità per modelli vendor dietro un altro trasporto compatibile | Il provider riconosce i propri modelli su trasporti proxy senza assumere il controllo del provider | -| 15 | `capabilities` | Metadati di trascrizione/tooling posseduti dal provider usati dalla logica condivisa del core | Il provider ha bisogno di particolarità della famiglia transcript/provider | -| 16 | `normalizeToolSchemas` | Normalizza gli schemi degli strumenti prima che l'embedded runner li veda | Il provider ha bisogno di pulizia dello schema per famiglia di trasporto | -| 17 | `inspectToolSchemas` | Espone diagnostiche degli schemi possedute dal provider dopo la normalizzazione | Il provider vuole warning sulle keyword senza insegnare al core regole specifiche del provider | -| 18 | `resolveReasoningOutputMode` | Seleziona il contratto di output di ragionamento nativo o taggato | Il provider ha bisogno di output finale/ragionamento taggato invece di campi nativi | -| 19 | `prepareExtraParams` | Normalizzazione dei parametri della richiesta prima dei wrapper generici delle opzioni di stream | Il provider ha bisogno di parametri di richiesta predefiniti o di pulizia dei parametri per provider | -| 20 | `createStreamFn` | Sostituisce completamente il normale percorso di stream con un trasporto personalizzato | Il provider ha bisogno di un protocollo wire personalizzato, non solo di un wrapper | -| 21 | `wrapStreamFn` | Wrapper dello stream dopo l'applicazione dei wrapper generici | Il provider ha bisogno di wrapper di compatibilità per header/body/modello della richiesta senza un trasporto personalizzato | -| 22 | `resolveTransportTurnState` | Collega header o metadati nativi per turno di trasporto | Il provider vuole che i trasporti generici inviino l'identità del turno nativa del provider | -| 23 | `resolveWebSocketSessionPolicy` | Collega header WebSocket nativi o policy di cool-down della sessione | Il provider vuole che i trasporti WS generici regolino gli header di sessione o la policy di fallback | -| 24 | `formatApiKey` | Formattatore del profilo di autenticazione: il profilo memorizzato diventa la stringa `apiKey` di runtime | Il provider memorizza metadati di autenticazione aggiuntivi e ha bisogno di una forma token di runtime personalizzata | -| 25 | `refreshOAuth` | Override del refresh OAuth per endpoint di refresh personalizzati o policy di fallimento del refresh | Il provider non rientra nei refresher condivisi `pi-ai` | -| 26 | `buildAuthDoctorHint` | Suggerimento di riparazione aggiunto quando il refresh OAuth fallisce | Il provider ha bisogno di indicazioni di riparazione dell'autenticazione possedute dal provider dopo un fallimento del refresh | -| 27 | `matchesContextOverflowError` | Matcher di overflow della finestra di contesto posseduto dal provider | Il provider ha errori raw di overflow che le euristiche generiche non rileverebbero | -| 28 | `classifyFailoverReason` | Classificazione del motivo di failover posseduta dal provider | Il provider può mappare errori raw di API/trasporto a rate-limit/sovraccarico/ecc. | -| 29 | `isCacheTtlEligible` | Policy della cache del prompt per provider proxy/backhaul | Il provider ha bisogno di gating TTL della cache specifico per proxy | -| 30 | `buildMissingAuthMessage` | Sostituzione del messaggio generico di recupero per autenticazione mancante | Il provider ha bisogno di un suggerimento di recupero per autenticazione mancante specifico del provider | -| 31 | `suppressBuiltInModel` | Soppressione di modelli upstream obsoleti più opzionale suggerimento di errore rivolto all'utente | Il provider ha bisogno di nascondere righe upstream obsolete o sostituirle con un suggerimento del vendor | -| 32 | `augmentModelCatalog` | Righe di catalogo sintetiche/finali aggiunte dopo il rilevamento | Il provider ha bisogno di righe sintetiche di forward-compat in `models list` e nei selettori | -| 33 | `isBinaryThinking` | Toggle di ragionamento on/off per provider a ragionamento binario | Il provider espone solo ragionamento binario attivo/disattivo | -| 34 | `supportsXHighThinking` | Supporto al ragionamento `xhigh` per modelli selezionati | Il provider vuole `xhigh` solo su un sottoinsieme di modelli | -| 35 | `resolveDefaultThinkingLevel` | Livello `/think` predefinito per una specifica famiglia di modelli | Il provider possiede la policy predefinita di `/think` per una famiglia di modelli | -| 36 | `isModernModelRef` | Matcher di modelli moderni per filtri di profilo live e selezione smoke | Il provider possiede il matching dei modelli preferiti live/smoke | -| 37 | `prepareRuntimeAuth` | Scambia una credenziale configurata con il token/chiave di runtime effettivo appena prima dell'inferenza | Il provider ha bisogno di uno scambio token o di una credenziale di richiesta a breve durata | -| 38 | `resolveUsageAuth` | Risolve le credenziali di utilizzo/fatturazione per `/usage` e relative superfici di stato | Il provider ha bisogno di parsing personalizzato del token di utilizzo/quota o di una credenziale di utilizzo diversa | -| 39 | `fetchUsageSnapshot` | Recupera e normalizza snapshot di utilizzo/quota specifici del provider dopo che l'autenticazione è stata risolta | Il provider ha bisogno di un endpoint di utilizzo specifico del provider o di un parser del payload | -| 40 | `createEmbeddingProvider` | Costruisce un adapter di embedding posseduto dal provider per memoria/ricerca | Il comportamento degli embedding per la memoria appartiene al plugin provider | -| 41 | `buildReplayPolicy` | Restituisce una policy di replay che controlla la gestione della trascrizione per il provider | Il provider ha bisogno di una policy di trascrizione personalizzata (per esempio, la rimozione dei blocchi di ragionamento) | -| 42 | `sanitizeReplayHistory` | Riscrive la cronologia di replay dopo la pulizia generica della trascrizione | Il provider ha bisogno di riscritture del replay specifiche del provider oltre agli helper condivisi di compattazione | -| 43 | `validateReplayTurns` | Validazione finale o rimodellazione dei turni di replay prima dell'embedded runner | Il trasporto del provider ha bisogno di una validazione dei turni più rigorosa dopo la sanificazione generica | -| 44 | `onModelSelected` | Esegue effetti collaterali post-selezione posseduti dal provider | Il provider ha bisogno di telemetria o stato posseduto dal provider quando un modello diventa attivo | +| 1 | `catalog` | Pubblica la configurazione del provider in `models.providers` durante la generazione di `models.json` | Il provider possiede un catalogo o valori predefiniti di base URL | +| 2 | `applyConfigDefaults` | Applica valori predefiniti globali di configurazione posseduti dal provider durante la materializzazione della configurazione | I valori predefiniti dipendono dalla modalità di autenticazione, dall'env o dalla semantica della famiglia di modelli del provider | +| -- | _(built-in model lookup)_ | OpenClaw prova prima il normale percorso registro/catalogo | _(non è un hook del plugin)_ | +| 3 | `normalizeModelId` | Normalizza alias legacy o preview degli ID modello prima del lookup | Il provider possiede la pulizia degli alias prima della risoluzione del modello canonico | +| 4 | `normalizeTransport` | Normalizza `api` / `baseUrl` della famiglia provider prima dell'assemblaggio generico del modello | Il provider possiede la pulizia del trasporto per ID provider personalizzati nella stessa famiglia di trasporto | +| 5 | `normalizeConfig` | Normalizza `models.providers.` prima della risoluzione del runtime/provider | Il provider richiede una pulizia della configurazione che dovrebbe stare con il plugin; gli helper bundled della famiglia Google fanno anche da backstop per le voci di configurazione Google supportate | +| 6 | `applyNativeStreamingUsageCompat` | Applica riscritture di compatibilità dell'uso dello streaming nativo ai provider di configurazione | Il provider richiede correzioni dei metadati di uso dello streaming nativo guidate dall'endpoint | +| 7 | `resolveConfigApiKey` | Risolve l'autenticazione con marker env per i provider di configurazione prima del caricamento dell'autenticazione di runtime | Il provider ha una risoluzione della chiave API con marker env posseduta dal provider; anche `amazon-bedrock` ha qui un resolver integrato per il marker env AWS | +| 8 | `resolveSyntheticAuth` | Espone autenticazione locale/self-hosted o supportata dalla configurazione senza persistere testo in chiaro | Il provider può operare con un marker di credenziale sintetico/locale | +| 9 | `resolveExternalAuthProfiles` | Sovrappone profili di autenticazione esterni posseduti dal provider; `persistence` predefinito è `runtime-only` per credenziali possedute da CLI/app | Il provider riutilizza credenziali di autenticazione esterna senza persistere refresh token copiati | +| 10 | `shouldDeferSyntheticProfileAuth` | Abbassa la priorità dei placeholder sintetici di profilo memorizzati rispetto all'autenticazione supportata da env/config | Il provider memorizza profili placeholder sintetici che non dovrebbero avere la precedenza | +| 11 | `resolveDynamicModel` | Fallback sincrono per ID modello posseduti dal provider non ancora presenti nel registro locale | Il provider accetta ID modello upstream arbitrari | +| 12 | `prepareDynamicModel` | Warm-up asincrono, poi `resolveDynamicModel` viene eseguito di nuovo | Il provider ha bisogno di metadati di rete prima di risolvere ID sconosciuti | +| 13 | `normalizeResolvedModel` | Riscrittura finale prima che l'embedded runner usi il modello risolto | Il provider richiede riscritture del trasporto ma usa comunque un trasporto del core | +| 14 | `contributeResolvedModelCompat` | Contribuisce flag di compatibilità per modelli vendor dietro un altro trasporto compatibile | Il provider riconosce i propri modelli su trasporti proxy senza assumere il controllo del provider | +| 15 | `capabilities` | Metadati di trascrizione/strumentazione posseduti dal provider usati dalla logica condivisa del core | Il provider richiede peculiarità della trascrizione/della famiglia del provider | +| 16 | `normalizeToolSchemas` | Normalizza gli schemi degli strumenti prima che l'embedded runner li veda | Il provider richiede pulizia dello schema della famiglia di trasporto | +| 17 | `inspectToolSchemas` | Espone diagnostica degli schemi posseduta dal provider dopo la normalizzazione | Il provider vuole warning sulle keyword senza insegnare al core regole specifiche del provider | +| 18 | `resolveReasoningOutputMode` | Seleziona il contratto di output del ragionamento nativo rispetto a quello con tag | Il provider richiede output di ragionamento/finale con tag invece di campi nativi | +| 19 | `prepareExtraParams` | Normalizzazione dei parametri della richiesta prima dei wrapper generici delle opzioni di stream | Il provider richiede parametri di richiesta predefiniti o pulizia dei parametri per provider | +| 20 | `createStreamFn` | Sostituisce completamente il normale percorso di stream con un trasporto personalizzato | Il provider richiede un protocollo wire personalizzato, non solo un wrapper | +| 21 | `wrapStreamFn` | Wrapper dello stream dopo l'applicazione dei wrapper generici | Il provider richiede wrapper di compatibilità per header/body/modello della richiesta senza un trasporto personalizzato | +| 22 | `resolveTransportTurnState` | Collega header o metadati nativi per turno al trasporto | Il provider vuole che i trasporti generici inviino l'identità del turno nativa del provider | +| 23 | `resolveWebSocketSessionPolicy` | Collega header WebSocket nativi o una policy di cool-down della sessione | Il provider vuole che i trasporti WS generici regolino gli header di sessione o la policy di fallback | +| 24 | `formatApiKey` | Formatter del profilo di autenticazione: il profilo memorizzato diventa la stringa `apiKey` di runtime | Il provider memorizza metadati di autenticazione aggiuntivi e richiede una forma personalizzata del token di runtime | +| 25 | `refreshOAuth` | Override dell'aggiornamento OAuth per endpoint di refresh personalizzati o policy di errore nel refresh | Il provider non rientra nei refresher condivisi `pi-ai` | +| 26 | `buildAuthDoctorHint` | Suggerimento di riparazione aggiunto quando il refresh OAuth fallisce | Il provider richiede indicazioni di riparazione dell'autenticazione possedute dal provider dopo un errore di refresh | +| 27 | `matchesContextOverflowError` | Matcher posseduto dal provider per overflow della finestra di contesto | Il provider ha errori raw di overflow che le euristiche generiche non intercetterebbero | +| 28 | `classifyFailoverReason` | Classificazione della ragione di failover posseduta dal provider | Il provider può mappare errori raw di API/trasporto a rate-limit/sovraccarico/ecc. | +| 29 | `isCacheTtlEligible` | Policy della prompt-cache per provider proxy/backhaul | Il provider richiede gating TTL della cache specifico per il proxy | +| 30 | `buildMissingAuthMessage` | Sostituzione del messaggio generico di recupero per autenticazione mancante | Il provider richiede un suggerimento di recupero per autenticazione mancante specifico del provider | +| 31 | `suppressBuiltInModel` | Soppressione di modelli upstream obsoleti più eventuale suggerimento d'errore rivolto all'utente | Il provider deve nascondere righe upstream obsolete o sostituirle con un suggerimento del vendor | +| 32 | `augmentModelCatalog` | Righe di catalogo sintetiche/finali aggiunte dopo l'individuazione | Il provider richiede righe sintetiche di forward-compat in `models list` e nei selettori | +| 33 | `isBinaryThinking` | Toggle di ragionamento on/off per provider con binary thinking | Il provider espone solo ragionamento binario attivo/disattivo | +| 34 | `supportsXHighThinking` | Supporto al ragionamento `xhigh` per modelli selezionati | Il provider vuole `xhigh` solo su un sottoinsieme di modelli | +| 35 | `resolveDefaultThinkingLevel` | Livello `/think` predefinito per una specifica famiglia di modelli | Il provider possiede la policy `/think` predefinita per una famiglia di modelli | +| 36 | `isModernModelRef` | Matcher di modelli moderni per filtri di profili live e selezione smoke | Il provider possiede il matching del modello preferito per live/smoke | +| 37 | `prepareRuntimeAuth` | Scambia una credenziale configurata con il token/chiave effettivo di runtime subito prima dell'inferenza | Il provider richiede uno scambio di token o una credenziale di richiesta di breve durata | +| 38 | `resolveUsageAuth` | Risolve le credenziali di utilizzo/fatturazione per `/usage` e superfici di stato correlate | Il provider richiede parsing personalizzato del token di utilizzo/quota o una credenziale di utilizzo diversa | +| 39 | `fetchUsageSnapshot` | Recupera e normalizza snapshot di utilizzo/quota specifici del provider dopo che l'autenticazione è risolta | Il provider richiede un endpoint di utilizzo specifico del provider o un parser del payload | +| 40 | `createEmbeddingProvider` | Costruisce un adattatore di embedding posseduto dal provider per memoria/ricerca | Il comportamento di embedding della memoria appartiene al plugin provider | +| 41 | `buildReplayPolicy` | Restituisce una policy di replay che controlla la gestione della trascrizione per il provider | Il provider richiede una policy personalizzata per la trascrizione (ad esempio la rimozione dei blocchi di thinking) | +| 42 | `sanitizeReplayHistory` | Riscrive la cronologia di replay dopo la pulizia generica della trascrizione | Il provider richiede riscritture di replay specifiche del provider oltre agli helper condivisi di compattazione | +| 43 | `validateReplayTurns` | Validazione finale o rimodellamento dei turni di replay prima dell'embedded runner | Il trasporto del provider richiede una validazione dei turni più rigorosa dopo la sanitizzazione generica | +| 44 | `onModelSelected` | Esegue effetti collaterali post-selezione posseduti dal provider | Il provider richiede telemetria o stato posseduto dal provider quando un modello diventa attivo | `normalizeModelId`, `normalizeTransport` e `normalizeConfig` controllano prima il -plugin provider corrispondente, poi passano agli altri plugin provider abilitati agli hook -finché uno non modifica effettivamente l'id modello o il trasporto/configurazione. Questo mantiene -funzionanti gli shim di alias/compatibilità dei provider senza richiedere al chiamante di sapere quale -plugin incluso possiede la riscrittura. Se nessun hook provider riscrive una voce di configurazione supportata -della famiglia Google, il normalizzatore di configurazione Google incluso applica comunque quella pulizia di compatibilità. +plugin provider corrispondente, poi passano agli altri plugin provider capaci di hook +finché uno non modifica effettivamente l'ID del modello o il trasporto/la configurazione. Questo mantiene +funzionanti gli shim di alias/compatibilità del provider senza richiedere al chiamante di sapere quale +plugin bundled possiede la riscrittura. Se nessun hook provider riscrive una voce di configurazione supportata +della famiglia Google, il normalizzatore di configurazione Google bundled applica comunque +quella pulizia di compatibilità. -Se il provider ha bisogno di un protocollo wire completamente personalizzato o di un esecutore di richieste personalizzato, +Se il provider richiede un protocollo wire completamente personalizzato o un esecutore di richieste personalizzato, si tratta di una classe diversa di estensione. Questi hook servono per il comportamento del provider che continua a essere eseguito nel normale loop di inferenza di OpenClaw. @@ -779,112 +787,107 @@ api.registerProvider({ `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` e `wrapStreamFn` perché possiede la forward-compat di Claude 4.6, - gli hint della famiglia provider, la guida alla riparazione dell'autenticazione, l'integrazione - dell'endpoint di utilizzo, l'idoneità della cache del prompt, i valori predefiniti della configurazione consapevoli dell'autenticazione, la - policy di thinking predefinita/adattiva di Claude e la modellazione dello stream specifica di Anthropic per + i suggerimenti della famiglia provider, la guida di riparazione dell'autenticazione, l'integrazione + dell'endpoint di utilizzo, l'idoneità della prompt-cache, i valori predefiniti di configurazione sensibili all'autenticazione, la policy di thinking + predefinita/adattiva di Claude e il model shaping dello stream specifico di Anthropic per header beta, `/fast` / `serviceTier` e `context1m`. -- Gli helper di stream specifici di Claude di Anthropic restano per ora nel - proprio seam pubblico `api.ts` / `contract-api.ts` del plugin incluso. Questa superficie del pacchetto +- Gli helper di stream specifici di Claude di Anthropic restano per ora nella + propria seam pubblica `api.ts` / `contract-api.ts` del plugin bundled. Questa superficie del pacchetto esporta `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, - `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` e i builder di wrapper Anthropic - di livello inferiore invece di ampliare l'SDK generico intorno alle regole degli header beta di un singolo + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` e i builder di wrapper Anthropic di livello inferiore invece di ampliare l'SDK generico attorno alle regole degli header beta di un solo provider. - OpenAI usa `resolveDynamicModel`, `normalizeResolvedModel` e `capabilities` più `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` e `isModernModelRef` perché possiede la forward-compat di GPT-5.4, la normalizzazione diretta di OpenAI - `openai-completions` -> `openai-responses`, gli hint di autenticazione consapevoli di Codex, + `openai-completions` -> `openai-responses`, i suggerimenti di autenticazione consapevoli di Codex, la soppressione di Spark, le righe sintetiche dell'elenco OpenAI e la policy di thinking / modello live di GPT-5; la famiglia di stream `openai-responses-defaults` possiede i wrapper condivisi nativi di OpenAI Responses per header di attribuzione, `/fast`/`serviceTier`, verbosità del testo, ricerca web nativa di Codex, - modellazione del payload di compatibilità del ragionamento e gestione del contesto di Responses. + model shaping del payload di compatibilità del reasoning e gestione del contesto di Responses. - OpenRouter usa `catalog` più `resolveDynamicModel` e `prepareDynamicModel` perché il provider è pass-through e può esporre nuovi - id modello prima che il catalogo statico di OpenClaw venga aggiornato; usa anche + ID modello prima che il catalogo statico di OpenClaw venga aggiornato; usa anche `capabilities`, `wrapStreamFn` e `isCacheTtlEligible` per mantenere - fuori dal core header di richiesta specifici del provider, metadati di routing, patch di ragionamento e - policy della cache del prompt. La sua policy di replay proviene dalla + header di richiesta specifici del provider, metadati di routing, patch del reasoning e + policy della prompt-cache fuori dal core. La sua policy di replay proviene dalla famiglia `passthrough-gemini`, mentre la famiglia di stream `openrouter-thinking` - possiede l'iniezione del ragionamento del proxy e i salti di modello non supportato / `auto`. + possiede l'iniezione del reasoning del proxy e i salti per modello non supportato / `auto`. - GitHub Copilot usa `catalog`, `auth`, `resolveDynamicModel` e - `capabilities` più `prepareRuntimeAuth` e `fetchUsageSnapshot` perché - ha bisogno di login del dispositivo posseduto dal provider, comportamento di fallback del modello, peculiarità - della trascrizione di Claude, uno scambio da token GitHub a token Copilot e un endpoint di utilizzo posseduto dal provider. + `capabilities` più `prepareRuntimeAuth` e `fetchUsageSnapshot` perché ha + bisogno di login dispositivo posseduto dal provider, comportamento di fallback del modello, peculiarità della trascrizione di Claude, + uno scambio token GitHub -> token Copilot e un endpoint di utilizzo posseduto dal provider. - OpenAI Codex usa `catalog`, `resolveDynamicModel`, `normalizeResolvedModel`, `refreshOAuth` e `augmentModelCatalog` più - `prepareExtraParams`, `resolveUsageAuth` e `fetchUsageSnapshot` perché - continua a funzionare sui trasporti core OpenAI ma possiede la propria normalizzazione - di trasporto/base URL, la policy di fallback del refresh OAuth, la scelta predefinita del trasporto, - le righe sintetiche del catalogo Codex e l'integrazione dell'endpoint di utilizzo ChatGPT; condivide - la stessa famiglia di stream `openai-responses-defaults` dell'OpenAI diretto. + `prepareExtraParams`, `resolveUsageAuth` e `fetchUsageSnapshot` perché continua + a funzionare sui trasporti OpenAI del core ma possiede la propria normalizzazione di + trasporto/base URL, la policy di fallback per il refresh OAuth, la scelta predefinita del trasporto, + le righe sintetiche del catalogo Codex e l'integrazione dell'endpoint di utilizzo di ChatGPT; condivide + la stessa famiglia di stream `openai-responses-defaults` di OpenAI diretto. - Google AI Studio e Gemini CLI OAuth usano `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, `resolveReasoningOutputMode`, `wrapStreamFn` e `isModernModelRef` perché la famiglia di replay `google-gemini` possiede il fallback di forward-compat di Gemini 3.1, - la validazione nativa del replay Gemini, la sanificazione del replay di bootstrap, la modalità di - output di ragionamento taggata e il matching dei modelli moderni, mentre la + la validazione nativa del replay Gemini, la sanitizzazione del replay di bootstrap, la modalità di output del reasoning + con tag e il matching dei modelli moderni, mentre la famiglia di stream `google-thinking` possiede la normalizzazione del payload di thinking di Gemini; Gemini CLI OAuth usa anche `formatApiKey`, `resolveUsageAuth` e - `fetchUsageSnapshot` per formattazione del token, parsing del token e - collegamento dell'endpoint della quota. + `fetchUsageSnapshot` per formattazione del token, parsing del token e collegamento + dell'endpoint quota. - Anthropic Vertex usa `buildReplayPolicy` tramite la - famiglia di replay `anthropic-by-model`, così la pulizia del replay specifica di Claude resta - limitata agli id Claude invece che a ogni trasporto `anthropic-messages`. + famiglia di replay `anthropic-by-model` così la pulizia del replay specifica di Claude resta + limitata agli ID Claude invece che a ogni trasporto `anthropic-messages`. - Amazon Bedrock usa `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` e `resolveDefaultThinkingLevel` perché possiede la classificazione - degli errori specifici di Bedrock per throttle/not-ready/context-overflow - per il traffico Anthropic-on-Bedrock; la sua policy di replay condivide comunque la stessa - guardia solo-Claude `anthropic-by-model`. + `classifyFailoverReason` e `resolveDefaultThinkingLevel` perché possiede + la classificazione degli errori specifica di Bedrock per throttling/non pronto/overflow del contesto + per il traffico Anthropic-on-Bedrock; la sua policy di replay condivide comunque lo stesso + guard solo-Claude `anthropic-by-model`. - OpenRouter, Kilocode, Opencode e Opencode Go usano `buildReplayPolicy` - tramite la famiglia di replay `passthrough-gemini` perché fanno proxy dei modelli Gemini - tramite trasporti compatibili con OpenAI e hanno bisogno della - sanificazione della thought-signature di Gemini senza validazione nativa del replay Gemini né + tramite la famiglia di replay `passthrough-gemini` perché fanno da proxy ai modelli Gemini + tramite trasporti compatibili con OpenAI e necessitano della + sanitizzazione della thought-signature di Gemini senza validazione nativa del replay Gemini né riscritture di bootstrap. - MiniMax usa `buildReplayPolicy` tramite la famiglia di replay `hybrid-anthropic-openai` perché un unico provider possiede sia la semantica - dei messaggi Anthropic sia quella compatibile con OpenAI; mantiene la rimozione dei blocchi di thinking solo-Claude - sul lato Anthropic, riportando la modalità di output del ragionamento a nativa, e la famiglia di stream `minimax-fast-mode` - possiede le riscritture dei modelli in fast mode sul percorso stream condiviso. -- Moonshot usa `catalog` più `wrapStreamFn` perché continua a usare il trasporto - OpenAI condiviso ma ha bisogno della normalizzazione del payload di thinking posseduta dal provider; la - famiglia di stream `moonshot-thinking` mappa configurazione più stato `/think` sul suo - payload nativo di thinking binario. + di messaggi Anthropic sia quella compatibile con OpenAI; mantiene la rimozione dei blocchi di thinking solo-Claude + sul lato Anthropic, mentre riporta la modalità di output del reasoning a quella nativa, e la famiglia di stream `minimax-fast-mode` + possiede le riscritture del modello in fast mode sul percorso di stream condiviso. +- Moonshot usa `catalog` più `wrapStreamFn` perché continua a usare il + trasporto OpenAI condiviso ma richiede una normalizzazione del payload di thinking posseduta dal provider; la + famiglia di stream `moonshot-thinking` mappa la configurazione più lo stato `/think` sul proprio payload nativo di binary thinking. - Kilocode usa `catalog`, `capabilities`, `wrapStreamFn` e `isCacheTtlEligible` perché ha bisogno di header di richiesta posseduti dal provider, - normalizzazione del payload di ragionamento, hint di trascrizione Gemini e - gating TTL della cache Anthropic; la famiglia di stream `kilocode-thinking` mantiene l'iniezione del thinking di Kilo - sul percorso stream proxy condiviso saltando `kilo/auto` e - altri id modello proxy che non supportano payload di ragionamento espliciti. + normalizzazione del payload di reasoning, suggerimenti di trascrizione Gemini e gating TTL della cache Anthropic; + la famiglia di stream `kilocode-thinking` mantiene l'iniezione del thinking Kilo + sul percorso di stream proxy condiviso saltando `kilo/auto` e + altri ID modello proxy che non supportano payload di reasoning espliciti. - Z.AI usa `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, `resolveUsageAuth` e `fetchUsageSnapshot` perché possiede il fallback GLM-5, - i valori predefiniti `tool_stream`, UX di thinking binario, matching dei modelli moderni e sia - l'autenticazione d'uso sia il recupero della quota; la famiglia di stream `tool-stream-default-on` mantiene + i valori predefiniti `tool_stream`, la UX del binary thinking, il matching dei modelli moderni e sia + l'autenticazione per l'utilizzo sia il recupero della quota; la famiglia di stream `tool-stream-default-on` mantiene il wrapper `tool_stream` attivo per impostazione predefinita fuori dalla colla scritta a mano per singolo provider. - xAI usa `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` e `isModernModelRef` - perché possiede la normalizzazione nativa del trasporto xAI Responses, le riscritture degli alias - fast-mode di Grok, il valore predefinito `tool_stream`, la pulizia rigorosa degli strumenti / del payload di ragionamento, - il riuso dell'autenticazione di fallback per gli strumenti posseduti dal plugin, la risoluzione forward-compat dei modelli Grok - e patch di compatibilità possedute dal provider come il profilo di schema degli strumenti xAI, - keyword di schema non supportate, `web_search` nativo e la decodifica degli argomenti - delle chiamate strumento con entità HTML. + perché possiede la normalizzazione nativa del trasporto xAI Responses, le riscritture alias della fast mode di Grok, il `tool_stream` predefinito, la pulizia di strict-tool / payload di reasoning, + il riuso dell'autenticazione di fallback per gli strumenti posseduti dal plugin, la risoluzione forward-compat del modello Grok e patch di compatibilità possedute dal provider come il profilo di schema degli strumenti xAI, + keyword di schema non supportate, `web_search` nativo e la decodifica delle entità HTML + negli argomenti delle chiamate di strumenti. - Mistral, OpenCode Zen e OpenCode Go usano solo `capabilities` per mantenere - le particolarità di trascrizione/tooling fuori dal core. -- I provider inclusi solo catalogo come `byteplus`, `cloudflare-ai-gateway`, + le peculiarità di trascrizione/strumentazione fuori dal core. +- I provider bundled solo catalogo come `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` e `volcengine` usano solo `catalog`. -- Qwen usa `catalog` per il proprio provider di testo più registrazioni condivise di comprensione dei media e - generazione video per le sue superfici multimodali. +- Qwen usa `catalog` per il proprio provider testuale più registrazioni condivise di comprensione dei media e generazione video per le sue superfici multimodali. - MiniMax e Xiaomi usano `catalog` più hook di utilizzo perché il loro comportamento `/usage` - è posseduto dal plugin anche se l'inferenza continua a passare per i trasporti condivisi. + è posseduto dal plugin anche se l'inferenza continua a passare attraverso i trasporti condivisi. ## Helper di runtime -I plugin possono accedere ad alcuni helper selezionati del core tramite `api.runtime`. Per TTS: +I plugin possono accedere a helper selezionati del core tramite `api.runtime`. Per la TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -906,10 +909,10 @@ const voices = await api.runtime.tts.listVoices({ Note: - `textToSpeech` restituisce il normale payload di output TTS del core per superfici file/messaggio vocale. -- Usa la configurazione `messages.tts` del core e la selezione del provider. +- Usa la configurazione core `messages.tts` e la selezione del provider. - Restituisce buffer audio PCM + sample rate. I plugin devono ricampionare/codificare per i provider. -- `listVoices` è facoltativo per provider. Usalo per picker di voce o flussi di setup posseduti dal vendor. -- Gli elenchi di voci possono includere metadati più ricchi come tag di lingua, genere e personalità per picker consapevoli del provider. +- `listVoices` è facoltativo per provider. Usalo per selettori vocali o flussi di setup posseduti dal vendor. +- Gli elenchi di voci possono includere metadati più ricchi come locale, genere e tag di personalità per selettori consapevoli del provider. - OpenAI ed ElevenLabs supportano oggi la telefonia. Microsoft no. I plugin possono anche registrare provider vocali tramite `api.registerSpeechProvider(...)`. @@ -934,13 +937,13 @@ Note: - Mantieni nel core la policy TTS, il fallback e la consegna delle risposte. - Usa i provider vocali per il comportamento di sintesi posseduto dal vendor. -- L'input legacy Microsoft `edge` viene normalizzato all'id provider `microsoft`. -- Il modello di proprietà preferito è orientato all'azienda: un unico plugin vendor può possedere - testo, voce, immagini e futuri provider media man mano che OpenClaw aggiunge questi +- L'input legacy Microsoft `edge` viene normalizzato all'ID provider `microsoft`. +- Il modello di proprietà preferito è orientato all'azienda: un solo plugin vendor può possedere + provider testuali, vocali, di immagini e futuri provider media man mano che OpenClaw aggiunge questi contratti di capacità. -Per la comprensione di immagini/audio/video, i plugin registrano un unico provider tipizzato -di media-understanding invece di una generica raccolta chiave/valore: +Per la comprensione di immagini/audio/video, i plugin registrano un solo provider tipizzato di +media-understanding invece di una generica raccolta chiave/valore: ```ts api.registerMediaUnderstandingProvider({ @@ -954,16 +957,16 @@ api.registerMediaUnderstandingProvider({ Note: -- Mantieni nel core orchestrazione, fallback, configurazione e wiring dei canali. -- Mantieni il comportamento vendor nel plugin provider. -- L'espansione additiva dovrebbe restare tipizzata: nuovi metodi opzionali, nuovi campi - di risultato opzionali, nuove capacità opzionali. -- La generazione video segue già lo stesso schema: +- Mantieni orchestrazione, fallback, configurazione e wiring dei canali nel core. +- Mantieni il comportamento del vendor nel plugin provider. +- L'espansione additiva dovrebbe restare tipizzata: nuovi metodi facoltativi, nuovi campi risultato + facoltativi, nuove capacità facoltative. +- La generazione video segue già lo stesso pattern: - il core possiede il contratto di capacità e l'helper di runtime - i plugin vendor registrano `api.registerVideoGenerationProvider(...)` - i plugin di funzionalità/canale consumano `api.runtime.videoGeneration.*` -Per gli helper di runtime di media-understanding, i plugin possono chiamare: +Per gli helper di runtime media-understanding, i plugin possono chiamare: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -978,14 +981,14 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Per la trascrizione audio, i plugin possono usare il runtime di media-understanding +Per la trascrizione audio, i plugin possono usare il runtime media-understanding oppure il vecchio alias STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Facoltativo quando il MIME non può essere dedotto in modo affidabile: + // Optional when MIME cannot be inferred reliably: mime: "audio/ogg", }); ``` @@ -994,11 +997,11 @@ Note: - `api.runtime.mediaUnderstanding.*` è la superficie condivisa preferita per la comprensione di immagini/audio/video. -- Usa la configurazione audio di media-understanding del core (`tools.media.audio`) e l'ordine di fallback del provider. +- Usa la configurazione audio media-understanding del core (`tools.media.audio`) e l'ordine di fallback del provider. - Restituisce `{ text: undefined }` quando non viene prodotto alcun output di trascrizione (per esempio input saltato/non supportato). - `api.runtime.stt.transcribeAudioFile(...)` resta come alias di compatibilità. -I plugin possono anche avviare esecuzioni di subagent in background tramite `api.runtime.subagent`: +I plugin possono anche avviare esecuzioni in background di subagent tramite `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1013,13 +1016,13 @@ const result = await api.runtime.subagent.run({ Note: - `provider` e `model` sono override facoltativi per singola esecuzione, non modifiche persistenti della sessione. -- OpenClaw applica questi campi di override solo per chiamanti attendibili. -- Per le esecuzioni di fallback possedute dal plugin, gli operatori devono aderire esplicitamente con `plugins.entries..subagent.allowModelOverride: true`. -- Usa `plugins.entries..subagent.allowedModels` per limitare i plugin attendibili a specifici target canonici `provider/model`, oppure `"*"` per consentire esplicitamente qualsiasi target. -- Le esecuzioni di subagent di plugin non attendibili continuano a funzionare, ma le richieste di override vengono rifiutate invece di ricadere silenziosamente su un fallback. +- OpenClaw onora questi campi di override solo per chiamanti attendibili. +- Per le esecuzioni di fallback possedute dal plugin, gli operatori devono effettuare l'opt-in con `plugins.entries..subagent.allowModelOverride: true`. +- Usa `plugins.entries..subagent.allowedModels` per limitare i plugin attendibili a target canonici specifici `provider/model`, oppure `"*"` per consentire esplicitamente qualsiasi target. +- Le esecuzioni subagent di plugin non attendibili continuano a funzionare, ma le richieste di override vengono rifiutate invece di ricadere silenziosamente nel fallback. Per la ricerca web, i plugin possono consumare l'helper di runtime condiviso invece di -accedere al wiring dello strumento dell'agente: +entrare nel wiring dello strumento agente: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1041,8 +1044,8 @@ I plugin possono anche registrare provider di ricerca web tramite Note: - Mantieni nel core la selezione del provider, la risoluzione delle credenziali e la semantica condivisa delle richieste. -- Usa i provider di ricerca web per trasporti di ricerca specifici del vendor. -- `api.runtime.webSearch.*` è la superficie condivisa preferita per i plugin di funzionalità/canale che hanno bisogno del comportamento di ricerca senza dipendere dal wrapper dello strumento dell'agente. +- Usa i provider di ricerca web per i trasporti di ricerca specifici del vendor. +- `api.runtime.webSearch.*` è la superficie condivisa preferita per i plugin di funzionalità/canale che hanno bisogno di comportamento di ricerca senza dipendere dal wrapper dello strumento agente. ### `api.runtime.imageGeneration` @@ -1080,7 +1083,7 @@ api.registerHttpRoute({ Campi della route: - `path`: percorso della route sotto il server HTTP del gateway. -- `auth`: obbligatorio. Usa `"gateway"` per richiedere la normale autenticazione del gateway, oppure `"plugin"` per autenticazione/verifica webhook gestita dal plugin. +- `auth`: obbligatorio. Usa `"gateway"` per richiedere la normale autenticazione del gateway, oppure `"plugin"` per autenticazione/validazione webhook gestita dal plugin. - `match`: facoltativo. `"exact"` (predefinito) oppure `"prefix"`. - `replaceExisting`: facoltativo. Consente allo stesso plugin di sostituire la propria registrazione di route esistente. - `handler`: restituisce `true` quando la route ha gestito la richiesta. @@ -1088,26 +1091,26 @@ Campi della route: Note: - `api.registerHttpHandler(...)` è stato rimosso e causerà un errore di caricamento del plugin. Usa invece `api.registerHttpRoute(...)`. -- Le route dei plugin devono dichiarare esplicitamente `auth`. +- Le route dei plugin devono dichiarare `auth` esplicitamente. - I conflitti esatti `path + match` vengono rifiutati a meno che `replaceExisting: true`, e un plugin non può sostituire la route di un altro plugin. -- Le route sovrapposte con livelli `auth` diversi vengono rifiutate. Mantieni le catene di fallthrough `exact`/`prefix` solo allo stesso livello di autenticazione. -- Le route `auth: "plugin"` **non** ricevono automaticamente scope di runtime dell'operatore. Servono per webhook/verifica di firma gestiti dal plugin, non per chiamate helper privilegiate del Gateway. +- Le route sovrapposte con livelli `auth` diversi vengono rifiutate. Mantieni le catene di fallthrough `exact`/`prefix` solo allo stesso livello di auth. +- Le route `auth: "plugin"` **non** ricevono automaticamente scope di runtime operatore. Servono per webhook/validazione firme gestiti dal plugin, non per chiamate helper del Gateway con privilegi. - Le route `auth: "gateway"` vengono eseguite all'interno di uno scope di runtime della richiesta Gateway, ma tale scope è intenzionalmente conservativo: - - l'autenticazione bearer con secret condiviso (`gateway.auth.mode = "token"` / `"password"`) mantiene gli scope di runtime delle route plugin bloccati su `operator.write`, anche se il chiamante invia `x-openclaw-scopes` - - le modalità HTTP attendibili basate su identità (per esempio `trusted-proxy` o `gateway.auth.mode = "none"` su un ingresso privato) rispettano `x-openclaw-scopes` solo quando l'header è esplicitamente presente + - l'autenticazione bearer con segreto condiviso (`gateway.auth.mode = "token"` / `"password"`) mantiene gli scope di runtime delle route plugin fissati a `operator.write`, anche se il chiamante invia `x-openclaw-scopes` + - le modalità HTTP affidabili basate su identità (per esempio `trusted-proxy` o `gateway.auth.mode = "none"` su un ingresso privato) onorano `x-openclaw-scopes` solo quando l'header è esplicitamente presente - se `x-openclaw-scopes` è assente in quelle richieste di route plugin basate su identità, lo scope di runtime ricade su `operator.write` -- Regola pratica: non presumere che una route plugin autenticata via gateway sia implicitamente una superficie admin. Se la tua route richiede un comportamento solo admin, richiedi una modalità di autenticazione basata su identità e documenta il contratto esplicito dell'header `x-openclaw-scopes`. +- Regola pratica: non presumere che una route plugin con autenticazione gateway sia implicitamente una superficie admin. Se la tua route richiede comportamento solo admin, richiedi una modalità di autenticazione basata su identità e documenta il contratto esplicito dell'header `x-openclaw-scopes`. -## Percorsi di importazione dell'SDK dei plugin +## Percorsi di import dell'SDK plugin Usa i sottopercorsi dell'SDK invece dell'import monolitico `openclaw/plugin-sdk` quando scrivi plugin: - `openclaw/plugin-sdk/plugin-entry` per le primitive di registrazione dei plugin. -- `openclaw/plugin-sdk/core` per il contratto condiviso generico rivolto ai plugin. -- `openclaw/plugin-sdk/config-schema` per l'esportazione dello schema Zod root di `openclaw.json` +- `openclaw/plugin-sdk/core` per il contratto generico condiviso rivolto ai plugin. +- `openclaw/plugin-sdk/config-schema` per l'esportazione dello schema Zod root `openclaw.json` (`OpenClawSchema`). -- Primitive di canale stabili come `openclaw/plugin-sdk/channel-setup`, +- Primitive stabili di canale come `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/setup-tools`, @@ -1119,15 +1122,15 @@ scrivi plugin: `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` e - `openclaw/plugin-sdk/webhook-ingress` per wiring condiviso di setup/autenticazione/risposta/webhook. - `channel-inbound` è la sede condivisa per debounce, matching delle mention, - helper della policy delle mention in ingresso, formattazione delle envelope e helper - del contesto delle envelope in ingresso. - `channel-setup` è il seam ristretto di setup con installazione facoltativa. + `openclaw/plugin-sdk/webhook-ingress` per il wiring condiviso di setup/auth/reply/webhook. + `channel-inbound` è la sede condivisa per debounce, corrispondenza delle mention, + helper della mention-policy inbound, formattazione delle envelope e helper del contesto + delle envelope inbound. + `channel-setup` è la seam ristretta di setup con installazione facoltativa. `setup-runtime` è la superficie di setup sicura per il runtime usata da `setupEntry` / - avvio differito, inclusi gli adapter di patch setup sicuri per l'importazione. - `setup-adapter-runtime` è il seam degli adapter di setup account consapevoli dell'env. - `setup-tools` è il piccolo seam helper per CLI/archivio/documentazione (`formatCliCommand`, + avvio differito, inclusi gli adattatori di patch di setup sicuri per l'import. + `setup-adapter-runtime` è la seam dell'adattatore di setup account consapevole dell'env. + `setup-tools` è la piccola seam helper per CLI/archivi/documentazione (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). - Sottopercorsi di dominio come `openclaw/plugin-sdk/channel-config-helpers`, @@ -1149,110 +1152,104 @@ scrivi plugin: `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` e `openclaw/plugin-sdk/directory-runtime` per helper condivisi di runtime/configurazione. - `telegram-command-config` è il seam pubblico ristretto per normalizzazione/validazione - dei comandi personalizzati di Telegram e resta disponibile anche se la superficie contrattuale - Telegram inclusa non è temporaneamente disponibile. - `text-runtime` è il seam condiviso per testo/markdown/logging, inclusi - rimozione del testo visibile all'assistente, helper di rendering/chunking markdown, helper di redazione, - helper per directive-tag e utility di testo sicuro. -- I seam di canale specifici per l'approvazione dovrebbero preferire un unico contratto - `approvalCapability` sul plugin. Il core legge poi autenticazione di approvazione, consegna, rendering, - routing nativo e comportamento lazy del gestore nativo tramite quell'unica capacità - invece di mischiare il comportamento di approvazione in campi del plugin non correlati. -- `openclaw/plugin-sdk/channel-runtime` è deprecato e resta solo come - shim di compatibilità per plugin più vecchi. Il nuovo codice dovrebbe importare invece le - primitive generiche più ristrette, e il codice del repository non dovrebbe aggiungere nuovi import dello + `telegram-command-config` è la seam pubblica ristretta per normalizzazione/validazione dei + comandi personalizzati Telegram e resta disponibile anche se la superficie di contratto Telegram bundled è temporaneamente non disponibile. + `text-runtime` è la seam condivisa per testo/Markdown/logging, inclusi + stripping del testo visibile all'assistente, helper di rendering/chunking Markdown, helper di redazione, helper dei tag direttiva e utilità di testo sicuro. +- Le seam di canale specifiche per l'approvazione dovrebbero preferire un singolo contratto `approvalCapability` + sul plugin. Il core legge poi autenticazione di approvazione, consegna, render, + routing nativo e comportamento lazy del gestore nativo tramite quella sola capacità + invece di mescolare il comportamento di approvazione in campi non correlati del plugin. +- `openclaw/plugin-sdk/channel-runtime` è deprecato e rimane solo come + shim di compatibilità per plugin meno recenti. Il nuovo codice dovrebbe importare invece le primitive generiche più ristrette, e il codice del repo non dovrebbe aggiungere nuovi import dello shim. -- Gli elementi interni delle estensioni incluse restano privati. I plugin esterni dovrebbero usare solo - i sottopercorsi `openclaw/plugin-sdk/*`. Il codice core/test di OpenClaw può usare gli - entry point pubblici del repository sotto la root di un pacchetto plugin come `index.js`, `api.js`, - `runtime-api.js`, `setup-entry.js` e file con ambito ristretto come +- Gli interni delle estensioni bundled restano privati. I plugin esterni dovrebbero usare solo i sottopercorsi `openclaw/plugin-sdk/*`. Il codice core/test di OpenClaw può usare i + punti di ingresso pubblici del repo sotto la root di un pacchetto plugin come `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js` e file a ambito ristretto come `login-qr-api.js`. Non importare mai `src/*` di un pacchetto plugin dal core o da un'altra estensione. -- Suddivisione degli entry point del repository: - `/api.js` è il barrel di helper/tipi, +- Suddivisione dei punti di ingresso del repo: + `/api.js` è il barrel helper/tipi, `/runtime-api.js` è il barrel solo runtime, - `/index.js` è l'entry del plugin incluso, + `/index.js` è l'entry del plugin bundled, e `/setup-entry.js` è l'entry del plugin di setup. -- Esempi attuali di provider inclusi: +- Esempi attuali di provider bundled: - Anthropic usa `api.js` / `contract-api.js` per helper di stream Claude come `wrapAnthropicProviderStream`, helper per header beta e parsing di `service_tier`. - - OpenAI usa `api.js` per builder di provider, helper per modelli predefiniti e - builder di provider realtime. - - OpenRouter usa `api.js` per il proprio builder di provider più helper di onboarding/configurazione, - mentre `register.runtime.js` può comunque riesportare helper generici - `plugin-sdk/provider-stream` per uso locale nel repository. -- Gli entry point pubblici caricati tramite facade preferiscono lo snapshot attivo della configurazione di runtime - quando esiste, poi ricadono sulla configurazione risolta su disco quando + - OpenAI usa `api.js` per builder provider, helper del modello predefinito e + builder provider realtime. + - OpenRouter usa `api.js` per il proprio builder provider più helper di onboarding/configurazione, mentre `register.runtime.js` può ancora riesportare helper generici `plugin-sdk/provider-stream` per uso locale nel repo. +- I punti di ingresso pubblici caricati tramite facade preferiscono lo snapshot attivo della configurazione di runtime + quando esiste, poi ricadono sul file di configurazione risolto su disco quando OpenClaw non sta ancora servendo uno snapshot di runtime. -- Le primitive condivise generiche restano il contratto pubblico preferito dell'SDK. Esiste ancora un piccolo - insieme di compatibilità riservato di seam helper brandizzati per canale incluso. Trattali come seam di manutenzione/compatibilità degli inclusi, non come nuovi target di importazione di terze parti; i nuovi contratti cross-channel dovrebbero comunque essere introdotti su sottopercorsi generici `plugin-sdk/*` oppure nei barrel locali del plugin `api.js` / +- Le primitive generiche condivise restano il contratto pubblico preferito dell'SDK. Esiste ancora un piccolo + insieme di compatibilità riservato di seam helper brandizzate per canali bundled. Trattale come seam di manutenzione/compatibilità bundled, non come nuovi target di import per terze parti; i nuovi contratti cross-channel dovrebbero comunque arrivare su sottopercorsi generici `plugin-sdk/*` o sui barrel locali del plugin `api.js` / `runtime-api.js`. Nota sulla compatibilità: - Evita il barrel root `openclaw/plugin-sdk` per il nuovo codice. -- Preferisci prima le primitive stabili ristrette. I sottopercorsi più recenti di setup/pairing/reply/ +- Preferisci prima le primitive stabili e ristrette. I sottopercorsi più recenti setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ allowlist/status/message-tool sono il contratto previsto per il nuovo - lavoro su plugin inclusi ed esterni. + lavoro su plugin bundled ed esterni. Il parsing/matching dei target appartiene a `openclaw/plugin-sdk/channel-targets`. - I gate delle azioni di messaggio e gli helper per gli id dei messaggi di reazione appartengono a + I gate delle azioni sui messaggi e gli helper message-id delle reazioni appartengono a `openclaw/plugin-sdk/channel-actions`. -- I barrel helper specifici delle estensioni incluse non sono stabili per impostazione predefinita. Se un - helper serve solo a un'estensione inclusa, tienilo dietro il seam locale - `api.js` o `runtime-api.js` dell'estensione invece di promuoverlo in +- I barrel helper specifici delle estensioni bundled non sono stabili per impostazione predefinita. Se un + helper serve solo a un'estensione bundled, tienilo dietro la seam locale `api.js` o `runtime-api.js` + dell'estensione invece di promuoverlo in `openclaw/plugin-sdk/`. -- I nuovi seam helper condivisi dovrebbero essere generici, non brandizzati per canale. Il parsing condiviso - dei target appartiene a `openclaw/plugin-sdk/channel-targets`; gli elementi interni specifici del canale - restano dietro il seam locale `api.js` o `runtime-api.js` del plugin proprietario. -- Sottopercorsi specifici per capacità come `image-generation`, - `media-understanding` e `speech` esistono perché i plugin inclusi/nativi li usano +- Le nuove seam helper condivise dovrebbero essere generiche, non brandizzate per canale. Il parsing condiviso dei target + appartiene a `openclaw/plugin-sdk/channel-targets`; gli interni specifici del canale + restano dietro la seam locale `api.js` o `runtime-api.js` del plugin proprietario. +- Sottopercorsi specifici della capacità come `image-generation`, + `media-understanding` e `speech` esistono perché i plugin bundled/nativi li usano oggi. La loro presenza non significa di per sé che ogni helper esportato sia un contratto esterno congelato a lungo termine. -## Schemi dello strumento di messaggio +## Schemi dello strumento dei messaggi I plugin dovrebbero possedere i contributi di schema specifici del canale per `describeMessageTool(...)`. Mantieni i campi specifici del provider nel plugin, non nel core condiviso. -Per frammenti di schema portabili condivisi, riusa gli helper generici esportati tramite +Per frammenti di schema condivisi e portabili, riusa gli helper generici esportati tramite `openclaw/plugin-sdk/channel-actions`: - `createMessageToolButtonsSchema()` per payload in stile griglia di pulsanti - `createMessageToolCardSchema()` per payload di card strutturate -Se una forma di schema ha senso solo per un provider, definiscila nel codice sorgente -di quel plugin invece di promuoverla nell'SDK condiviso. +Se una forma di schema ha senso solo per un provider, definiscila nel codice +del plugin stesso invece di promuoverla nell'SDK condiviso. ## Risoluzione dei target di canale -I plugin di canale dovrebbero possedere la semantica dei target specifica del canale. Mantieni -generico l'host outbound condiviso e usa la superficie dell'adapter di messaggistica per le regole del provider: +I plugin di canale dovrebbero possedere la semantica dei target specifica del canale. Mantieni generico +l'host outbound condiviso e usa la superficie dell'adattatore di messaggistica per le regole del provider: - `messaging.inferTargetChatType({ to })` decide se un target normalizzato - debba essere trattato come `direct`, `group` o `channel` prima della ricerca nella directory. -- `messaging.targetResolver.looksLikeId(raw, normalized)` indica al core se un - input deve saltare direttamente alla risoluzione in stile id invece che alla ricerca nella directory. + deve essere trattato come `direct`, `group` o `channel` prima del lookup nella directory. +- `messaging.targetResolver.looksLikeId(raw, normalized)` dice al core se un + input deve saltare direttamente alla risoluzione simile a ID invece che alla ricerca nella directory. - `messaging.targetResolver.resolveTarget(...)` è il fallback del plugin quando il core ha bisogno di una risoluzione finale posseduta dal provider dopo la normalizzazione o dopo un mancato riscontro nella directory. -- `messaging.resolveOutboundSessionRoute(...)` possiede la costruzione della route - di sessione specifica del provider una volta che un target è stato risolto. +- `messaging.resolveOutboundSessionRoute(...)` possiede la costruzione della route di sessione specifica del provider + una volta che un target è stato risolto. Suddivisione consigliata: - Usa `inferTargetChatType` per decisioni di categoria che dovrebbero avvenire prima - della ricerca di peer/gruppi. -- Usa `looksLikeId` per controlli del tipo "tratta questo come un id target esplicito/nativo". -- Usa `resolveTarget` per il fallback di normalizzazione specifico del provider, non per - una ricerca ampia nella directory. -- Mantieni gli id nativi del provider come chat id, thread id, JID, handle e room - id dentro i valori `target` o nei parametri specifici del provider, non in campi generici dell'SDK. + della ricerca in peer/gruppi. +- Usa `looksLikeId` per controlli del tipo “tratta questo come ID target esplicito/nativo”. +- Usa `resolveTarget` per il fallback di normalizzazione specifico del provider, non per una + ricerca ampia nella directory. +- Mantieni gli ID nativi del provider come chat id, thread id, JID, handle e room + id dentro valori `target` o parametri specifici del provider, non in campi SDK generici. ## Directory supportate dalla configurazione -I plugin che derivano voci di directory dalla configurazione dovrebbero mantenere questa logica nel +I plugin che derivano voci di directory dalla configurazione dovrebbero mantenere quella logica nel plugin e riutilizzare gli helper condivisi di `openclaw/plugin-sdk/directory-runtime`. @@ -1265,14 +1262,14 @@ Usalo quando un canale ha peer/gruppi supportati dalla configurazione come: Gli helper condivisi in `directory-runtime` gestiscono solo operazioni generiche: - filtraggio delle query -- applicazione dei limiti -- helper di deduplicazione/normalizzazione +- applicazione del limite +- helper di deduplica/normalizzazione - costruzione di `ChannelDirectoryEntry[]` -L'ispezione dell'account e la normalizzazione degli id specifiche del canale dovrebbero restare +L'ispezione specifica dell'account del canale e la normalizzazione degli ID dovrebbero restare nell'implementazione del plugin. -## Cataloghi dei provider +## Cataloghi provider I plugin provider possono definire cataloghi di modelli per l'inferenza con `registerProvider({ catalog: { run(...) { ... } } })`. @@ -1280,29 +1277,29 @@ I plugin provider possono definire cataloghi di modelli per l'inferenza con `catalog.run(...)` restituisce la stessa forma che OpenClaw scrive in `models.providers`: -- `{ provider }` per una voce di provider -- `{ providers }` per più voci di provider +- `{ provider }` per una voce provider +- `{ providers }` per più voci provider -Usa `catalog` quando il plugin possiede id modello specifici del provider, valori predefiniti di base URL +Usa `catalog` quando il plugin possiede ID modello specifici del provider, valori predefiniti di base URL o metadati di modello protetti da autenticazione. `catalog.order` controlla quando il catalogo di un plugin viene unito rispetto ai provider impliciti integrati di OpenClaw: -- `simple`: provider semplici basati su chiave API o env -- `profile`: provider che appaiono quando esistono profili di autenticazione -- `paired`: provider che sintetizzano più voci di provider correlate +- `simple`: provider semplici guidati da chiave API o env +- `profile`: provider che compaiono quando esistono profili di autenticazione +- `paired`: provider che sintetizzano più voci provider correlate - `late`: ultimo passaggio, dopo gli altri provider impliciti -I provider successivi vincono in caso di collisione di chiave, quindi i plugin possono -sostituire intenzionalmente una voce di provider integrata con lo stesso id provider. +I provider successivi vincono in caso di collisione di chiavi, così i plugin possono intenzionalmente sovrascrivere una +voce provider integrata con lo stesso ID provider. Compatibilità: -- `discovery` funziona ancora come alias legacy +- `discovery` continua a funzionare come alias legacy - se sono registrati sia `catalog` sia `discovery`, OpenClaw usa `catalog` -## Ispezione del canale in sola lettura +## Ispezione in sola lettura dei canali Se il tuo plugin registra un canale, preferisci implementare `plugin.config.inspectAccount(cfg, accountId)` insieme a `resolveAccount(...)`. @@ -1312,29 +1309,30 @@ Perché: - `resolveAccount(...)` è il percorso di runtime. Può presumere che le credenziali siano completamente materializzate e può fallire rapidamente quando mancano segreti richiesti. - I percorsi di comando in sola lettura come `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` e i flussi di riparazione - doctor/config non dovrebbero aver bisogno di materializzare credenziali di runtime solo per - descrivere la configurazione. + `openclaw channels status`, `openclaw channels resolve` e i flussi di doctor/riparazione + della configurazione non dovrebbero aver bisogno di materializzare credenziali di runtime solo + per descrivere la configurazione. Comportamento consigliato di `inspectAccount(...)`: -- Restituisci solo lo stato descrittivo dell'account. -- Preserva `enabled` e `configured`. -- Includi campi di sorgente/stato delle credenziali quando rilevanti, come: +- Restituire solo lo stato descrittivo dell'account. +- Preservare `enabled` e `configured`. +- Includere campi di sorgente/stato delle credenziali quando rilevanti, come: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Non è necessario restituire valori raw dei token solo per riportare la - disponibilità in sola lettura. Restituire `tokenStatus: "available"` (e il campo sorgente corrispondente) è sufficiente per i comandi di tipo stato. +- Non è necessario restituire i valori raw dei token solo per riportare la + disponibilità in sola lettura. Restituire `tokenStatus: "available"` (e il relativo campo di sorgente) è sufficiente per i comandi in stile status. - Usa `configured_unavailable` quando una credenziale è configurata tramite SecretRef ma non disponibile nel percorso di comando corrente. -Questo consente ai comandi in sola lettura di riportare "configurato ma non disponibile in questo percorso di comando" invece di andare in crash o segnalare erroneamente l'account come non configurato. +Questo consente ai comandi in sola lettura di riportare “configurato ma non disponibile in questo percorso di comando” +invece di andare in crash o riportare erroneamente l'account come non configurato. ## Package pack -Una directory di plugin può includere un `package.json` con `openclaw.extensions`: +Una directory plugin può includere un `package.json` con `openclaw.extensions`: ```json { @@ -1346,64 +1344,62 @@ Una directory di plugin può includere un `package.json` con `openclaw.extension } ``` -Ogni voce diventa un plugin. Se il pack elenca più estensioni, l'id del plugin +Ogni voce diventa un plugin. Se il pack elenca più estensioni, l'ID plugin diventa `name/`. -Se il tuo plugin importa dipendenze npm, installale in quella directory in modo che +Se il tuo plugin importa dipendenze npm, installale in quella directory così `node_modules` sia disponibile (`npm install` / `pnpm install`). -Guardrail di sicurezza: ogni voce `openclaw.extensions` deve restare all'interno della directory del plugin +Guardrail di sicurezza: ogni voce `openclaw.extensions` deve restare all'interno della directory plugin dopo la risoluzione dei symlink. Le voci che escono dalla directory del pacchetto vengono rifiutate. Nota di sicurezza: `openclaw plugins install` installa le dipendenze del plugin con -`npm install --omit=dev --ignore-scripts` (nessuno script del ciclo di vita, nessuna dipendenza di sviluppo a runtime). Mantieni gli alberi di dipendenze dei plugin "puri JS/TS" ed evita pacchetti che richiedono build `postinstall`. +`npm install --omit=dev --ignore-scripts` (nessuno script lifecycle, nessuna dipendenza dev a runtime). Mantieni gli alberi delle dipendenze dei plugin in “pure JS/TS” ed evita pacchetti che richiedono build `postinstall`. Facoltativo: `openclaw.setupEntry` può puntare a un modulo leggero solo setup. Quando OpenClaw ha bisogno di superfici di setup per un plugin di canale disabilitato, oppure quando un plugin di canale è abilitato ma ancora non configurato, carica `setupEntry` invece dell'entry completa del plugin. Questo mantiene avvio e setup più leggeri -quando l'entry principale del plugin collega anche strumenti, hook o altro codice solo runtime. +quando l'entry principale del plugin collega anche strumenti, hook o altro codice +solo runtime. Facoltativo: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -può fare aderire un plugin di canale allo stesso percorso `setupEntry` durante la fase -di avvio pre-listen del gateway, anche quando il canale è già configurato. +può includere un plugin di canale nello stesso percorso `setupEntry` durante la fase di +avvio pre-listen del gateway, anche quando il canale è già configurato. -Usa questa opzione solo quando `setupEntry` copre completamente la superficie di avvio che deve esistere -prima che il gateway inizi ad ascoltare. In pratica, ciò significa che l'entry di setup -deve registrare ogni capacità posseduta dal canale da cui l'avvio dipende, come: +Usalo solo quando `setupEntry` copre completamente la superficie di avvio che deve esistere +prima che il gateway inizi ad ascoltare. In pratica, questo significa che l'entry di setup +deve registrare ogni capacità posseduta dal canale da cui dipende l'avvio, come: -- la registrazione del canale stesso -- qualsiasi route HTTP che deve essere disponibile prima che il gateway inizi ad ascoltare -- qualsiasi metodo gateway, strumento o servizio che deve esistere durante quella stessa finestra +- la registrazione del canale stessa +- eventuali route HTTP che devono essere disponibili prima che il gateway inizi ad ascoltare +- eventuali metodi gateway, strumenti o servizi che devono esistere durante quella stessa finestra -Se la tua entry completa possiede ancora una capacità di avvio richiesta, non abilitare -questo flag. Mantieni il plugin nel comportamento predefinito e lascia che OpenClaw carichi -l'entry completa durante l'avvio. +Se la tua entry completa possiede ancora qualche capacità richiesta all'avvio, non abilitare +questo flag. Mantieni il comportamento predefinito del plugin e lascia che OpenClaw carichi l'entry completa durante l'avvio. -I canali inclusi possono anche pubblicare helper della superficie contrattuale solo setup che il core -può consultare prima che il runtime completo del canale sia caricato. L'attuale superficie -di promozione del setup è: +I canali bundled possono anche pubblicare helper di superficie contrattuale solo setup che il core +può consultare prima che il runtime completo del canale sia caricato. L'attuale superficie di promozione setup +è: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Il core usa questa superficie quando deve promuovere una configurazione di canale legacy single-account +Il core usa questa superficie quando deve promuovere una configurazione legacy di canale a account singolo in `channels..accounts.*` senza caricare l'entry completa del plugin. -Matrix è l'esempio incluso attuale: sposta solo chiavi di auth/bootstrap in un -account promosso con nome quando esistono già account con nome, e può preservare una -chiave default-account non canonica configurata invece di creare sempre +Matrix è l'esempio bundled attuale: sposta solo le chiavi auth/bootstrap in un +account promosso con nome quando esistono già account con nome e può preservare una +chiave default-account configurata non canonica invece di creare sempre `accounts.default`. -Questi adapter di patch setup mantengono lazy il rilevamento della superficie contrattuale inclusa. Il tempo -di importazione resta leggero; la superficie di promozione viene caricata solo al primo utilizzo invece di -rientrare nell'avvio del canale incluso durante l'importazione del modulo. +Questi adattatori di patch setup mantengono lazy l'individuazione della superficie contrattuale bundled. Il tempo di import resta leggero; la superficie di promozione viene caricata solo al primo utilizzo invece di rientrare nell'avvio del canale bundled all'import del modulo. Quando queste superfici di avvio includono metodi RPC del gateway, mantienili su un prefisso specifico del plugin. I namespace admin del core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) restano riservati e si risolvono sempre -in `operator.admin`, anche se un plugin richiede uno scope più ristretto. +`exec.approvals.*`, `wizard.*`, `update.*`) restano riservati e vengono sempre risolti +a `operator.admin`, anche se un plugin richiede uno scope più ristretto. Esempio: @@ -1420,10 +1416,10 @@ Esempio: } ``` -### Metadati del catalogo canali +### Metadati del catalogo dei canali -I plugin di canale possono pubblicizzare metadati di setup/rilevamento tramite `openclaw.channel` e -suggerimenti di installazione tramite `openclaw.install`. Questo mantiene il catalogo del core privo di dati. +I plugin di canale possono pubblicizzare metadati di setup/individuazione tramite `openclaw.channel` e +suggerimenti di installazione tramite `openclaw.install`. Questo mantiene il core privo di dati di catalogo. Esempio: @@ -1454,37 +1450,37 @@ Esempio: Campi utili di `openclaw.channel` oltre all'esempio minimo: - `detailLabel`: etichetta secondaria per superfici più ricche di catalogo/stato -- `docsLabel`: sostituisce il testo del link per il link alla documentazione -- `preferOver`: id plugin/canale a priorità inferiore che questa voce di catalogo dovrebbe superare -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: controlli del testo della superficie di selezione -- `markdownCapable`: contrassegna il canale come compatibile con Markdown per le decisioni di formattazione outbound +- `docsLabel`: sovrascrive il testo del link per il collegamento alla documentazione +- `preferOver`: ID plugin/canale a priorità più bassa che questa voce di catalogo dovrebbe superare +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: controlli di testo per la superficie di selezione +- `markdownCapable`: segna il canale come capace di Markdown per le decisioni di formattazione outbound - `exposure.configured`: nasconde il canale dalle superfici di elenco dei canali configurati quando impostato su `false` - `exposure.setup`: nasconde il canale dai picker interattivi di setup/configurazione quando impostato su `false` -- `exposure.docs`: contrassegna il canale come interno/privato per le superfici di navigazione della documentazione +- `exposure.docs`: segna il canale come interno/privato per le superfici di navigazione della documentazione - `showConfigured` / `showInSetup`: alias legacy ancora accettati per compatibilità; preferisci `exposure` -- `quickstartAllowFrom`: fa aderire il canale al flusso standard `allowFrom` del quickstart -- `forceAccountBinding`: richiede un binding esplicito dell'account anche quando esiste un solo account -- `preferSessionLookupForAnnounceTarget`: preferisce la ricerca della sessione durante la risoluzione dei target di announce +- `quickstartAllowFrom`: include il canale nel flusso standard quickstart `allowFrom` +- `forceAccountBinding`: richiede un account binding esplicito anche quando esiste un solo account +- `preferSessionLookupForAnnounceTarget`: preferisce il lookup di sessione durante la risoluzione dei target di annuncio -OpenClaw può anche unire **cataloghi di canali esterni** (per esempio un'esportazione -del registro MPM). Inserisci un file JSON in uno di questi percorsi: +OpenClaw può anche unire **cataloghi di canali esterni** (per esempio, un export di registro MPM). +Inserisci un file JSON in uno di questi percorsi: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` -Oppure imposta `OPENCLAW_PLUGIN_CATALOG_PATHS` (o `OPENCLAW_MPM_CATALOG_PATHS`) su -uno o più file JSON (delimitati da virgola/punto e virgola/`PATH`). Ogni file dovrebbe +Oppure punta `OPENCLAW_PLUGIN_CATALOG_PATHS` (o `OPENCLAW_MPM_CATALOG_PATHS`) a +uno o più file JSON (delimitati da virgole/punto e virgola/`PATH`). Ogni file dovrebbe contenere `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Il parser accetta anche `"packages"` o `"plugins"` come alias legacy per la chiave `"entries"`. ## Plugin del motore di contesto I plugin del motore di contesto possiedono l'orchestrazione del contesto di sessione per ingestione, assemblaggio e compattazione. Registrali dal tuo plugin con -`api.registerContextEngine(id, factory)`, quindi seleziona il motore attivo con +`api.registerContextEngine(id, factory)`, poi seleziona il motore attivo con `plugins.slots.contextEngine`. -Usa questo quando il tuo plugin ha bisogno di sostituire o estendere la pipeline di contesto +Usa questo quando il tuo plugin deve sostituire o estendere la pipeline di contesto predefinita invece di limitarsi ad aggiungere ricerca nella memoria o hook. ```ts @@ -1551,60 +1547,60 @@ export default function (api) { ## Aggiunta di una nuova capacità -Quando un plugin ha bisogno di un comportamento che non rientra nell'API attuale, non bypassare -il sistema dei plugin con un accesso privato diretto. Aggiungi la capacità mancante. +Quando un plugin ha bisogno di un comportamento che non rientra nell'API attuale, non aggirare +il sistema dei plugin con un accesso privato interno. Aggiungi la capacità mancante. Sequenza consigliata: 1. definire il contratto del core - Decidi quale comportamento condiviso deve possedere il core: policy, fallback, merge della configurazione, + Decidi quale comportamento condiviso dovrebbe possedere il core: policy, fallback, merge della configurazione, ciclo di vita, semantica rivolta ai canali e forma dell'helper di runtime. 2. aggiungere superfici tipizzate di registrazione/runtime dei plugin Estendi `OpenClawPluginApi` e/o `api.runtime` con la superficie di capacità tipizzata - più piccola ma utile. -3. collegare il core + i consumer di canali/funzionalità + più piccola utile. +3. collegare i consumer del core + canale/funzionalità I canali e i plugin di funzionalità dovrebbero consumare la nuova capacità tramite il core, non importando direttamente un'implementazione vendor. -4. registrare le implementazioni vendor - I plugin vendor registrano quindi i loro backend rispetto alla capacità. +4. registrare implementazioni vendor + I plugin vendor registrano poi i propri backend rispetto alla capacità. 5. aggiungere copertura contrattuale - Aggiungi test in modo che la proprietà e la forma di registrazione restino esplicite nel tempo. + Aggiungi test così che proprietà e forma di registrazione restino esplicite nel tempo. -È così che OpenClaw resta opinionato senza diventare codificato rigidamente secondo la visione del mondo di un solo -provider. Vedi il [Capability Cookbook](/it/plugins/architecture) +Questo è il modo in cui OpenClaw resta opinionato senza diventare hardcoded sulla visione del mondo di un +singolo provider. Vedi il [Capability Cookbook](/it/plugins/architecture) per una checklist concreta dei file e un esempio completo. -### Checklist delle capacità +### Checklist della capacità -Quando aggiungi una nuova capacità, l'implementazione dovrebbe di solito toccare insieme queste -superfici: +Quando aggiungi una nuova capacità, l'implementazione dovrebbe di solito toccare queste +superfici insieme: - tipi di contratto del core in `src//types.ts` - runner/helper di runtime del core in `src//runtime.ts` - superficie di registrazione dell'API plugin in `src/plugins/types.ts` - wiring del registro dei plugin in `src/plugins/registry.ts` -- esposizione del runtime dei plugin in `src/plugins/runtime/*` quando i plugin di funzionalità/canale +- esposizione di runtime del plugin in `src/plugins/runtime/*` quando i plugin di funzionalità/canale devono consumarla -- helper di capture/test in `src/test-utils/plugin-registration.ts` +- helper di acquisizione/test in `src/test-utils/plugin-registration.ts` - asserzioni di proprietà/contratto in `src/plugins/contracts/registry.ts` - documentazione per operatori/plugin in `docs/` -Se una di queste superfici manca, di solito è un segno che la capacità +Se una di queste superfici manca, di solito è un segnale che la capacità non è ancora completamente integrata. -### Template di capacità +### Template della capacità -Schema minimo: +Pattern minimo: ```ts -// contratto del core +// core contract export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// API plugin +// plugin API api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1613,14 +1609,14 @@ api.registerVideoGenerationProvider({ }, }); -// helper di runtime condiviso per plugin di funzionalità/canale +// shared runtime helper for feature/channel plugins const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, }); ``` -Schema di test di contratto: +Pattern del test di contratto: ```ts expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); diff --git a/docs/it/plugins/manifest.md b/docs/it/plugins/manifest.md index c64abde57..014d043db 100644 --- a/docs/it/plugins/manifest.md +++ b/docs/it/plugins/manifest.md @@ -1,14 +1,14 @@ --- read_when: - Stai creando un plugin OpenClaw - - Devi distribuire uno schema di configurazione del plugin o eseguire il debug degli errori di convalida del plugin -summary: Manifest del plugin + requisiti dello schema JSON (convalida rigorosa della configurazione) + - Devi distribuire uno schema di configurazione del plugin o eseguire il debug degli errori di validazione del plugin +summary: Manifest del plugin + requisiti dello schema JSON (validazione rigorosa della configurazione) title: Manifest del plugin x-i18n: - generated_at: "2026-04-11T15:16:06Z" + generated_at: "2026-04-12T08:07:55Z" model: gpt-5.4 provider: openai - source_hash: 42d454b560a8f6bf714c5d782f34216be1216d83d0a319d08d7349332c91a9e4 + source_hash: bf666b0f41f07641375a248f52e29ba6a68c3ec20404bedb6b52a20a5cd92e91 source_path: plugins/manifest.md workflow: 15 --- @@ -27,15 +27,15 @@ I formati di bundle compatibili usano file manifest diversi: OpenClaw rileva automaticamente anche questi layout di bundle, ma non vengono convalidati rispetto allo schema `openclaw.plugin.json` descritto qui. -Per i bundle compatibili, OpenClaw attualmente legge i metadati del bundle più le root delle skill dichiarate, le root dei comandi Claude, i valori predefiniti di `settings.json` del bundle Claude, i valori predefiniti LSP del bundle Claude e i pacchetti hook supportati quando il layout corrisponde alle aspettative di runtime di OpenClaw. +Per i bundle compatibili, OpenClaw attualmente legge i metadati del bundle più le radici delle skill dichiarate, le radici dei comandi Claude, i valori predefiniti di `settings.json` del bundle Claude, i valori predefiniti LSP del bundle Claude e i pacchetti hook supportati quando il layout corrisponde alle aspettative del runtime di OpenClaw. -Ogni plugin OpenClaw nativo **deve** includere un file `openclaw.plugin.json` nella **root del plugin**. OpenClaw usa questo manifest per convalidare la configurazione **senza eseguire il codice del plugin**. I manifest mancanti o non validi sono trattati come errori del plugin e bloccano la convalida della configurazione. +Ogni plugin OpenClaw nativo **deve** includere un file `openclaw.plugin.json` nella **radice del plugin**. OpenClaw usa questo manifest per convalidare la configurazione **senza eseguire il codice del plugin**. I manifest mancanti o non validi vengono trattati come errori del plugin e bloccano la convalida della configurazione. -Vedi la guida completa al sistema dei plugin: [Plugin](/it/tools/plugin). -Per il modello di capability nativo e le indicazioni correnti sulla compatibilità esterna: -[Modello di capability](/it/plugins/architecture#public-capability-model). +Consulta la guida completa al sistema dei plugin: [Plugin](/it/tools/plugin). +Per il modello nativo delle capacità e le indicazioni attuali sulla compatibilità esterna: +[Modello delle capacità](/it/plugins/architecture#public-capability-model). -## Cosa fa questo file +## A cosa serve questo file `openclaw.plugin.json` è il metadato che OpenClaw legge prima di caricare il codice del tuo plugin. @@ -45,17 +45,17 @@ Usalo per: - convalida della configurazione - metadati di autenticazione e onboarding che devono essere disponibili senza avviare il runtime del plugin - suggerimenti di attivazione leggeri che le superfici del control plane possono ispezionare prima del caricamento del runtime -- descrittori di configurazione leggeri che le superfici di setup/onboarding possono ispezionare prima del caricamento del runtime -- metadati di alias e attivazione automatica che devono essere risolti prima del caricamento del runtime del plugin -- metadati abbreviati di proprietà della famiglia di modelli che devono attivare automaticamente il plugin prima del caricamento del runtime -- snapshot statiche della proprietà delle capability usate per il cablaggio di compatibilità bundled e la copertura dei contratti +- descrittori di configurazione leggeri che le superfici di configurazione/onboarding possono ispezionare prima del caricamento del runtime +- metadati di alias e abilitazione automatica che devono risolversi prima del caricamento del runtime del plugin +- metadati abbreviati sulla proprietà della famiglia di modelli che dovrebbero attivare automaticamente il plugin prima del caricamento del runtime +- istantanee statiche della proprietà delle capacità usate per il wiring di compatibilità dei bundle e la copertura dei contratti - metadati di configurazione specifici del canale che devono essere uniti nelle superfici di catalogo e convalida senza caricare il runtime - suggerimenti UI per la configurazione Non usarlo per: - registrare il comportamento del runtime -- dichiarare entrypoint del codice +- dichiarare gli entrypoint del codice - metadati di installazione npm Questi appartengono al codice del tuo plugin e a `package.json`. @@ -79,7 +79,7 @@ Questi appartengono al codice del tuo plugin e a `package.json`. { "id": "openrouter", "name": "OpenRouter", - "description": "OpenRouter provider plugin", + "description": "Plugin provider OpenRouter", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -100,19 +100,19 @@ Questi appartengono al codice del tuo plugin e a `package.json`. "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "OpenRouter API key", + "choiceLabel": "Chiave API OpenRouter", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "OpenRouter API key", + "cliDescription": "Chiave API OpenRouter", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "API key", + "label": "Chiave API", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -133,58 +133,58 @@ Questi appartengono al codice del tuo plugin e a `package.json`. | Campo | Obbligatorio | Tipo | Significato | | ----------------------------------- | ------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | Sì | `string` | ID canonico del plugin. È l'ID usato in `plugins.entries.`. | -| `configSchema` | Sì | `object` | Schema JSON inline per la configurazione di questo plugin. | -| `enabledByDefault` | No | `true` | Contrassegna un plugin bundled come abilitato per impostazione predefinita. Omettilo, oppure imposta qualsiasi valore diverso da `true`, per lasciare il plugin disabilitato per impostazione predefinita. | -| `legacyPluginIds` | No | `string[]` | ID legacy che vengono normalizzati in questo ID canonico del plugin. | -| `autoEnableWhenConfiguredProviders` | No | `string[]` | ID provider che dovrebbero abilitare automaticamente questo plugin quando autenticazione, configurazione o riferimenti ai modelli li menzionano. | +| `id` | Sì | `string` | ID canonico del plugin. Questo è l'ID usato in `plugins.entries.`. | +| `configSchema` | Sì | `object` | Schema JSON inline per la configurazione di questo plugin. | +| `enabledByDefault` | No | `true` | Contrassegna un plugin bundle come abilitato per impostazione predefinita. Omettilo, o imposta qualsiasi valore diverso da `true`, per lasciare il plugin disabilitato per impostazione predefinita. | +| `legacyPluginIds` | No | `string[]` | ID legacy che vengono normalizzati a questo ID canonico del plugin. | +| `autoEnableWhenConfiguredProviders` | No | `string[]` | ID provider che dovrebbero abilitare automaticamente questo plugin quando auth, configurazione o riferimenti a modelli li menzionano. | | `kind` | No | `"memory"` \| `"context-engine"` | Dichiara un tipo di plugin esclusivo usato da `plugins.slots.*`. | -| `channels` | No | `string[]` | ID dei canali posseduti da questo plugin. Usati per discovery e convalida della configurazione. | -| `providers` | No | `string[]` | ID dei provider posseduti da questo plugin. | -| `modelSupport` | No | `object` | Metadati abbreviati della famiglia di modelli posseduti dal manifest usati per caricare automaticamente il plugin prima del runtime. | -| `cliBackends` | No | `string[]` | ID dei backend di inferenza CLI posseduti da questo plugin. Usati per l'attivazione automatica all'avvio da riferimenti espliciti nella configurazione. | -| `commandAliases` | No | `object[]` | Nomi di comando posseduti da questo plugin che dovrebbero produrre diagnostica di configurazione e CLI consapevole del plugin prima del caricamento del runtime. | +| `channels` | No | `string[]` | ID dei canali posseduti da questo plugin. Usati per il rilevamento e la convalida della configurazione. | +| `providers` | No | `string[]` | ID provider posseduti da questo plugin. | +| `modelSupport` | No | `object` | Metadati abbreviati relativi alla famiglia di modelli posseduti dal manifest, usati per caricare automaticamente il plugin prima del runtime. | +| `cliBackends` | No | `string[]` | ID dei backend di inferenza CLI posseduti da questo plugin. Usati per l'attivazione automatica all'avvio da riferimenti espliciti nella configurazione. | +| `commandAliases` | No | `object[]` | Nomi di comandi posseduti da questo plugin che dovrebbero produrre diagnostica di configurazione e CLI consapevole del plugin prima del caricamento del runtime. | | `providerAuthEnvVars` | No | `Record` | Metadati env leggeri per l'autenticazione del provider che OpenClaw può ispezionare senza caricare il codice del plugin. | -| `providerAuthAliases` | No | `Record` | ID provider che dovrebbero riutilizzare un altro ID provider per la ricerca dell'autenticazione, ad esempio un provider di coding che condivide la chiave API e i profili di autenticazione del provider base. | -| `channelEnvVars` | No | `Record` | Metadati env leggeri del canale che OpenClaw può ispezionare senza caricare il codice del plugin. Usali per setup del canale guidato da env o superfici di autenticazione che gli helper generici di avvio/config dovrebbero vedere. | -| `providerAuthChoices` | No | `object[]` | Metadati leggeri delle scelte di autenticazione per selettori di onboarding, risoluzione del provider preferito e semplice collegamento dei flag CLI. | -| `activation` | No | `object` | Suggerimenti di attivazione leggeri per il caricamento attivato da provider, comando, canale, route e capability. Solo metadati; il runtime del plugin continua a possedere il comportamento reale. | -| `setup` | No | `object` | Descrittori leggeri di setup/onboarding che le superfici di discovery e setup possono ispezionare senza caricare il runtime del plugin. | -| `contracts` | No | `object` | Snapshot statica delle capability bundled per speech, trascrizione realtime, voce realtime, media-understanding, image-generation, music-generation, video-generation, web-fetch, ricerca web e proprietà degli strumenti. | -| `channelConfigs` | No | `Record` | Metadati di configurazione del canale posseduti dal manifest uniti nelle superfici di discovery e convalida prima del caricamento del runtime. | -| `skills` | No | `string[]` | Directory Skills da caricare, relative alla root del plugin. | -| `name` | No | `string` | Nome leggibile del plugin. | +| `providerAuthAliases` | No | `Record` | ID provider che dovrebbero riutilizzare un altro ID provider per la ricerca auth, ad esempio un provider di coding che condivide la chiave API del provider di base e i profili auth. | +| `channelEnvVars` | No | `Record` | Metadati env leggeri per i canali che OpenClaw può ispezionare senza caricare il codice del plugin. Usalo per superfici di configurazione o auth del canale guidate da env che i helper generici di avvio/configurazione dovrebbero vedere. | +| `providerAuthChoices` | No | `object[]` | Metadati leggeri delle scelte auth per selettori di onboarding, risoluzione del provider preferito e semplice collegamento dei flag CLI. | +| `activation` | No | `object` | Suggerimenti di attivazione leggeri per il caricamento attivato da provider, comando, canale, route e capacità. Solo metadati; il runtime del plugin continua a possedere il comportamento effettivo. | +| `setup` | No | `object` | Descrittori leggeri di configurazione/onboarding che le superfici di rilevamento e configurazione possono ispezionare senza caricare il runtime del plugin. | +| `contracts` | No | `object` | Istantanea statica delle capacità bundle per speech, trascrizione in tempo reale, voce in tempo reale, media-understanding, generazione di immagini, generazione musicale, generazione video, web-fetch, ricerca web e proprietà degli strumenti. | +| `channelConfigs` | No | `Record` | Metadati di configurazione del canale posseduti dal manifest, uniti nelle superfici di rilevamento e convalida prima del caricamento del runtime. | +| `skills` | No | `string[]` | Directory delle Skills da caricare, relative alla radice del plugin. | +| `name` | No | `string` | Nome leggibile del plugin. | | `description` | No | `string` | Breve riepilogo mostrato nelle superfici del plugin. | -| `version` | No | `string` | Versione informativa del plugin. | -| `uiHints` | No | `Record` | Etichette UI, segnaposto e suggerimenti di sensibilità per i campi di configurazione. | +| `version` | No | `string` | Versione informativa del plugin. | +| `uiHints` | No | `Record` | Etichette UI, placeholder e suggerimenti di sensibilità per i campi di configurazione. | ## Riferimento `providerAuthChoices` -Ogni voce `providerAuthChoices` descrive una scelta di onboarding o autenticazione. -OpenClaw la legge prima che il runtime del provider venga caricato. +Ogni voce di `providerAuthChoices` descrive una scelta di onboarding o autenticazione. +OpenClaw la legge prima del caricamento del runtime del provider. -| Campo | Obbligatorio | Tipo | Significato | -| --------------------- | ------------ | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `provider` | Sì | `string` | ID del provider a cui appartiene questa scelta. | -| `method` | Sì | `string` | ID del metodo di autenticazione a cui inoltrare. | -| `choiceId` | Sì | `string` | ID stabile della scelta di autenticazione usato dai flussi di onboarding e CLI. | -| `choiceLabel` | No | `string` | Etichetta visibile all'utente. Se omessa, OpenClaw usa `choiceId` come fallback. | -| `choiceHint` | No | `string` | Breve testo di supporto per il selettore. | -| `assistantPriority` | No | `number` | I valori più bassi vengono ordinati prima nei selettori interattivi guidati dall'assistente. | -| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Nasconde la scelta dai selettori dell'assistente, continuando però a consentire la selezione manuale da CLI. | -| `deprecatedChoiceIds` | No | `string[]` | ID legacy delle scelte che dovrebbero reindirizzare gli utenti a questa scelta sostitutiva. | -| `groupId` | No | `string` | ID di gruppo facoltativo per raggruppare scelte correlate. | -| `groupLabel` | No | `string` | Etichetta visibile all'utente per quel gruppo. | -| `groupHint` | No | `string` | Breve testo di supporto per il gruppo. | -| `optionKey` | No | `string` | Chiave interna dell'opzione per semplici flussi di autenticazione con un solo flag. | -| `cliFlag` | No | `string` | Nome del flag CLI, ad esempio `--openrouter-api-key`. | -| `cliOption` | No | `string` | Forma completa dell'opzione CLI, ad esempio `--openrouter-api-key `. | -| `cliDescription` | No | `string` | Descrizione usata nella guida CLI. | +| Campo | Obbligatorio | Tipo | Significato | +| --------------------- | ------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `provider` | Sì | `string` | ID del provider a cui appartiene questa scelta. | +| `method` | Sì | `string` | ID del metodo auth a cui inoltrare. | +| `choiceId` | Sì | `string` | ID stabile della scelta auth usato dai flussi di onboarding e CLI. | +| `choiceLabel` | No | `string` | Etichetta visibile all'utente. Se omessa, OpenClaw usa `choiceId` come fallback. | +| `choiceHint` | No | `string` | Breve testo di supporto per il selettore. | +| `assistantPriority` | No | `number` | I valori più bassi vengono ordinati prima nei selettori interattivi guidati dall'assistente. | +| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Nasconde la scelta dai selettori dell'assistente, consentendo comunque la selezione manuale tramite CLI. | +| `deprecatedChoiceIds` | No | `string[]` | ID legacy delle scelte che dovrebbero reindirizzare gli utenti a questa scelta sostitutiva. | +| `groupId` | No | `string` | ID di gruppo facoltativo per raggruppare scelte correlate. | +| `groupLabel` | No | `string` | Etichetta visibile all'utente per quel gruppo. | +| `groupHint` | No | `string` | Breve testo di supporto per il gruppo. | +| `optionKey` | No | `string` | Chiave interna dell'opzione per flussi auth semplici a flag singolo. | +| `cliFlag` | No | `string` | Nome del flag CLI, ad esempio `--openrouter-api-key`. | +| `cliOption` | No | `string` | Forma completa dell'opzione CLI, ad esempio `--openrouter-api-key `. | +| `cliDescription` | No | `string` | Descrizione usata nella guida CLI. | | `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | In quali superfici di onboarding dovrebbe comparire questa scelta. Se omesso, il valore predefinito è `["text-inference"]`. | ## Riferimento `commandAliases` -Usa `commandAliases` quando un plugin possiede un nome di comando runtime che gli utenti potrebbero inserire per errore in `plugins.allow` o tentare di eseguire come comando CLI root. OpenClaw usa questi metadati per la diagnostica senza importare il codice runtime del plugin. +Usa `commandAliases` quando un plugin possiede un nome di comando runtime che gli utenti potrebbero erroneamente inserire in `plugins.allow` o provare a eseguire come comando CLI di radice. OpenClaw usa questi metadati per la diagnostica senza importare il codice runtime del plugin. ```json { @@ -201,14 +201,14 @@ Usa `commandAliases` quando un plugin possiede un nome di comando runtime che gl | Campo | Obbligatorio | Tipo | Significato | | ------------ | ------------ | ----------------- | -------------------------------------------------------------------------- | | `name` | Sì | `string` | Nome del comando che appartiene a questo plugin. | -| `kind` | No | `"runtime-slash"` | Contrassegna l'alias come comando slash della chat anziché come comando CLI root. | -| `cliCommand` | No | `string` | Comando CLI root correlato da suggerire per le operazioni CLI, se esiste. | +| `kind` | No | `"runtime-slash"` | Contrassegna l'alias come comando slash della chat anziché come comando CLI di radice. | +| `cliCommand` | No | `string` | Comando CLI di radice correlato da suggerire per le operazioni CLI, se esiste. | ## Riferimento `activation` Usa `activation` quando il plugin può dichiarare in modo leggero quali eventi del control plane dovrebbero attivarlo in seguito. -Questo blocco contiene solo metadati. Non registra il comportamento del runtime e non sostituisce `register(...)`, `setupEntry` o altri entrypoint runtime/plugin. +Questo blocco contiene solo metadati. Non registra il comportamento runtime e non sostituisce `register(...)`, `setupEntry` o altri entrypoint runtime/plugin. ```json { @@ -224,15 +224,15 @@ Questo blocco contiene solo metadati. Non registra il comportamento del runtime | Campo | Obbligatorio | Tipo | Significato | | ---------------- | ------------ | ---------------------------------------------------- | ---------------------------------------------------------------- | -| `onProviders` | No | `string[]` | ID provider che dovrebbero attivare questo plugin quando richiesti. | +| `onProviders` | No | `string[]` | ID provider che dovrebbero attivare questo plugin quando richiesto. | | `onCommands` | No | `string[]` | ID comando che dovrebbero attivare questo plugin. | | `onChannels` | No | `string[]` | ID canale che dovrebbero attivare questo plugin. | | `onRoutes` | No | `string[]` | Tipi di route che dovrebbero attivare questo plugin. | -| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Suggerimenti generali di capability usati dalla pianificazione di attivazione del control plane. | +| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Suggerimenti generali sulle capacità usati dalla pianificazione dell'attivazione del control plane. | ## Riferimento `setup` -Usa `setup` quando le superfici di setup e onboarding hanno bisogno di metadati leggeri posseduti dal plugin prima che il runtime venga caricato. +Usa `setup` quando le superfici di configurazione e onboarding hanno bisogno di metadati leggeri posseduti dal plugin prima del caricamento del runtime. ```json { @@ -251,24 +251,28 @@ Usa `setup` quando le superfici di setup e onboarding hanno bisogno di metadati } ``` -Il `cliBackends` di primo livello rimane valido e continua a descrivere i backend di inferenza CLI. `setup.cliBackends` è la superficie descrittiva specifica del setup per i flussi di control plane/setup che devono rimanere solo metadati. +Il `cliBackends` di primo livello resta valido e continua a descrivere i backend di inferenza CLI. `setup.cliBackends` è la superficie descrittiva specifica del setup per i flussi di setup/control plane che devono restare solo metadati. + +Quando presenti, `setup.providers` e `setup.cliBackends` sono la superficie di ricerca preferita, basata prima sui descrittori, per il rilevamento del setup. Se il descrittore restringe solo il plugin candidato e il setup ha comunque bisogno di hook runtime più ricchi in fase di configurazione, imposta `requiresRuntime: true` e mantieni `setup-api` come percorso di esecuzione di fallback. + +Poiché la ricerca del setup può eseguire codice `setup-api` posseduto dal plugin, i valori normalizzati di `setup.providers[].id` e `setup.cliBackends[]` devono rimanere univoci tra i plugin rilevati. Una proprietà ambigua fallisce in modo conservativo invece di scegliere un vincitore in base all'ordine di rilevamento. ### Riferimento `setup.providers` -| Campo | Obbligatorio | Tipo | Significato | -| ------------- | ------------ | ---------- | ------------------------------------------------------------------------------- | -| `id` | Sì | `string` | ID del provider esposto durante il setup o l'onboarding. | -| `authMethods` | No | `string[]` | ID dei metodi di setup/autenticazione supportati da questo provider senza caricare il runtime completo. | -| `envVars` | No | `string[]` | Variabili env che le superfici generiche di setup/stato possono controllare prima che il runtime del plugin venga caricato. | +| Campo | Obbligatorio | Tipo | Significato | +| ------------- | ------------ | ---------- | ------------------------------------------------------------------------------------ | +| `id` | Sì | `string` | ID provider esposto durante setup o onboarding. Mantieni gli ID normalizzati univoci a livello globale. | +| `authMethods` | No | `string[]` | ID dei metodi di setup/auth supportati da questo provider senza caricare il runtime completo. | +| `envVars` | No | `string[]` | Variabili env che le superfici generiche di setup/stato possono controllare prima del caricamento del runtime del plugin. | -### Campi `setup` +### Campi di `setup` -| Campo | Obbligatorio | Tipo | Significato | -| ------------------ | ------------ | ---------- | ---------------------------------------------------------------------- | -| `providers` | No | `object[]` | Descrittori di setup del provider esposti durante setup e onboarding. | -| `cliBackends` | No | `string[]` | ID backend disponibili in fase di setup senza attivazione completa del runtime. | -| `configMigrations` | No | `string[]` | ID delle migrazioni di configurazione possedute dalla superficie di setup di questo plugin. | -| `requiresRuntime` | No | `boolean` | Indica se il setup necessita ancora dell'esecuzione del runtime del plugin dopo il lookup del descrittore. | +| Campo | Obbligatorio | Tipo | Significato | +| ------------------ | ------------ | ---------- | --------------------------------------------------------------------------------------------------- | +| `providers` | No | `object[]` | Descrittori di setup del provider esposti durante setup e onboarding. | +| `cliBackends` | No | `string[]` | ID backend in fase di setup usati per la ricerca del setup basata prima sui descrittori. Mantieni gli ID normalizzati univoci a livello globale. | +| `configMigrations` | No | `string[]` | ID delle migrazioni di configurazione possedute dalla superficie di setup di questo plugin. | +| `requiresRuntime` | No | `boolean` | Indica se il setup richiede ancora l'esecuzione di `setup-api` dopo la ricerca basata sui descrittori. | ## Riferimento `uiHints` @@ -289,18 +293,18 @@ Il `cliBackends` di primo livello rimane valido e continua a descrivere i backen Ogni suggerimento di campo può includere: -| Campo | Tipo | Significato | -| ------------- | ---------- | ------------------------------------------ | -| `label` | `string` | Etichetta del campo visibile all'utente. | -| `help` | `string` | Breve testo di supporto. | -| `tags` | `string[]` | Tag UI facoltativi. | -| `advanced` | `boolean` | Contrassegna il campo come avanzato. | +| Campo | Tipo | Significato | +| ------------- | ---------- | ---------------------------------------- | +| `label` | `string` | Etichetta del campo visibile all'utente. | +| `help` | `string` | Breve testo di supporto. | +| `tags` | `string[]` | Tag UI facoltativi. | +| `advanced` | `boolean` | Contrassegna il campo come avanzato. | | `sensitive` | `boolean` | Contrassegna il campo come segreto o sensibile. | -| `placeholder` | `string` | Testo segnaposto per gli input dei moduli. | +| `placeholder` | `string` | Testo segnaposto per gli input del modulo. | ## Riferimento `contracts` -Usa `contracts` solo per metadati statici di proprietà delle capability che OpenClaw può leggere senza importare il runtime del plugin. +Usa `contracts` solo per metadati statici sulla proprietà delle capacità che OpenClaw può leggere senza importare il runtime del plugin. ```json { @@ -320,21 +324,21 @@ Usa `contracts` solo per metadati statici di proprietà delle capability che Ope Ogni elenco è facoltativo: -| Campo | Tipo | Significato | -| -------------------------------- | ---------- | ------------------------------------------------------------- | -| `speechProviders` | `string[]` | ID dei provider speech posseduti da questo plugin. | -| `realtimeTranscriptionProviders` | `string[]` | ID dei provider di trascrizione realtime posseduti da questo plugin. | -| `realtimeVoiceProviders` | `string[]` | ID dei provider voce realtime posseduti da questo plugin. | +| Campo | Tipo | Significato | +| -------------------------------- | ---------- | --------------------------------------------------------------- | +| `speechProviders` | `string[]` | ID dei provider speech posseduti da questo plugin. | +| `realtimeTranscriptionProviders` | `string[]` | ID dei provider di trascrizione in tempo reale posseduti da questo plugin. | +| `realtimeVoiceProviders` | `string[]` | ID dei provider voce in tempo reale posseduti da questo plugin. | | `mediaUnderstandingProviders` | `string[]` | ID dei provider media-understanding posseduti da questo plugin. | -| `imageGenerationProviders` | `string[]` | ID dei provider image-generation posseduti da questo plugin. | -| `videoGenerationProviders` | `string[]` | ID dei provider video-generation posseduti da questo plugin. | -| `webFetchProviders` | `string[]` | ID dei provider web-fetch posseduti da questo plugin. | -| `webSearchProviders` | `string[]` | ID dei provider di ricerca web posseduti da questo plugin. | -| `tools` | `string[]` | Nomi degli strumenti dell'agente posseduti da questo plugin per i controlli dei contratti bundled. | +| `imageGenerationProviders` | `string[]` | ID dei provider di generazione immagini posseduti da questo plugin. | +| `videoGenerationProviders` | `string[]` | ID dei provider di generazione video posseduti da questo plugin. | +| `webFetchProviders` | `string[]` | ID dei provider web-fetch posseduti da questo plugin. | +| `webSearchProviders` | `string[]` | ID dei provider di ricerca web posseduti da questo plugin. | +| `tools` | `string[]` | Nomi degli strumenti dell'agente posseduti da questo plugin per i controlli dei contratti bundle. | ## Riferimento `channelConfigs` -Usa `channelConfigs` quando un plugin di canale ha bisogno di metadati di configurazione leggeri prima che il runtime venga caricato. +Usa `channelConfigs` quando un plugin di canale ha bisogno di metadati di configurazione leggeri prima del caricamento del runtime. ```json { @@ -349,12 +353,12 @@ Usa `channelConfigs` quando un plugin di canale ha bisogno di metadati di config }, "uiHints": { "homeserverUrl": { - "label": "Homeserver URL", + "label": "URL homeserver", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Matrix homeserver connection", + "description": "Connessione homeserver Matrix", "preferOver": ["matrix-legacy"] } } @@ -365,15 +369,15 @@ Ogni voce di canale può includere: | Campo | Tipo | Significato | | ------------- | ------------------------ | ------------------------------------------------------------------------------------------- | -| `schema` | `object` | Schema JSON per `channels.`. Obbligatorio per ogni voce dichiarata di configurazione del canale. | -| `uiHints` | `Record` | Etichette UI facoltative/segnaposto/suggerimenti di sensibilità per quella sezione di configurazione del canale. | -| `label` | `string` | Etichetta del canale unita nelle superfici di selezione e ispezione quando i metadati di runtime non sono pronti. | +| `schema` | `object` | Schema JSON per `channels.`. Obbligatorio per ogni voce di configurazione canale dichiarata. | +| `uiHints` | `Record` | Etichette UI / placeholder / suggerimenti di sensibilità facoltativi per quella sezione di configurazione del canale. | +| `label` | `string` | Etichetta del canale unita nelle superfici di selezione e ispezione quando i metadati runtime non sono pronti. | | `description` | `string` | Breve descrizione del canale per le superfici di ispezione e catalogo. | -| `preferOver` | `string[]` | ID di plugin legacy o a priorità inferiore che questo canale dovrebbe superare nelle superfici di selezione. | +| `preferOver` | `string[]` | ID plugin legacy o a priorità inferiore che questo canale dovrebbe superare nelle superfici di selezione. | ## Riferimento `modelSupport` -Usa `modelSupport` quando OpenClaw deve dedurre il tuo plugin provider da ID modello abbreviati come `gpt-5.4` o `claude-sonnet-4.6` prima che il runtime del plugin venga caricato. +Usa `modelSupport` quando OpenClaw deve dedurre il tuo plugin provider da ID modello abbreviati come `gpt-5.4` o `claude-sonnet-4.6` prima del caricamento del runtime del plugin. ```json { @@ -387,57 +391,57 @@ Usa `modelSupport` quando OpenClaw deve dedurre il tuo plugin provider da ID mod OpenClaw applica questa precedenza: - i riferimenti espliciti `provider/model` usano i metadati `providers` del manifest proprietario -- `modelPatterns` ha precedenza su `modelPrefixes` -- se corrispondono sia un plugin non bundled sia un plugin bundled, vince il plugin non bundled +- `modelPatterns` ha la precedenza su `modelPrefixes` +- se un plugin non bundle e un plugin bundle corrispondono entrambi, vince il plugin non bundle - l'ambiguità rimanente viene ignorata finché l'utente o la configurazione non specificano un provider Campi: -| Campo | Tipo | Significato | -| --------------- | ---------- | ------------------------------------------------------------------------------ | -| `modelPrefixes` | `string[]` | Prefissi confrontati con `startsWith` rispetto agli ID modello abbreviati. | +| Campo | Tipo | Significato | +| --------------- | ---------- | ------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Prefissi confrontati con `startsWith` rispetto agli ID modello abbreviati. | | `modelPatterns` | `string[]` | Sorgenti regex confrontate con gli ID modello abbreviati dopo la rimozione del suffisso del profilo. | -Le chiavi legacy di capability di primo livello sono deprecate. Usa `openclaw doctor --fix` per spostare `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` e `webSearchProviders` sotto `contracts`; il normale caricamento del manifest non tratta più quei campi di primo livello come proprietà di capability. +Le chiavi legacy di capacità di primo livello sono deprecate. Usa `openclaw doctor --fix` per spostare `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` e `webSearchProviders` sotto `contracts`; il normale caricamento del manifest non tratta più quei campi di primo livello come proprietà delle capacità. ## Manifest rispetto a package.json -I due file svolgono compiti diversi: +I due file svolgono ruoli diversi: -| File | Usalo per | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Discovery, convalida della configurazione, metadati delle scelte di autenticazione e suggerimenti UI che devono esistere prima dell'esecuzione del codice del plugin | -| `package.json` | Metadati npm, installazione delle dipendenze e blocco `openclaw` usato per entrypoint, gating di installazione, setup o metadati di catalogo | +| File | Usalo per | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Rilevamento, convalida della configurazione, metadati delle scelte auth e suggerimenti UI che devono esistere prima dell'esecuzione del codice del plugin | +| `package.json` | Metadati npm, installazione delle dipendenze e blocco `openclaw` usato per entrypoint, gating dell'installazione, setup o metadati di catalogo | -Se non sei sicuro di dove debba stare un elemento di metadati, usa questa regola: +Se non sei sicuro di dove collocare un metadato, usa questa regola: - se OpenClaw deve conoscerlo prima di caricare il codice del plugin, inseriscilo in `openclaw.plugin.json` -- se riguarda packaging, file entry o comportamento di installazione npm, inseriscilo in `package.json` +- se riguarda il packaging, i file di entry o il comportamento di installazione npm, inseriscilo in `package.json` -### Campi `package.json` che influenzano la discovery +### Campi di `package.json` che influenzano il rilevamento -Alcuni metadati del plugin pre-runtime vivono intenzionalmente in `package.json` sotto il blocco `openclaw` invece che in `openclaw.plugin.json`. +Alcuni metadati del plugin prima del runtime vivono intenzionalmente in `package.json` sotto il blocco `openclaw` invece che in `openclaw.plugin.json`. Esempi importanti: | Campo | Significato | | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Dichiara gli entrypoint del plugin nativo. | -| `openclaw.setupEntry` | Entrypoint leggero solo setup usato durante onboarding e avvio differito del canale. | -| `openclaw.channel` | Metadati leggeri del catalogo canali come etichette, percorsi docs, alias e testo di selezione. | -| `openclaw.channel.configuredState` | Metadati leggeri del controllo dello stato configurato che possono rispondere a "esiste già una configurazione solo env?" senza caricare il runtime completo del canale. | -| `openclaw.channel.persistedAuthState` | Metadati leggeri del controllo dello stato di autenticazione persistito che possono rispondere a "c'è già qualcosa con accesso effettuato?" senza caricare il runtime completo del canale. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Suggerimenti di installazione/aggiornamento per plugin bundled e pubblicati esternamente. | -| `openclaw.install.defaultChoice` | Percorso di installazione preferito quando sono disponibili più origini di installazione. | +| `openclaw.extensions` | Dichiara gli entrypoint dei plugin nativi. | +| `openclaw.setupEntry` | Entry point leggero solo per il setup usato durante l'onboarding e l'avvio differito del canale. | +| `openclaw.channel` | Metadati leggeri del catalogo canali come etichette, percorsi della documentazione, alias e testo di selezione. | +| `openclaw.channel.configuredState` | Metadati leggeri del verificatore dello stato configurato che possono rispondere a "esiste già una configurazione solo env?" senza caricare il runtime completo del canale. | +| `openclaw.channel.persistedAuthState` | Metadati leggeri del verificatore dello stato auth persistito che possono rispondere a "c'è già qualcosa con accesso effettuato?" senza caricare il runtime completo del canale. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Suggerimenti di installazione/aggiornamento per plugin bundle e plugin pubblicati esternamente. | +| `openclaw.install.defaultChoice` | Percorso di installazione preferito quando sono disponibili più sorgenti di installazione. | | `openclaw.install.minHostVersion` | Versione minima supportata dell'host OpenClaw, usando una soglia semver come `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Consente un percorso ristretto di recupero della reinstallazione del plugin bundled quando la configurazione non è valida. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Consente alle superfici del canale solo setup di caricarsi prima del plugin canale completo durante l'avvio. | +| `openclaw.install.allowInvalidConfigRecovery` | Consente un percorso limitato di recupero della reinstallazione del plugin bundle quando la configurazione non è valida. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Consente alle superfici del canale solo-setup di caricarsi prima del plugin canale completo durante l'avvio. | -`openclaw.install.minHostVersion` viene applicato durante l'installazione e il caricamento del registro dei manifest. I valori non validi vengono rifiutati; i valori validi ma più recenti fanno saltare il plugin sugli host più vecchi. +`openclaw.install.minHostVersion` viene applicato durante l'installazione e il caricamento del registro dei manifest. I valori non validi vengono rifiutati; i valori validi ma più recenti saltano il plugin sugli host meno recenti. -`openclaw.install.allowInvalidConfigRecovery` è intenzionalmente limitato. Non rende installabili configurazioni arbitrarie danneggiate. Oggi consente solo ai flussi di installazione di recuperare da specifici errori obsoleti di aggiornamento del plugin bundled, come un percorso mancante del plugin bundled o una voce `channels.` obsoleta per quello stesso plugin bundled. Gli errori di configurazione non correlati continuano a bloccare l'installazione e indirizzano gli operatori a `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` è intenzionalmente limitato. Non rende installabili configurazioni arbitrarie non valide. Oggi consente solo ai flussi di installazione di recuperare da specifici errori di aggiornamento obsoleti del plugin bundle, come un percorso del plugin bundle mancante o una voce `channels.` obsoleta per quello stesso plugin bundle. Gli errori di configurazione non correlati continuano a bloccare l'installazione e indirizzano gli operatori a `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` è metadato di pacchetto per un piccolo modulo di controllo: +`openclaw.channel.persistedAuthState` è un metadato di package per un piccolo modulo di controllo: ```json { @@ -453,9 +457,9 @@ Esempi importanti: } ``` -Usalo quando i flussi di setup, doctor o stato configurato hanno bisogno di una verifica di autenticazione sì/no economica prima che venga caricato il plugin completo del canale. L'export di destinazione deve essere una piccola funzione che legge solo lo stato persistito; non instradarla attraverso il barrel completo del runtime del canale. +Usalo quando i flussi di setup, doctor o stato configurato hanno bisogno di una sonda auth sì/no economica prima del caricamento del plugin canale completo. L'export di destinazione dovrebbe essere una piccola funzione che legge solo lo stato persistito; non instradarla attraverso il barrel runtime completo del canale. -`openclaw.channel.configuredState` segue la stessa forma per controlli economici dello stato configurato solo env: +`openclaw.channel.configuredState` segue la stessa struttura per controlli economici dello stato configurato solo env: ```json { @@ -471,43 +475,43 @@ Usalo quando i flussi di setup, doctor o stato configurato hanno bisogno di una } ``` -Usalo quando un canale può determinare lo stato configurato da env o da altri piccoli input non runtime. Se il controllo richiede la risoluzione completa della configurazione o il runtime reale del canale, mantieni invece quella logica nell'hook `config.hasConfiguredState` del plugin. +Usalo quando un canale può determinare lo stato configurato da env o altri input minimi non runtime. Se il controllo richiede la risoluzione completa della configurazione o il vero runtime del canale, mantieni invece quella logica nell'hook `config.hasConfiguredState` del plugin. ## Requisiti dello schema JSON - **Ogni plugin deve includere uno schema JSON**, anche se non accetta alcuna configurazione. -- È accettabile uno schema vuoto, ad esempio `{ "type": "object", "additionalProperties": false }`. -- Gli schemi vengono convalidati in fase di lettura/scrittura della configurazione, non in fase di runtime. +- È accettabile uno schema vuoto (ad esempio `{ "type": "object", "additionalProperties": false }`). +- Gli schemi vengono convalidati in fase di lettura/scrittura della configurazione, non a runtime. ## Comportamento della convalida -- Le chiavi sconosciute `channels.*` sono **errori**, a meno che l'ID del canale non sia dichiarato da un manifest del plugin. +- Le chiavi sconosciute `channels.*` sono **errori**, a meno che l'ID del canale non sia dichiarato da un manifest di plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` e `plugins.slots.*` devono fare riferimento a ID plugin **rilevabili**. Gli ID sconosciuti sono **errori**. -- Se un plugin è installato ma ha un manifest o uno schema danneggiato o mancante, la convalida fallisce e Doctor segnala l'errore del plugin. +- Se un plugin è installato ma ha un manifest o uno schema mancante o non valido, la convalida fallisce e Doctor segnala l'errore del plugin. - Se la configurazione del plugin esiste ma il plugin è **disabilitato**, la configurazione viene mantenuta e viene mostrato un **avviso** in Doctor + nei log. -Vedi [Riferimento della configurazione](/it/gateway/configuration) per lo schema completo `plugins.*`. +Consulta [Riferimento della configurazione](/it/gateway/configuration) per lo schema completo di `plugins.*`. ## Note - Il manifest è **obbligatorio per i plugin OpenClaw nativi**, inclusi i caricamenti locali dal filesystem. -- Il runtime continua a caricare separatamente il modulo del plugin; il manifest serve solo per discovery + convalida. -- I manifest nativi vengono analizzati con JSON5, quindi commenti, virgole finali e chiavi senza virgolette sono accettati purché il valore finale resti un oggetto. -- Il loader del manifest legge solo i campi del manifest documentati. Evita di aggiungere qui chiavi di primo livello personalizzate. -- `providerAuthEnvVars` è il percorso di metadati economico per verifiche di autenticazione, convalida dei marker env e superfici simili di autenticazione del provider che non devono avviare il runtime del plugin solo per ispezionare i nomi env. -- `providerAuthAliases` consente alle varianti del provider di riutilizzare le variabili env di autenticazione di un altro provider, i profili di autenticazione, l'autenticazione basata sulla configurazione e la scelta di onboarding della chiave API senza codificare rigidamente quella relazione nel core. -- `channelEnvVars` è il percorso di metadati economico per fallback shell-env, prompt di setup e superfici di canale simili che non devono avviare il runtime del plugin solo per ispezionare i nomi env. -- `providerAuthChoices` è il percorso di metadati economico per selettori di scelta di autenticazione, risoluzione di `--auth-choice`, mapping del provider preferito e semplice registrazione dei flag CLI di onboarding prima che il runtime del provider venga caricato. Per i metadati del wizard runtime che richiedono codice del provider, vedi [Hook runtime del provider](/it/plugins/architecture#provider-runtime-hooks). +- Il runtime continua comunque a caricare separatamente il modulo del plugin; il manifest serve solo per rilevamento + convalida. +- I manifest nativi vengono analizzati con JSON5, quindi sono accettati commenti, virgole finali e chiavi senza virgolette, purché il valore finale resti comunque un oggetto. +- Il loader del manifest legge solo i campi del manifest documentati. Evita di aggiungere qui chiavi personalizzate di primo livello. +- `providerAuthEnvVars` è il percorso di metadati leggero per sonde auth, convalida dei marker env e superfici simili di autenticazione del provider che non dovrebbero avviare il runtime del plugin solo per ispezionare i nomi env. +- `providerAuthAliases` consente alle varianti del provider di riutilizzare le variabili env auth di un altro provider, i profili auth, l'auth basata sulla configurazione e la scelta di onboarding della chiave API senza codificare rigidamente questa relazione nel core. +- `channelEnvVars` è il percorso di metadati leggero per fallback shell-env, prompt di setup e superfici di canale simili che non dovrebbero avviare il runtime del plugin solo per ispezionare i nomi env. +- `providerAuthChoices` è il percorso di metadati leggero per selettori di scelta auth, risoluzione `--auth-choice`, mappatura del provider preferito e semplice registrazione dei flag CLI di onboarding prima del caricamento del runtime del provider. Per i metadati del wizard runtime che richiedono codice del provider, vedi [Hook runtime del provider](/it/plugins/architecture#provider-runtime-hooks). - I tipi di plugin esclusivi vengono selezionati tramite `plugins.slots.*`. - `kind: "memory"` viene selezionato da `plugins.slots.memory`. - `kind: "context-engine"` viene selezionato da `plugins.slots.contextEngine` (predefinito: `legacy` integrato). - `channels`, `providers`, `cliBackends` e `skills` possono essere omessi quando un plugin non ne ha bisogno. -- Se il tuo plugin dipende da moduli nativi, documenta i passaggi di build e gli eventuali requisiti di allowlist del gestore di pacchetti, ad esempio pnpm `allow-build-scripts` - - `pnpm rebuild `. +- Se il tuo plugin dipende da moduli nativi, documenta i passaggi di build e qualsiasi requisito di allowlist del gestore di pacchetti (ad esempio pnpm `allow-build-scripts` + - `pnpm rebuild `). ## Correlati - [Creazione di plugin](/it/plugins/building-plugins) — introduzione ai plugin - [Architettura dei plugin](/it/plugins/architecture) — architettura interna -- [Panoramica dell'SDK](/it/plugins/sdk-overview) — riferimento dell'SDK dei plugin +- [Panoramica SDK](/it/plugins/sdk-overview) — riferimento del Plugin SDK diff --git a/docs/it/reference/templates/AGENTS.md b/docs/it/reference/templates/AGENTS.md index 851b458a1..10d05cda1 100644 --- a/docs/it/reference/templates/AGENTS.md +++ b/docs/it/reference/templates/AGENTS.md @@ -1,13 +1,13 @@ --- read_when: - - Bootstrap manuale di un workspace -summary: Template di workspace per AGENTS.md -title: Template AGENTS.md + - Inizializzazione manuale di un workspace +summary: Modello di workspace per AGENTS.md +title: Modello AGENTS.md x-i18n: - generated_at: "2026-04-11T02:47:46Z" + generated_at: "2026-04-12T08:07:54Z" model: gpt-5.4 provider: openai - source_hash: 6d8a3e96f547da6cc082d747c042555b0ec4963b66921d1700b4590f0e0c38b4 + source_hash: b7a68a1f0b4b837298bfe6edf8ce855d6ef6902ea8e7277b0d9a8442b23daf54 source_path: reference/templates/AGENTS.md workflow: 15 --- @@ -16,45 +16,50 @@ x-i18n: Questa cartella è casa. Trattala come tale. -## Primo avvio +## Prima esecuzione Se esiste `BOOTSTRAP.md`, quello è il tuo certificato di nascita. Seguilo, capisci chi sei, poi eliminalo. Non ti servirà più. ## Avvio della sessione -Prima di fare qualsiasi altra cosa: +Usa prima il contesto di avvio fornito dal runtime. -1. Leggi `SOUL.md` — questo è chi sei -2. Leggi `USER.md` — questa è la persona che stai aiutando -3. Leggi `memory/YYYY-MM-DD.md` (oggi + ieri) per il contesto recente -4. **Se sei nella SESSIONE PRINCIPALE** (chat diretta con il tuo umano): leggi anche `MEMORY.md` +Quel contesto potrebbe già includere: -Non chiedere permesso. Fallo e basta. +- `AGENTS.md`, `SOUL.md` e `USER.md` +- memoria quotidiana recente come `memory/YYYY-MM-DD.md` +- `MEMORY.md` quando questa è la sessione principale + +Non rileggere manualmente i file di avvio a meno che: + +1. L'utente non lo chieda esplicitamente +2. Nel contesto fornito manchi qualcosa di cui hai bisogno +3. Ti serva una lettura di approfondimento oltre il contesto di avvio fornito ## Memoria Ti risvegli da zero a ogni sessione. Questi file sono la tua continuità: -- **Note giornaliere:** `memory/YYYY-MM-DD.md` (crea `memory/` se serve) — log grezzi di quello che è successo +- **Note quotidiane:** `memory/YYYY-MM-DD.md` (crea `memory/` se necessario) — log grezzi di ciò che è successo - **Lungo termine:** `MEMORY.md` — i tuoi ricordi curati, come la memoria a lungo termine di un umano -Annota ciò che conta. Decisioni, contesto, cose da ricordare. Salta i segreti, a meno che non ti venga chiesto di conservarli. +Annota ciò che conta. Decisioni, contesto, cose da ricordare. Evita i segreti, a meno che non ti venga chiesto di conservarli. ### 🧠 MEMORY.md - La tua memoria a lungo termine - **Caricalo SOLO nella sessione principale** (chat dirette con il tuo umano) -- **NON caricarlo in contesti condivisi** (Discord, chat di gruppo, sessioni con altre persone) -- Questo è per **sicurezza** — contiene contesto personale che non dovrebbe trapelare a estranei -- Puoi **leggere, modificare e aggiornare** liberamente `MEMORY.md` nelle sessioni principali -- Scrivi eventi significativi, pensieri, decisioni, opinioni, lezioni imparate +- **NON caricarlo nei contesti condivisi** (Discord, chat di gruppo, sessioni con altre persone) +- Questo serve per la **sicurezza** — contiene contesto personale che non dovrebbe trapelare a estranei +- Puoi **leggere, modificare e aggiornare** `MEMORY.md` liberamente nelle sessioni principali +- Scrivi eventi significativi, pensieri, decisioni, opinioni, lezioni apprese - Questa è la tua memoria curata — l'essenza distillata, non i log grezzi -- Col tempo, rivedi i tuoi file giornalieri e aggiorna `MEMORY.md` con ciò che vale la pena conservare +- Nel tempo, rivedi i tuoi file quotidiani e aggiorna `MEMORY.md` con ciò che vale la pena conservare -### 📝 Scrivilo - niente "note mentali"! +### 📝 Scrivilo - Niente "note mentali"! -- **La memoria è limitata** — se vuoi ricordare qualcosa, SCRIVILA IN UN FILE -- Le "note mentali" non sopravvivono ai riavvii di sessione. I file sì. -- Quando qualcuno dice "ricordati questo" → aggiorna `memory/YYYY-MM-DD.md` o il file pertinente +- **La memoria è limitata** — se vuoi ricordare qualcosa, SCRIVILO IN UN FILE +- Le "note mentali" non sopravvivono al riavvio delle sessioni. I file sì. +- Quando qualcuno dice "ricorda questo" → aggiorna `memory/YYYY-MM-DD.md` o il file pertinente - Quando impari una lezione → aggiorna AGENTS.md, TOOLS.md o la skill pertinente - Quando fai un errore → documentalo così il tuo io futuro non lo ripeterà - **Testo > Cervello** 📝 @@ -66,23 +71,23 @@ Annota ciò che conta. Decisioni, contesto, cose da ricordare. Salta i segreti, - `trash` > `rm` (recuperabile è meglio che sparito per sempre) - Nel dubbio, chiedi. -## Esterno vs interno +## Esterno vs Interno **Sicuro da fare liberamente:** - Leggere file, esplorare, organizzare, imparare -- Cercare sul web, controllare calendari +- Cercare sul web, controllare i calendari - Lavorare all'interno di questo workspace **Chiedi prima:** - Inviare email, tweet, post pubblici -- Qualsiasi cosa che lasci la macchina +- Qualsiasi cosa lasci la macchina - Qualsiasi cosa su cui non sei sicuro ## Chat di gruppo -Hai accesso alle cose del tuo umano. Questo non significa che tu _condivida_ le sue cose. Nei gruppi sei un partecipante — non la sua voce, non il suo delegato. Pensa prima di parlare. +Hai accesso alle cose del tuo umano. Questo non significa che tu _condivida_ le sue cose. Nei gruppi, sei un partecipante — non la sua voce, non il suo tramite. Pensa prima di parlare. ### 💬 Sappi quando parlare! @@ -92,21 +97,21 @@ Nelle chat di gruppo in cui ricevi ogni messaggio, sii **intelligente su quando - Vieni menzionato direttamente o ti viene fatta una domanda - Puoi aggiungere valore reale (informazioni, intuizioni, aiuto) -- Qualcosa di arguto/divertente si inserisce in modo naturale -- Correggi informazioni importanti errate -- Fai un riepilogo quando richiesto +- Qualcosa di spiritoso/divertente si inserisce in modo naturale +- Devi correggere disinformazione importante +- Ti viene chiesto di fare un riepilogo -**Rimani in silenzio (`HEARTBEAT_OK`) quando:** +**Resta in silenzio (HEARTBEAT_OK) quando:** -- È solo chiacchiera casuale tra umani +- È solo chiacchiera informale tra umani - Qualcuno ha già risposto alla domanda - La tua risposta sarebbe solo "sì" o "bello" -- La conversazione scorre bene anche senza di te +- La conversazione sta fluendo bene senza di te - Aggiungere un messaggio interromperebbe l'atmosfera -**La regola umana:** gli umani nelle chat di gruppo non rispondono a ogni singolo messaggio. Nemmeno tu dovresti farlo. Qualità > quantità. Se non lo invieresti in una vera chat di gruppo con amici, non inviarlo. +**La regola umana:** Gli umani nelle chat di gruppo non rispondono a ogni singolo messaggio. Nemmeno tu dovresti farlo. Qualità > quantità. Se non lo invieresti in una vera chat di gruppo con amici, non inviarlo. -**Evita il triplo tocco:** non rispondere più volte allo stesso messaggio con reazioni diverse. Una risposta pensata vale più di tre frammenti. +**Evita il triplo tocco:** Non rispondere più volte allo stesso messaggio con reazioni diverse. Una risposta ponderata è meglio di tre frammenti. Partecipa, non dominare. @@ -119,55 +124,55 @@ Sulle piattaforme che supportano le reazioni (Discord, Slack), usa le reazioni e - Apprezzi qualcosa ma non hai bisogno di rispondere (👍, ❤️, 🙌) - Qualcosa ti ha fatto ridere (😂, 💀) - Lo trovi interessante o stimolante (🤔, 💡) -- Vuoi riconoscere qualcosa senza interrompere il flusso -- È una situazione semplice di sì/no o approvazione (✅, 👀) +- Vuoi dare conferma senza interrompere il flusso +- È una semplice situazione di sì/no o di approvazione (✅, 👀) **Perché è importante:** -Le reazioni sono segnali sociali leggeri. Gli umani le usano continuamente — dicono "ho visto questo, ti riconosco" senza riempire la chat. Dovresti farlo anche tu. +Le reazioni sono segnali sociali leggeri. Gli umani le usano continuamente — dicono "ho visto questo, ti riconosco" senza ingombrare la chat. Dovresti farlo anche tu. -**Non esagerare:** massimo una reazione per messaggio. Scegli quella più adatta. +**Non esagerare:** Al massimo una reazione per messaggio. Scegli quella più adatta. ## Strumenti -Le Skills ti forniscono i tuoi strumenti. Quando te ne serve uno, controlla il suo `SKILL.md`. Tieni note locali (nomi delle fotocamere, dettagli SSH, preferenze vocali) in `TOOLS.md`. +Le Skills ti forniscono i tuoi strumenti. Quando te ne serve uno, controlla il suo `SKILL.md`. Tieni le note locali (nomi delle telecamere, dettagli SSH, preferenze vocali) in `TOOLS.md`. -**🎭 Narrazione vocale:** se hai `sag` (ElevenLabs TTS), usa la voce per storie, riassunti di film e momenti "storytime"! Molto più coinvolgente di muri di testo. Sorprendi le persone con voci divertenti. +**🎭 Narrazione vocale:** Se hai `sag` (ElevenLabs TTS), usa la voce per storie, riassunti di film e momenti "storytime"! Molto più coinvolgente di muri di testo. Sorprendi le persone con voci divertenti. **📝 Formattazione per piattaforma:** -- **Discord/WhatsApp:** niente tabelle Markdown! Usa invece elenchi puntati -- **Link Discord:** racchiudi più link in `<>` per sopprimere gli embed: `` -- **WhatsApp:** niente intestazioni — usa il **grassetto** o il MAIUSCOLO per dare enfasi +- **Discord/WhatsApp:** Niente tabelle markdown! Usa invece elenchi puntati +- **Link Discord:** Racchiudi più link in `<>` per sopprimere gli embed: `` +- **WhatsApp:** Niente intestazioni — usa il **grassetto** o le MAIUSCOLE per dare enfasi -## 💓 Heartbeat - sii proattivo! +## 💓 Heartbeat - Sii proattivo! -Quando ricevi un heartbeat poll (messaggio che corrisponde al prompt heartbeat configurato), non rispondere sempre e solo `HEARTBEAT_OK`. Usa gli heartbeat in modo produttivo! +Quando ricevi un heartbeat poll (un messaggio che corrisponde al prompt heartbeat configurato), non limitarti a rispondere `HEARTBEAT_OK` ogni volta. Usa gli heartbeat in modo produttivo! -Puoi modificare liberamente `HEARTBEAT.md` con una breve checklist o dei promemoria. Mantienilo piccolo per limitare il consumo di token. +Sei libero di modificare `HEARTBEAT.md` con una breve checklist o promemoria. Mantienilo piccolo per limitare il consumo di token. ### Heartbeat vs Cron: quando usare ciascuno **Usa heartbeat quando:** -- Più controlli possono essere raggruppati insieme (posta + calendario + notifiche in un solo turno) -- Hai bisogno del contesto conversazionale dei messaggi recenti +- Più controlli possono essere raggruppati insieme (posta in arrivo + calendario + notifiche in un unico turno) +- Ti serve il contesto conversazionale dei messaggi recenti - Il timing può slittare leggermente (ogni ~30 minuti va bene, non deve essere preciso) - Vuoi ridurre le chiamate API combinando controlli periodici **Usa cron quando:** -- Il timing preciso conta ("alle 9:00 in punto ogni lunedì") -- Il task deve essere isolato dalla cronologia della sessione principale -- Vuoi un modello o un livello di thinking diverso per il task -- Promemoria one-shot ("ricordamelo tra 20 minuti") +- Il timing preciso è importante ("alle 9:00 in punto ogni lunedì") +- L'attività deve essere isolata dalla cronologia della sessione principale +- Vuoi un modello o un livello di ragionamento diverso per l'attività +- Promemoria una tantum ("ricordamelo tra 20 minuti") - L'output deve essere consegnato direttamente a un canale senza coinvolgere la sessione principale -**Suggerimento:** raggruppa controlli periodici simili in `HEARTBEAT.md` invece di creare più job cron. Usa cron per pianificazioni precise e task standalone. +**Suggerimento:** Raggruppa controlli periodici simili in `HEARTBEAT.md` invece di creare più cron job. Usa cron per pianificazioni precise e attività indipendenti. -**Cose da controllare** (ruotale, 2-4 volte al giorno): +**Cose da controllare (ruotale, 2-4 volte al giorno):** -- **Email** - Ci sono messaggi non letti urgenti? -- **Calendario** - Eventi in arrivo nelle prossime 24-48 ore? +- **Email** - Ci sono messaggi urgenti non letti? +- **Calendario** - Ci sono eventi in arrivo nelle prossime 24-48 ore? - **Menzioni** - Notifiche Twitter/social? - **Meteo** - Rilevante se il tuo umano potrebbe uscire? @@ -186,16 +191,16 @@ Puoi modificare liberamente `HEARTBEAT.md` con una breve checklist o dei promemo **Quando contattare:** - È arrivata un'email importante -- Un evento del calendario è imminente (<2h) +- Un evento in calendario sta per iniziare (<2h) - Hai trovato qualcosa di interessante - Sono passate >8h dall'ultima volta che hai detto qualcosa -**Quando restare in silenzio (`HEARTBEAT_OK`):** +**Quando restare in silenzio (HEARTBEAT_OK):** -- Tarda notte (23:00-08:00) a meno che non sia urgente +- A tarda notte (23:00-08:00) a meno che non sia urgente - L'umano è chiaramente occupato - Non c'è nulla di nuovo dall'ultimo controllo -- Hai appena controllato da <30 minuti +- Hai appena controllato <30 minuti fa **Lavoro proattivo che puoi fare senza chiedere:** @@ -203,20 +208,20 @@ Puoi modificare liberamente `HEARTBEAT.md` con una breve checklist o dei promemo - Controllare i progetti (git status, ecc.) - Aggiornare la documentazione - Fare commit e push delle tue modifiche -- **Rivedere e aggiornare `MEMORY.md`** (vedi sotto) +- **Rivedere e aggiornare MEMORY.md** (vedi sotto) ### 🔄 Manutenzione della memoria (durante gli heartbeat) Periodicamente (ogni pochi giorni), usa un heartbeat per: 1. Leggere i file recenti `memory/YYYY-MM-DD.md` -2. Identificare eventi significativi, lezioni o intuizioni che vale la pena conservare a lungo termine -3. Aggiornare `MEMORY.md` con gli apprendimenti distillati -4. Rimuovere da `MEMORY.md` le informazioni obsolete che non sono più rilevanti +2. Identificare eventi significativi, lezioni o intuizioni che valga la pena conservare a lungo termine +3. Aggiornare `MEMORY.md` con apprendimenti distillati +4. Rimuovere da MEMORY.md le informazioni obsolete che non sono più rilevanti -Pensalo come un umano che rivede il proprio diario e aggiorna il proprio modello mentale. I file giornalieri sono note grezze; `MEMORY.md` è saggezza curata. +Pensalo come un umano che rivede il proprio diario e aggiorna il proprio modello mentale. I file quotidiani sono note grezze; `MEMORY.md` è saggezza curata. -L'obiettivo: essere utile senza risultare fastidioso. Fai un check-in qualche volta al giorno, svolgi lavoro utile in background, ma rispetta i momenti di quiete. +L'obiettivo: essere utile senza essere fastidioso. Fai un check-in qualche volta al giorno, svolgi lavoro utile in background, ma rispetta i momenti di quiete. ## Rendilo tuo diff --git a/docs/it/reference/token-use.md b/docs/it/reference/token-use.md index b23201d6f..ea2074aa6 100644 --- a/docs/it/reference/token-use.md +++ b/docs/it/reference/token-use.md @@ -1,22 +1,21 @@ --- read_when: - - Spiegazione di uso dei token, costi o finestre di contesto - - Debug della crescita del contesto o del comportamento di compattazione -summary: Come OpenClaw costruisce il contesto del prompt e riporta uso dei token + costi -title: Uso dei token e costi + - Spiegazione dell'utilizzo dei token, dei costi o delle finestre di contesto + - Debug del comportamento di crescita o compattazione del contesto +summary: Come OpenClaw costruisce il contesto del prompt e riporta l'utilizzo dei token e i costi +title: Utilizzo dei token e costi x-i18n: - generated_at: "2026-04-07T08:17:27Z" + generated_at: "2026-04-12T08:08:25Z" model: gpt-5.4 provider: openai - source_hash: 0683693d6c6fcde7d5fba236064ba97dd4b317ae6bea3069db969fcd178119d9 + source_hash: f8c856549cd28b8364a640e6fa9ec26aa736895c7a993e96cbe85838e7df2dfb source_path: reference/token-use.md workflow: 15 --- -# Uso dei token e costi +# Utilizzo dei token e costi -OpenClaw tiene traccia dei **token**, non dei caratteri. I token sono specifici del modello, ma la maggior parte -dei modelli in stile OpenAI ha una media di circa 4 caratteri per token per il testo inglese. +OpenClaw tiene traccia dei **token**, non dei caratteri. I token dipendono dal modello, ma la maggior parte dei modelli in stile OpenAI ha una media di circa 4 caratteri per token per il testo in inglese. ## Come viene costruito il prompt di sistema @@ -24,13 +23,13 @@ OpenClaw assembla il proprio prompt di sistema a ogni esecuzione. Include: - Elenco degli strumenti + brevi descrizioni - Elenco delle Skills (solo metadati; le istruzioni vengono caricate su richiesta con `read`) -- Istruzioni di auto-aggiornamento -- Workspace + file bootstrap (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` quando nuovi, più `MEMORY.md` quando presente o `memory.md` come fallback minuscolo). I file grandi vengono troncati da `agents.defaults.bootstrapMaxChars` (predefinito: 20000), e l'iniezione bootstrap totale è limitata da `agents.defaults.bootstrapTotalMaxChars` (predefinito: 150000). I file `memory/*.md` sono su richiesta tramite gli strumenti memory e non vengono iniettati automaticamente. +- Istruzioni per l'autoaggiornamento +- File del workspace + bootstrap (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` quando nuovo, più `MEMORY.md` quando presente o `memory.md` come fallback in minuscolo). I file grandi vengono troncati da `agents.defaults.bootstrapMaxChars` (predefinito: 20000), e l'iniezione bootstrap totale è limitata da `agents.defaults.bootstrapTotalMaxChars` (predefinito: 150000). I file giornalieri `memory/*.md` non fanno parte del normale prompt bootstrap; restano disponibili su richiesta tramite gli strumenti di memoria nei turni ordinari, ma `/new` e `/reset` senza argomenti possono anteporre un blocco di contesto di avvio monouso con la memoria giornaliera recente per quel primo turno. Questo preambolo di avvio è controllato da `agents.defaults.startupContext`. - Ora (UTC + fuso orario dell'utente) - Tag di risposta + comportamento heartbeat -- Metadati runtime (host/OS/modello/thinking) +- Metadati di runtime (host/OS/modello/riflessione) -Vedi la scomposizione completa in [Prompt di sistema](/it/concepts/system-prompt). +Vedi la suddivisione completa in [Prompt di sistema](/it/concepts/system-prompt). ## Cosa rientra nella finestra di contesto @@ -40,53 +39,39 @@ Tutto ciò che il modello riceve conta ai fini del limite di contesto: - Cronologia della conversazione (messaggi utente + assistente) - Chiamate agli strumenti e risultati degli strumenti - Allegati/trascrizioni (immagini, audio, file) -- Riepiloghi di compattazione e artefatti di pruning -- Wrapper del provider o header di sicurezza (non visibili, ma comunque conteggiati) +- Riepiloghi di compattazione e artefatti di potatura +- Wrapper del provider o intestazioni di sicurezza (non visibili, ma comunque conteggiati) -Per le immagini, OpenClaw riduce la scala dei payload immagine di trascrizione/strumenti prima delle chiamate al provider. +Per le immagini, OpenClaw ridimensiona i payload immagine di trascrizione/strumenti prima delle chiamate al provider. Usa `agents.defaults.imageMaxDimensionPx` (predefinito: `1200`) per regolare questo aspetto: -- Valori più bassi di solito riducono l'uso di vision-token e la dimensione del payload. -- Valori più alti preservano più dettaglio visivo per screenshot ricchi di OCR/UI. +- Valori più bassi di solito riducono l'uso di vision token e la dimensione del payload. +- Valori più alti preservano più dettaglio visivo per OCR/screenshot ricchi di interfaccia. -Per una scomposizione pratica (per file iniettato, strumenti, Skills e dimensione del prompt di sistema), usa `/context list` o `/context detail`. Vedi [Contesto](/it/concepts/context). +Per una suddivisione pratica (per ogni file iniettato, strumenti, Skills e dimensione del prompt di sistema), usa `/context list` o `/context detail`. Vedi [Contesto](/it/concepts/context). -## Come vedere l'uso corrente dei token +## Come vedere l'utilizzo attuale dei token Usa questi comandi in chat: -- `/status` → **scheda di stato ricca di emoji** con il modello della sessione, utilizzo del contesto, - token input/output dell'ultima risposta e **costo stimato** (solo chiave API). +- `/status` → **scheda di stato ricca di emoji** con il modello della sessione, utilizzo del contesto, token di input/output dell'ultima risposta e **costo stimato** (solo chiave API). - `/usage off|tokens|full` → aggiunge un **footer di utilizzo per risposta** a ogni risposta. - Persiste per sessione (memorizzato come `responseUsage`). - L'autenticazione OAuth **nasconde il costo** (solo token). -- `/usage cost` → mostra un riepilogo locale dei costi dai log di sessione OpenClaw. +- `/usage cost` → mostra un riepilogo locale dei costi dai log di sessione di OpenClaw. Altre superfici: - **TUI/Web TUI:** `/status` + `/usage` sono supportati. -- **CLI:** `openclaw status --usage` e `openclaw channels list` mostrano - finestre di quota provider normalizzate (`X% left`, non costi per risposta). - Provider attuali con finestra di utilizzo: Anthropic, GitHub Copilot, Gemini CLI, - OpenAI Codex, MiniMax, Xiaomi e z.ai. +- **CLI:** `openclaw status --usage` e `openclaw channels list` mostrano finestre di quota provider normalizzate (`X% rimanente`, non costi per risposta). + Provider attuali per le finestre di utilizzo: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi e z.ai. Le superfici di utilizzo normalizzano gli alias comuni dei campi nativi del provider prima della visualizzazione. -Per il traffico OpenAI-family Responses, questo include sia `input_tokens` / -`output_tokens` sia `prompt_tokens` / `completion_tokens`, così i nomi dei campi specifici del trasporto -non cambiano `/status`, `/usage` o i riepiloghi della sessione. -Anche l'utilizzo JSON di Gemini CLI viene normalizzato: il testo della risposta proviene da `response`, e -`stats.cached` viene mappato a `cacheRead` con `stats.input_tokens - stats.cached` -usato quando la CLI omette un campo esplicito `stats.input`. -Per il traffico nativo OpenAI-family Responses, gli alias di utilizzo WebSocket/SSE sono -normalizzati allo stesso modo, e i totali ricadono su input + output normalizzati quando -`total_tokens` è mancante o uguale a `0`. -Quando lo snapshot della sessione corrente è scarno, `/status` e `session_status` possono -anche recuperare contatori token/cache e l'etichetta del modello runtime attivo dal -log di utilizzo della trascrizione più recente. I valori live non nulli esistenti hanno comunque la precedenza sui valori di fallback della trascrizione, e i totali di trascrizione più grandi orientati al prompt -possono prevalere quando i totali memorizzati sono mancanti o più piccoli. -L'autenticazione di utilizzo per le finestre di quota del provider proviene da hook specifici del provider quando -disponibili; altrimenti OpenClaw ricade sulla corrispondenza delle credenziali OAuth/API-key -da profili auth, env o configurazione. +Per il traffico OpenAI-family Responses, questo include sia `input_tokens` / `output_tokens` sia `prompt_tokens` / `completion_tokens`, quindi i nomi dei campi specifici del trasporto non cambiano `/status`, `/usage` o i riepiloghi di sessione. +Anche l'utilizzo JSON di Gemini CLI viene normalizzato: il testo della risposta proviene da `response`, e `stats.cached` viene mappato a `cacheRead`, con `stats.input_tokens - stats.cached` usato quando la CLI omette un campo `stats.input` esplicito. +Per il traffico nativo OpenAI-family Responses, gli alias di utilizzo WebSocket/SSE vengono normalizzati allo stesso modo, e i totali ricadono su input + output normalizzati quando `total_tokens` manca o vale `0`. +Quando lo snapshot della sessione corrente è scarno, `/status` e `session_status` possono anche recuperare i contatori token/cache e l'etichetta del modello di runtime attivo dal log di utilizzo della trascrizione più recente. I valori live esistenti e non nulli hanno comunque la precedenza sui valori di fallback della trascrizione, e i totali di trascrizione orientati al prompt più grandi possono prevalere quando i totali memorizzati mancano o sono più piccoli. +L'autenticazione di utilizzo per le finestre di quota del provider proviene da hook specifici del provider quando disponibili; altrimenti OpenClaw ricorre alla corrispondenza di credenziali OAuth/chiave API dai profili di autenticazione, dall'ambiente o dalla configurazione. ## Stima dei costi (quando mostrata) @@ -96,33 +81,24 @@ I costi sono stimati dalla configurazione dei prezzi del tuo modello: models.providers..models[].cost ``` -Questi sono **USD per 1M token** per `input`, `output`, `cacheRead` e -`cacheWrite`. Se i prezzi mancano, OpenClaw mostra solo i token. I token OAuth -non mostrano mai il costo in dollari. +Questi sono **USD per 1M token** per `input`, `output`, `cacheRead` e `cacheWrite`. Se i prezzi mancano, OpenClaw mostra solo i token. I token OAuth non mostrano mai il costo in dollari. -## Impatto di cache TTL e pruning +## Impatto di TTL della cache e potatura -La cache dei prompt del provider si applica solo entro la finestra TTL della cache. OpenClaw può -facoltativamente eseguire il **cache-ttl pruning**: esegue il pruning della sessione una volta che il TTL della cache -è scaduto, quindi reimposta la finestra della cache così le richieste successive possano riutilizzare il contesto appena memorizzato in cache invece di rimettere in cache l'intera cronologia. Questo mantiene più bassi i costi di scrittura della cache quando una sessione resta inattiva oltre il TTL. +La cache del prompt del provider si applica solo entro la finestra TTL della cache. OpenClaw può opzionalmente eseguire la **potatura cache-ttl**: pota la sessione una volta scaduto il TTL della cache, poi reimposta la finestra della cache in modo che le richieste successive possano riutilizzare il contesto appena messo in cache invece di rimettere in cache l'intera cronologia. Questo mantiene più bassi i costi di scrittura della cache quando una sessione resta inattiva oltre il TTL. -Configuralo in [Configurazione Gateway](/it/gateway/configuration) e vedi i -dettagli del comportamento in [Pruning della sessione](/it/concepts/session-pruning). +Configuralo in [Configurazione del Gateway](/it/gateway/configuration) e vedi i dettagli del comportamento in [Potatura della sessione](/it/concepts/session-pruning). -Heartbeat può mantenere la cache **calda** durante gli intervalli di inattività. Se il TTL della cache del tuo modello -è `1h`, impostare l'intervallo heartbeat appena sotto quel valore (ad esempio `55m`) può evitare -di rimettere in cache l'intero prompt, riducendo i costi di scrittura della cache. +Heartbeat può mantenere la cache **calda** durante i periodi di inattività. Se il TTL della cache del tuo modello è `1h`, impostare l'intervallo heartbeat appena sotto quel valore (ad esempio `55m`) può evitare di rimettere in cache l'intero prompt, riducendo i costi di scrittura della cache. -Nelle configurazioni multi-agent, puoi mantenere una configurazione modello condivisa e regolare il comportamento della cache -per agente con `agents.list[].params.cacheRetention`. +Nelle configurazioni multi-agent, puoi mantenere una configurazione del modello condivisa e regolare il comportamento della cache per agente con `agents.list[].params.cacheRetention`. -Per una guida completa comando per comando, vedi [Caching dei prompt](/it/reference/prompt-caching). +Per una guida completa, parametro per parametro, vedi [Prompt Caching](/it/reference/prompt-caching). -Per i prezzi dell'API Anthropic, le letture della cache sono significativamente più economiche dei token -di input, mentre le scritture della cache vengono fatturate con un moltiplicatore più alto. Vedi i prezzi del prompt caching di Anthropic per le tariffe più recenti e i moltiplicatori TTL: +Per i prezzi dell'API Anthropic, le letture della cache sono significativamente più economiche dei token di input, mentre le scritture della cache vengono fatturate con un moltiplicatore più alto. Vedi i prezzi del prompt caching di Anthropic per le tariffe e i moltiplicatori TTL più aggiornati: [https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching) -### Esempio: mantenere calda per 1h la cache con heartbeat +### Esempio: mantenere calda una cache di 1h con heartbeat ```yaml agents: @@ -137,7 +113,7 @@ agents: every: "55m" ``` -### Esempio: traffico misto con strategia cache per agente +### Esempio: traffico misto con strategia di cache per agente ```yaml agents: @@ -152,20 +128,17 @@ agents: - id: "research" default: true heartbeat: - every: "55m" # mantiene calda la cache lunga per sessioni profonde + every: "55m" # mantiene calda la cache lunga per le sessioni profonde - id: "alerts" params: - cacheRetention: "none" # evita scritture cache per notifiche intermittenti + cacheRetention: "none" # evita scritture della cache per notifiche intermittenti ``` -`agents.list[].params` viene unito sopra `params` del modello selezionato, quindi puoi -sovrascrivere solo `cacheRetention` ed ereditare invariati gli altri valori predefiniti del modello. +`agents.list[].params` viene unito sopra i `params` del modello selezionato, quindi puoi sovrascrivere solo `cacheRetention` e lasciare invariati gli altri valori predefiniti del modello. -### Esempio: abilitare l'header beta Anthropic 1M context +### Esempio: abilitare l'intestazione beta Anthropic da 1M di contesto -La finestra di contesto Anthropic da 1M è attualmente protetta da beta. OpenClaw può iniettare il -valore `anthropic-beta` richiesto quando abiliti `context1m` sui modelli Opus -o Sonnet supportati. +La finestra di contesto da 1M di Anthropic è attualmente protetta da beta. OpenClaw può iniettare il valore `anthropic-beta` richiesto quando abiliti `context1m` sui modelli Opus o Sonnet supportati. ```yaml agents: @@ -176,23 +149,20 @@ agents: context1m: true ``` -Questo viene mappato all'header beta Anthropic `context-1m-2025-08-07`. +Questo viene mappato all'intestazione beta `context-1m-2025-08-07` di Anthropic. -Questo si applica solo quando `context1m: true` è impostato su quella voce modello. +Questo si applica solo quando `context1m: true` è impostato su quella voce del modello. -Requisito: la credenziale deve essere idonea per l'uso long-context. In caso contrario, -Anthropic risponde con un errore di rate limit lato provider per quella richiesta. +Requisito: la credenziale deve essere idonea all'uso del contesto lungo. In caso contrario, Anthropic risponde con un errore di rate limit lato provider per quella richiesta. -Se autentichi Anthropic con token OAuth/abbonamento (`sk-ant-oat-*`), -OpenClaw salta l'header beta `context-1m-*` perché Anthropic attualmente -rifiuta questa combinazione con HTTP 401. +Se autentichi Anthropic con token OAuth/abbonamento (`sk-ant-oat-*`), OpenClaw salta l'intestazione beta `context-1m-*` perché Anthropic attualmente rifiuta quella combinazione con HTTP 401. ## Suggerimenti per ridurre la pressione sui token -- Usa `/compact` per riassumere sessioni lunghe. +- Usa `/compact` per riepilogare sessioni lunghe. - Riduci i grandi output degli strumenti nei tuoi workflow. - Abbassa `agents.defaults.imageMaxDimensionPx` per sessioni ricche di screenshot. - Mantieni brevi le descrizioni delle Skills (l'elenco delle Skills viene iniettato nel prompt). -- Preferisci modelli più piccoli per lavoro verboso ed esplorativo. +- Preferisci modelli più piccoli per lavori verbosi ed esplorativi. Vedi [Skills](/it/tools/skills) per la formula esatta del sovraccarico dell'elenco delle Skills.