chore(i18n): refresh it translations

This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-08 06:06:15 +00:00
parent f368abe421
commit 5b10b3888e
13 changed files with 2078 additions and 1667 deletions

View File

@ -1,13 +1,13 @@
---
read_when:
- Configurazione di Slack o debug della modalità socket/HTTP di Slack
summary: Configurazione di Slack e comportamento di runtime (Socket Mode + URL di richiesta HTTP)
summary: Configurazione di Slack e comportamento in fase di esecuzione (Socket Mode + URL di richiesta HTTP)
title: Slack
x-i18n:
generated_at: "2026-04-07T08:12:56Z"
generated_at: "2026-04-08T06:02:10Z"
model: gpt-5.4
provider: openai
source_hash: 2b8fd2cc6c638ee82069f0af2c2b6f6f49c87da709b941433a0343724a9907ea
source_hash: cad132131ddce688517def7c14703ad314441c67aacc4cc2a2a721e1d1c01942
source_path: channels/slack.md
workflow: 15
---
@ -24,7 +24,7 @@ Stato: pronto per la produzione per DM + canali tramite integrazioni dell'app Sl
Comportamento nativo dei comandi e catalogo dei comandi.
</Card>
<Card title="Risoluzione dei problemi dei canali" icon="wrench" href="/it/channels/troubleshooting">
Diagnostica tra canali e playbook di riparazione.
Diagnostica tra canali e procedure di ripristino.
</Card>
</CardGroup>
@ -37,9 +37,9 @@ 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 [manifest di esempio](#manifest-and-scope-checklist) qui sotto e continua per creare
- incolla il [manifesto di esempio](#manifest-and-scope-checklist) qui sotto e continua per creare l'app
- genera un **App-Level Token** (`xapp-...`) con `connections:write`
- installa l'app e copia il **Bot Token** (`xoxb-...`) mostrato
- installa l'app e copia il **Bot Token** (`xoxb-...`) visualizzato
</Step>
<Step title="Configura OpenClaw">
@ -83,9 +83,9 @@ 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 [manifest di esempio](#manifest-and-scope-checklist) e aggiorna gli URL prima di creare
- incolla il [manifesto 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-...`) mostrato
- installa l'app e copia il **Bot Token** (`xoxb-...`) visualizzato
</Step>
@ -125,7 +125,7 @@ openclaw gateway
</Tab>
</Tabs>
## Checklist di manifest e scope
## Manifesto ed elenco di controllo degli scope
<Tabs>
<Tab title="Socket Mode (predefinita)">
@ -290,13 +290,12 @@ openclaw gateway
</Tabs>
<AccordionGroup>
<Accordion title="Scope di paternità facoltativi (operazioni di scrittura)">
<Accordion title="Scope di authoring opzionali (operazioni di scrittura)">
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.
Se usi un'icona emoji, Slack si aspetta la sintassi `:emoji_name:`.
</Accordion>
<Accordion title="Scope facoltativi del token utente (operazioni di lettura)">
<Accordion title="Scope opzionali per user token (operazioni di lettura)">
Se configuri `channels.slack.userToken`, gli scope di lettura tipici sono:
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
@ -305,7 +304,7 @@ openclaw gateway
- `reactions:read`
- `pins:read`
- `emoji:read`
- `search:read` (se dipendi dalle letture di ricerca di Slack)
- `search:read` (se dipendi dalle letture della ricerca di Slack)
</Accordion>
</AccordionGroup>
@ -316,26 +315,26 @@ openclaw gateway
- La modalità HTTP richiede `botToken` + `signingSecret`.
- `botToken`, `appToken`, `signingSecret` e `userToken` accettano stringhe
in chiaro o oggetti SecretRef.
- I token di configurazione sovrascrivono il fallback env.
- I token nella 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 usa per impostazione predefinita il comportamento di sola lettura (`userTokenReadOnly: true`).
- `userToken` (`xoxp-...`) è solo di configurazione (nessun fallback env) e per impostazione predefinita usa il comportamento di sola lettura (`userTokenReadOnly: true`).
Comportamento dello snapshot di stato:
Comportamento dell'istantanea di stato:
- L'ispezione dell'account Slack traccia i campi `*Source` e `*Status`
per credenziale (`botToken`, `appToken`, `signingSecret`, `userToken`).
- Lo stato è `available`, `configured_unavailable` o `missing`.
per ogni credenziale (`botToken`, `appToken`, `signingSecret`, `userToken`).
- Lo stato può essere `available`, `configured_unavailable` o `missing`.
- `configured_unavailable` significa che l'account è configurato tramite SecretRef
o un'altra sorgente di secret non inline, ma il percorso di comando/runtime corrente
o un'altra origine di segreti non inline, ma il percorso di comando/esecuzione corrente
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`.
<Tip>
Per le letture di azioni/directory, il token utente può essere preferito 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.
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.
</Tip>
## Azioni e controlli
## Azioni e vincoli
Le azioni Slack sono controllate da `channels.slack.actions.*`.
@ -343,13 +342,13 @@ Gruppi di azioni disponibili negli strumenti Slack correnti:
| Gruppo | Predefinito |
| ---------- | ----------- |
| messages | abilitato |
| reactions | abilitato |
| pins | abilitato |
| memberInfo | abilitato |
| emojiList | abilitato |
| messages | abilitato |
| reactions | abilitato |
| pins | abilitato |
| memberInfo | abilitato |
| emojiList | abilitato |
Le attuali azioni sui messaggi Slack includono `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` ed `emoji-list`.
Le azioni correnti sui messaggi Slack includono `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` ed `emoji-list`.
## Controllo degli accessi e instradamento
@ -362,53 +361,53 @@ Le attuali azioni sui messaggi Slack includono `send`, `upload-file`, `download-
- `open` (richiede che `channels.slack.allowFrom` includa `"*"`; legacy: `channels.slack.dm.allowFrom`)
- `disabled`
Flag dei DM:
Flag DM:
- `dm.enabled` (predefinito true)
- `channels.slack.allowFrom` (consigliato)
- `channels.slack.allowFrom` (preferito)
- `dm.allowFrom` (legacy)
- `dm.groupEnabled` (i DM di gruppo sono false per impostazione predefinita)
- `dm.groupChannels` (allowlist MPIM facoltativa)
- `dm.groupEnabled` (DM di gruppo predefiniti su false)
- `dm.groupChannels` (allowlist MPIM opzionale)
Precedenza multi-account:
- `channels.slack.accounts.default.allowFrom` si applica solo all'account `default`.
- Gli account con nome ereditano `channels.slack.allowFrom` quando il proprio `allowFrom` non è impostato.
- Gli account con nome ereditano `channels.slack.allowFrom` quando il loro `allowFrom` non è impostato.
- Gli account con nome non ereditano `channels.slack.accounts.default.allowFrom`.
L'associazione nei DM usa `openclaw pairing approve slack <code>`.
</Tab>
<Tab title="Criterio del canale">
<Tab title="Criterio canale">
`channels.slack.groupPolicy` controlla la gestione dei canali:
- `open`
- `allowlist`
- `disabled`
L'allowlist dei canali si trova in `channels.slack.channels` e dovrebbe usare ID canale stabili.
L'allowlist dei canali si trova in `channels.slack.channels` e dovrebbe usare ID di canale stabili.
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).
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).
Risoluzione nome/ID:
- le voci dell'allowlist dei canali e dell'allowlist dei DM vengono risolte all'avvio quando l'accesso tramite token lo consente
- le voci irrisolte del nome del canale vengono mantenute come configurate ma ignorate per impostazione predefinita ai fini dell'instradamento
- l'autorizzazione in ingresso e l'instradamento del canale sono basati prima di tutto sugli ID; la corrispondenza diretta di username/slug richiede `channels.slack.dangerouslyAllowNameMatching: true`
- 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`
</Tab>
<Tab title="Menzioni e utenti del canale">
I messaggi del canale sono per impostazione predefinita soggetti al controllo delle menzioni.
Per impostazione predefinita, i messaggi nel canale sono vincolati dalle menzioni.
Sorgenti delle menzioni:
Origini delle menzioni:
- menzione esplicita dell'app (`<@botId>`)
- pattern regex di menzione (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- comportamento implicito di risposta nel thread al bot (disabilitato quando `thread.requireExplicitMention` è `true`)
- comportamento implicito di risposta nei thread al bot (disabilitato quando `thread.requireExplicitMention` è `true`)
Controlli per canale (`channels.slack.channels.<id>`; nomi solo tramite risoluzione all'avvio o `dangerouslyAllowNameMatching`):
Controlli per canale (`channels.slack.channels.<id>`; i nomi solo tramite risoluzione all'avvio o `dangerouslyAllowNameMatching`):
- `requireMention`
- `users` (allowlist)
@ -416,7 +415,7 @@ Le attuali azioni sui messaggi Slack includono `send`, `upload-file`, `download-
- `skills`
- `systemPrompt`
- `tools`, `toolsBySender`
- formato della chiave `toolsBySender`: `id:`, `e164:`, `username:`, `name:` o wildcard `"*"`
- formato chiave `toolsBySender`: `id:`, `e164:`, `username:`, `name:` oppure wildcard `"*"`
(le chiavi legacy senza prefisso continuano a essere mappate solo a `id:`)
</Tab>
@ -424,28 +423,28 @@ Le attuali azioni sui messaggi Slack includono `send`, `upload-file`, `download-
## Thread, sessioni e tag di risposta
- I DM sono instradati come `direct`; i canali come `channel`; gli MPIM come `group`.
- Con il valore predefinito `session.dmScope=main`, i DM di Slack confluiscono nella sessione principale dell'agente.
- Sessioni del canale: `agent:<agentId>:slack:channel:<channelId>`.
- Le risposte nei thread possono creare suffissi di sessione del thread (`:thread:<threadTs>`) quando applicabile.
- 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.
- Sessioni canale: `agent:<agentId>:slack:channel:<channelId>`.
- Le risposte nei thread possono creare suffissi di sessione thread (`:thread:<threadTs>`) 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 del thread (predefinito `20`; imposta `0` per disabilitare).
- `channels.slack.thread.requireExplicitMention` (predefinito `false`): quando è `true`, sopprime le menzioni implicite nel 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 questo, le risposte in un thread a cui partecipa il bot bypassano il controllo `requireMention`.
- `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`.
Controlli del threading delle risposte:
Controlli del thread di risposta:
- `channels.slack.replyToMode`: `off|first|all|batched` (predefinito `off`)
- `channels.slack.replyToModeByChatType`: per `direct|group|channel`
- fallback legacy per le chat dirette: `channels.slack.dm.replyToMode`
- fallback legacy per chat dirette: `channels.slack.dm.replyToMode`
Sono supportati tag di risposta manuali:
Sono supportati i tag di risposta manuali:
- `[[reply_to_current]]`
- `[[reply_to:<id>]]`
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 al 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 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.
## Reazioni di conferma
## Reazioni di ack
`ackReaction` invia un'emoji di conferma mentre OpenClaw elabora un messaggio in ingresso.
@ -458,7 +457,7 @@ Ordine di risoluzione:
Note:
- Slack si aspetta shortcodes (ad esempio `"eyes"`).
- Slack si aspetta shortcodes (per esempio `"eyes"`).
- Usa `""` per disabilitare la reazione per l'account Slack o globalmente.
## Streaming del testo
@ -467,23 +466,27 @@ Note:
- `off`: disabilita lo streaming dell'anteprima in tempo reale.
- `partial` (predefinito): sostituisce il testo di anteprima con l'output parziale più recente.
- `block`: aggiunge aggiornamenti di anteprima suddivisi in blocchi.
- `block`: aggiunge aggiornamenti di anteprima a blocchi.
- `progress`: mostra testo di stato dell'avanzamento durante la generazione, poi invia il testo finale.
`channels.slack.nativeStreaming` controlla lo streaming nativo del testo di Slack quando `streaming` è `partial` (predefinito: `true`).
`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é appaia lo streaming nativo del testo. La selezione del thread continua comunque a seguire `replyToMode`. In assenza di un thread, viene usata la normale anteprima bozza.
- I contenuti multimediali e i payload non testuali usano il fallback alla consegna normale.
- 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.
- 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 nativo del testo di Slack:
Usa l'anteprima bozza invece dello streaming di testo nativo di Slack:
```json5
{
channels: {
slack: {
streaming: "partial",
nativeStreaming: false,
streaming: {
mode: "partial",
nativeTransport: false,
},
},
},
}
@ -491,12 +494,13 @@ Usa l'anteprima bozza invece dello streaming nativo del testo di Slack:
Chiavi legacy:
- `channels.slack.streamMode` (`replace | status_final | append`) viene migrato automaticamente in `channels.slack.streaming`.
- il booleano `channels.slack.streaming` viene migrato automaticamente in `channels.slack.nativeStreaming`.
- `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`.
## 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. Questo è particolarmente utile al di fuori delle risposte nei thread, che usano un indicatore di stato predefinito "sta scrivendo...".
`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...".
Ordine di risoluzione:
@ -505,24 +509,24 @@ Ordine di risoluzione:
Note:
- Slack si aspetta shortcodes (ad esempio `"hourglass_flowing_sand"`).
- La reazione è best-effort e la pulizia viene tentata automaticamente al termine della risposta o del percorso di errore.
- 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.
## Media, suddivisione in blocchi e consegna
<AccordionGroup>
<Accordion title="Allegati in ingresso">
Gli allegati di file Slack vengono scaricati da URL privati ospitati da Slack (flusso di richiesta autenticato con token) e scritti nel media store quando il recupero riesce e i limiti di dimensione lo consentono.
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.
Il limite di dimensione in ingresso in runtime è per impostazione predefinita `20MB`, salvo override tramite `channels.slack.mediaMaxMb`.
Il limite di dimensione in ingresso in fase di esecuzione è per impostazione predefinita `20MB`, salvo override con `channels.slack.mediaMaxMb`.
</Accordion>
<Accordion title="Testo e file in uscita">
- i blocchi di testo usano `channels.slack.textChunkLimit` (predefinito 4000)
- `channels.slack.chunkMode="newline"` abilita la suddivisione con priorità ai paragrafi
- `channels.slack.chunkMode="newline"` abilita la suddivisione dando 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 dei media
- 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
</Accordion>
<Accordion title="Destinazioni di consegna">
@ -531,26 +535,26 @@ Note:
- `user:<id>` per i DM
- `channel:<id>` per i canali
I DM di Slack vengono aperti tramite le API di conversazione di Slack quando si invia a destinazioni utente.
I DM Slack vengono aperti tramite le API di conversazione di Slack quando si invia verso destinazioni utente.
</Accordion>
</AccordionGroup>
## Comandi e comportamento slash
- La modalità automatica dei comandi nativi è **disattivata** per Slack (`commands.native: "auto"` non abilita i comandi nativi di Slack).
- Abilita gli handler dei comandi nativi di Slack con `channels.slack.commands.native: true` (o globale `commands.native: true`).
- 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 `/<command>`), 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 degli argomenti nativi ora adattano la loro strategia di rendering:
- I menu argomento nativi ora adattano la propria strategia di rendering:
- fino a 5 opzioni: blocchi di pulsanti
- 6-100 opzioni: menu di selezione statico
- oltre 100 opzioni: selezione esterna con filtro asincrono delle opzioni quando sono disponibili gli handler delle opzioni di interattività
- 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 del comando slash:
Impostazioni predefinite dei comandi slash:
- `enabled: false`
- `name: "openclaw"`
@ -561,11 +565,11 @@ Le sessioni slash usano chiavi isolate:
- `agent:<agentId>:slack:slash:<userId>`
e continuano comunque a instradare l'esecuzione del comando verso la sessione della conversazione di destinazione (`CommandTargetSessionKey`).
e continuano a instradare l'esecuzione del comando rispetto alla sessione della conversazione di destinazione (`CommandTargetSessionKey`).
## Risposte interattive
Slack può visualizzare controlli interattivi di risposta creati dall'agente, ma questa funzionalità è disabilitata per impostazione predefinita.
Slack può eseguire il rendering di controlli interattivi di risposta creati dagli agenti, ma questa funzionalità è disabilitata per impostazione predefinita.
Abilitala globalmente:
@ -599,42 +603,42 @@ Oppure abilitala solo per un account Slack:
}
```
Quando è abilitata, gli agenti possono emettere direttive di risposta solo per Slack:
Quando è abilitata, gli agenti possono emettere direttive di risposta solo 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 attraverso il percorso eventi di interazione Slack esistente.
Queste direttive vengono compilate in Slack Block Kit e instradano clic o selezioni di nuovo attraverso il percorso eventi di interazione Slack esistente.
Note:
- Questa è un'interfaccia utente specifica di Slack. Gli altri canali non traducono le direttive Slack Block Kit nei propri sistemi di pulsanti.
- 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 di testo originale invece di inviare un payload di blocchi non valido.
- 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 e interazioni interattive, invece di usare il fallback alla Web UI o al terminale.
Slack può agire come client di approvazione nativo con pulsanti interattivi e interazioni, invece di usare il fallback alla Web UI o al terminale.
- Le approvazioni exec usano `channels.slack.execApprovals.*` per l'instradamento nativo di DM/canali.
- Le approvazioni dei plugin possono comunque essere risolte tramite la stessa superficie nativa di pulsanti Slack quando la richiesta arriva già in Slack e il tipo di ID di approvazione è `plugin:`.
- L'autorizzazione dell'approvatore continua a essere applicata: solo gli utenti identificati come approvatori possono approvare o rifiutare richieste tramite Slack.
- 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.
Questo usa la stessa superficie condivisa di 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, sono l'esperienza utente primaria per l'approvazione; OpenClaw
dovrebbe includere un comando `/approve` manuale solo quando il risultato dello strumento indica che le
approvazioni in chat non sono disponibili o che l'approvazione manuale è l'unico percorso.
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
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.
Percorso di configurazione:
- `channels.slack.execApprovals.enabled`
- `channels.slack.execApprovals.approvers` (facoltativo; usa come fallback `commands.ownerAllowFrom` quando possibile)
- `channels.slack.execApprovals.approvers` (opzionale; 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
approvatore. Imposta `enabled: false` per disabilitare esplicitamente Slack come client di approvazione nativo.
Imposta `enabled: true` per forzare l'attivazione delle approvazioni native quando gli approvatori vengono risolti.
Imposta `enabled: true` per forzare le approvazioni native quando vengono risolti gli approvatori.
Comportamento predefinito senza configurazione esplicita delle approvazioni exec Slack:
@ -647,7 +651,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 alla chat di origine:
scegliere la consegna nella chat di origine:
```json5
{
@ -663,24 +667,24 @@ scegliere la consegna alla chat di origine:
}
```
L'inoltro condiviso `approvals.exec` è separato. Usalo solo quando i prompt di approvazione exec devono essere inoltrati anche
ad altre chat o a destinazioni esplicite fuori banda. Anche l'inoltro condiviso `approvals.plugin` è
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à
in Slack.
Anche `/approve` nella stessa chat funziona nei canali e nei DM di Slack che supportano già i comandi. Vedi [Approvazioni exec](/it/tools/exec-approvals) per il modello completo di inoltro delle approvazioni.
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.
## Eventi e comportamento operativo
- Le modifiche/eliminazioni dei messaggi e i thread broadcast vengono mappati 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/ridenominazione del canale e aggiunta/rimozione dei pin vengono mappati in eventi di sistema.
- 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.
- 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 messaggio iniziale del thread e il seeding iniziale del contesto della cronologia del thread vengono filtrati dagli allowlist del mittente configurati quando applicabile.
- Le azioni di blocco e le interazioni modali emettono eventi di sistema strutturati `Slack interaction: ...` con campi payload avanzati:
- azioni di blocco: 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
- 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
## Puntatori al riferimento di configurazione
@ -689,19 +693,19 @@ Riferimento principale:
- [Riferimento di configurazione - Slack](/it/gateway/configuration-reference#slack)
Campi Slack ad alto segnale:
- modalità/autenticazione: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
- modalità/auth: `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` (break-glass; tienilo disattivato salvo necessità)
- accesso ai canali: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
- interruttore di compatibilità: `dangerouslyAllowNameMatching` (ultima risorsa; lascialo disattivato salvo necessità)
- accesso canale: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
- threading/cronologia: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
- consegna: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `nativeStreaming`
- consegna: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`
- operazioni/funzionalità: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
## Risoluzione dei problemi
<AccordionGroup>
<Accordion title="Nessuna risposta nei canali">
Controlla, in ordine:
Verifica, in ordine:
- `groupPolicy`
- allowlist dei canali (`channels.slack.channels`)
@ -719,11 +723,11 @@ openclaw doctor
</Accordion>
<Accordion title="Messaggi DM ignorati">
Controlla:
Verifica:
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy` (o il legacy `channels.slack.dm.policy`)
- approvazioni di associazione / voci di allowlist
- `channels.slack.dmPolicy` (o legacy `channels.slack.dm.policy`)
- approvazioni di associazione / voci dell'allowlist
```bash
openclaw pairing list slack
@ -746,11 +750,11 @@ openclaw pairing list slack
- signing secret
- percorso webhook
- URL di richiesta Slack (Eventi + Interattività + Comandi slash)
- `webhookPath` univoco per account HTTP
- URL di richiesta Slack (Eventi + Interattività + Comandi Slash)
- `webhookPath` univoco per ogni account HTTP
Se `signingSecretStatus: "configured_unavailable"` appare negli snapshot
dell'account, l'account HTTP è configurato ma il runtime corrente non è riuscito
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.
</Accordion>
@ -758,10 +762,10 @@ openclaw pairing list slack
<Accordion title="I comandi nativi/slash non si attivano">
Verifica se intendevi usare:
- modalità comandi nativi (`channels.slack.commands.native: true`) con i corrispondenti comandi slash registrati in Slack
- modalità di comando nativo (`channels.slack.commands.native: true`) con i corrispondenti comandi slash registrati in Slack
- oppure modalità comando slash singolo (`channels.slack.slashCommand.enabled: true`)
Controlla anche `commands.useAccessGroups` e le allowlist di canale/utente.
Controlla anche `commands.useAccessGroups` e le allowlist di canali/utenti.
</Accordion>
</AccordionGroup>
@ -771,7 +775,7 @@ openclaw pairing list slack
- [Associazione](/it/channels/pairing)
- [Gruppi](/it/channels/groups)
- [Sicurezza](/it/gateway/security)
- [Instradamento dei canali](/it/channels/channel-routing)
- [Instradamento del canale](/it/channels/channel-routing)
- [Risoluzione dei problemi](/it/channels/troubleshooting)
- [Configurazione](/it/gateway/configuration)
- [Comandi slash](/it/tools/slash-commands)

View File

@ -5,128 +5,160 @@ read_when:
summary: Come OpenClaw ricorda le cose tra una sessione e l'altra
title: Panoramica della memoria
x-i18n:
generated_at: "2026-04-06T03:06:46Z"
generated_at: "2026-04-08T06:00:56Z"
model: gpt-5.4
provider: openai
source_hash: d19d4fa9c4b3232b7a97f7a382311d2a375b562040de15e9fe4a0b1990b825e7
source_hash: 3bb8552341b0b651609edaaae826a22fdc535d240aed4fad4af4b069454004af
source_path: concepts/memory.md
workflow: 15
---
# Panoramica della memoria
OpenClaw ricorda le cose scrivendo **semplici file Markdown** nel workspace del
tuo agente. Il modello "ricorda" solo ciò che viene salvato su disco -- non c'è
alcuno stato nascosto.
OpenClaw ricorda le cose scrivendo **semplici file Markdown** nello spazio di
lavoro del tuo agente. Il modello "ricorda" solo ciò che viene salvato su disco:
non esiste alcuno stato nascosto.
## Come funziona
Il tuo agente ha tre file correlati alla memoria:
Il tuo agente ha tre file relativi alla memoria:
- **`MEMORY.md`** -- memoria a lungo termine. Fatti durevoli, preferenze e
decisioni. Viene caricato all'inizio di ogni sessione DM.
- **`MEMORY.md`** -- memoria a lungo termine. Fatti duraturi, preferenze e
decisioni. Caricato all'inizio di ogni sessione di messaggi diretti.
- **`memory/YYYY-MM-DD.md`** -- note giornaliere. Contesto in corso e osservazioni.
Le note di oggi e di ieri vengono caricate automaticamente.
- **`DREAMS.md`** (sperimentale, facoltativo) -- Dream Diary e riepiloghi delle
scansioni di dreaming per la revisione umana.
- **`DREAMS.md`** (sperimentale, facoltativo) -- Diario dei sogni e riepiloghi
delle sessioni di dreaming per la revisione umana.
Questi file si trovano nel workspace dell'agente (predefinito `~/.openclaw/workspace`).
Questi file si trovano nello spazio di lavoro dell'agente (predefinito `~/.openclaw/workspace`).
<Tip>
Se vuoi che il tuo agente ricordi qualcosa, chiediglielo semplicemente: "Ricorda che
Se vuoi che il tuo agente ricordi qualcosa, basta chiederglielo: "Ricorda che
preferisco TypeScript." Lo scriverà nel file appropriato.
</Tip>
## Strumenti di memoria
L'agente ha due strumenti per lavorare con la memoria:
L'agente dispone di due strumenti per lavorare con la memoria:
- **`memory_search`** -- trova note pertinenti usando la ricerca semantica, anche quando
la formulazione è diversa dall'originale.
- **`memory_get`** -- legge uno specifico file di memoria o un intervallo di righe.
- **`memory_search`** -- trova note pertinenti usando la ricerca semantica, anche
quando la formulazione è diversa dall'originale.
- **`memory_get`** -- legge un file di memoria specifico o un intervallo di righe.
Entrambi gli strumenti sono forniti dal plugin di memoria attivo (predefinito: `memory-core`).
## Plugin complementare Memory Wiki
Se vuoi che la memoria duratura si comporti più come una base di conoscenza
mantenuta che come semplici note grezze, usa il plugin incluso `memory-wiki`.
`memory-wiki` compila la conoscenza duratura in un archivio wiki con:
- struttura delle pagine deterministica
- affermazioni ed evidenze strutturate
- tracciamento delle contraddizioni e dell'attualità
- dashboard generate
- digest compilati per i consumer agent/runtime
- strumenti nativi wiki come `wiki_search`, `wiki_get`, `wiki_apply` e `wiki_lint`
Non sostituisce il plugin di memoria attivo. Il plugin di memoria attivo
continua a gestire il richiamo, la promozione e il dreaming. `memory-wiki`
aggiunge accanto ad esso un livello di conoscenza ricco di provenienza.
Vedi [Memory Wiki](/it/plugins/memory-wiki).
## Ricerca nella memoria
Quando è configurato un provider di embedding, `memory_search` usa la **ricerca
ibrida** -- combinando la similarità vettoriale (significato semantico) con la corrispondenza di parole chiave
(termini esatti come ID e simboli di codice). Funziona subito una volta che hai
una chiave API per qualsiasi provider supportato.
ibrida** -- combinando similarità vettoriale (significato semantico) con
corrispondenza di parole chiave (termini esatti come ID e simboli di codice).
Funziona subito, non appena disponi di una chiave API per qualsiasi provider supportato.
<Info>
OpenClaw rileva automaticamente il tuo provider di embedding dalle chiavi API disponibili. Se
hai configurato una chiave OpenAI, Gemini, Voyage o Mistral, la ricerca nella memoria è
abilitata automaticamente.
OpenClaw rileva automaticamente il tuo provider di embedding dalle chiavi API
disponibili. Se hai configurato una chiave OpenAI, Gemini, Voyage o Mistral, la
ricerca nella memoria viene abilitata automaticamente.
</Info>
Per i dettagli su come funziona la ricerca, le opzioni di ottimizzazione e la configurazione del provider, vedi
[Ricerca nella memoria](/it/concepts/memory-search).
Per i dettagli su come funziona la ricerca, le opzioni di regolazione e la
configurazione del provider, vedi
[Memory Search](/it/concepts/memory-search).
## Backend di memoria
<CardGroup cols={3}>
<Card title="Integrato (predefinito)" icon="database" href="/it/concepts/memory-builtin">
Basato su SQLite. Funziona subito con ricerca per parole chiave, similarità vettoriale e
ricerca ibrida. Nessuna dipendenza aggiuntiva.
Basato su SQLite. Funziona subito con ricerca per parole chiave, similarità
vettoriale e ricerca ibrida. Nessuna dipendenza aggiuntiva.
</Card>
<Card title="QMD" icon="search" href="/it/concepts/memory-qmd">
Sidecar local-first con reranking, espansione delle query e la possibilità di indicizzare
directory esterne al workspace.
Sidecar local-first con reranking, espansione delle query e la possibilità di
indicizzare directory esterne allo spazio di lavoro.
</Card>
<Card title="Honcho" icon="brain" href="/it/concepts/memory-honcho">
Memoria cross-session nativa per l'AI con modellazione dell'utente, ricerca semantica e
consapevolezza multi-agente. Installazione del plugin.
Memoria cross-session AI-native con modellazione dell'utente, ricerca semantica
e consapevolezza multi-agente. Installazione tramite plugin.
</Card>
</CardGroup>
## Livello wiki della conoscenza
<CardGroup cols={1}>
<Card title="Memory Wiki" icon="book" href="/it/plugins/memory-wiki">
Compila la memoria duratura in un archivio wiki ricco di provenienza con
affermazioni, dashboard, modalità bridge e flussi di lavoro compatibili con Obsidian.
</Card>
</CardGroup>
## Flush automatico della memoria
Prima che la [compattazione](/it/concepts/compaction) riassuma la tua conversazione, OpenClaw
Prima che la [compaction](/it/concepts/compaction) riepiloghi la tua conversazione, OpenClaw
esegue un turno silenzioso che ricorda all'agente di salvare il contesto importante nei file
di memoria. È attivo per impostazione predefinita -- non devi configurare nulla.
di memoria. È attivo per impostazione predefinita: non devi configurare nulla.
<Tip>
Il flush della memoria evita la perdita di contesto durante la compattazione. Se il tuo agente ha
fatti importanti nella conversazione che non sono ancora stati scritti in un file, verranno
salvati automaticamente prima che avvenga il riepilogo.
Il flush della memoria previene la perdita di contesto durante la compaction. Se
nella conversazione sono presenti fatti importanti che il tuo agente non ha
ancora scritto in un file, verranno salvati automaticamente prima che venga
generato il riepilogo.
</Tip>
## Dreaming (sperimentale)
Il dreaming è un passaggio facoltativo di consolidamento in background per la memoria. Raccoglie
segnali a breve termine, assegna un punteggio ai candidati e promuove solo gli elementi qualificati nella
memoria a lungo termine (`MEMORY.md`).
Il dreaming è un passaggio opzionale di consolidamento della memoria in background. Raccoglie
segnali a breve termine, valuta i candidati e promuove nella memoria a lungo
termine (`MEMORY.md`) solo gli elementi qualificati.
È progettato per mantenere alto il rapporto segnale/rumore nella memoria a lungo termine:
È progettato per mantenere alta la qualità della memoria a lungo termine:
- **Attivazione facoltativa**: disabilitato per impostazione predefinita.
- **Pianificato**: quando è abilitato, `memory-core` gestisce automaticamente un job cron ricorrente
per una scansione completa di dreaming.
- **Con soglia**: le promozioni devono superare le soglie di punteggio, frequenza di richiamo e
diversità delle query.
- **Rivedibile**: i riepiloghi delle fasi e le voci del diario vengono scritti in `DREAMS.md`
per la revisione umana.
- **Attivazione esplicita**: disabilitato per impostazione predefinita.
- **Pianificato**: quando è abilitato, `memory-core` gestisce automaticamente un
job cron ricorrente per una sessione completa di dreaming.
- **Con soglia**: le promozioni devono superare soglie di punteggio, frequenza
di richiamo e diversità delle query.
- **Verificabile**: i riepiloghi delle fasi e le voci del diario vengono scritti
in `DREAMS.md` per la revisione umana.
Per il comportamento delle fasi, i segnali di punteggio e i dettagli del Dream Diary, vedi
[Dreaming (sperimentale)](/concepts/dreaming).
Per il comportamento delle fasi, i segnali di punteggio e i dettagli del Diario
dei sogni, vedi [Dreaming (experimental)](/it/concepts/dreaming).
## CLI
```bash
openclaw memory status # Controlla lo stato dell'indice e del provider
openclaw memory status # Controlla lo stato dell'indice e il provider
openclaw memory search "query" # Cerca dalla riga di comando
openclaw memory index --force # Ricostruisce l'indice
```
## Ulteriori letture
## Approfondimenti
- [Builtin Memory Engine](/it/concepts/memory-builtin) -- backend SQLite predefinito
- [QMD Memory Engine](/it/concepts/memory-qmd) -- sidecar local-first avanzato
- [Honcho Memory](/it/concepts/memory-honcho) -- memoria cross-session nativa per l'AI
- [Honcho Memory](/it/concepts/memory-honcho) -- memoria cross-session AI-native
- [Memory Wiki](/it/plugins/memory-wiki) -- archivio di conoscenza compilato e strumenti nativi wiki
- [Memory Search](/it/concepts/memory-search) -- pipeline di ricerca, provider e
ottimizzazione
- [Dreaming (experimental)](/concepts/dreaming) -- promozione in background
regolazione
- [Dreaming (experimental)](/it/concepts/dreaming) -- promozione in background
dal richiamo a breve termine alla memoria a lungo termine
- [Riferimento alla configurazione della memoria](/it/reference/memory-config) -- tutte le opzioni di configurazione
- [Compattazione](/it/concepts/compaction) -- come la compattazione interagisce con la memoria
- [Memory configuration reference](/it/reference/memory-config) -- tutte le opzioni di configurazione
- [Compaction](/it/concepts/compaction) -- come la compaction interagisce con la memoria

View File

@ -1,38 +1,38 @@
---
read_when:
- Ti serve un riferimento per la configurazione dei modelli provider per provider
- Vuoi configurazioni di esempio o comandi di onboarding CLI per i provider di modelli
- Hai bisogno di un riferimento per la configurazione dei modelli provider per provider
- Vuoi configurazioni di esempio o comandi CLI di onboarding per i provider di modelli
summary: Panoramica dei provider di modelli con configurazioni di esempio + flussi CLI
title: Provider di modelli
x-i18n:
generated_at: "2026-04-08T02:15:56Z"
generated_at: "2026-04-08T06:02:39Z"
model: gpt-5.4
provider: openai
source_hash: 26b36a2bc19a28a7ef39aa8e81a0050fea1d452ac4969122e5cdf8755e690258
source_hash: 558ac9e34b67fcc3dd6791a01bebc17e1c34152fa6c5611593d681e8cfa532d9
source_path: concepts/model-providers.md
workflow: 15
---
# Provider di modelli
Questa pagina copre i **provider di LLM/modelli** (non i canali chat come WhatsApp/Telegram).
Per le regole di selezione dei modelli, vedi [/concepts/models](/it/concepts/models).
Questa pagina tratta i **provider LLM/modello** (non i canali di chat come WhatsApp/Telegram).
Per le regole di selezione del modello, vedi [/concepts/models](/it/concepts/models).
## Regole rapide
- I riferimenti ai modelli usano `provider/model` (esempio: `opencode/claude-opus-4-6`).
- Se imposti `agents.defaults.models`, diventa l'allowlist.
- Se imposti `agents.defaults.models`, diventa la allowlist.
- Helper CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
- Le regole di runtime per il fallback, i probe di cooldown e la persistenza delle override di sessione sono
documentate in [/concepts/model-failover](/it/concepts/model-failover).
- Le regole di runtime per il fallback, i probe di cooldown e la persistenza
della sovrascrittura di sessione sono documentate in [/concepts/model-failover](/it/concepts/model-failover).
- `models.providers.*.models[].contextWindow` sono metadati nativi del modello;
`models.providers.*.models[].contextTokens` è il limite effettivo di runtime.
- I plugin provider possono iniettare cataloghi di modelli tramite `registerProvider({ catalog })`;
OpenClaw unisce quell'output in `models.providers` prima di scrivere
`models.json`.
- I manifest dei provider possono dichiarare `providerAuthEnvVars` così le sonde generiche di autenticazione
basate su variabili d'ambiente non devono caricare il runtime del plugin. La mappa rimanente
delle variabili d'ambiente del core ora serve solo per provider core/non-plugin e per alcuni casi
- I manifest dei provider possono dichiarare `providerAuthEnvVars` in modo che i probe generici
di autenticazione basati su env non debbano caricare il runtime del plugin. La mappa restante
delle variabili env del core ora serve solo per provider non-plugin/core e per alcuni casi
di precedenza generica, come l'onboarding Anthropic con priorità alla chiave API.
- I plugin provider possono anche gestire il comportamento runtime del provider tramite
`normalizeModelId`, `normalizeTransport`, `normalizeConfig`,
@ -52,218 +52,217 @@ Per le regole di selezione dei modelli, vedi [/concepts/models](/it/concepts/mod
`resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`,
`prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, e
`onModelSelected`.
- Nota: `capabilities` del runtime del provider sono metadati condivisi del runner (famiglia
del provider, particolarità di trascrizione/tooling, suggerimenti di transport/cache). Non sono la
stessa cosa del [modello di capability pubblico](/it/plugins/architecture#public-capability-model)
che descrive ciò che registra un plugin (inferenza testuale, voce, ecc.).
- Nota: il runtime `capabilities` del provider è metadato condiviso del runner (famiglia
del provider, particolarità di transcript/tooling, suggerimenti su transport/cache). Non è la
stessa cosa del [modello pubblico delle capability](/it/plugins/architecture#public-capability-model)
che descrive ciò che un plugin registra (inferenza testuale, voce, ecc.).
## Comportamento del provider gestito dal plugin
I plugin provider ora possono gestire la maggior parte della logica specifica del provider, mentre OpenClaw mantiene
il ciclo di inferenza generico.
I plugin provider possono ora gestire la maggior parte della logica specifica del provider, mentre OpenClaw mantiene
il loop di inferenza generico.
Suddivisione tipica:
- `auth[].run` / `auth[].runNonInteractive`: il provider gestisce i flussi di onboarding/login
per `openclaw onboard`, `openclaw models auth` e la configurazione headless
- `wizard.setup` / `wizard.modelPicker`: il provider gestisce etichette delle scelte di autenticazione,
alias legacy, suggerimenti per l'allowlist dell'onboarding e voci di configurazione nei picker di onboarding/modello
- `catalog`: il provider appare in `models.providers`
- `normalizeModelId`: il provider normalizza gli id dei modelli legacy/preview prima della
ricerca o canonicalizzazione
- `wizard.setup` / `wizard.modelPicker`: il provider gestisce etichette di scelta dell'autenticazione,
alias legacy, suggerimenti di allowlist per l'onboarding e voci di configurazione nei selettori di onboarding/modello
- `catalog`: il provider compare in `models.providers`
- `normalizeModelId`: il provider normalizza gli id dei modelli legacy/preview prima
della ricerca o della canonizzazione
- `normalizeTransport`: il provider normalizza `api` / `baseUrl` della famiglia di transport
prima dell'assemblaggio generico del modello; OpenClaw controlla prima il provider corrispondente,
poi gli altri plugin provider con capacità di hook finché uno non modifica effettivamente il
poi gli altri plugin provider compatibili con hook finché uno non modifica effettivamente il
transport
- `normalizeConfig`: il provider normalizza la configurazione `models.providers.<id>` prima che il
runtime la usi; OpenClaw controlla prima il provider corrispondente, poi gli altri
plugin provider con capacità di hook finché uno non modifica effettivamente la configurazione. Se nessun
- `normalizeConfig`: il provider normalizza la configurazione `models.providers.<id>` prima
che il runtime la usi; OpenClaw controlla prima il provider corrispondente, poi gli altri
plugin provider compatibili con hook finché uno non modifica effettivamente la configurazione. Se nessun
hook provider riscrive la configurazione, gli helper Google-family inclusi continuano comunque
a normalizzare le voci provider Google supportate.
- `applyNativeStreamingUsageCompat`: il provider applica riscritture di compatibilità dell'uso dello streaming nativo guidate dall'endpoint per i provider di configurazione
- `resolveConfigApiKey`: il provider risolve l'autenticazione tramite marker d'ambiente per i provider di configurazione
- `applyNativeStreamingUsageCompat`: il provider applica riscritture di compatibilità per l'uso dello streaming nativo guidate dall'endpoint per i provider di configurazione
- `resolveConfigApiKey`: il provider risolve l'autenticazione tramite marker env per i provider di configurazione
senza forzare il caricamento completo dell'autenticazione runtime. `amazon-bedrock` ha anche un
resolver integrato per marker d'ambiente AWS qui, anche se l'autenticazione runtime di Bedrock usa
risolutore integrato di marker env AWS qui, anche se l'autenticazione runtime di Bedrock usa
la catena predefinita dell'SDK AWS.
- `resolveSyntheticAuth`: il provider può esporre la disponibilità di autenticazione locale/self-hosted o altra
autenticazione basata su configurazione senza persistere segreti in chiaro
- `shouldDeferSyntheticProfileAuth`: il provider può contrassegnare i placeholder di profili sintetici memorizzati
come di precedenza inferiore rispetto all'autenticazione basata su env/config
- `resolveDynamicModel`: il provider accetta id modello non ancora presenti nel
catalogo statico locale
- `prepareDynamicModel`: il provider necessita di un refresh dei metadati prima di ritentare
- `resolveSyntheticAuth`: il provider può esporre la disponibilità di autenticazione locale/self-hosted o di altro tipo
basata sulla configurazione senza persistere segreti in chiaro
- `shouldDeferSyntheticProfileAuth`: il provider può contrassegnare i placeholder di profilo sintetico memorizzati
come a precedenza più bassa rispetto all'autenticazione basata su env/config
- `resolveDynamicModel`: il provider accetta id di modelli non ancora presenti nel catalogo statico locale
- `prepareDynamicModel`: il provider richiede un aggiornamento dei metadati prima di ritentare
la risoluzione dinamica
- `normalizeResolvedModel`: il provider necessita di riscritture del transport o del base URL
- `normalizeResolvedModel`: il provider richiede riscritture di transport o URL base
- `contributeResolvedModelCompat`: il provider contribuisce flag di compatibilità per i propri
modelli vendor anche quando arrivano tramite un altro transport compatibile
- `capabilities`: il provider pubblica particolarità di trascrizione/tooling/famiglia provider
- `normalizeToolSchemas`: il provider ripulisce gli schemi degli strumenti prima che il
runner incorporato li veda
- `capabilities`: il provider pubblica particolarità di transcript/tooling/famiglia provider
- `normalizeToolSchemas`: il provider ripulisce gli schemi degli strumenti prima che il runner
incorporato li veda
- `inspectToolSchemas`: il provider espone avvisi di schema specifici del transport
dopo la normalizzazione
- `resolveReasoningOutputMode`: il provider sceglie contratti di output del ragionamento nativi o con tag
- `prepareExtraParams`: il provider imposta valori predefiniti o normalizza i parametri di richiesta per modello
- `createStreamFn`: il provider sostituisce il normale percorso di streaming con un
transport completamente personalizzato
- `wrapStreamFn`: il provider applica wrapper di compatibilità per header/body/modello della richiesta
- `resolveTransportTurnState`: il provider fornisce header o metadati di transport nativi
- `resolveReasoningOutputMode`: il provider sceglie contratti di output di reasoning
nativi o con tag
- `prepareExtraParams`: il provider imposta valori predefiniti o normalizza parametri di richiesta per modello
- `createStreamFn`: il provider sostituisce il normale percorso di stream con un transport
completamente personalizzato
- `wrapStreamFn`: il provider applica wrapper di compatibilità a header/body/modello della richiesta
- `resolveTransportTurnState`: il provider fornisce header o metadati nativi del transport
per turno
- `resolveWebSocketSessionPolicy`: il provider fornisce header nativi della sessione WebSocket
- `resolveWebSocketSessionPolicy`: il provider fornisce header di sessione WebSocket nativi
o una policy di cool-down della sessione
- `createEmbeddingProvider`: il provider gestisce il comportamento degli embedding di memoria quando
appartiene al plugin provider invece che allo switchboard embedding del core
- `formatApiKey`: il provider formatta i profili di autenticazione memorizzati nella stringa `apiKey`
di runtime attesa dal transport
- `refreshOAuth`: il provider gestisce il refresh OAuth quando i refresher condivisi `pi-ai`
non sono sufficienti
- `buildAuthDoctorHint`: il provider aggiunge indicazioni di riparazione quando il refresh OAuth
deve appartenere al plugin provider invece che allo switchboard embedding del core
- `formatApiKey`: il provider formatta i profili di autenticazione memorizzati nella stringa runtime
`apiKey` attesa dal transport
- `refreshOAuth`: il provider gestisce l'aggiornamento OAuth quando i refresher condivisi
`pi-ai` non sono sufficienti
- `buildAuthDoctorHint`: il provider aggiunge indicazioni di riparazione quando l'aggiornamento OAuth
fallisce
- `matchesContextOverflowError`: il provider riconosce errori di overflow della finestra di contesto
specifici del provider che le euristiche generiche non rileverebbero
- `classifyFailoverReason`: il provider mappa errori grezzi del transport/API specifici del provider
in motivi di failover come rate limit o overload
- `isCacheTtlEligible`: il provider decide quali id modello upstream supportano il TTL della cache del prompt
- `buildMissingAuthMessage`: il provider sostituisce l'errore generico dell'auth store
specifici del provider che le euristiche generiche non intercetterebbero
- `classifyFailoverReason`: il provider mappa errori raw di transport/API specifici del provider
in motivi di failover come limite di frequenza o sovraccarico
- `isCacheTtlEligible`: il provider decide quali id di modelli upstream supportano il TTL della cache dei prompt
- `buildMissingAuthMessage`: il provider sostituisce l'errore generico dell'auth-store
con un suggerimento di recupero specifico del provider
- `suppressBuiltInModel`: il provider nasconde righe upstream obsolete e può restituire un
errore gestito dal vendor per i fallimenti di risoluzione diretta
errore gestito dal vendor per errori di risoluzione diretta
- `augmentModelCatalog`: il provider aggiunge righe di catalogo sintetiche/finali dopo
discovery e unione della configurazione
- `isBinaryThinking`: il provider gestisce la UX di thinking binario on/off
discovery e merge della configurazione
- `isBinaryThinking`: il provider gestisce l'esperienza utente thinking binaria on/off
- `supportsXHighThinking`: il provider abilita `xhigh` per i modelli selezionati
- `resolveDefaultThinkingLevel`: il provider gestisce la policy `/think` predefinita per una
- `resolveDefaultThinkingLevel`: il provider gestisce la policy predefinita di `/think` per una
famiglia di modelli
- `applyConfigDefaults`: il provider applica valori predefiniti globali specifici del provider
durante la materializzazione della configurazione in base a modalità di autenticazione, env o famiglia di modelli
- `isModernModelRef`: il provider gestisce il matching dei modelli preferiti per live/smoke
- `prepareRuntimeAuth`: il provider trasforma una credenziale configurata in un
token runtime di breve durata
- `resolveUsageAuth`: il provider risolve le credenziali di uso/quota per `/usage`
e superfici correlate di stato/reporting
- `fetchUsageSnapshot`: il provider gestisce il fetch/parsing dell'endpoint di uso mentre
il core mantiene comunque la shell di riepilogo e la formattazione
- `applyConfigDefaults`: il provider applica valori globali predefiniti specifici del provider
durante la materializzazione della configurazione in base alla modalità auth, all'env o alla famiglia di modelli
- `isModernModelRef`: il provider gestisce il matching del modello preferito per live/smoke
- `prepareRuntimeAuth`: il provider trasforma una credenziale configurata in un token runtime
di breve durata
- `resolveUsageAuth`: il provider risolve le credenziali di utilizzo/quota per `/usage`
e le relative superfici di stato/reporting
- `fetchUsageSnapshot`: il provider gestisce il fetch/parsing dell'endpoint di utilizzo mentre
il core continua a gestire shell di riepilogo e formattazione
- `onModelSelected`: il provider esegue effetti collaterali post-selezione come
telemetria o bookkeeping della sessione gestito dal provider
telemetria o bookkeeping di sessione gestito dal provider
Esempi bundled attuali:
Esempi inclusi attuali:
- `anthropic`: fallback forward-compat per Claude 4.6, suggerimenti di riparazione auth, fetch dell'endpoint
di uso, metadati cache-TTL/famiglia provider e valori predefiniti globali
della configurazione consapevoli dell'autenticazione
- `amazon-bedrock`: riconoscimento dell'overflow del contesto e classificazione dei
motivi di failover per errori specifici di Bedrock come throttle/not-ready, più
la famiglia di replay condivisa `anthropic-by-model` per le sole policy di replay Claude
sul traffico Anthropic
- `anthropic-vertex`: guardie di replay-policy solo per Claude sul traffico
di utilizzo, metadati cache-TTL/famiglia provider e valori predefiniti globali di configurazione
consapevoli dell'autenticazione
- `amazon-bedrock`: rilevamento dell'overflow di contesto e classificazione dei
motivi di failover gestiti dal provider per errori throttle/not-ready specifici di Bedrock, più
la famiglia di replay condivisa `anthropic-by-model` per protezioni di replay-policy
solo Claude sul traffico Anthropic
- `anthropic-vertex`: protezioni di replay-policy solo Claude sul traffico
Anthropic-message
- `openrouter`: id modello pass-through, wrapper di richiesta, suggerimenti di capability
del provider, sanificazione della Gemini thought-signature sul traffico Gemini in proxy,
iniezione del reasoning proxy tramite la famiglia di stream `openrouter-thinking`,
inoltro dei metadati di routing e policy cache-TTL
- `github-copilot`: onboarding/device login, fallback forward-compat del modello,
suggerimenti di trascrizione Claude-thinking, scambio di token runtime e fetch dell'endpoint
di uso
- `openai`: fallback forward-compat per GPT-5.4, normalizzazione diretta del transport OpenAI,
suggerimenti per autenticazione mancante consapevoli di Codex, soppressione di Spark, righe di catalogo
sintetiche OpenAI/Codex, policy di thinking/modello live, normalizzazione degli alias dei token
di uso (`input` / `output` e famiglie `prompt` / `completion`), la famiglia di stream condivisa
- `openrouter`: id modello pass-through, wrapper di richiesta, suggerimenti di capability del provider,
sanificazione della thought-signature Gemini su traffico Gemini via proxy, iniezione del
reasoning via proxy tramite la famiglia stream `openrouter-thinking`, inoltro dei metadati
di routing e policy cache-TTL
- `github-copilot`: onboarding/login del dispositivo, fallback modello forward-compat,
suggerimenti transcript Claude-thinking, scambio token runtime e fetch dell'endpoint
di utilizzo
- `openai`: fallback forward-compat GPT-5.4, normalizzazione diretta del transport OpenAI,
suggerimenti missing-auth consapevoli di Codex, soppressione di Spark, righe di catalogo sintetiche
OpenAI/Codex, policy thinking/live-model, normalizzazione degli alias dei token di utilizzo
(`input` / `output` e famiglie `prompt` / `completion`), la famiglia stream condivisa
`openai-responses-defaults` per wrapper nativi OpenAI/Codex,
metadati della famiglia provider, registrazione bundled del provider di generazione immagini
per `gpt-image-1` e registrazione bundled del provider di generazione video
metadati di famiglia provider, registrazione inclusa del provider di generazione immagini
per `gpt-image-1` e registrazione inclusa del provider di generazione video
per `sora-2`
- `google` e `google-gemini-cli`: fallback forward-compat per Gemini 3.1,
validazione nativa del replay Gemini, sanificazione del replay bootstrap, modalità
di output del ragionamento con tag, matching dei modelli moderni, registrazione bundled del provider
di generazione immagini per i modelli Gemini image-preview e registrazione bundled del provider
di generazione video per i modelli Veo; Gemini CLI OAuth inoltre
gestisce la formattazione del token del profilo auth, il parsing del token di uso e il fetch
dell'endpoint quota per le superfici di uso
- `moonshot`: transport condiviso, normalizzazione del payload di thinking gestita dal plugin
- `kilocode`: transport condiviso, header di richiesta gestiti dal plugin, payload di reasoning
normalizzato, sanificazione della thought-signature per proxy-Gemini e policy
cache-TTL
- `zai`: fallback forward-compat per GLM-5, valori predefiniti `tool_stream`, policy cache-TTL,
policy binary-thinking/live-model e autenticazione di uso + fetch quota;
gli id sconosciuti `glm-5*` sono sintetizzati dal template bundled `glm-4.7`
- `xai`: normalizzazione nativa del transport Responses, riscritture dell'alias `/fast` per
le varianti veloci Grok, valore predefinito `tool_stream`, pulizia di schema degli strumenti /
payload di reasoning specifica xAI e registrazione bundled del provider di generazione video
- `google` e `google-gemini-cli`: fallback forward-compat Gemini 3.1,
validazione del replay Gemini nativo, sanificazione del replay bootstrap, modalità
di output reasoning con tag, matching del modello moderno, registrazione inclusa del provider
di generazione immagini per modelli Gemini image-preview e registrazione inclusa del
provider di generazione video per modelli Veo; Gemini CLI OAuth inoltre
gestisce la formattazione del token del profilo auth, il parsing del token di utilizzo e il fetch
dell'endpoint quota per le superfici di utilizzo
- `moonshot`: transport condiviso, normalizzazione del payload thinking gestita dal plugin
- `kilocode`: transport condiviso, header di richiesta gestiti dal plugin, normalizzazione del payload di reasoning,
sanificazione della thought-signature Gemini via proxy e policy cache-TTL
- `zai`: fallback forward-compat GLM-5, valori predefiniti `tool_stream`, policy cache-TTL,
policy binary-thinking/live-model e autenticazione utilizzo + fetch quota;
gli id sconosciuti `glm-5*` vengono sintetizzati dal template incluso `glm-4.7`
- `xai`: normalizzazione del transport Responses nativo, riscritture dell'alias `/fast` per
varianti Grok fast, `tool_stream` predefinito, pulizia degli schemi strumento /
payload di reasoning specifica xAI e registrazione inclusa del provider di generazione video
per `grok-imagine-video`
- `mistral`: metadati delle capability gestiti dal plugin
- `opencode` e `opencode-go`: metadati delle capability gestiti dal plugin più
sanificazione della thought-signature per proxy-Gemini
- `alibaba`: catalogo di generazione video gestito dal plugin per riferimenti diretti ai modelli Wan
- `mistral`: metadati capability gestiti dal plugin
- `opencode` e `opencode-go`: metadati capability gestiti dal plugin più
sanificazione della thought-signature Gemini via proxy
- `alibaba`: catalogo di generazione video gestito dal plugin per riferimenti diretti a modelli Wan
come `alibaba/wan2.6-t2v`
- `byteplus`: cataloghi gestiti dal plugin più registrazione bundled del provider di generazione video
per i modelli Seedance text-to-video/image-to-video
- `fal`: registrazione bundled del provider di generazione video per provider di terze parti ospitati
registrazione del provider di generazione immagini per i modelli immagine FLUX più registrazione bundled
- `byteplus`: cataloghi gestiti dal plugin più registrazione inclusa del provider di generazione video
per modelli Seedance text-to-video/image-to-video
- `fal`: registrazione inclusa del provider di generazione video per provider ospitati di terze parti
registrazione del provider di generazione immagini per modelli immagine FLUX più registrazione inclusa
del provider di generazione video per modelli video ospitati di terze parti
- `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`,
`stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` e `volcengine`:
solo cataloghi gestiti dal plugin
- `qwen`: cataloghi gestiti dal plugin per i modelli testuali più registrazioni condivise
del provider media-understanding e video-generation per le sue superfici multimodali;
la generazione video Qwen usa gli endpoint video Standard DashScope con
modelli Wan bundled come `wan2.6-t2v` e `wan2.7-r2v`
- `runway`: registrazione del provider di generazione video gestita dal plugin
per modelli nativi Runway basati su task come `gen4.5`
- `minimax`: cataloghi gestiti dal plugin, registrazione bundled del provider di generazione video
per i modelli video Hailuo, registrazione bundled del provider di generazione immagini
- `qwen`: cataloghi gestiti dal plugin per modelli testuali più registrazioni condivise
dei provider media-understanding e video-generation per le sue superfici multimodali;
la generazione video Qwen usa gli endpoint video Standard DashScope con modelli Wan inclusi
come `wan2.6-t2v` e `wan2.7-r2v`
- `runway`: registrazione del provider di generazione video gestita dal plugin per modelli nativi
basati su task Runway come `gen4.5`
- `minimax`: cataloghi gestiti dal plugin, registrazione inclusa del provider di generazione video
per modelli video Hailuo, registrazione inclusa del provider di generazione immagini
per `image-01`, selezione ibrida della replay-policy Anthropic/OpenAI
e logica di autenticazione/snapshot dell'uso
- `together`: cataloghi gestiti dal plugin più registrazione bundled del provider di generazione video
per i modelli video Wan
- `xiaomi`: cataloghi gestiti dal plugin più logica di autenticazione/snapshot dell'uso
e logica auth/snapshot di utilizzo
- `together`: cataloghi gestiti dal plugin più registrazione inclusa del provider di generazione video
per modelli video Wan
- `xiaomi`: cataloghi gestiti dal plugin più logica auth/snapshot di utilizzo
Il plugin bundled `openai` ora gestisce entrambi gli id provider: `openai` e
Il plugin incluso `openai` ora gestisce entrambi gli id provider: `openai` e
`openai-codex`.
Questo copre i provider che rientrano ancora nei normali transport di OpenClaw. Un provider
che richiede un esecutore di richieste totalmente personalizzato è una superficie di estensione
Questo copre i provider che rientrano ancora nei transport normali di OpenClaw. Un provider
che necessita di un esecutore di richieste totalmente personalizzato è una superficie di estensione
separata e più profonda.
## Rotazione delle chiavi API
- Supporta la rotazione generica dei provider per provider selezionati.
- Supporta la rotazione generica del provider per provider selezionati.
- Configura più chiavi tramite:
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (singola override live, massima priorità)
- `<PROVIDER>_API_KEYS` (elenco separato da virgole o punto e virgola)
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (singolo override live, priorità più alta)
- `<PROVIDER>_API_KEYS` (lista separata da virgole o punti e virgola)
- `<PROVIDER>_API_KEY` (chiave primaria)
- `<PROVIDER>_API_KEY_*` (elenco numerato, ad esempio `<PROVIDER>_API_KEY_1`)
- `<PROVIDER>_API_KEY_*` (lista numerata, per esempio `<PROVIDER>_API_KEY_1`)
- Per i provider Google, `GOOGLE_API_KEY` è incluso anche come fallback.
- L'ordine di selezione delle chiavi preserva la priorità e rimuove i duplicati.
- L'ordine di selezione delle chiavi preserva la priorità e deduplica i valori.
- Le richieste vengono ritentate con la chiave successiva solo in caso di risposte con rate limit (per
esempio `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many
concurrent requests`, `ThrottlingException`, `concurrency limit reached`,
`workers_ai ... quota limit exceeded`, o messaggi periodici di limite d'uso).
- I fallimenti non dovuti a rate limit falliscono immediatamente; non viene tentata alcuna rotazione delle chiavi.
`workers_ai ... quota limit exceeded` o messaggi periodici di limite d'uso).
- Gli errori non dovuti a rate limit falliscono immediatamente; non viene tentata alcuna rotazione delle chiavi.
- Quando tutte le chiavi candidate falliscono, viene restituito l'errore finale dell'ultimo tentativo.
## Provider integrati (catalogo pi-ai)
OpenClaw include il catalogo piai. Questi provider non richiedono alcuna
configurazione `models.providers`; basta impostare l'autenticazione + scegliere un modello.
OpenClaw include il catalogo pi-ai. Questi provider non richiedono alcuna configurazione
`models.providers`; basta impostare l'autenticazione e scegliere un modello.
### OpenAI
- Provider: `openai`
- Auth: `OPENAI_API_KEY`
- Rotazione opzionale: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, più `OPENCLAW_LIVE_OPENAI_KEY` (singola override)
- Rotazione opzionale: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, più `OPENCLAW_LIVE_OPENAI_KEY` (singolo override)
- Modelli di esempio: `openai/gpt-5.4`, `openai/gpt-5.4-pro`
- CLI: `openclaw onboard --auth-choice openai-api-key`
- Il transport predefinito è `auto` (prima WebSocket, fallback SSE)
- Override per modello tramite `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"` o `"auto"`)
- Il warm-up WebSocket di OpenAI Responses è abilitato per impostazione predefinita tramite `params.openaiWsWarmup` (`true`/`false`)
- L'elaborazione prioritaria OpenAI può essere abilitata tramite `agents.defaults.models["openai/<model>"].params.serviceTier`
- `/fast` e `params.fastMode` mappano le richieste Responses dirette `openai/*` a `service_tier=priority` su `api.openai.com`
- `/fast` e `params.fastMode` mappano le richieste dirette `openai/*` Responses a `service_tier=priority` su `api.openai.com`
- Usa `params.serviceTier` quando vuoi un livello esplicito invece del toggle condiviso `/fast`
- Gli header di attribuzione nascosti di OpenClaw (`originator`, `version`,
`User-Agent`) si applicano solo al traffico OpenAI nativo verso `api.openai.com`, non
a proxy generici compatibili con OpenAI
- I percorsi OpenAI nativi mantengono anche `store` di Responses, suggerimenti di cache del prompt e
- Gli header di attribuzione OpenClaw nascosti (`originator`, `version`,
`User-Agent`) si applicano solo al traffico nativo OpenAI verso `api.openai.com`, non
ai proxy generici compatibili con OpenAI
- I percorsi OpenAI nativi mantengono anche `store` di Responses, suggerimenti per la cache dei prompt e
modellazione del payload di compatibilità reasoning OpenAI; i percorsi proxy no
- `openai/gpt-5.3-codex-spark` è intenzionalmente soppresso in OpenClaw perché l'API OpenAI live lo rifiuta; Spark è trattato solo come Codex
- `openai/gpt-5.3-codex-spark` è intenzionalmente soppresso in OpenClaw perché l'API OpenAI live lo rifiuta; Spark è trattato come solo Codex
```json5
{
@ -275,12 +274,12 @@ configurazione `models.providers`; basta impostare l'autenticazione + scegliere
- Provider: `anthropic`
- Auth: `ANTHROPIC_API_KEY`
- Rotazione opzionale: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, più `OPENCLAW_LIVE_ANTHROPIC_KEY` (singola override)
- Rotazione opzionale: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, più `OPENCLAW_LIVE_ANTHROPIC_KEY` (singolo override)
- Modello di esempio: `anthropic/claude-opus-4-6`
- CLI: `openclaw onboard --auth-choice apiKey`
- Le richieste Anthropic pubbliche dirette supportano il toggle condiviso `/fast` e `params.fastMode`, incluso il traffico autenticato con chiave API e OAuth inviato a `api.anthropic.com`; OpenClaw lo mappa a `service_tier` di Anthropic (`auto` vs `standard_only`)
- Nota Anthropic: lo staff Anthropic ci ha detto che l'uso in stile Claude CLI di OpenClaw è di nuovo consentito, quindi OpenClaw tratta il riuso di Claude CLI e l'uso di `claude -p` come autorizzati per questa integrazione finché Anthropic non pubblica una nuova policy.
- Il setup-token Anthropic resta disponibile come percorso di token OpenClaw supportato, ma OpenClaw ora preferisce il riuso di Claude CLI e `claude -p` quando disponibili.
- Le richieste Anthropic pubbliche dirette supportano il toggle condiviso `/fast` e `params.fastMode`, incluso il traffico autenticato con chiave API e OAuth inviato a `api.anthropic.com`; OpenClaw lo mappa a Anthropic `service_tier` (`auto` vs `standard_only`)
- Nota Anthropic: il personale Anthropic ci ha detto che l'uso in stile Claude CLI di OpenClaw è di nuovo consentito, quindi OpenClaw tratta il riuso di Claude CLI e l'uso di `claude -p` come autorizzati per questa integrazione, a meno che Anthropic non pubblichi una nuova policy.
- Il setup-token Anthropic rimane disponibile come percorso token OpenClaw supportato, ma OpenClaw ora preferisce il riuso di Claude CLI e `claude -p` quando disponibili.
```json5
{
@ -296,13 +295,13 @@ configurazione `models.providers`; basta impostare l'autenticazione + scegliere
- CLI: `openclaw onboard --auth-choice openai-codex` o `openclaw models auth login --provider openai-codex`
- Il transport predefinito è `auto` (prima WebSocket, fallback SSE)
- Override per modello tramite `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"` o `"auto"`)
- `params.serviceTier` viene inoltrato anche nelle richieste native Codex Responses (`chatgpt.com/backend-api`)
- Gli header di attribuzione nascosti di OpenClaw (`originator`, `version`,
- `params.serviceTier` viene inoltrato anche sulle richieste native Codex Responses (`chatgpt.com/backend-api`)
- Gli header di attribuzione OpenClaw nascosti (`originator`, `version`,
`User-Agent`) vengono allegati solo sul traffico Codex nativo verso
`chatgpt.com/backend-api`, non su proxy generici compatibili con OpenAI
`chatgpt.com/backend-api`, non ai proxy generici compatibili con OpenAI
- Condivide lo stesso toggle `/fast` e la stessa configurazione `params.fastMode` di `openai/*` diretto; OpenClaw lo mappa a `service_tier=priority`
- `openai-codex/gpt-5.3-codex-spark` resta disponibile quando il catalogo OAuth Codex lo espone; dipende dai diritti
- `openai-codex/gpt-5.4` mantiene `contextWindow = 1050000` nativo e un `contextTokens = 272000` di runtime predefinito; esegui l'override del limite di runtime con `models.providers.openai-codex.models[].contextTokens`
- `openai-codex/gpt-5.3-codex-spark` rimane disponibile quando il catalogo OAuth Codex lo espone; dipende dai diritti
- `openai-codex/gpt-5.4` mantiene `contextWindow = 1050000` nativo e un `contextTokens = 272000` di runtime predefinito; sovrascrivi il limite runtime con `models.providers.openai-codex.models[].contextTokens`
- Nota sulla policy: OpenAI Codex OAuth è esplicitamente supportato per strumenti/workflow esterni come OpenClaw.
```json5
@ -323,10 +322,10 @@ configurazione `models.providers`; basta impostare l'autenticazione + scegliere
}
```
### Altre opzioni hosted in stile abbonamento
### Altre opzioni ospitate in stile abbonamento
- [Qwen Cloud](/it/providers/qwen): superficie provider Qwen Cloud più mappatura degli endpoint Alibaba DashScope e Coding Plan
- [MiniMax](/it/providers/minimax): accesso MiniMax Coding Plan tramite OAuth o chiave API
- [Qwen Cloud](/it/providers/qwen): superficie provider Qwen Cloud più mapping degli endpoint Alibaba DashScope e Coding Plan
- [MiniMax](/it/providers/minimax): accesso MiniMax Coding Plan OAuth o tramite chiave API
- [GLM Models](/it/providers/glm): endpoint Z.AI Coding Plan o API generali
### OpenCode
@ -347,37 +346,37 @@ configurazione `models.providers`; basta impostare l'autenticazione + scegliere
- Provider: `google`
- Auth: `GEMINI_API_KEY`
- Rotazione opzionale: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `GOOGLE_API_KEY` e `OPENCLAW_LIVE_GEMINI_KEY` (singola override)
- Rotazione opzionale: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `GOOGLE_API_KEY` e `OPENCLAW_LIVE_GEMINI_KEY` (singolo override)
- Modelli di esempio: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview`
- Compatibilità: la configurazione legacy di OpenClaw che usa `google/gemini-3.1-flash-preview` viene normalizzata a `google/gemini-3-flash-preview`
- Compatibilità: la configurazione legacy di OpenClaw che usa `google/gemini-3.1-flash-preview` viene normalizzata in `google/gemini-3-flash-preview`
- CLI: `openclaw onboard --auth-choice gemini-api-key`
- Le esecuzioni Gemini dirette accettano anche `agents.defaults.models["google/<model>"].params.cachedContent`
(o il legacy `cached_content`) per inoltrare un handle nativo del provider
`cachedContents/...`; i cache hit Gemini vengono esposti come OpenClaw `cacheRead`
(o il legacy `cached_content`) per inoltrare un handle
`cachedContents/...` nativo del provider; gli hit della cache Gemini emergono come OpenClaw `cacheRead`
### Google Vertex e Gemini CLI
- Provider: `google-vertex`, `google-gemini-cli`
- Auth: Vertex usa gcloud ADC; Gemini CLI usa il proprio flusso OAuth
- Attenzione: Gemini CLI OAuth in OpenClaw è un'integrazione non ufficiale. Alcuni utenti hanno segnalato restrizioni sull'account Google dopo aver usato client di terze parti. Controlla i termini di Google e usa un account non critico se scegli di procedere.
- Gemini CLI OAuth viene distribuito come parte del plugin bundled `google`.
- Auth: Vertex usa gcloud ADC; Gemini CLI usa il suo flusso OAuth
- Attenzione: Gemini CLI OAuth in OpenClaw è un'integrazione non ufficiale. Alcuni utenti hanno segnalato restrizioni sugli account Google dopo aver usato client di terze parti. Consulta i termini di Google e usa un account non critico se scegli di procedere.
- Gemini CLI OAuth è incluso come parte del plugin `google`.
- Installa prima Gemini CLI:
- `brew install gemini-cli`
- oppure `npm install -g @google/gemini-cli`
- Abilita: `openclaw plugins enable google`
- Login: `openclaw models auth login --provider google-gemini-cli --set-default`
- Modello predefinito: `google-gemini-cli/gemini-3-flash-preview`
- Nota: **non** incolli un client id o un secret in `openclaw.json`. Il flusso di login CLI memorizza
i token nei profili auth sull'host del gateway.
- Se le richieste falliscono dopo il login, imposta `GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` sull'host del gateway.
- Le risposte JSON di Gemini CLI vengono analizzate da `response`; l'uso usa come fallback
- Nota: **non** incolli un client id o secret in `openclaw.json`. Il flusso di login CLI memorizza
i token nei profili di autenticazione sull'host gateway.
- Se le richieste falliscono dopo il login, imposta `GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` sull'host gateway.
- Le risposte JSON di Gemini CLI vengono parse da `response`; l'utilizzo usa come fallback
`stats`, con `stats.cached` normalizzato in OpenClaw `cacheRead`.
### Z.AI (GLM)
- Provider: `zai`
- Auth: `ZAI_API_KEY`
- Modello di esempio: `zai/glm-5`
- Modello di esempio: `zai/glm-5.1`
- CLI: `openclaw onboard --auth-choice zai-api-key`
- Alias: `z.ai/*` e `z-ai/*` vengono normalizzati in `zai/*`
- `zai-api-key` rileva automaticamente l'endpoint Z.AI corrispondente; `zai-coding-global`, `zai-coding-cn`, `zai-global` e `zai-cn` forzano una superficie specifica
@ -395,8 +394,8 @@ configurazione `models.providers`; basta impostare l'autenticazione + scegliere
- Auth: `KILOCODE_API_KEY`
- Modello di esempio: `kilocode/kilo/auto`
- CLI: `openclaw onboard --auth-choice kilocode-api-key`
- Base URL: `https://api.kilo.ai/api/gateway/`
- Il catalogo statico di fallback include `kilocode/kilo/auto`; la discovery live di
- URL base: `https://api.kilo.ai/api/gateway/`
- Il catalogo di fallback statico include `kilocode/kilo/auto`; la discovery live di
`https://api.kilo.ai/api/gateway/models` può espandere ulteriormente il catalogo
runtime.
- Il routing upstream esatto dietro `kilocode/kilo/auto` è gestito da Kilo Gateway,
@ -404,30 +403,30 @@ configurazione `models.providers`; basta impostare l'autenticazione + scegliere
Vedi [/providers/kilocode](/it/providers/kilocode) per i dettagli di configurazione.
### Altri plugin provider bundled
### Altri plugin provider inclusi
- OpenRouter: `openrouter` (`OPENROUTER_API_KEY`)
- Modello di esempio: `openrouter/auto`
- OpenClaw applica gli header di attribuzione dell'app documentati da OpenRouter solo quando
- OpenClaw applica gli header di attribuzione app documentati da OpenRouter solo quando
la richiesta punta effettivamente a `openrouter.ai`
- I marker Anthropic `cache_control` specifici di OpenRouter sono allo stesso modo limitati
a route OpenRouter verificate, non a URL proxy arbitrari
- OpenRouter resta sul percorso in stile proxy compatibile con OpenAI, quindi la modellazione nativa delle richieste
solo-OpenAI (`serviceTier`, `store` di Responses,
suggerimenti di cache del prompt, payload di compatibilità reasoning OpenAI) non viene inoltrata
- I riferimenti OpenRouter basati su Gemini mantengono solo la sanificazione della thought-signature per proxy-Gemini;
la validazione del replay Gemini nativo e le riscritture bootstrap restano disattivate
- I marker `cache_control` specifici di OpenRouter per Anthropic sono analogamente limitati
alle route OpenRouter verificate, non a URL proxy arbitrari
- OpenRouter rimane sul percorso in stile proxy compatibile con OpenAI, quindi la modellazione
nativa delle richieste solo OpenAI (`serviceTier`, `store` di Responses,
suggerimenti per la cache dei prompt, payload di compatibilità reasoning OpenAI) non viene inoltrata
- I riferimenti OpenRouter basati su Gemini mantengono solo la sanificazione della thought-signature
proxy-Gemini; la validazione del replay Gemini nativo e le riscritture bootstrap restano disattivate
- Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`)
- Modello di esempio: `kilocode/kilo/auto`
- I riferimenti Kilo basati su Gemini mantengono lo stesso percorso di sanificazione della thought-signature
per proxy-Gemini; `kilocode/kilo/auto` e altri suggerimenti che non supportano il proxy-reasoning
saltano l'iniezione del proxy reasoning
- I riferimenti Kilo basati su Gemini mantengono lo stesso percorso di sanificazione della
thought-signature proxy-Gemini; `kilocode/kilo/auto` e altri suggerimenti proxy che non supportano reasoning
saltano l'iniezione di reasoning via proxy
- MiniMax: `minimax` (chiave API) e `minimax-portal` (OAuth)
- Auth: `MINIMAX_API_KEY` per `minimax`; `MINIMAX_OAUTH_TOKEN` o `MINIMAX_API_KEY` per `minimax-portal`
- Modello di esempio: `minimax/MiniMax-M2.7` o `minimax-portal/MiniMax-M2.7`
- La configurazione onboarding/chiave API di MiniMax scrive definizioni esplicite del modello M2.7 con
`input: ["text", "image"]`; il catalogo provider bundled mantiene i riferimenti chat
solo testuali finché quella configurazione provider non viene materializzata
- L'onboarding/configurazione con chiave API di MiniMax scrive definizioni esplicite dei modelli M2.7 con
`input: ["text", "image"]`; il catalogo provider incluso mantiene i riferimenti chat
solo testo finché quella configurazione provider non viene materializzata
- Moonshot: `moonshot` (`MOONSHOT_API_KEY`)
- Modello di esempio: `moonshot/kimi-k2.5`
- Kimi Coding: `kimi` (`KIMI_API_KEY` o `KIMICODE_API_KEY`)
@ -453,43 +452,43 @@ Vedi [/providers/kilocode](/it/providers/kilocode) per i dettagli di configurazi
- BytePlus: `byteplus` (`BYTEPLUS_API_KEY`)
- Modello di esempio: `byteplus-plan/ark-code-latest`
- xAI: `xai` (`XAI_API_KEY`)
- Le richieste xAI bundled native usano il percorso xAI Responses
- Le richieste xAI native incluse usano il percorso xAI Responses
- `/fast` o `params.fastMode: true` riscrivono `grok-3`, `grok-3-mini`,
`grok-4` e `grok-4-0709` nelle rispettive varianti `*-fast`
- `tool_stream` è attivo per impostazione predefinita; imposta
`agents.defaults.models["xai/<model>"].params.tool_stream` su `false` per
disattivarlo
disabilitarlo
- Mistral: `mistral` (`MISTRAL_API_KEY`)
- Modello di esempio: `mistral/mistral-large-latest`
- CLI: `openclaw onboard --auth-choice mistral-api-key`
- Groq: `groq` (`GROQ_API_KEY`)
- Cerebras: `cerebras` (`CEREBRAS_API_KEY`)
- I modelli GLM su Cerebras usano gli id `zai-glm-4.7` e `zai-glm-4.6`.
- Base URL compatibile con OpenAI: `https://api.cerebras.ai/v1`.
- URL base compatibile con OpenAI: `https://api.cerebras.ai/v1`.
- GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`)
- Modello di esempio per Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Vedi [Hugging Face (Inference)](/it/providers/huggingface).
- Modello di esempio Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Vedi [Hugging Face (Inference)](/it/providers/huggingface).
## Provider tramite `models.providers` (custom/base URL)
## Provider tramite `models.providers` (URL base/personalizzato)
Usa `models.providers` (o `models.json`) per aggiungere provider **custom** o
Usa `models.providers` (o `models.json`) per aggiungere provider **personalizzati** o
proxy compatibili con OpenAI/Anthropic.
Molti dei plugin provider bundled qui sotto pubblicano già un catalogo predefinito.
Usa voci esplicite `models.providers.<id>` solo quando vuoi sovrascrivere il
base URL, gli header o l'elenco dei modelli predefiniti.
Molti dei plugin provider inclusi qui sotto pubblicano già un catalogo predefinito.
Usa voci esplicite `models.providers.<id>` solo quando vuoi sovrascrivere
l'URL base, gli header o la lista di modelli predefiniti.
### Moonshot AI (Kimi)
Moonshot viene distribuito come plugin provider bundled. Usa il provider integrato per
Moonshot è incluso come plugin provider. Usa il provider integrato per
impostazione predefinita e aggiungi una voce esplicita `models.providers.moonshot` solo quando
devi sovrascrivere il base URL o i metadati del modello:
devi sovrascrivere l'URL base o i metadati del modello:
- Provider: `moonshot`
- Auth: `MOONSHOT_API_KEY`
- Modello di esempio: `moonshot/kimi-k2.5`
- CLI: `openclaw onboard --auth-choice moonshot-api-key` o `openclaw onboard --auth-choice moonshot-api-key-cn`
ID dei modelli Kimi K2:
ID modello Kimi K2:
[//]: # "moonshot-kimi-k2-model-refs:start"
@ -536,7 +535,7 @@ Kimi Coding usa l'endpoint compatibile con Anthropic di Moonshot AI:
}
```
Il legacy `kimi/k2p5` resta accettato come id modello di compatibilità.
Il legacy `kimi/k2p5` continua a essere accettato come id modello di compatibilità.
### Volcano Engine (Doubao)
@ -556,12 +555,12 @@ Volcano Engine (火山引擎) fornisce accesso a Doubao e ad altri modelli in Ci
```
L'onboarding usa per impostazione predefinita la superficie coding, ma il catalogo generale `volcengine/*`
viene registrato allo stesso tempo.
viene registrato contemporaneamente.
Nei picker di onboarding/configurazione modello, la scelta auth Volcengine preferisce sia le righe
Nei selettori di onboarding/configurazione del modello, la scelta auth Volcengine preferisce sia le righe
`volcengine/*` sia quelle `volcengine-plan/*`. Se questi modelli non sono ancora caricati,
OpenClaw usa come fallback il catalogo non filtrato invece di mostrare un picker vuoto
limitato al provider.
OpenClaw ripiega sul catalogo non filtrato invece di mostrare un selettore
vuoto con ambito provider.
Modelli disponibili:
@ -597,12 +596,12 @@ BytePlus ARK fornisce accesso agli stessi modelli di Volcano Engine per gli uten
```
L'onboarding usa per impostazione predefinita la superficie coding, ma il catalogo generale `byteplus/*`
viene registrato allo stesso tempo.
viene registrato contemporaneamente.
Nei picker di onboarding/configurazione modello, la scelta auth BytePlus preferisce sia le righe
Nei selettori di onboarding/configurazione del modello, la scelta auth BytePlus preferisce sia le righe
`byteplus/*` sia quelle `byteplus-plan/*`. Se questi modelli non sono ancora caricati,
OpenClaw usa come fallback il catalogo non filtrato invece di mostrare un picker vuoto
limitato al provider.
OpenClaw ripiega sul catalogo non filtrato invece di mostrare un selettore
vuoto con ambito provider.
Modelli disponibili:
@ -652,27 +651,27 @@ MiniMax è configurato tramite `models.providers` perché usa endpoint personali
- MiniMax OAuth (globale): `--auth-choice minimax-global-oauth`
- MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth`
- MiniMax chiave API (globale): `--auth-choice minimax-global-api`
- MiniMax chiave API (CN): `--auth-choice minimax-cn-api`
- Chiave API MiniMax (globale): `--auth-choice minimax-global-api`
- Chiave API MiniMax (CN): `--auth-choice minimax-cn-api`
- Auth: `MINIMAX_API_KEY` per `minimax`; `MINIMAX_OAUTH_TOKEN` o
`MINIMAX_API_KEY` per `minimax-portal`
Vedi [/providers/minimax](/it/providers/minimax) per dettagli di configurazione, opzioni dei modelli e snippet di configurazione.
Sul percorso di streaming compatibile con Anthropic di MiniMax, OpenClaw disattiva thinking per
Sul percorso di streaming compatibile con Anthropic di MiniMax, OpenClaw disabilita thinking per
impostazione predefinita a meno che tu non lo imposti esplicitamente, e `/fast on` riscrive
`MiniMax-M2.7` in `MiniMax-M2.7-highspeed`.
Suddivisione delle capability gestita dal plugin:
- I valori predefiniti text/chat restano su `minimax/MiniMax-M2.7`
- I valori predefiniti testo/chat restano su `minimax/MiniMax-M2.7`
- La generazione immagini è `minimax/image-01` o `minimax-portal/image-01`
- La comprensione delle immagini è `MiniMax-VL-01` gestita dal plugin su entrambi i percorsi auth MiniMax
- La comprensione immagini è `MiniMax-VL-01` gestito dal plugin su entrambi i percorsi auth MiniMax
- La ricerca web resta sull'id provider `minimax`
### Ollama
Ollama viene distribuito come plugin provider bundled e usa l'API nativa di Ollama:
Ollama è incluso come plugin provider e usa l'API nativa di Ollama:
- Provider: `ollama`
- Auth: Nessuna richiesta (server locale)
@ -692,26 +691,26 @@ ollama pull llama3.3
}
```
Ollama viene rilevato localmente su `http://127.0.0.1:11434` quando abiliti la funzione con
`OLLAMA_API_KEY`, e il plugin provider bundled aggiunge Ollama direttamente a
`openclaw onboard` e al picker dei modelli. Vedi [/providers/ollama](/it/providers/ollama)
Ollama viene rilevato localmente su `http://127.0.0.1:11434` quando scegli di attivarlo con
`OLLAMA_API_KEY`, e il plugin provider incluso aggiunge Ollama direttamente a
`openclaw onboard` e al selettore di modelli. Vedi [/providers/ollama](/it/providers/ollama)
per onboarding, modalità cloud/locale e configurazione personalizzata.
### vLLM
vLLM viene distribuito come plugin provider bundled per server locali/self-hosted compatibili con OpenAI:
vLLM è incluso come plugin provider per server locali/self-hosted compatibili con OpenAI:
- Provider: `vllm`
- Auth: Opzionale (dipende dal tuo server)
- Base URL predefinito: `http://127.0.0.1:8000/v1`
- URL base predefinito: `http://127.0.0.1:8000/v1`
Per abilitare l'auto-discovery locale (qualsiasi valore va bene se il tuo server non impone l'autenticazione):
Per attivare l'auto-discovery locale (qualsiasi valore va bene se il tuo server non impone l'autenticazione):
```bash
export VLLM_API_KEY="vllm-local"
```
Poi imposta un modello (sostituiscilo con uno degli ID restituiti da `/v1/models`):
Poi imposta un modello (sostituisci con uno degli ID restituiti da `/v1/models`):
```json5
{
@ -725,21 +724,21 @@ Vedi [/providers/vllm](/it/providers/vllm) per i dettagli.
### SGLang
SGLang viene distribuito come plugin provider bundled per server self-hosted veloci
SGLang è incluso come plugin provider per server self-hosted veloci
compatibili con OpenAI:
- Provider: `sglang`
- Auth: Opzionale (dipende dal tuo server)
- Base URL predefinito: `http://127.0.0.1:30000/v1`
- URL base predefinito: `http://127.0.0.1:30000/v1`
Per abilitare l'auto-discovery locale (qualsiasi valore va bene se il tuo server non
Per attivare l'auto-discovery locale (qualsiasi valore va bene se il tuo server non
impone l'autenticazione):
```bash
export SGLANG_API_KEY="sglang-local"
```
Poi imposta un modello (sostituiscilo con uno degli ID restituiti da `/v1/models`):
Poi imposta un modello (sostituisci con uno degli ID restituiti da `/v1/models`):
```json5
{
@ -788,21 +787,21 @@ Esempio (compatibile con OpenAI):
Note:
- Per i provider personalizzati, `reasoning`, `input`, `cost`, `contextWindow` e `maxTokens` sono opzionali.
Se omessi, OpenClaw usa come valori predefiniti:
- Per i provider personalizzati, `reasoning`, `input`, `cost`, `contextWindow` e `maxTokens` sono facoltativi.
Se omessi, OpenClaw usa i seguenti valori predefiniti:
- `reasoning: false`
- `input: ["text"]`
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
- `contextWindow: 200000`
- `maxTokens: 8192`
- Consigliato: imposta valori espliciti che corrispondano ai limiti del tuo proxy/modello.
- Per `api: "openai-completions"` su endpoint non nativi (qualsiasi `baseUrl` non vuoto il cui host non sia `api.openai.com`), OpenClaw forza `compat.supportsDeveloperRole: false` per evitare errori 400 del provider per ruoli `developer` non supportati.
- I percorsi in stile proxy compatibili con OpenAI saltano anche la modellazione nativa delle richieste solo-OpenAI:
niente `service_tier`, niente `store` di Responses, niente suggerimenti di cache del prompt, niente
modellazione del payload di compatibilità reasoning OpenAI e nessun header di attribuzione nascosto
di OpenClaw.
- Se `baseUrl` è vuoto/omesso, OpenClaw mantiene il comportamento predefinito di OpenAI (che risolve a `api.openai.com`).
- Per sicurezza, un valore esplicito `compat.supportsDeveloperRole: true` viene comunque sovrascritto sugli endpoint non nativi `openai-completions`.
- Per `api: "openai-completions"` su endpoint non nativi (qualsiasi `baseUrl` non vuoto il cui host non sia `api.openai.com`), OpenClaw forza `compat.supportsDeveloperRole: false` per evitare errori provider 400 dovuti a ruoli `developer` non supportati.
- I percorsi in stile proxy compatibili con OpenAI saltano anche la modellazione delle richieste nativa solo OpenAI:
niente `service_tier`, niente `store` di Responses, niente suggerimenti per la cache dei prompt, niente
modellazione del payload di compatibilità reasoning OpenAI e nessun header di attribuzione OpenClaw
nascosto.
- Se `baseUrl` è vuoto/omesso, OpenClaw mantiene il comportamento OpenAI predefinito (che risolve a `api.openai.com`).
- Per sicurezza, un `compat.supportsDeveloperRole: true` esplicito viene comunque sovrascritto sugli endpoint `openai-completions` non nativi.
## Esempi CLI
@ -816,7 +815,7 @@ Vedi anche: [/gateway/configuration](/it/gateway/configuration) per esempi compl
## Correlati
- [Models](/it/concepts/models) — configurazione dei modelli e alias
- [Model Failover](/it/concepts/model-failover) — catene di fallback e comportamento dei retry
- [Models](/it/concepts/models) — configurazione e alias dei modelli
- [Model Failover](/it/concepts/model-failover) — catene di fallback e comportamento dei tentativi
- [Configuration Reference](/it/gateway/configuration-reference#agent-defaults) — chiavi di configurazione del modello
- [Providers](/it/providers) — guide di configurazione per provider

View File

@ -1,33 +1,32 @@
---
read_when:
- Estendere qa-lab o qa-channel
- Aggiungere scenari QA supportati dal repository
- Creare un'automazione QA più realistica attorno alla dashboard del Gateway
summary: Struttura dell'automazione QA privata per qa-lab, qa-channel, scenari predefiniti e report di protocollo
- Estensione di qa-lab o qa-channel
- Aggiunta di scenari QA supportati dal repository
- Creazione di un'automazione QA più realistica intorno alla dashboard del Gateway
summary: Struttura privata dell'automazione QA per qa-lab, qa-channel, scenari iniziali e report di protocollo
title: Automazione QA E2E
x-i18n:
generated_at: "2026-04-08T02:14:03Z"
generated_at: "2026-04-08T06:00:44Z"
model: gpt-5.4
provider: openai
source_hash: 3b4aa5acc8e77303f4045d4f04372494cae21b89d2fdaba856dbb4855ced9d27
source_hash: 57da147dc06abf9620290104e01a83b42182db1806514114fd9e8467492cda99
source_path: concepts/qa-e2e-automation.md
workflow: 15
---
# Automazione QA E2E
Lo stack QA privato è pensato per esercitare OpenClaw in modo più realistico,
con una forma simile a quella dei canali, rispetto a quanto possa fare un
singolo test unitario.
Lo stack QA privato è pensato per testare OpenClaw in un modo più realistico e
simile a un canale rispetto a quanto possa fare un singolo test unitario.
Componenti attuali:
- `extensions/qa-channel`: canale di messaggi sintetico con superfici per DM, canale, thread,
reazione, modifica ed eliminazione.
- `extensions/qa-channel`: canale di messaggistica sintetico con superfici per messaggi diretti, canale, thread,
reazioni, modifiche ed eliminazioni.
- `extensions/qa-lab`: interfaccia utente di debug e bus QA per osservare la trascrizione,
iniettare messaggi in ingresso ed esportare un report in Markdown.
- `qa/`: risorse predefinite supportate dal repository per l'attività iniziale e gli scenari QA
di base.
inserire messaggi in ingresso ed esportare un report in Markdown.
- `qa/`: risorse iniziali supportate dal repository per il task iniziale e gli
scenari QA di base.
L'attuale flusso operativo QA è un sito QA a due pannelli:
@ -40,13 +39,13 @@ Eseguilo con:
pnpm qa:lab:up
```
Questo compila il sito QA, avvia il percorso gateway supportato da Docker ed espone la
pagina QA Lab in cui un operatore o un ciclo di automazione può assegnare all'agente una
missione QA, osservare il comportamento reale del canale e registrare ciò che ha funzionato, fallito o
è rimasto bloccato.
Questo comando compila il sito QA, avvia la corsia del gateway supportata da Docker ed espone la
pagina di QA Lab dove un operatore o un ciclo di automazione può assegnare all'agente una
missione QA, osservare il comportamento reale del canale e registrare cosa ha funzionato, cosa è fallito o
cosa è rimasto bloccato.
Per un'iterazione più rapida dell'interfaccia utente di QA Lab senza ricompilare ogni volta l'immagine Docker,
avvia lo stack con un bundle QA Lab montato tramite bind:
Per iterare più rapidamente sull'interfaccia utente di QA Lab senza ricompilare ogni volta l'immagine Docker,
avvia lo stack con un bundle di QA Lab montato tramite bind:
```bash
pnpm openclaw qa docker-build-image
@ -57,17 +56,18 @@ pnpm qa:lab:watch
`qa:lab:up:fast` mantiene i servizi Docker su un'immagine precompilata e monta tramite bind
`extensions/qa-lab/web/dist` nel container `qa-lab`. `qa:lab:watch`
ricompila quel bundle a ogni modifica e il browser si ricarica automaticamente quando cambia l'hash
delle risorse di QA Lab.
ricompila quel bundle a ogni modifica e il browser si ricarica automaticamente quando l'hash
delle risorse di QA Lab cambia.
## Risorse predefinite supportate dal repository
## Risorse iniziali supportate dal repository
Le risorse predefinite si trovano in `qa/`:
Le risorse iniziali si trovano in `qa/`:
- `qa/scenarios.md`
- `qa/scenarios/index.md`
- `qa/scenarios/*.md`
Queste sono intenzionalmente incluse in git in modo che il piano QA sia visibile sia agli esseri umani sia
all'agente. L'elenco di base dovrebbe rimanere abbastanza ampio da coprire:
Questi file sono intenzionalmente in git in modo che il piano QA sia visibile sia agli esseri umani sia all'
agente. L'elenco di base dovrebbe rimanere sufficientemente ampio da coprire:
- chat in DM e nei canali
- comportamento dei thread
@ -75,13 +75,13 @@ all'agente. L'elenco di base dovrebbe rimanere abbastanza ampio da coprire:
- callback cron
- richiamo della memoria
- cambio di modello
- passaggio a subagent
- passaggio a un subagente
- lettura del repository e della documentazione
- una piccola attività di build come Lobster Invaders
- un piccolo task di build come Lobster Invaders
## Reportistica
`qa-lab` esporta un report di protocollo in Markdown dalla timeline del bus osservata.
`qa-lab` esporta un report di protocollo in Markdown dalla timeline del bus osservato.
Il report dovrebbe rispondere a:
- Cosa ha funzionato

View File

@ -1,15 +1,15 @@
---
read_when:
- Vuoi spiegare come funzionano lo streaming o il chunking nei canali
- Stai modificando il comportamento dello streaming a blocchi o del chunking nei canali
- Stai eseguendo il debug di risposte a blocchi duplicate/anticipate o del preview streaming nei canali
summary: Comportamento di streaming + chunking (risposte a blocchi, preview streaming nei canali, mappatura delle modalità)
- Spiegare come funzionano lo streaming o il chunking sui canali
- Modificare il comportamento dello streaming a blocchi o del chunking del canale
- Eseguire il debug di risposte a blocchi duplicate/premature o dello streaming di anteprima del canale
summary: Comportamento di streaming + chunking (risposte a blocchi, streaming di anteprima del canale, mappatura delle modalità)
title: Streaming e Chunking
x-i18n:
generated_at: "2026-04-05T13:50:57Z"
generated_at: "2026-04-08T06:00:57Z"
model: gpt-5.4
provider: openai
source_hash: 44b0d08c7eafcb32030ef7c8d5719c2ea2d34e4bac5fdad8cc8b3f4e9e9fad97
source_hash: a8e847bb7da890818cd79dec7777f6ae488e6d6c0468e948e56b6b6c598e0000
source_path: concepts/streaming.md
workflow: 15
---
@ -18,48 +18,48 @@ x-i18n:
OpenClaw ha due livelli di streaming separati:
- **Streaming a blocchi (canali):** emette **blocchi** completati mentre l'assistente scrive. Si tratta di normali messaggi del canale (non delta di token).
- **Preview streaming (Telegram/Discord/Slack):** aggiorna un **messaggio di anteprima** temporaneo durante la generazione.
- **Streaming a blocchi (canali):** emette **blocchi** completati mentre l'assistente scrive. Questi sono normali messaggi del canale (non delta di token).
- **Streaming di anteprima (Telegram/Discord/Slack):** aggiorna un **messaggio di anteprima** temporaneo durante la generazione.
Oggi **non esiste un vero streaming a delta di token** verso i messaggi del canale. Il preview streaming è basato sui messaggi (invio + modifiche/aggiunte).
Al momento **non esiste un vero streaming token-delta** verso i messaggi del canale. Lo streaming di anteprima è basato sui messaggi (invio + modifiche/append).
## Streaming a blocchi (messaggi del canale)
Lo streaming a blocchi invia l'output dell'assistente in blocchi grossolani man mano che diventa disponibile.
Lo streaming a blocchi invia l'output dell'assistente in chunk grossolani man mano che diventano disponibili.
```
Output del modello
Model output
└─ text_delta/events
├─ (blockStreamingBreak=text_end)
│ └─ il chunker emette blocchi man mano che il buffer cresce
│ └─ chunker emits blocks as buffer grows
└─ (blockStreamingBreak=message_end)
└─ il chunker svuota il buffer a message_end
└─ invio al canale (risposte a blocchi)
└─ chunker flushes at message_end
└─ channel send (block replies)
```
Legenda:
- `text_delta/events`: eventi di streaming del modello (possono essere radi per i modelli non streaming).
- `text_delta/events`: eventi del flusso del modello (possono essere radi per i modelli non in streaming).
- `chunker`: `EmbeddedBlockChunker` che applica limiti min/max + preferenza di interruzione.
- `channel send`: messaggi effettivi in uscita (risposte a blocchi).
- `channel send`: messaggi effettivamente inviati in uscita (risposte a blocchi).
**Controlli:**
- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (predefinito off).
- Override per canale: `*.blockStreaming` (e varianti per account) per forzare `"on"`/`"off"` per canale.
- Override del canale: `*.blockStreaming` (e varianti per account) per forzare `"on"`/`"off"` per canale.
- `agents.defaults.blockStreamingBreak`: `"text_end"` o `"message_end"`.
- `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`.
- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (unisce i blocchi in streaming prima dell'invio).
- Limite rigido del canale: `*.textChunkLimit` (ad esempio `channels.whatsapp.textChunkLimit`).
- Modalità chunk del canale: `*.chunkMode` (`length` predefinito, `newline` divide sulle righe vuote, cioè ai confini dei paragrafi, prima del chunking per lunghezza).
- Limite morbido Discord: `channels.discord.maxLinesPerMessage` (predefinito 17) divide le risposte alte per evitare il clipping nell'interfaccia.
- Modalità di chunking del canale: `*.chunkMode` (`length` predefinito, `newline` divide sulle righe vuote (confini dei paragrafi) prima del chunking per lunghezza).
- Limite morbido di Discord: `channels.discord.maxLinesPerMessage` (predefinito 17) divide le risposte alte per evitare il clipping dell'interfaccia.
**Semantica dei confini:**
- `text_end`: trasmette i blocchi non appena il chunker li emette; svuota il buffer a ogni `text_end`.
- `message_end`: attende che il messaggio dell'assistente termini, poi svuota l'output bufferizzato.
- `text_end`: trasmette i blocchi non appena il chunker li emette; svuota a ogni `text_end`.
- `message_end`: attende che il messaggio dell'assistente finisca, poi svuota l'output nel buffer.
`message_end` usa comunque il chunker se il testo bufferizzato supera `maxChars`, quindi può emettere più chunk alla fine.
`message_end` usa comunque il chunker se il testo nel buffer supera `maxChars`, quindi può emettere più chunk alla fine.
## Algoritmo di chunking (limiti basso/alto)
@ -67,30 +67,30 @@ Il chunking a blocchi è implementato da `EmbeddedBlockChunker`:
- **Limite basso:** non emette finché il buffer non è >= `minChars` (a meno che non sia forzato).
- **Limite alto:** preferisce divisioni prima di `maxChars`; se forzato, divide a `maxChars`.
- **Preferenza di interruzione:** `paragraph``newline``sentence``whitespace` → interruzione rigida.
- **Code fence:** non divide mai all'interno delle fence; quando è forzato a `maxChars`, chiude e riapre la fence per mantenere valido il Markdown.
- **Preferenza di interruzione:** `paragraph``newline``sentence``whitespace` → interruzione forzata.
- **Blocchi di codice:** non divide mai all'interno dei blocchi; quando è forzato a `maxChars`, chiude e riapre il blocco per mantenere valido il Markdown.
`maxChars` è vincolato al `textChunkLimit` del canale, quindi non puoi superare i limiti per canale.
`maxChars` è limitato a `textChunkLimit` del canale, quindi non puoi superare i limiti per canale.
## Coalescenza (unione dei blocchi in streaming)
Quando lo streaming a blocchi è abilitato, OpenClaw può **unire chunk di blocchi consecutivi**
prima di inviarli. Questo riduce lo “spam di singole righe” pur continuando a fornire
prima di inviarli. Questo riduce lo “spam di righe singole” pur fornendo
un output progressivo.
- La coalescenza attende **intervalli di inattività** (`idleMs`) prima di svuotare il buffer.
- I buffer sono limitati da `maxChars` e vengono svuotati se lo superano.
- La coalescenza attende **intervalli di inattività** (`idleMs`) prima di svuotare.
- I buffer sono limitati da `maxChars` e verranno svuotati se li superano.
- `minChars` impedisce l'invio di frammenti minuscoli finché non si accumula abbastanza testo
(lo svuotamento finale invia sempre il testo rimanente).
- Il separatore deriva da `blockStreamingChunk.breakPreference`
(`paragraph` → `\n\n`, `newline``\n`, `sentence` → spazio).
- Sono disponibili override per canale tramite `*.blockStreamingCoalesce` (incluse le configurazioni per account).
- Il valore predefinito di coalescenza `minChars` viene portato a 1500 per Signal/Slack/Discord salvo override.
- Sono disponibili override del canale tramite `*.blockStreamingCoalesce` (incluse le configurazioni per account).
- Il valore predefinito di coalescenza `minChars` viene aumentato a 1500 per Signal/Slack/Discord, salvo override.
## Ritmo umano tra i blocchi
## Cadenza umana tra i blocchi
Quando lo streaming a blocchi è abilitato, puoi aggiungere una **pausa casuale** tra
le risposte a blocchi (dopo il primo blocco). Questo rende le risposte multi-bolla
le risposte a blocchi (dopo il primo blocco). Questo rende le risposte con più bolle
più naturali.
- Configurazione: `agents.defaults.humanDelay` (override per agente tramite `agents.list[].humanDelay`).
@ -101,68 +101,69 @@ più naturali.
Questo corrisponde a:
- **Trasmettere i chunk:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (emette man mano). I canali non Telegram richiedono anche `*.blockStreaming: true`.
- **Trasmettere tutto alla fine:** `blockStreamingBreak: "message_end"` (svuota una volta sola, eventualmente in più chunk se è molto lungo).
- **Trasmettere i chunk:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (emette man mano). I canali diversi da Telegram richiedono anche `*.blockStreaming: true`.
- **Trasmettere tutto alla fine:** `blockStreamingBreak: "message_end"` (svuota una volta, possibilmente in più chunk se molto lungo).
- **Nessuno streaming a blocchi:** `blockStreamingDefault: "off"` (solo risposta finale).
**Nota sui canali:** Lo streaming a blocchi è **disattivato a meno che**
`*.blockStreaming` non sia esplicitamente impostato su `true`. I canali possono trasmettere una preview live
**Nota sul canale:** lo streaming a blocchi è **disattivato a meno che**
`*.blockStreaming` non sia impostato esplicitamente su `true`. I canali possono trasmettere un'anteprima live
(`channels.<channel>.streaming`) senza risposte a blocchi.
Promemoria sulla posizione della configurazione: i valori predefiniti `blockStreaming*` si trovano in
Promemoria sulla posizione della configurazione: i valori predefiniti `blockStreaming*` si trovano sotto
`agents.defaults`, non nella configurazione root.
## Modalità di preview streaming
## Modalità di streaming di anteprima
Chiave canonica: `channels.<channel>.streaming`
Modalità:
- `off`: disabilita il preview streaming.
- `partial`: singola anteprima che viene sostituita con il testo più recente.
- `block`: l'anteprima si aggiorna in passaggi suddivisi in chunk/aggiunti.
- `off`: disabilita lo streaming di anteprima.
- `partial`: una singola anteprima che viene sostituita con il testo più recente.
- `block`: l'anteprima viene aggiornata in passaggi a chunk/in append.
- `progress`: anteprima di avanzamento/stato durante la generazione, risposta finale al completamento.
### Mappatura per canale
### Mappatura dei canali
| Canale | `off` | `partial` | `block` | `progress` |
| -------- | ----- | --------- | ------- | ----------------- |
| Telegram | ✅ | ✅ | ✅ | corrisponde a `partial` |
| Discord | ✅ | ✅ | ✅ | corrisponde a `partial` |
| Slack | ✅ | ✅ | ✅ | ✅ |
| Canale | `off` | `partial` | `block` | `progress` |
| -------- | ----- | --------- | ------- | ------------------ |
| Telegram | ✅ | ✅ | ✅ | mappa a `partial` |
| Discord | ✅ | ✅ | ✅ | mappa a `partial` |
| Slack | ✅ | ✅ | ✅ | ✅ |
Solo Slack:
- `channels.slack.nativeStreaming` abilita/disabilita le chiamate API di streaming nativo di Slack quando `streaming=partial` (predefinito: `true`).
- `channels.slack.streaming.nativeTransport` abilita/disabilita le chiamate API di streaming native di Slack quando `channels.slack.streaming.mode="partial"` (predefinito: `true`).
- Lo streaming nativo di Slack e lo stato del thread assistant di Slack richiedono una destinazione in thread di risposta; i DM di primo livello non mostrano quell'anteprima in stile thread.
Migrazione delle chiavi legacy:
- Telegram: `streamMode` + booleano `streaming` vengono migrati automaticamente all'enum `streaming`.
- Discord: `streamMode` + booleano `streaming` vengono migrati automaticamente all'enum `streaming`.
- Slack: `streamMode` viene migrato automaticamente all'enum `streaming`; il booleano `streaming` viene migrato automaticamente a `nativeStreaming`.
- Slack: `streamMode` viene migrato automaticamente a `streaming.mode`; il booleano `streaming` viene migrato automaticamente a `streaming.mode` più `streaming.nativeTransport`; il legacy `nativeStreaming` viene migrato automaticamente a `streaming.nativeTransport`.
### Comportamento a runtime
### Comportamento in runtime
Telegram:
- Usa gli aggiornamenti di anteprima `sendMessage` + `editMessageText` tra DM e gruppi/topic.
- Il preview streaming viene saltato quando lo streaming a blocchi di Telegram è esplicitamente abilitato (per evitare doppio streaming).
- Usa aggiornamenti di anteprima `sendMessage` + `editMessageText` in DM e gruppi/topic.
- Lo streaming di anteprima viene saltato quando lo streaming a blocchi di Telegram è esplicitamente abilitato (per evitare il doppio streaming).
- `/reasoning stream` può scrivere il ragionamento nell'anteprima.
Discord:
- Usa messaggi di anteprima con invio + modifica.
- La modalità `block` usa il chunking delle bozze (`draftChunk`).
- Il preview streaming viene saltato quando lo streaming a blocchi di Discord è esplicitamente abilitato.
- Lo streaming di anteprima viene saltato quando lo streaming a blocchi di Discord è esplicitamente abilitato.
Slack:
- `partial` può usare lo streaming nativo di Slack (`chat.startStream`/`append`/`stop`) quando disponibile.
- `block` usa anteprime bozza in stile append.
- `progress` usa testo di anteprima dello stato, poi la risposta finale.
- `progress` usa il testo di anteprima dello stato, poi la risposta finale.
## Correlati
- [Messaggi](/concepts/messages) — ciclo di vita e consegna dei messaggi
- [Retry](/concepts/retry) — comportamento di retry in caso di errore di consegna
- [Messaggi](/it/concepts/messages) — ciclo di vita e consegna dei messaggi
- [Retry](/it/concepts/retry) — comportamento di retry in caso di errore di consegna
- [Canali](/it/channels) — supporto dello streaming per canale

File diff suppressed because it is too large Load Diff

View File

@ -1,15 +1,15 @@
---
read_when:
- Stai configurando OpenClaw per la prima volta
- Cerchi pattern di configurazione comuni
- Vuoi navigare verso sezioni specifiche della configurazione
- Configurare OpenClaw per la prima volta
- Cercare modelli di configurazione comuni
- Passare a sezioni specifiche della configurazione
summary: 'Panoramica della configurazione: attività comuni, configurazione rapida e link al riferimento completo'
title: Configurazione
x-i18n:
generated_at: "2026-04-05T13:52:44Z"
generated_at: "2026-04-08T06:01:49Z"
model: gpt-5.4
provider: openai
source_hash: a39a7de09c5f9540785ec67f37d435a7a86201f0f5f640dae663054f35976712
source_hash: 199a1e515bd4003319e71593a2659bb883299a76ff67e273d92583df03c96604
source_path: gateway/configuration.md
workflow: 15
---
@ -20,14 +20,14 @@ OpenClaw legge una configurazione facoltativa in <Tooltip tip="JSON5 supporta co
Se il file manca, OpenClaw usa impostazioni predefinite sicure. Motivi comuni per aggiungere una configurazione:
- Connettere i canali e controllare chi può inviare messaggi al bot
- Collegare i canali e controllare chi può inviare messaggi al bot
- Impostare modelli, strumenti, sandboxing o automazione (cron, hook)
- Ottimizzare sessioni, media, rete o UI
- Regolare sessioni, contenuti multimediali, rete o UI
Consulta il [riferimento completo](/gateway/configuration-reference) per ogni campo disponibile.
Consulta il [riferimento completo](/it/gateway/configuration-reference) per ogni campo disponibile.
<Tip>
**Sei nuovo alla configurazione?** Inizia con `openclaw onboard` per la configurazione interattiva, oppure consulta la guida [Esempi di configurazione](/gateway/configuration-examples) per configurazioni complete da copiare e incollare.
**Sei nuovo alla configurazione?** Inizia con `openclaw onboard` per una configurazione interattiva, oppure consulta la guida [Esempi di configurazione](/it/gateway/configuration-examples) per configurazioni complete da copiare e incollare.
</Tip>
## Configurazione minima
@ -40,12 +40,12 @@ Consulta il [riferimento completo](/gateway/configuration-reference) per ogni ca
}
```
## Modificare la configurazione
## Modifica della configurazione
<Tabs>
<Tab title="Procedura guidata interattiva">
```bash
openclaw onboard # flusso completo di onboarding
openclaw onboard # flusso di onboarding completo
openclaw configure # procedura guidata di configurazione
```
</Tab>
@ -58,39 +58,45 @@ Consulta il [riferimento completo](/gateway/configuration-reference) per ogni ca
</Tab>
<Tab title="UI di controllo">
Apri [http://127.0.0.1:18789](http://127.0.0.1:18789) e usa la scheda **Config**.
La UI di controllo visualizza un modulo dallo schema di configurazione live, inclusi i metadati di documentazione dei campi
`title` / `description` più gli schemi di plugin e canale quando
disponibili, con un editor **Raw JSON** come via di fuga. Per UI di analisi dettagliata
e altri strumenti, il gateway espone anche `config.schema.lookup` per
recuperare un nodo di schema limitato a un percorso più i riepiloghi dei figli immediati.
La UI di controllo visualizza un modulo dallo schema di configurazione live, inclusi i metadati della documentazione dei campi
`title` / `description` più gli schemi di plugin e canali quando
disponibili, con un editor **Raw JSON** come via di fuga. Per UI di
approfondimento e altri strumenti, il gateway espone anche `config.schema.lookup` per
recuperare un nodo dello schema limitato a un percorso più riepiloghi immediati dei nodi figli.
</Tab>
<Tab title="Modifica diretta">
Modifica direttamente `~/.openclaw/openclaw.json`. Il Gateway osserva il file e applica automaticamente le modifiche (vedi [hot reload](#config-hot-reload)).
Modifica direttamente `~/.openclaw/openclaw.json`. Il Gateway osserva il file e applica automaticamente le modifiche (vedi [ricaricamento a caldo](#config-hot-reload)).
</Tab>
</Tabs>
## Validazione rigorosa
## Convalida rigorosa
<Warning>
OpenClaw accetta solo configurazioni che corrispondono completamente allo schema. Chiavi sconosciute, tipi non validi o valori non validi fanno sì che il Gateway **si rifiuti di avviarsi**. L'unica eccezione a livello root è `$schema` (stringa), così gli editor possono collegare metadati JSON Schema.
OpenClaw accetta solo configurazioni che corrispondono completamente allo schema. Chiavi sconosciute, tipi non validi o valori non validi fanno sì che il Gateway **si rifiuti di avviarsi**. L'unica eccezione a livello root è `$schema` (stringa), così gli editor possono associare metadati JSON Schema.
</Warning>
Note sugli strumenti di schema:
Note sugli strumenti dello schema:
- `openclaw config schema` stampa la stessa famiglia di JSON Schema usata dalla UI di controllo
e dalla validazione della configurazione.
- I valori `title` e `description` dei campi vengono riportati nell'output dello schema per
editor e strumenti per moduli.
- Le voci di oggetti annidati, wildcard (`*`) e elementi di array (`[]`) ereditano gli stessi
metadati di documentazione dove esiste documentazione di campo corrispondente.
- Anche i rami di composizione `anyOf` / `oneOf` / `allOf` ereditano gli stessi metadati
di documentazione, così le varianti union/intersection mantengono lo stesso aiuto per i campi.
- `config.schema.lookup` restituisce un percorso di configurazione normalizzato con un nodo di schema superficiale (`title`, `description`, `type`, `enum`, `const`, limiti comuni
e campi di validazione simili), metadati di suggerimento UI corrispondenti e riepiloghi dei figli immediati per strumenti di analisi dettagliata.
- Gli schemi runtime di plugin/canale vengono uniti quando il gateway riesce a caricare il
registro manifest corrente.
e dalla convalida della configurazione.
- Tratta l'output di quello schema come il contratto canonico leggibile dalle macchine per
`openclaw.json`; questa panoramica e il riferimento di configurazione lo riassumono.
- I valori dei campi `title` e `description` vengono riportati nell'output dello schema per
strumenti di editing e moduli.
- Le voci di oggetti nidificati, wildcard (`*`) e elementi di array (`[]`) ereditano gli stessi
metadati della documentazione dove esiste documentazione del campo corrispondente.
- Anche i rami di composizione `anyOf` / `oneOf` / `allOf` ereditano gli stessi
metadati della documentazione, così le varianti union/intersection mantengono lo stesso aiuto per il campo.
- `config.schema.lookup` restituisce un percorso di configurazione normalizzato con un nodo di
schema superficiale (`title`, `description`, `type`, `enum`, `const`, limiti comuni
e campi di convalida simili), metadati dei suggerimenti UI corrispondenti e riepiloghi immediati dei nodi figli
per strumenti di approfondimento.
- Gli schemi runtime di plugin/canali vengono uniti quando il gateway può caricare il
registro dei manifest corrente.
- `pnpm config:docs:check` rileva divergenze tra gli artefatti di baseline della configurazione rivolti alla documentazione
e la superficie dello schema corrente.
Quando la validazione fallisce:
Quando la convalida fallisce:
- Il Gateway non si avvia
- Funzionano solo i comandi diagnostici (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`)
@ -114,7 +120,7 @@ Quando la validazione fallisce:
- [iMessage](/it/channels/imessage) — `channels.imessage`
- [Mattermost](/it/channels/mattermost) — `channels.mattermost`
Tutti i canali condividono lo stesso pattern di policy DM:
Tutti i canali condividono lo stesso modello di criterio DM:
```json5
{
@ -132,7 +138,7 @@ Quando la validazione fallisce:
</Accordion>
<Accordion title="Scegliere e configurare i modelli">
Imposta il modello principale e gli eventuali fallback:
Imposta il modello primario e gli eventuali fallback:
```json5
{
@ -151,30 +157,30 @@ Quando la validazione fallisce:
}
```
- `agents.defaults.models` definisce il catalogo modelli e funge da allowlist per `/model`.
- `agents.defaults.models` definisce il catalogo dei modelli e funge da allowlist per `/model`.
- I riferimenti ai modelli usano il formato `provider/model` (ad esempio `anthropic/claude-opus-4-6`).
- `agents.defaults.imageMaxDimensionPx` controlla il ridimensionamento delle immagini in trascrizione/strumenti (predefinito `1200`); valori inferiori in genere riducono l'uso di token vision nelle esecuzioni ricche di screenshot.
- Vedi [Models CLI](/concepts/models) per cambiare modello in chat e [Model Failover](/concepts/model-failover) per il comportamento di rotazione auth e fallback.
- Per provider personalizzati/self-hosted, vedi [Provider personalizzati](/gateway/configuration-reference#custom-providers-and-base-urls) nel riferimento.
- `agents.defaults.imageMaxDimensionPx` controlla il ridimensionamento delle immagini di transcript/tool (predefinito `1200`); valori più bassi di solito riducono l'uso di vision token nelle esecuzioni ricche di screenshot.
- Consulta [Models CLI](/it/concepts/models) per cambiare modello in chat e [Model Failover](/it/concepts/model-failover) per il comportamento di rotazione dell'autenticazione e fallback.
- Per provider personalizzati/self-hosted, consulta [Provider personalizzati](/it/gateway/configuration-reference#custom-providers-and-base-urls) nel riferimento.
</Accordion>
<Accordion title="Controllare chi può inviare messaggi al bot">
L'accesso DM è controllato per canale tramite `dmPolicy`:
- `"pairing"` (predefinito): i mittenti sconosciuti ricevono un codice pairing monouso da approvare
- `"allowlist"`: solo i mittenti in `allowFrom` (o nello store paired allow)
- `"open"`: consente tutti i DM in ingresso (richiede `allowFrom: ["*"]`)
- `"pairing"` (predefinito): i mittenti sconosciuti ricevono un codice di pairing monouso da approvare
- `"allowlist"`: solo i mittenti in `allowFrom` (o nello store allow associato)
- `"open"`: consenti tutti i DM in ingresso (richiede `allowFrom: ["*"]`)
- `"disabled"`: ignora tutti i DM
Per i gruppi, usa `groupPolicy` + `groupAllowFrom` o allowlist specifiche del canale.
Consulta il [riferimento completo](/gateway/configuration-reference#dm-and-group-access) per i dettagli per canale.
Consulta il [riferimento completo](/it/gateway/configuration-reference#dm-and-group-access) per i dettagli per canale.
</Accordion>
<Accordion title="Configurare il gating per menzione nelle chat di gruppo">
I messaggi di gruppo per impostazione predefinita **richiedono una menzione**. Configura i pattern per agente:
<Accordion title="Configurare il filtro per menzione nelle chat di gruppo">
Per impostazione predefinita, i messaggi di gruppo **richiedono una menzione**. Configura i pattern per agente:
```json5
{
@ -196,15 +202,14 @@ Quando la validazione fallisce:
}
```
- **Menzioni nei metadati**: @-mention native (tap-to-mention di WhatsApp, @bot di Telegram, ecc.)
- **Menzioni nei metadati**: @-mention native (WhatsApp tap-to-mention, Telegram @bot, ecc.)
- **Pattern di testo**: pattern regex sicuri in `mentionPatterns`
- Consulta il [riferimento completo](/gateway/configuration-reference#group-chat-mention-gating) per override per canale e modalità self-chat.
- Consulta il [riferimento completo](/it/gateway/configuration-reference#group-chat-mention-gating) per gli override per canale e la modalità self-chat.
</Accordion>
<Accordion title="Limitare le Skills per agente">
Usa `agents.defaults.skills` per una baseline condivisa, quindi fai override di
agenti specifici con `agents.list[].skills`:
Usa `agents.defaults.skills` per una baseline condivisa, quindi fai override di agenti specifici con `agents.list[].skills`:
```json5
{
@ -214,23 +219,23 @@ Quando la validazione fallisce:
},
list: [
{ id: "writer" }, // eredita github, weather
{ id: "docs", skills: ["docs-search"] }, // sostituisce i default
{ id: "docs", skills: ["docs-search"] }, // sostituisce i valori predefiniti
{ id: "locked-down", skills: [] }, // nessuna Skills
],
},
}
```
- Ometti `agents.defaults.skills` per avere Skills senza restrizioni per impostazione predefinita.
- Ometti `agents.defaults.skills` per Skills senza restrizioni per impostazione predefinita.
- Ometti `agents.list[].skills` per ereditare i valori predefiniti.
- Imposta `agents.list[].skills: []` per nessuna Skills.
- Consulta [Skills](/tools/skills), [Config Skills](/tools/skills-config) e
il [Riferimento configurazione](/gateway/configuration-reference#agentsdefaultsskills).
- Consulta [Skills](/it/tools/skills), [Configurazione delle Skills](/it/tools/skills-config), e
il [Riferimento di configurazione](/it/gateway/configuration-reference#agentsdefaultsskills).
</Accordion>
<Accordion title="Regolare il monitoraggio dello stato dei canali del gateway">
Controlla quanto aggressivamente il gateway riavvia i canali che sembrano obsoleti:
Controlla quanto aggressivamente il gateway riavvia i canali che sembrano inattivi:
```json5
{
@ -252,20 +257,20 @@ Quando la validazione fallisce:
}
```
- Imposta `gateway.channelHealthCheckMinutes: 0` per disabilitare globalmente i riavvii del monitoraggio dello stato.
- `channelStaleEventThresholdMinutes` dovrebbe essere maggiore o uguale all'intervallo di controllo.
- Imposta `gateway.channelHealthCheckMinutes: 0` per disabilitare globalmente i riavvii del monitor di stato.
- `channelStaleEventThresholdMinutes` deve essere maggiore o uguale all'intervallo di controllo.
- Usa `channels.<provider>.healthMonitor.enabled` o `channels.<provider>.accounts.<id>.healthMonitor.enabled` per disabilitare i riavvii automatici per un canale o account senza disabilitare il monitor globale.
- Consulta [Health Checks](/gateway/health) per il debug operativo e il [riferimento completo](/gateway/configuration-reference#gateway) per tutti i campi.
- Consulta [Controlli di stato](/it/gateway/health) per il debug operativo e il [riferimento completo](/it/gateway/configuration-reference#gateway) per tutti i campi.
</Accordion>
<Accordion title="Configurare sessioni e reset">
Le sessioni controllano continuità e isolamento della conversazione:
<Accordion title="Configurare sessioni e reimpostazioni">
Le sessioni controllano la continuità e l'isolamento delle conversazioni:
```json5
{
session: {
dmScope: "per-channel-peer", // consigliato per multiutente
dmScope: "per-channel-peer", // consigliato per più utenti
threadBindings: {
enabled: true,
idleHours: 24,
@ -282,13 +287,13 @@ Quando la validazione fallisce:
- `dmScope`: `main` (condivisa) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`: valori predefiniti globali per l'instradamento delle sessioni associate ai thread (Discord supporta `/focus`, `/unfocus`, `/agents`, `/session idle` e `/session max-age`).
- Consulta [Gestione delle sessioni](/concepts/session) per ambito, collegamenti di identità e policy di invio.
- Consulta il [riferimento completo](/gateway/configuration-reference#session) per tutti i campi.
- Consulta [Gestione delle sessioni](/it/concepts/session) per ambito, collegamenti di identità e criterio di invio.
- Consulta il [riferimento completo](/it/gateway/configuration-reference#session) per tutti i campi.
</Accordion>
<Accordion title="Abilitare il sandboxing">
Esegui le sessioni agente in container Docker isolati:
Esegui le sessioni dell'agente in container Docker isolati:
```json5
{
@ -303,16 +308,16 @@ Quando la validazione fallisce:
}
```
Costruisci prima l'immagine: `scripts/sandbox-setup.sh`
Crea prima l'immagine: `scripts/sandbox-setup.sh`
Consulta [Sandboxing](/gateway/sandboxing) per la guida completa e il [riferimento completo](/gateway/configuration-reference#agentsdefaultssandbox) per tutte le opzioni.
Consulta [Sandboxing](/it/gateway/sandboxing) per la guida completa e il [riferimento completo](/it/gateway/configuration-reference#agentsdefaultssandbox) per tutte le opzioni.
</Accordion>
<Accordion title="Abilitare il push supportato da relay per le build iOS ufficiali">
Il push supportato da relay si configura in `openclaw.json`.
Il push supportato da relay è configurato in `openclaw.json`.
Imposta questo nella configurazione gateway:
Imposta questo nella configurazione del gateway:
```json5
{
@ -338,31 +343,31 @@ Quando la validazione fallisce:
Cosa fa:
- Consente al gateway di inviare `push.test`, wake nudges e wake di riconnessione tramite il relay esterno.
- Usa un permesso di invio limitato alla registrazione inoltrato dall'app iOS paired. Il gateway non ha bisogno di un token relay valido per tutta la distribuzione.
- Associa ogni registrazione supportata da relay all'identità del gateway con cui l'app iOS ha effettuato il pairing, così un altro gateway non può riutilizzare la registrazione memorizzata.
- Mantiene le build iOS locali/manuali su APNs diretti. Gli invii supportati da relay si applicano solo alle build ufficiali distribuite che si sono registrate tramite il relay.
- Consente al gateway di inviare `push.test`, solleciti di wake e wake di riconnessione tramite il relay esterno.
- Usa un'autorizzazione di invio limitata alla registrazione inoltrata dall'app iOS associata. Il gateway non ha bisogno di un token relay valido per l'intera distribuzione.
- Associa ogni registrazione supportata da relay all'identità del gateway con cui l'app iOS è stata associata, così un altro gateway non può riutilizzare la registrazione memorizzata.
- Mantiene le build iOS locali/manuali su APNs diretto. Gli invii supportati da relay si applicano solo alle build ufficiali distribuite che si sono registrate tramite il relay.
- Deve corrispondere al base URL del relay incorporato nella build iOS ufficiale/TestFlight, così il traffico di registrazione e invio raggiunge la stessa distribuzione relay.
Flusso end-to-end:
1. Installa una build iOS ufficiale/TestFlight compilata con lo stesso base URL del relay.
2. Configura `gateway.push.apns.relay.baseUrl` sul gateway.
3. Esegui il pairing dell'app iOS con il gateway e lascia che si connettano sia le sessioni node sia quelle operator.
4. L'app iOS recupera l'identità del gateway, si registra presso il relay usando App Attest più la ricevuta dell'app e quindi pubblica il payload `push.apns.register` supportato da relay sul gateway paired.
5. Il gateway memorizza l'handle relay e il permesso di invio, poi li usa per `push.test`, wake nudges e wake di riconnessione.
3. Associa l'app iOS al gateway e lascia che si connettano sia le sessioni node sia quelle operatore.
4. L'app iOS recupera l'identità del gateway, si registra presso il relay usando App Attest più la ricevuta dell'app e poi pubblica il payload `push.apns.register` supportato da relay sul gateway associato.
5. Il gateway memorizza l'handle relay e l'autorizzazione di invio, quindi li usa per `push.test`, solleciti di wake e wake di riconnessione.
Note operative:
- Se sposti l'app iOS su un gateway diverso, ricollega l'app così potrà pubblicare una nuova registrazione relay associata a quel gateway.
- Se distribuisci una nuova build iOS che punta a una distribuzione relay diversa, l'app aggiorna la registrazione relay memorizzata invece di riutilizzare la vecchia origine relay.
- Se passi l'app iOS a un gateway diverso, riconnetti l'app così può pubblicare una nuova registrazione relay associata a quel gateway.
- Se distribuisci una nuova build iOS che punta a una distribuzione relay diversa, l'app aggiorna la registrazione relay memorizzata nella cache invece di riutilizzare il vecchio relay di origine.
Nota di compatibilità:
- `OPENCLAW_APNS_RELAY_BASE_URL` e `OPENCLAW_APNS_RELAY_TIMEOUT_MS` funzionano ancora come override temporanei via env.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` rimane una via di fuga di sviluppo solo loopback; non mantenere URL relay HTTP nella configurazione.
- `OPENCLAW_APNS_RELAY_BASE_URL` e `OPENCLAW_APNS_RELAY_TIMEOUT_MS` funzionano ancora come override temporanei dell'env.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` resta una via di fuga di sviluppo solo loopback; non rendere persistenti URL relay HTTP nella configurazione.
Consulta [App iOS](/platforms/ios#relay-backed-push-for-official-builds) per il flusso end-to-end e [Flusso di autenticazione e attendibilità](/platforms/ios#authentication-and-trust-flow) per il modello di sicurezza del relay.
Consulta [App iOS](/it/platforms/ios#relay-backed-push-for-official-builds) per il flusso end-to-end e [Flusso di autenticazione e trust](/it/platforms/ios#authentication-and-trust-flow) per il modello di sicurezza del relay.
</Accordion>
@ -382,12 +387,12 @@ Quando la validazione fallisce:
- `every`: stringa di durata (`30m`, `2h`). Imposta `0m` per disabilitare.
- `target`: `last` | `none` | `<channel-id>` (ad esempio `discord`, `matrix`, `telegram` o `whatsapp`)
- `directPolicy`: `allow` (predefinito) oppure `block` per target heartbeat in stile DM
- Consulta [Heartbeat](/gateway/heartbeat) per la guida completa.
- `directPolicy`: `allow` (predefinito) o `block` per target heartbeat in stile DM
- Consulta [Heartbeat](/it/gateway/heartbeat) per la guida completa.
</Accordion>
<Accordion title="Configurare i cron job">
<Accordion title="Configurare job cron">
```json5
{
cron: {
@ -402,9 +407,9 @@ Quando la validazione fallisce:
}
```
- `sessionRetention`: elimina le sessioni isolate completate da `sessions.json` (predefinito `24h`; imposta `false` per disabilitare).
- `runLog`: pota `cron/runs/<jobId>.jsonl` in base a dimensione e righe mantenute.
- Consulta [Cron jobs](/it/automation/cron-jobs) per la panoramica della funzionalità e gli esempi CLI.
- `sessionRetention`: elimina dalle `sessions.json` le sessioni isolate completate (predefinito `24h`; imposta `false` per disabilitare).
- `runLog`: riduce `cron/runs/<jobId>.jsonl` in base a dimensione e righe mantenute.
- Consulta [Job cron](/it/automation/cron-jobs) per la panoramica della funzionalità e gli esempi CLI.
</Accordion>
@ -432,16 +437,16 @@ Quando la validazione fallisce:
}
```
Nota di sicurezza:
Nota sulla sicurezza:
- Tratta tutto il contenuto dei payload hook/webhook come input non attendibile.
- Usa un `hooks.token` dedicato; non riutilizzare il token condiviso del Gateway.
- L'autenticazione hook è solo header (`Authorization: Bearer ...` o `x-openclaw-token`); i token nella query string vengono rifiutati.
- L'autenticazione degli hook è solo tramite header (`Authorization: Bearer ...` o `x-openclaw-token`); i token nella query string vengono rifiutati.
- `hooks.path` non può essere `/`; mantieni l'ingresso webhook su un sottopercorso dedicato come `/hooks`.
- Mantieni disabilitati i flag di bypass per contenuto non sicuro (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`) a meno che tu non stia facendo debug molto mirato.
- Se abiliti `hooks.allowRequestSessionKey`, imposta anche `hooks.allowedSessionKeyPrefixes` per limitare le chiavi di sessione selezionabili dal chiamante.
- Per agenti guidati da hook, preferisci livelli di modello moderni e forti e una policy strumenti rigorosa (ad esempio solo messaggistica più sandboxing dove possibile).
- Mantieni disabilitati i flag di bypass per contenuti non sicuri (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`) a meno che tu non stia facendo debug strettamente circoscritto.
- Se abiliti `hooks.allowRequestSessionKey`, imposta anche `hooks.allowedSessionKeyPrefixes` per limitare le chiavi di sessione selezionate dal chiamante.
- Per agenti guidati da hook, preferisci tier di modelli moderni e robusti e un criterio tool rigoroso (ad esempio solo messaggistica più sandboxing dove possibile).
Consulta il [riferimento completo](/gateway/configuration-reference#hooks) per tutte le opzioni di mapping e l'integrazione Gmail.
Consulta il [riferimento completo](/it/gateway/configuration-reference#hooks) per tutte le opzioni di mapping e l'integrazione con Gmail.
</Accordion>
@ -463,12 +468,12 @@ Quando la validazione fallisce:
}
```
Consulta [Multi-Agent](/concepts/multi-agent) e il [riferimento completo](/gateway/configuration-reference#multi-agent-routing) per regole di binding e profili di accesso per agente.
Consulta [Multi-Agent](/it/concepts/multi-agent) e il [riferimento completo](/it/gateway/configuration-reference#multi-agent-routing) per le regole di binding e i profili di accesso per agente.
</Accordion>
<Accordion title="Suddividere la configurazione in più file ($include)">
Usa `$include` per organizzare configurazioni grandi:
Usa `$include` per organizzare configurazioni di grandi dimensioni:
```json5
// ~/.openclaw/openclaw.json
@ -482,26 +487,26 @@ Quando la validazione fallisce:
```
- **File singolo**: sostituisce l'oggetto contenitore
- **Array di file**: deep-merge in ordine (l'ultimo vince)
- **Array di file**: unione profonda in ordine (vince l'ultimo)
- **Chiavi sibling**: unite dopo gli include (sovrascrivono i valori inclusi)
- **Include annidati**: supportati fino a 10 livelli di profondità
- **Include nidificati**: supportati fino a 10 livelli di profondità
- **Percorsi relativi**: risolti relativamente al file che include
- **Gestione errori**: errori chiari per file mancanti, errori di parsing e include circolari
- **Gestione degli errori**: errori chiari per file mancanti, errori di parsing e include circolari
</Accordion>
</AccordionGroup>
## Hot reload della configurazione
## Ricaricamento a caldo della configurazione
Il Gateway osserva `~/.openclaw/openclaw.json` e applica automaticamente le modifiche — per la maggior parte delle impostazioni non è necessario alcun riavvio manuale.
Il Gateway osserva `~/.openclaw/openclaw.json` e applica automaticamente le modifiche — nella maggior parte dei casi non è necessario alcun riavvio manuale.
### Modalità di ricarica
### Modalità di ricaricamento
| Modalità | Comportamento |
| ---------------------- | -------------------------------------------------------------------------------------- |
| **`hybrid`** (predefinita) | Applica a caldo immediatamente le modifiche sicure. Si riavvia automaticamente per quelle critiche. |
| **`hot`** | Applica a caldo solo le modifiche sicure. Registra un avviso quando è necessario un riavvio — lo gestisci tu. |
| **`restart`** | Riavvia il Gateway a ogni modifica della configurazione, sicura o meno. |
| **`hybrid`** (predefinita) | Applica a caldo immediatamente le modifiche sicure. Riavvia automaticamente per quelle critiche. |
| **`hot`** | Applica a caldo solo le modifiche sicure. Registra un avviso quando è necessario un riavvio — te ne occupi tu. |
| **`restart`** | Riavvia il Gateway per qualsiasi modifica della configurazione, sicura o meno. |
| **`off`** | Disabilita l'osservazione del file. Le modifiche hanno effetto al successivo riavvio manuale. |
```json5
@ -514,18 +519,18 @@ Il Gateway osserva `~/.openclaw/openclaw.json` e applica automaticamente le modi
### Cosa viene applicato a caldo e cosa richiede un riavvio
La maggior parte dei campi viene applicata a caldo senza downtime. In modalità `hybrid`, le modifiche che richiedono un riavvio vengono gestite automaticamente.
La maggior parte dei campi viene applicata a caldo senza downtime. In modalità `hybrid`, le modifiche che richiedono riavvio vengono gestite automaticamente.
| Categoria | Campi | Riavvio necessario? |
| ------------------- | -------------------------------------------------------------------- | --------------- |
| Canali | `channels.*`, `web` (WhatsApp) — tutti i canali built-in ed extension | No |
| Agente e modelli | `agent`, `agents`, `models`, `routing` | No |
| Automazione | `hooks`, `cron`, `agent.heartbeat` | No |
| Sessioni e messaggi | `session`, `messages` | No |
| Strumenti e media | `tools`, `browser`, `skills`, `audio`, `talk` | No |
| UI e varie | `ui`, `logging`, `identity`, `bindings` | No |
| Server Gateway | `gateway.*` (porta, bind, auth, tailscale, TLS, HTTP) | **Sì** |
| Infrastruttura | `discovery`, `canvasHost`, `plugins` | **Sì** |
| Categoria | Campi | Riavvio necessario? |
| -------------------- | -------------------------------------------------------------------- | ------------------- |
| Canali | `channels.*`, `web` (WhatsApp) — tutti i canali built-in e di estensione | No |
| Agente e modelli | `agent`, `agents`, `models`, `routing` | No |
| Automazione | `hooks`, `cron`, `agent.heartbeat` | No |
| Sessioni e messaggi | `session`, `messages` | No |
| Strumenti e media | `tools`, `browser`, `skills`, `audio`, `talk` | No |
| UI e varie | `ui`, `logging`, `identity`, `bindings` | No |
| Server gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Sì** |
| Infrastruttura | `discovery`, `canvasHost`, `plugins` | **Sì** |
<Note>
`gateway.reload` e `gateway.remote` sono eccezioni — modificarli **non** attiva un riavvio.
@ -534,23 +539,24 @@ La maggior parte dei campi viene applicata a caldo senza downtime. In modalità
## RPC di configurazione (aggiornamenti programmatici)
<Note>
Le RPC di scrittura del control-plane (`config.apply`, `config.patch`, `update.run`) hanno un rate limit di **3 richieste per 60 secondi** per `deviceId+clientIp`. Quando il limite viene raggiunto, la RPC restituisce `UNAVAILABLE` con `retryAfterMs`.
Le RPC di scrittura del control plane (`config.apply`, `config.patch`, `update.run`) sono soggette a rate limit di **3 richieste ogni 60 secondi** per `deviceId+clientIp`. Quando si raggiunge il limite, la RPC restituisce `UNAVAILABLE` con `retryAfterMs`.
</Note>
Flusso sicuro/predefinito:
- `config.schema.lookup`: ispeziona un sottoalbero di configurazione limitato a un percorso con un nodo di schema superficiale, metadati di suggerimento corrispondenti e riepiloghi dei figli immediati
- `config.get`: recupera l'istantanea corrente + hash
- `config.schema.lookup`: ispeziona un sottoalbero della configurazione limitato a un percorso con un nodo di schema superficiale,
metadati dei suggerimenti corrispondenti e riepiloghi immediati dei nodi figli
- `config.get`: recupera lo snapshot corrente + hash
- `config.patch`: percorso preferito per aggiornamenti parziali
- `config.apply`: sostituzione completa della configurazione solo
- `update.run`: auto-aggiornamento esplicito + riavvio
- `config.apply`: solo sostituzione completa della configurazione
- `update.run`: autoaggiornamento esplicito + riavvio
Quando non stai sostituendo l'intera configurazione, preferisci `config.schema.lookup`
poi `config.patch`.
<AccordionGroup>
<Accordion title="config.apply (sostituzione completa)">
Valida + scrive l'intera configurazione e riavvia il Gateway in un unico passaggio.
Convalida + scrive l'intera configurazione e riavvia il Gateway in un solo passaggio.
<Warning>
`config.apply` sostituisce l'**intera configurazione**. Usa `config.patch` per aggiornamenti parziali, oppure `openclaw config set` per singole chiavi.
@ -559,8 +565,8 @@ poi `config.patch`.
Parametri:
- `raw` (stringa) — payload JSON5 per l'intera configurazione
- `baseHash` (facoltativo) — hash di configurazione da `config.get` (obbligatorio quando la configurazione esiste)
- `sessionKey` (facoltativo) — chiave di sessione per il ping di wake-up post-riavvio
- `baseHash` (facoltativo) — hash della configurazione da `config.get` (richiesto quando la configurazione esiste)
- `sessionKey` (facoltativo) — chiave di sessione per il ping di riattivazione post-riavvio
- `note` (facoltativo) — nota per il sentinel di riavvio
- `restartDelayMs` (facoltativo) — ritardo prima del riavvio (predefinito 2000)
@ -578,16 +584,16 @@ poi `config.patch`.
</Accordion>
<Accordion title="config.patch (aggiornamento parziale)">
Unisce un aggiornamento parziale alla configurazione esistente (semantica JSON merge patch):
Unisce un aggiornamento parziale nella configurazione esistente (semantica JSON merge patch):
- Gli oggetti vengono uniti ricorsivamente
- `null` elimina una chiave
- Gli array sostituiscono
- Gli array vengono sostituiti
Parametri:
- `raw` (stringa) — JSON5 con solo le chiavi da modificare
- `baseHash` (obbligatorio) — hash di configurazione da `config.get`
- `baseHash` (obbligatorio) — hash della configurazione da `config.get`
- `sessionKey`, `note`, `restartDelayMs` — uguali a `config.apply`
Il comportamento di riavvio corrisponde a `config.apply`: riavvii in attesa accorpati più un cooldown di 30 secondi tra i cicli di riavvio.
@ -621,7 +627,7 @@ Nessuno dei due file sovrascrive le variabili d'ambiente esistenti. Puoi anche i
```
<Accordion title="Importazione env della shell (facoltativa)">
Se abilitato e le chiavi previste non sono impostate, OpenClaw esegue la shell di login e importa solo le chiavi mancanti:
Se abilitato e le chiavi previste non sono impostate, OpenClaw esegue la tua login shell e importa solo le chiavi mancanti:
```json5
{
@ -635,7 +641,7 @@ Equivalente come variabile d'ambiente: `OPENCLAW_LOAD_SHELL_ENV=1`
</Accordion>
<Accordion title="Sostituzione di variabili d'ambiente nei valori di configurazione">
Fai riferimento alle variabili d'ambiente in qualsiasi valore stringa della configurazione con `${VAR_NAME}`:
Riferisci le variabili d'ambiente in qualsiasi valore stringa della configurazione con `${VAR_NAME}`:
```json5
{
@ -646,15 +652,15 @@ Equivalente come variabile d'ambiente: `OPENCLAW_LOAD_SHELL_ENV=1`
Regole:
- Vengono riconosciuti solo nomi maiuscoli corrispondenti a: `[A-Z_][A-Z0-9_]*`
- Variabili mancanti/vuote generano un errore al caricamento
- Esegui l'escape con `$${VAR}` per output letterale
- Funziona nei file `$include`
- Vengono corrisposti solo nomi in maiuscolo: `[A-Z_][A-Z0-9_]*`
- Variabili mancanti/vuote generano un errore in fase di caricamento
- Usa l'escape `$${VAR}` per output letterale
- Funziona all'interno dei file `$include`
- Sostituzione inline: `"${BASE}/v1"``"https://api.example.com/v1"`
</Accordion>
<Accordion title="Riferimenti ai secret (env, file, exec)">
<Accordion title="Riferimenti a segreti (env, file, exec)">
Per i campi che supportano oggetti SecretRef, puoi usare:
```json5
@ -687,16 +693,16 @@ Regole:
}
```
I dettagli su SecretRef (inclusi `secrets.providers` per `env`/`file`/`exec`) sono in [Gestione dei secret](/gateway/secrets).
I percorsi credenziali supportati sono elencati in [Superficie credenziali SecretRef](/reference/secretref-credential-surface).
I dettagli di SecretRef (inclusi `secrets.providers` per `env`/`file`/`exec`) sono in [Gestione dei segreti](/it/gateway/secrets).
I percorsi delle credenziali supportati sono elencati in [Superficie delle credenziali SecretRef](/it/reference/secretref-credential-surface).
</Accordion>
Consulta [Ambiente](/help/environment) per la precedenza completa e le sorgenti.
Consulta [Ambiente](/it/help/environment) per la precedenza completa e le origini.
## Riferimento completo
Per il riferimento completo campo per campo, consulta **[Riferimento configurazione](/gateway/configuration-reference)**.
Per il riferimento completo campo per campo, consulta **[Riferimento di configurazione](/it/gateway/configuration-reference)**.
---
_Correlati: [Esempi di configurazione](/gateway/configuration-examples) · [Riferimento configurazione](/gateway/configuration-reference) · [Doctor](/gateway/doctor)_
_Correlati: [Esempi di configurazione](/it/gateway/configuration-examples) · [Riferimento di configurazione](/it/gateway/configuration-reference) · [Doctor](/it/gateway/doctor)_

View File

@ -0,0 +1,370 @@
---
read_when:
- Vuoi una conoscenza persistente oltre alle semplici note MEMORY.md
- Stai configurando il plugin bundled memory-wiki
- Vuoi capire wiki_search, wiki_get o la modalità bridge
summary: 'memory-wiki: archivio di conoscenza compilato con provenienza, asserzioni, dashboard e modalità bridge'
title: Wiki della memoria
x-i18n:
generated_at: "2026-04-08T06:01:10Z"
model: gpt-5.4
provider: openai
source_hash: b78dd6a4ef4451dae6b53197bf0c7c2a2ba846b08e4a3a93c1026366b1598d82
source_path: plugins/memory-wiki.md
workflow: 15
---
# Wiki della memoria
`memory-wiki` è un plugin bundled che trasforma la memoria durevole in un
archivio di conoscenza compilato.
**Non** sostituisce il plugin di memoria attivo. Il plugin di memoria attivo
continua a gestire richiamo, promozione, indicizzazione e dreaming. `memory-wiki`
si affianca ad esso e compila la conoscenza durevole in una wiki navigabile con
pagine deterministiche, asserzioni strutturate, provenienza, dashboard e digest
leggibili dalle macchine.
Usalo quando vuoi che la memoria si comporti più come un livello di conoscenza
mantenuto e meno come un insieme di file Markdown.
## Cosa aggiunge
- Un archivio wiki dedicato con layout delle pagine deterministico
- Metadati strutturati per asserzioni ed evidenze, non solo prosa
- Provenienza a livello di pagina, confidenza, contraddizioni e domande aperte
- Digest compilati per i consumer agent/runtime
- Strumenti nativi della wiki per search/get/apply/lint
- Modalità bridge opzionale che importa artefatti pubblici dal plugin di memoria attivo
- Modalità di rendering opzionale compatibile con Obsidian e integrazione CLI
## Come si integra con la memoria
Considera la suddivisione in questo modo:
| Livello | Gestisce |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Plugin di memoria attivo (`memory-core`, QMD, Honcho, ecc.) | Richiamo, ricerca semantica, promozione, dreaming, runtime della memoria |
| `memory-wiki` | Pagine wiki compilate, sintesi ricche di provenienza, dashboard, search/get/apply specifici della wiki |
Se il plugin di memoria attivo espone artefatti di richiamo condivisi, OpenClaw può cercare
in entrambi i livelli in un unico passaggio con `memory_search corpus=all`.
Quando ti servono ranking specifico della wiki, provenienza o accesso diretto
alle pagine, usa invece gli strumenti nativi della wiki.
## Modalità dell'archivio
`memory-wiki` supporta tre modalità di archivio:
### `isolated`
Archivio proprio, sorgenti proprie, nessuna dipendenza da `memory-core`.
Usa questa modalità quando vuoi che la wiki sia il proprio archivio di
conoscenza curato.
### `bridge`
Legge artefatti pubblici della memoria ed eventi di memoria dal plugin di memoria attivo
tramite punti di integrazione pubblici del plugin SDK.
Usa questa modalità quando vuoi che la wiki compili e organizzi gli
artefatti esportati dal plugin di memoria senza accedere agli elementi interni
privati del plugin.
La modalità bridge può indicizzare:
- artefatti di memoria esportati
- report di dream
- note giornaliere
- file radice della memoria
- log degli eventi di memoria
### `unsafe-local`
Via di fuga esplicita sulla stessa macchina per percorsi privati locali.
Questa modalità è intenzionalmente sperimentale e non portabile. Usala solo se
comprendi il confine di fiducia e hai bisogno in modo specifico di accesso al
filesystem locale che la modalità bridge non può fornire.
## Layout dell'archivio
Il plugin inizializza un archivio in questo modo:
```text
<vault>/
AGENTS.md
WIKI.md
index.md
inbox.md
entities/
concepts/
syntheses/
sources/
reports/
_attachments/
_views/
.openclaw-wiki/
```
Il contenuto gestito rimane all'interno di blocchi generati. I blocchi di note
umani vengono preservati.
I gruppi principali di pagine sono:
- `sources/` per materiale grezzo importato e pagine supportate dal bridge
- `entities/` per elementi durevoli, persone, sistemi, progetti e oggetti
- `concepts/` per idee, astrazioni, pattern e policy
- `syntheses/` per riepiloghi compilati e rollup mantenuti
- `reports/` per dashboard generate
## Asserzioni ed evidenze strutturate
Le pagine possono includere `claims` nel frontmatter strutturato, non solo testo libero.
Ogni asserzione può includere:
- `id`
- `text`
- `status`
- `confidence`
- `evidence[]`
- `updatedAt`
Le voci di evidenza possono includere:
- `sourceId`
- `path`
- `lines`
- `weight`
- `note`
- `updatedAt`
È questo che fa sì che la wiki si comporti più come un livello di credenze che
come un archivio passivo di note. Le asserzioni possono essere tracciate,
valutate, contestate e ricondotte alle sorgenti.
## Pipeline di compilazione
Il passaggio di compilazione legge le pagine della wiki, normalizza i riepiloghi
ed emette artefatti stabili orientati alle macchine in:
- `.openclaw-wiki/cache/agent-digest.json`
- `.openclaw-wiki/cache/claims.jsonl`
Questi digest esistono affinché gli agent e il codice runtime non debbano fare scraping
delle pagine Markdown.
L'output compilato alimenta anche:
- indicizzazione iniziale della wiki per i flussi di search/get
- lookup degli id delle asserzioni per risalire alle pagine proprietarie
- supplementi compatti per i prompt
- generazione di report/dashboard
## Dashboard e report di stato
Quando `render.createDashboards` è abilitato, la compilazione mantiene le dashboard in `reports/`.
I report integrati includono:
- `reports/open-questions.md`
- `reports/contradictions.md`
- `reports/low-confidence.md`
- `reports/claim-health.md`
- `reports/stale-pages.md`
Questi report tengono traccia di elementi come:
- cluster di note di contraddizione
- cluster di asserzioni concorrenti
- asserzioni prive di evidenze strutturate
- pagine e asserzioni a bassa confidenza
- aggiornamento obsoleto o sconosciuto
- pagine con domande irrisolte
## Ricerca e recupero
`memory-wiki` supporta due backend di ricerca:
- `shared`: usa il flusso di ricerca della memoria condivisa quando disponibile
- `local`: cerca nella wiki localmente
Supporta anche tre corpora:
- `wiki`
- `memory`
- `all`
Comportamento importante:
- `wiki_search` e `wiki_get` usano i digest compilati come primo passaggio quando possibile
- gli id delle asserzioni possono essere ricondotti alla pagina proprietaria
- asserzioni contestate/obsolete/aggiornate influenzano il ranking
- le etichette di provenienza possono essere mantenute nei risultati
Regola pratica:
- usa `memory_search corpus=all` per un singolo passaggio ampio di richiamo
- usa `wiki_search` + `wiki_get` quando ti interessano ranking specifico della wiki,
provenienza o struttura delle credenze a livello di pagina
## Strumenti dell'agente
Il plugin registra questi strumenti:
- `wiki_status`
- `wiki_search`
- `wiki_get`
- `wiki_apply`
- `wiki_lint`
Cosa fanno:
- `wiki_status`: modalità dell'archivio corrente, stato, disponibilità della CLI di Obsidian
- `wiki_search`: cerca nelle pagine wiki e, quando configurato, nei corpora di memoria condivisa
- `wiki_get`: legge una pagina wiki per id/percorso o ripiega sul corpus di memoria condivisa
- `wiki_apply`: mutazioni ristrette di sintesi/metadati senza interventi liberi sulla pagina
- `wiki_lint`: controlli strutturali, lacune di provenienza, contraddizioni, domande aperte
Il plugin registra anche un supplemento di corpus di memoria non esclusivo, così
`memory_search` e `memory_get` condivisi possono raggiungere la wiki quando il plugin di memoria
attivo supporta la selezione del corpus.
## Comportamento di prompt e contesto
Quando `context.includeCompiledDigestPrompt` è abilitato, le sezioni del prompt della memoria
aggiungono uno snapshot compilato compatto da `agent-digest.json`.
Quello snapshot è intenzionalmente piccolo e ad alto segnale:
- solo pagine principali
- solo asserzioni principali
- conteggio delle contraddizioni
- conteggio delle domande
- qualificatori di confidenza/aggiornamento
Questa opzione è facoltativa perché modifica la forma del prompt ed è utile
soprattutto per i motori di contesto o per l'assemblaggio legacy dei prompt che
consumano esplicitamente supplementi di memoria.
## Configurazione
Inserisci la configurazione sotto `plugins.entries.memory-wiki.config`:
```json5
{
plugins: {
entries: {
"memory-wiki": {
enabled: true,
config: {
vaultMode: "isolated",
vault: {
path: "~/.openclaw/wiki/main",
renderMode: "obsidian",
},
obsidian: {
enabled: true,
useOfficialCli: true,
vaultName: "OpenClaw Wiki",
openAfterWrites: false,
},
bridge: {
enabled: false,
readMemoryArtifacts: true,
indexDreamReports: true,
indexDailyNotes: true,
indexMemoryRoot: true,
followMemoryEvents: true,
},
ingest: {
autoCompile: true,
maxConcurrentJobs: 1,
allowUrlIngest: true,
},
search: {
backend: "shared",
corpus: "wiki",
},
context: {
includeCompiledDigestPrompt: false,
},
render: {
preserveHumanBlocks: true,
createBacklinks: true,
createDashboards: true,
},
},
},
},
},
}
```
Interruttori principali:
- `vaultMode`: `isolated`, `bridge`, `unsafe-local`
- `vault.renderMode`: `native` o `obsidian`
- `bridge.readMemoryArtifacts`: importa gli artefatti pubblici del plugin di memoria attivo
- `bridge.followMemoryEvents`: include i log degli eventi in modalità bridge
- `search.backend`: `shared` o `local`
- `search.corpus`: `wiki`, `memory` o `all`
- `context.includeCompiledDigestPrompt`: aggiunge uno snapshot compatto del digest alle sezioni del prompt della memoria
- `render.createBacklinks`: genera blocchi correlati deterministici
- `render.createDashboards`: genera pagine dashboard
## CLI
`memory-wiki` espone anche una superficie CLI di primo livello:
```bash
openclaw wiki status
openclaw wiki doctor
openclaw wiki init
openclaw wiki ingest ./notes/alpha.md
openclaw wiki compile
openclaw wiki lint
openclaw wiki search "alpha"
openclaw wiki get entity.alpha
openclaw wiki apply synthesis "Alpha Summary" --body "..." --source-id source.alpha
openclaw wiki bridge import
openclaw wiki obsidian status
```
Vedi [CLI: wiki](/cli/wiki) per il riferimento completo dei comandi.
## Supporto Obsidian
Quando `vault.renderMode` è impostato su `obsidian`, il plugin scrive Markdown
compatibile con Obsidian e può facoltativamente usare la CLI ufficiale `obsidian`.
I flussi di lavoro supportati includono:
- verifica dello stato
- ricerca nell'archivio
- apertura di una pagina
- invocazione di un comando Obsidian
- salto alla nota giornaliera
Questa opzione è facoltativa. La wiki continua a funzionare in modalità nativa
anche senza Obsidian.
## Flusso di lavoro consigliato
1. Mantieni il tuo plugin di memoria attivo per richiamo/promozione/dreaming.
2. Abilita `memory-wiki`.
3. Inizia con la modalità `isolated` a meno che tu non voglia esplicitamente la modalità bridge.
4. Usa `wiki_search` / `wiki_get` quando la provenienza è importante.
5. Usa `wiki_apply` per sintesi ristrette o aggiornamenti dei metadati.
6. Esegui `wiki_lint` dopo modifiche significative.
7. Attiva le dashboard se vuoi visibilità su contenuti obsoleti/contraddizioni.
## Documentazione correlata
- [Panoramica della memoria](/it/concepts/memory)
- [CLI: memory](/cli/memory)
- [CLI: wiki](/cli/wiki)
- [Panoramica del Plugin SDK](/it/plugins/sdk-overview)

View File

@ -1,33 +1,33 @@
---
read_when:
- Vuoi i modelli GLM in OpenClaw
- Hai bisogno della convenzione di naming dei modelli e del setup
- Vuoi usare i modelli GLM in OpenClaw
- Hai bisogno della convenzione di denominazione dei modelli e della configurazione
summary: Panoramica della famiglia di modelli GLM + come usarla in OpenClaw
title: Modelli GLM
x-i18n:
generated_at: "2026-04-05T14:01:19Z"
generated_at: "2026-04-08T06:00:53Z"
model: gpt-5.4
provider: openai
source_hash: 59622edab5094d991987f9788fbf08b33325e737e7ff88632b0c3ac89412d4c7
source_hash: 79a55acfa139847b4b85dbc09f1068cbd2febb1e49f984a23ea9e3b43bc910eb
source_path: providers/glm.md
workflow: 15
---
# Modelli GLM
GLM è una **famiglia di modelli** (non un'azienda) disponibile tramite la piattaforma Z.AI. In OpenClaw, i modelli
GLM sono accessibili tramite il provider `zai` e ID modello come `zai/glm-5`.
GLM è una **famiglia di modelli** (non un'azienda) disponibile tramite la piattaforma Z.AI. In OpenClaw, i modelli GLM
si usano tramite il provider `zai` e ID modello come `zai/glm-5`.
## Setup CLI
## Configurazione della CLI
```bash
# Setup generico con chiave API e rilevamento automatico dell'endpoint
# Configurazione generica della chiave API con rilevamento automatico dell'endpoint
openclaw onboard --auth-choice zai-api-key
# Coding Plan Global, consigliato per gli utenti Coding Plan
# Piano Coding Global, consigliato per gli utenti di Coding Plan
openclaw onboard --auth-choice zai-coding-global
# Coding Plan CN (regione Cina), consigliato per gli utenti Coding Plan
# Piano Coding CN (regione Cina), consigliato per gli utenti di Coding Plan
openclaw onboard --auth-choice zai-coding-cn
# API generale
@ -37,22 +37,22 @@ openclaw onboard --auth-choice zai-global
openclaw onboard --auth-choice zai-cn
```
## Snippet di configurazione
## Frammento di configurazione
```json5
{
env: { ZAI_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "zai/glm-5" } } },
agents: { defaults: { model: { primary: "zai/glm-5.1" } } },
}
```
`zai-api-key` consente a OpenClaw di rilevare l'endpoint Z.AI corrispondente dalla chiave e
applicare automaticamente il base URL corretto. Usa le scelte regionali esplicite quando
vuoi forzare una specifica superficie Coding Plan o API generale.
applicare automaticamente l'URL di base corretto. Usa le scelte regionali esplicite quando
vuoi forzare una specifica superficie del Piano Coding o dell'API generale.
## Modelli GLM bundled attuali
OpenClaw attualmente inizializza il provider bundled `zai` con questi riferimenti GLM:
OpenClaw attualmente inizializza il provider `zai` bundled con questi riferimenti GLM:
- `glm-5.1`
- `glm-5`
@ -70,6 +70,6 @@ OpenClaw attualmente inizializza il provider bundled `zai` con questi riferiment
## Note
- Le versioni e la disponibilità di GLM possono cambiare; consulta la documentazione di Z.AI per le novità.
- Il riferimento di modello bundled predefinito è `zai/glm-5`.
- Per i dettagli del provider, vedi [/providers/zai](/providers/zai).
- Le versioni e la disponibilità di GLM possono cambiare; controlla la documentazione di Z.AI per le informazioni più aggiornate.
- Il riferimento al modello bundled predefinito è `zai/glm-5.1`.
- Per i dettagli sul provider, vedi [/providers/zai](/it/providers/zai).

View File

@ -1,34 +1,34 @@
---
read_when:
- Vuoi usare modelli Z.AI / GLM in OpenClaw
- Hai bisogno di una semplice configurazione di `ZAI_API_KEY`
- Vuoi usare Z.AI / i modelli GLM in OpenClaw
- Hai bisogno di una semplice configurazione con ZAI_API_KEY
summary: Usare Z.AI (modelli GLM) con OpenClaw
title: Z.AI
x-i18n:
generated_at: "2026-04-05T14:02:36Z"
generated_at: "2026-04-08T06:01:02Z"
model: gpt-5.4
provider: openai
source_hash: 48006cdd580484f0c62e2877b27a6a68d7bc44795b3e97a28213d95182d9acf9
source_hash: 66cbd9813ee28d202dcae34debab1b0cf9927793acb00743c1c62b48d9e381f9
source_path: providers/zai.md
workflow: 15
---
# Z.AI
Z.AI è la piattaforma API per i modelli **GLM**. Fornisce API REST per GLM e usa API key
per l'autenticazione. Crea la tua API key nella console Z.AI. OpenClaw usa il provider `zai`
con una API key Z.AI.
Z.AI è la piattaforma API per i modelli **GLM**. Fornisce API REST per GLM e usa chiavi API
per l'autenticazione. Crea la tua chiave API nella console di Z.AI. OpenClaw usa il provider `zai`
con una chiave API di Z.AI.
## Configurazione CLI
## Configurazione della CLI
```bash
# Configurazione generica con API key e rilevamento automatico dell'endpoint
# Configurazione generica della chiave API con rilevamento automatico dell'endpoint
openclaw onboard --auth-choice zai-api-key
# Coding Plan Global, consigliato per gli utenti Coding Plan
# Piano Coding Global, consigliato per gli utenti di Coding Plan
openclaw onboard --auth-choice zai-coding-global
# Coding Plan CN (regione Cina), consigliato per gli utenti Coding Plan
# Piano Coding CN (regione Cina), consigliato per gli utenti di Coding Plan
openclaw onboard --auth-choice zai-coding-cn
# API generale
@ -38,22 +38,22 @@ openclaw onboard --auth-choice zai-global
openclaw onboard --auth-choice zai-cn
```
## Esempio di configurazione
## Frammento di configurazione
```json5
{
env: { ZAI_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "zai/glm-5" } } },
agents: { defaults: { model: { primary: "zai/glm-5.1" } } },
}
```
`zai-api-key` consente a OpenClaw di rilevare dall'API key l'endpoint Z.AI corrispondente
e applicare automaticamente il `baseUrl` corretto. Usa le scelte regionali esplicite quando
vuoi forzare una specifica superficie Coding Plan o API generale.
`zai-api-key` consente a OpenClaw di rilevare l'endpoint Z.AI corrispondente dalla chiave e
applicare automaticamente l'URL di base corretto. Usa le scelte regionali esplicite quando
vuoi forzare una specifica superficie del Piano Coding o dell'API generale.
## Catalogo GLM incluso
## Catalogo GLM bundled
Attualmente OpenClaw inizializza il provider `zai` incluso con:
OpenClaw attualmente inizializza il provider `zai` bundled con:
- `glm-5.1`
- `glm-5`
@ -72,11 +72,11 @@ Attualmente OpenClaw inizializza il provider `zai` incluso con:
## Note
- I modelli GLM sono disponibili come `zai/<model>` (esempio: `zai/glm-5`).
- Riferimento al modello incluso predefinito: `zai/glm-5`
- Gli id `glm-5*` sconosciuti vengono comunque risolti in inoltro sul percorso del provider incluso
sintetizzando metadati di proprietà del provider a partire dal template `glm-4.7` quando l'id
corrisponde all'attuale struttura della famiglia GLM-5.
- `tool_stream` è abilitato per impostazione predefinita per lo streaming delle tool call Z.AI. Imposta
- Riferimento al modello bundled predefinito: `zai/glm-5.1`
- Gli ID `glm-5*` sconosciuti continuano a essere risolti in inoltro sul percorso del provider bundled
sintetizzando metadati di proprietà del provider dal modello `glm-4.7` quando l'ID
corrisponde alla forma attuale della famiglia GLM-5.
- `tool_stream` è abilitato per impostazione predefinita per lo streaming delle chiamate agli strumenti di Z.AI. Imposta
`agents.defaults.models["zai/<model>"].params.tool_stream` su `false` per disabilitarlo.
- Vedi [/providers/glm](/providers/glm) per la panoramica della famiglia di modelli.
- Z.AI usa autenticazione Bearer con la tua API key.
- Vedi [/providers/glm](/it/providers/glm) per la panoramica della famiglia di modelli.
- Z.AI usa l'autenticazione Bearer con la tua chiave API.

View File

@ -1,91 +1,95 @@
---
x-i18n:
generated_at: "2026-04-08T02:18:14Z"
generated_at: "2026-04-08T06:01:40Z"
model: gpt-5.4
provider: openai
source_hash: 0e156cc8e2fe946a0423862f937754a7caa1fe7e6863b50a80bff49a1c86e1e8
source_hash: 4a9066b2a939c5a9ba69141d75405f0e8097997b523164340e2f0e9a0d5060dd
source_path: refactor/qa.md
workflow: 15
---
# Refactor QA
# Refactor di QA
Stato: migrazione fondamentale completata.
## Obiettivo
Spostare la QA di OpenClaw da un modello a definizione suddivisa a una singola fonte di verità:
Spostare il sistema QA di OpenClaw da un modello a definizione suddivisa a un'unica fonte di verità:
- metadati dello scenario
- metadati degli scenari
- prompt inviati al modello
- setup e teardown
- logica dell'harness
- asserzioni e criteri di successo
- artifact e suggerimenti per il report
- artifact e suggerimenti per i report
Lo stato finale desiderato è un harness QA generico che carica potenti file di definizione degli scenari invece di codificare rigidamente la maggior parte del comportamento in TypeScript.
Lo stato finale desiderato è un harness QA generico che carichi file di definizione degli scenari potenti invece di hardcodare la maggior parte del comportamento in TypeScript.
## Stato attuale
La fonte di verità primaria ora si trova in `qa/scenarios.md`.
La fonte primaria di verità ora si trova in `qa/scenarios/index.md` più un file per
ogni scenario in `qa/scenarios/*.md`.
Implementato:
- `qa/scenarios.md`
- pack QA canonico
- `qa/scenarios/index.md`
- metadati canonici del pacchetto QA
- identità dell'operatore
- missione di kickoff
- missione di avvio
- `qa/scenarios/*.md`
- un file markdown per scenario
- metadati dello scenario
- binding degli handler
- configurazione di esecuzione specifica dello scenario
- `extensions/qa-lab/src/scenario-catalog.ts`
- parser del pack Markdown + validazione zod
- parser del pacchetto markdown + validazione zod
- `extensions/qa-lab/src/qa-agent-bootstrap.ts`
- rendering del piano dal pack Markdown
- rendering del piano dal pacchetto markdown
- `extensions/qa-lab/src/qa-agent-workspace.ts`
- inizializza file di compatibilità generati più `QA_SCENARIOS.md`
- genera file di compatibilità iniziali più `QA_SCENARIOS.md`
- `extensions/qa-lab/src/suite.ts`
- seleziona scenari eseguibili tramite binding degli handler definiti nel Markdown
- Protocollo bus QA + UI
- seleziona gli scenari eseguibili tramite binding degli handler definiti nel markdown
- protocollo QA bus + UI
- allegati inline generici per il rendering di immagini/video/audio/file
Superfici ancora suddivise:
- `extensions/qa-lab/src/suite.ts`
- gestisce ancora la maggior parte della logica eseguibile degli handler personalizzati
- possiede ancora la maggior parte della logica eseguibile degli handler personalizzati
- `extensions/qa-lab/src/report.ts`
- deriva ancora la struttura del report dagli output di runtime
- ricava ancora la struttura del report dagli output di runtime
Quindi la divisione della fonte di verità è stata corretta, ma l'esecuzione è ancora per lo più supportata da handler anziché essere completamente dichiarativa.
Quindi la divisione della fonte di verità è stata risolta, ma l'esecuzione è ancora per lo più basata su handler invece di essere completamente dichiarativa.
## Che aspetto ha realmente la superficie degli scenari
## Come appare davvero la superficie degli scenari
Leggendo la suite attuale si vedono alcune classi distinte di scenari.
Leggere la suite attuale mostra alcune classi distinte di scenari.
### Interazione semplice
- baseline del canale
- baseline DM
- follow-up in thread
- cambio modello
- cambio di modello
- completamento dell'approvazione
- reaction/edit/delete
- reazione/modifica/eliminazione
### Mutazione di configurazione e runtime
### Configurazione e mutazione del runtime
- config patch skill disable
- config apply restart wake-up
- config restart capability flip
- controllo del drift dell'inventario runtime
- patch di config con disabilitazione delle Skills
- config apply con riavvio e wake-up
- inversione della capacità al riavvio della config
- controllo del drift dell'inventario di runtime
### Asserzioni su filesystem e repository
- report di individuazione source/docs
- build Lobster Invaders
- lookup di artifact immagine generata
- report di rilevamento source/docs
- build di Lobster Invaders
- ricerca di artifact di immagini generate
### Orchestrazione della memoria
- memory recall
- richiamo della memoria
- strumenti di memoria nel contesto del canale
- fallback in caso di errore della memoria
- ranking della memoria di sessione
@ -96,56 +100,57 @@ Leggendo la suite attuale si vedono alcune classi distinte di scenari.
- chiamata MCP plugin-tools
- visibilità delle Skills
- installazione a caldo delle skill
- installazione a caldo delle Skills
- generazione nativa di immagini
- roundtrip delle immagini
- comprensione di immagini da allegato
### Multi-turn e multi-attore
### Multi-turno e multi-attore
- handoff a subagent
- handoff del subagent
- sintesi fanout del subagent
- flussi in stile recovery dopo riavvio
- flussi in stile recupero dopo riavvio
Queste categorie sono importanti perché guidano i requisiti della DSL. Un elenco piatto di prompt + testo atteso non è sufficiente.
## Direzione
### Singola fonte di verità
### Unica fonte di verità
Usare `qa/scenarios.md` come fonte di verità creata manualmente.
Usare `qa/scenarios/index.md` più `qa/scenarios/*.md` come fonte di verità
scritta.
Il pack dovrebbe restare:
Il pacchetto deve rimanere:
- leggibile per gli umani in review
- interpretabile dalla macchina
- abbastanza ricco da guidare:
- leggibile dagli umani in review
- analizzabile dalle macchine
- sufficientemente ricco da guidare:
- esecuzione della suite
- bootstrap del workspace QA
- metadati della UI di QA Lab
- prompt di docs/discovery
- generazione del report
- bootstrap dello spazio di lavoro QA
- metadati dell'interfaccia QA Lab
- prompt per documentazione/discovery
- generazione dei report
### Formato di authoring preferito
Usare Markdown come formato di primo livello, con YAML strutturato al suo interno.
Usare markdown come formato di livello superiore, con YAML strutturato al suo interno.
Struttura consigliata:
- YAML frontmatter
- frontmatter YAML
- id
- title
- surface
- tags
- docs refs
- code refs
- riferimenti docs
- riferimenti codice
- override di modello/provider
- prerequisiti
- sezioni in prosa
- objective
- notes
- debugging hints
- blocchi YAML delimitati
- obiettivo
- note
- suggerimenti per il debugging
- blocchi YAML fenced
- setup
- steps
- assertions
@ -153,11 +158,11 @@ Struttura consigliata:
Questo offre:
- migliore leggibilità nelle PR rispetto a grandi file JSON
- contesto più ricco rispetto al puro YAML
- migliore leggibilità nelle PR rispetto a enormi file JSON
- contesto più ricco rispetto al solo YAML
- parsing rigoroso e validazione zod
Il JSON grezzo è accettabile solo come forma intermedia generata.
Il JSON grezzo è accettabile solo come formato intermedio generato.
## Forma proposta del file di scenario
@ -234,7 +239,7 @@ Verify generated media is reattached on the follow-up turn.
## Capacità del runner che la DSL deve coprire
In base alla suite attuale, il runner generico ha bisogno di più della sola esecuzione dei prompt.
In base alla suite attuale, il runner generico ha bisogno di più della semplice esecuzione dei prompt.
### Azioni di ambiente e setup
@ -309,127 +314,128 @@ Esempi dalla suite attuale:
- creare un thread, poi riutilizzare `threadId`
- creare una sessione, poi riutilizzare `sessionKey`
- generare un'immagine, poi allegare il file al turno successivo
- generare una stringa wake marker, poi verificare che compaia più tardi
- generare una stringa marcatore di wake, poi verificare che compaia in seguito
Capacità necessarie:
- `saveAs`
- `${vars.name}`
- `${artifacts.name}`
- riferimenti tipizzati per percorsi, chiavi di sessione, id thread, marker, output dei tool
- riferimenti tipizzati per percorsi, chiavi di sessione, id dei thread, marcatori, output dei tool
Senza supporto per le variabili, l'harness continuerà a far trapelare la logica degli scenari in TypeScript.
Senza supporto per le variabili, l'harness continuerà a far rifluire la logica degli scenari in TypeScript.
## Cosa dovrebbe restare come via di fuga
Un runner completamente dichiarativo puro non è realistico nella fase 1.
Un runner completamente dichiarativo non è realistico nella fase 1.
Alcuni scenari sono intrinsecamente pesanti dal punto di vista dell'orchestrazione:
Alcuni scenari sono intrinsecamente pesanti sul piano dell'orchestrazione:
- sweep di dreaming della memoria
- config apply restart wake-up
- config restart capability flip
- risoluzione dell'artifact immagine generata tramite timestamp/percorso
- config apply con riavvio e wake-up
- inversione della capacità al riavvio della config
- risoluzione dell'artifact di immagine generato per timestamp/percorso
- valutazione del discovery-report
Per ora questi dovrebbero usare handler personalizzati espliciti.
Per ora, questi dovrebbero usare handler personalizzati espliciti.
Regola consigliata:
- 85-90% dichiarativo
- step `customHandler` espliciti per il resto più difficile
- solo custom handler con nome e documentati
- passaggi `customHandler` espliciti per la parte restante più difficile
- solo handler personalizzati nominati e documentati
- nessun codice inline anonimo nel file di scenario
Questo mantiene pulito il motore generico pur consentendo di progredire.
Questo mantiene pulito il motore generico pur consentendo comunque progressi.
## Cambio architetturale
## Cambiamento architetturale
### Attuale
Il Markdown degli scenari è già la fonte di verità per:
Il markdown degli scenari è già la fonte di verità per:
- esecuzione della suite
- file di bootstrap del workspace
- catalogo degli scenari della UI di QA Lab
- metadati del report
- file bootstrap dello spazio di lavoro
- catalogo degli scenari dell'interfaccia QA Lab
- metadati dei report
- prompt di discovery
Compatibilità generata:
- il workspace inizializzato include ancora `QA_KICKOFF_TASK.md`
- il workspace inizializzato include ancora `QA_SCENARIO_PLAN.md`
- il workspace inizializzato ora include anche `QA_SCENARIOS.md`
- lo spazio di lavoro inizializzato include ancora `QA_KICKOFF_TASK.md`
- lo spazio di lavoro inizializzato include ancora `QA_SCENARIO_PLAN.md`
- lo spazio di lavoro inizializzato ora include anche `QA_SCENARIOS.md`
## Piano di refactor
### Fase 1: loader e schema
Completata.
Fatto.
- aggiunto `qa/scenarios.md`
- aggiunto parser per contenuti pack YAML Markdown con nome
- aggiunto `qa/scenarios/index.md`
- suddivisi gli scenari in `qa/scenarios/*.md`
- aggiunto il parser per il contenuto YAML markdown nominato del pacchetto
- validato con zod
- passati i consumer al pack parsato
- rimossi `qa/seed-scenarios.json` e `qa/QA_KICKOFF_TASK.md` a livello repository
- passati i consumer al pacchetto analizzato
- rimossi `qa/seed-scenarios.json` e `qa/QA_KICKOFF_TASK.md` a livello di repository
### Fase 2: motore generico
- dividere `extensions/qa-lab/src/suite.ts` in:
- suddividere `extensions/qa-lab/src/suite.ts` in:
- loader
- motore
- registro delle azioni
- registro delle asserzioni
- custom handler
- registry delle azioni
- registry delle asserzioni
- handler personalizzati
- mantenere le funzioni helper esistenti come operazioni del motore
Deliverable:
- il motore esegue scenari dichiarativi semplici
Iniziare con scenari che sono per lo più prompt + attesa + asserzione:
Iniziare con scenari che sono soprattutto prompt + attesa + asserzione:
- follow-up in thread
- comprensione di immagini da allegato
- visibilità e invocazione delle skill
- visibilità e invocazione delle Skills
- baseline del canale
Deliverable:
- primi veri scenari definiti in Markdown distribuiti tramite il motore generico
- primi scenari reali definiti nel markdown distribuiti tramite il motore generico
### Fase 4: migrare scenari di media complessità
- roundtrip di generazione immagini
- roundtrip di generazione di immagini
- strumenti di memoria nel contesto del canale
- ranking della memoria di sessione
- handoff a subagent
- handoff del subagent
- sintesi fanout del subagent
Deliverable:
- variabili, artifact, asserzioni sui tool, asserzioni sui request log verificati nella pratica
- variabili, artifact, asserzioni sui tool e asserzioni sul request log verificati nella pratica
### Fase 5: mantenere gli scenari difficili su custom handler
### Fase 5: mantenere gli scenari difficili su handler personalizzati
- sweep di dreaming della memoria
- config apply restart wake-up
- config restart capability flip
- runtime inventory drift
- config apply con riavvio e wake-up
- inversione della capacità al riavvio della config
- drift dell'inventario di runtime
Deliverable:
- stesso formato di authoring, ma con blocchi di step personalizzati espliciti dove necessario
- stesso formato di authoring, ma con blocchi di passaggi personalizzati espliciti dove necessario
### Fase 6: eliminare la mappa degli scenari hardcoded
Quando la copertura del pack sarà abbastanza buona:
Quando la copertura del pacchetto sarà sufficientemente buona:
- rimuovere la maggior parte del branching TypeScript specifico per scenario da `extensions/qa-lab/src/suite.ts`
- rimuovere la maggior parte della logica TypeScript specifica per scenario da `extensions/qa-lab/src/suite.ts`
## Supporto Fake Slack / Rich Media
L'attuale bus QA è incentrato sul testo.
L'attuale QA bus è orientato principalmente al testo.
File rilevanti:
@ -439,17 +445,17 @@ File rilevanti:
- `extensions/qa-lab/src/bus-server.ts`
- `extensions/qa-lab/web/src/ui-render.ts`
Oggi il bus QA supporta:
Oggi il QA bus supporta:
- testo
- reaction
- reazioni
- thread
Non modella ancora allegati media inline.
Non modella ancora gli allegati multimediali inline.
### Contratto di transport necessario
### Contratto di trasporto necessario
Aggiungere un modello generico di allegato per il bus QA:
Aggiungere un modello generico di allegato QA bus:
```ts
type QaBusAttachment = {
@ -474,61 +480,61 @@ Poi aggiungere `attachments?: QaBusAttachment[]` a:
- `QaBusInboundMessageInput`
- `QaBusOutboundMessageInput`
### Perché prima un approccio generico
### Perché prima il generico
Non costruire un modello media solo per Slack.
Invece:
- un unico modello di transport QA generico
- più renderer sopra di esso
- l'attuale chat di QA Lab
- il futuro fake Slack web
- qualsiasi altra vista di fake transport
- un unico modello di trasporto QA generico
- più renderer costruiti sopra di esso
- chat attuale di QA Lab
- futuro fake Slack web
- qualsiasi altra vista di trasporto fittizio
Questo evita logica duplicata e consente agli scenari media di restare indipendenti dal transport.
Questo evita la logica duplicata e permette agli scenari multimediali di restare agnostici rispetto al trasporto.
### Lavoro UI necessario
Aggiornare la UI QA per renderizzare:
Aggiornare l'interfaccia QA per renderizzare:
- anteprima immagine inline
- player audio inline
- player video inline
- chip allegato file
- chip per allegato file
L'attuale UI può già renderizzare thread e reaction, quindi il rendering degli allegati dovrebbe sovrapporsi allo stesso modello di card dei messaggi.
L'interfaccia attuale può già renderizzare thread e reazioni, quindi il rendering degli allegati dovrebbe stratificarsi sullo stesso modello di scheda messaggio.
### Lavoro sugli scenari abilitato dal transport media
### Lavoro sugli scenari abilitato dal trasporto media
Una volta che gli allegati passano attraverso il bus QA, possiamo aggiungere scenari fake-chat più ricchi:
Una volta che gli allegati fluiscono attraverso il QA bus, possiamo aggiungere scenari fake-chat più ricchi:
- reply con immagine inline in fake Slack
- risposta con immagine inline in fake Slack
- comprensione di allegati audio
- comprensione di allegati video
- ordinamento misto degli allegati
- reply in thread con media mantenuti
- risposta in thread con media mantenuti
## Raccomandazione
Il prossimo blocco di implementazione dovrebbe essere:
1. aggiungere loader di scenari Markdown + schema zod
2. generare il catalogo attuale dal Markdown
1. aggiungere loader degli scenari markdown + schema zod
2. generare il catalogo attuale dal markdown
3. migrare prima alcuni scenari semplici
4. aggiungere supporto generico agli allegati del bus QA
5. renderizzare immagini inline nella UI QA
6. poi espandere ad audio e video
4. aggiungere supporto generico agli allegati QA bus
5. renderizzare immagini inline nell'interfaccia QA
6. poi estendere ad audio e video
Questo è il percorso più piccolo che dimostra entrambi gli obiettivi:
- QA generica definita in Markdown
- superfici di messaggistica simulata più ricche
- QA generico definito nel markdown
- superfici di messaggistica fittizia più ricche
## Domande aperte
## Questioni aperte
- se i file di scenario debbano consentire template di prompt Markdown incorporati con interpolazione di variabili
- se i file di scenario debbano consentire template di prompt markdown incorporati con interpolazione di variabili
- se setup/cleanup debbano essere sezioni nominate o semplicemente elenchi ordinati di azioni
- se i riferimenti agli artifact debbano essere fortemente tipizzati nello schema o basati su stringhe
- se i custom handler debbano vivere in un unico registro o in registri per superficie
- se gli handler personalizzati debbano risiedere in un unico registry o in registry per superficie
- se il file di compatibilità JSON generato debba restare versionato durante la migrazione

View File

@ -1,14 +1,14 @@
---
read_when:
- Uso o configurazione dei comandi chat
- Debug dell'instradamento dei comandi o dei permessi
- Usare o configurare i comandi di chat
- Eseguire il debug dell'instradamento dei comandi o delle autorizzazioni
summary: 'Comandi slash: testo vs nativi, configurazione e comandi supportati'
title: Comandi slash
title: Comandi Slash
x-i18n:
generated_at: "2026-04-06T03:13:56Z"
generated_at: "2026-04-08T06:01:59Z"
model: gpt-5.4
provider: openai
source_hash: 417e35b9ddd87f25f6c019111b55b741046ea11039dde89210948185ced5696d
source_hash: 4a7ee7f1a8012058279b9e632889b291d4e659e4ec81209ca8978afbb9ad4b96
source_path: tools/slash-commands.md
workflow: 15
---
@ -16,17 +16,17 @@ x-i18n:
# Comandi slash
I comandi sono gestiti dal Gateway. La maggior parte dei comandi deve essere inviata come messaggio **autonomo** che inizia con `/`.
Il comando chat bash solo host usa `! <cmd>` (con `/bash <cmd>` come alias).
Il comando bash di chat solo host usa `! <cmd>` (con `/bash <cmd>` come alias).
Esistono due sistemi correlati:
- **Comandi**: messaggi autonomi `/...`.
- **Comandi**: messaggi `/...` autonomi.
- **Direttive**: `/think`, `/fast`, `/verbose`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
- Le direttive vengono rimosse dal messaggio prima che il modello lo veda.
- Nei normali messaggi di chat (non composti solo da direttive), vengono trattate come “suggerimenti inline” e **non** rendono persistenti le impostazioni della sessione.
- Nei messaggi composti solo da direttive (il messaggio contiene solo direttive), diventano persistenti per la sessione e rispondono con una conferma.
- Le direttive vengono applicate solo per i **mittenti autorizzati**. Se `commands.allowFrom` è impostato, è l'unica
allowlist usata; altrimenti l'autorizzazione deriva dalle allowlist/pairing del canale più `commands.useAccessGroups`.
- Nei messaggi composti solo da direttive (il messaggio contiene solo direttive), rendono persistenti le impostazioni nella sessione e rispondono con una conferma.
- Le direttive vengono applicate solo ai **mittenti autorizzati**. Se `commands.allowFrom` è impostato, è l'unica
allowlist usata; altrimenti l'autorizzazione deriva dalle allowlist del canale/dall'abbinamento più `commands.useAccessGroups`.
I mittenti non autorizzati vedono le direttive trattate come testo normale.
Esistono anche alcune **scorciatoie inline** (solo per mittenti in allowlist/autorizzati): `/help`, `/commands`, `/status`, `/whoami` (`/id`).
@ -46,7 +46,10 @@ Vengono eseguite immediatamente, vengono rimosse prima che il modello veda il me
mcp: false,
plugins: false,
debug: false,
restart: false,
restart: true,
ownerAllowFrom: ["discord:123456789012345678"],
ownerDisplay: "raw",
ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
allowFrom: {
"*": ["user1"],
discord: ["user:123"],
@ -56,143 +59,179 @@ Vengono eseguite immediatamente, vengono rimosse prima che il modello veda il me
}
```
- `commands.text` (predefinito `true`) abilita il parsing di `/...` nei messaggi chat.
- Sulle superfici senza comandi nativi (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), i comandi testuali continuano a funzionare anche se imposti questo valore su `false`.
- `commands.text` (predefinito `true`) abilita il parsing di `/...` nei messaggi di chat.
- Nelle superfici senza comandi nativi (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), i comandi testuali continuano a funzionare anche se imposti questo valore su `false`.
- `commands.native` (predefinito `"auto"`) registra i comandi nativi.
- Auto: attivo per Discord/Telegram; disattivo per Slack (finché non aggiungi slash command); ignorato per i provider senza supporto nativo.
- Imposta `channels.discord.commands.native`, `channels.telegram.commands.native` o `channels.slack.commands.native` per fare override per provider (bool o `"auto"`).
- `false` cancella i comandi registrati in precedenza su Discord/Telegram all'avvio. I comandi Slack sono gestiti nell'app Slack e non vengono rimossi automaticamente.
- `commands.nativeSkills` (predefinito `"auto"`) registra i comandi **Skill** in modo nativo quando supportato.
- Auto: attivo per Discord/Telegram; disattivo per Slack (Slack richiede la creazione di uno slash command per ogni Skill).
- Imposta `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` o `channels.slack.commands.nativeSkills` per fare override per provider (bool o `"auto"`).
- `commands.bash` (predefinito `false`) abilita `! <cmd>` per eseguire comandi shell host (`/bash <cmd>` è un alias; richiede allowlist `tools.elevated`).
- `commands.bashForegroundMs` (predefinito `2000`) controlla per quanto tempo bash attende prima di passare alla modalità background (`0` manda subito in background).
- Auto: attivo per Discord/Telegram; disattivo per Slack (finché non aggiungi i comandi slash); ignorato per i provider senza supporto nativo.
- Imposta `channels.discord.commands.native`, `channels.telegram.commands.native` o `channels.slack.commands.native` per eseguire un override per provider (bool o `"auto"`).
- `false` cancella all'avvio i comandi registrati in precedenza su Discord/Telegram. I comandi Slack sono gestiti nell'app Slack e non vengono rimossi automaticamente.
- `commands.nativeSkills` (predefinito `"auto"`) registra in modo nativo i comandi **Skill** quando supportati.
- Auto: attivo per Discord/Telegram; disattivo per Slack (Slack richiede la creazione di un comando slash per ogni skill).
- Imposta `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` o `channels.slack.commands.nativeSkills` per eseguire un override per provider (bool o `"auto"`).
- `commands.bash` (predefinito `false`) abilita `! <cmd>` per eseguire comandi shell sull'host (`/bash <cmd>` è un alias; richiede le allowlist di `tools.elevated`).
- `commands.bashForegroundMs` (predefinito `2000`) controlla per quanto tempo bash attende prima di passare alla modalità in background (`0` manda immediatamente in background).
- `commands.config` (predefinito `false`) abilita `/config` (legge/scrive `openclaw.json`).
- `commands.mcp` (predefinito `false`) abilita `/mcp` (legge/scrive la configurazione MCP gestita da OpenClaw sotto `mcp.servers`).
- `commands.plugins` (predefinito `false`) abilita `/plugins` (discovery/stato dei plugin più controlli di installazione + abilitazione/disabilitazione).
- `commands.plugins` (predefinito `false`) abilita `/plugins` (rilevamento/stato dei plugin più controlli di installazione + abilitazione/disabilitazione).
- `commands.debug` (predefinito `false`) abilita `/debug` (override solo runtime).
- `commands.allowFrom` (opzionale) imposta una allowlist per provider per l'autorizzazione ai comandi. Quando è configurata, è l'unica origine di autorizzazione per comandi e direttive (le allowlist/pairing del canale e `commands.useAccessGroups`
vengono ignorati). Usa `"*"` come valore predefinito globale; le chiavi specifiche del provider lo sovrascrivono.
- `commands.useAccessGroups` (predefinito `true`) applica allowlist/policy per i comandi quando `commands.allowFrom` non è impostato.
- `commands.restart` (predefinito `true`) abilita `/restart` più le azioni degli strumenti di riavvio del gateway.
- `commands.ownerAllowFrom` (opzionale) imposta la allowlist esplicita del proprietario per le superfici di comandi/strumenti riservate al proprietario. È separata da `commands.allowFrom`.
- `commands.ownerDisplay` controlla come gli ID proprietario compaiono nel prompt di sistema: `raw` o `hash`.
- `commands.ownerDisplaySecret` imposta facoltativamente il segreto HMAC usato quando `commands.ownerDisplay="hash"`.
- `commands.allowFrom` (opzionale) imposta una allowlist per provider per l'autorizzazione dei comandi. Quando configurata, è l'unica
fonte di autorizzazione per comandi e direttive (le allowlist del canale/l'abbinamento e `commands.useAccessGroups`
vengono ignorati). Usa `"*"` per un valore predefinito globale; le chiavi specifiche del provider lo sovrascrivono.
- `commands.useAccessGroups` (predefinito `true`) applica allowlist/policy ai comandi quando `commands.allowFrom` non è impostato.
## Elenco dei comandi
Testo + nativi (quando abilitati):
Fonte di verità attuale:
- `/help`
- `/commands`
- `/tools [compact|verbose]` (mostra cosa l'agent corrente può usare in questo momento; `verbose` aggiunge descrizioni)
- `/skill <name> [input]` (esegue una Skill per nome)
- `/status` (mostra lo stato corrente; include utilizzo/quota del provider per il provider del modello corrente quando disponibile)
- `/tasks` (elenca le attività in background per la sessione corrente; mostra dettagli delle attività attive e recenti con conteggi di fallback locali all'agent)
- `/allowlist` (elenca/aggiunge/rimuove voci di allowlist)
- `/approve <id> <decision>` (risolve i prompt di approvazione exec; usa il messaggio di approvazione in sospeso per le decisioni disponibili)
- `/context [list|detail|json]` (spiega il “contesto”; `detail` mostra dimensioni per file + per strumento + per Skill + prompt di sistema)
- `/btw <question>` (fa una domanda laterale effimera sulla sessione corrente senza modificare il contesto futuro della sessione; consulta [/tools/btw](/it/tools/btw))
- `/export-session [path]` (alias: `/export`) (esporta la sessione corrente in HTML con il prompt di sistema completo)
- `/whoami` (mostra il tuo sender id; alias: `/id`)
- `/session idle <duration|off>` (gestisce il disallineamento automatico per inattività per i binding dei thread focalizzati)
- `/session max-age <duration|off>` (gestisce il disallineamento automatico hard max-age per i binding dei thread focalizzati)
- `/subagents list|kill|log|info|send|steer|spawn` (ispeziona, controlla o avvia esecuzioni di sub-agent per la sessione corrente)
- `/acp spawn|cancel|steer|close|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|sessions` (ispeziona e controlla le sessioni runtime ACP)
- `/agents` (elenca gli agent associati ai thread per questa sessione)
- `/focus <target>` (Discord: associa questo thread, o un nuovo thread, a una destinazione session/subagent)
- `/unfocus` (Discord: rimuove l'associazione corrente del thread)
- `/kill <id|#|all>` (interrompe immediatamente uno o tutti i sub-agent in esecuzione per questa sessione; nessun messaggio di conferma)
- `/steer <id|#> <message>` (indirizza immediatamente un sub-agent in esecuzione: durante l'esecuzione quando possibile, altrimenti interrompe il lavoro corrente e riavvia sul messaggio di indirizzamento)
- `/tell <id|#> <message>` (alias per `/steer`)
- `/config show|get|set|unset` (rende persistente la configurazione su disco, solo proprietario; richiede `commands.config: true`)
- `/mcp show|get|set|unset` (gestisce la configurazione del server MCP OpenClaw, solo proprietario; richiede `commands.mcp: true`)
- `/plugins list|show|get|install|enable|disable` (ispeziona i plugin rilevati, installa nuovi plugin e attiva/disattiva l'abilitazione; solo proprietario per le scritture; richiede `commands.plugins: true`)
- `/plugin` è un alias per `/plugins`.
- `/plugin install <spec>` accetta le stesse specifiche di plugin di `openclaw plugins install`: percorso locale/archivio, pacchetto npm o `clawhub:<pkg>`.
- Le scritture di abilitazione/disabilitazione rispondono comunque con un suggerimento di riavvio. Su un gateway foreground monitorato, OpenClaw può eseguire automaticamente quel riavvio subito dopo la scrittura.
- `/debug show|set|unset|reset` (override runtime, solo proprietario; richiede `commands.debug: true`)
- `/usage off|tokens|full|cost` (footer di utilizzo per risposta o riepilogo locale dei costi)
- `/tts off|always|inbound|tagged|status|provider|limit|summary|audio` (controlla TTS; consulta [/tts](/it/tools/tts))
- Discord: il comando nativo è `/voice` (Discord riserva `/tts`); il testo `/tts` continua a funzionare.
- `/stop`
- `/restart`
- `/dock-telegram` (alias: `/dock_telegram`) (sposta le risposte su Telegram)
- `/dock-discord` (alias: `/dock_discord`) (sposta le risposte su Discord)
- `/dock-slack` (alias: `/dock_slack`) (sposta le risposte su Slack)
- `/activation mention|always` (solo gruppi)
- `/send on|off|inherit` (solo proprietario)
- `/reset` o `/new [model]` (suggerimento modello opzionale; il resto viene inoltrato)
- `/think <off|minimal|low|medium|high|xhigh>` (scelte dinamiche per modello/provider; alias: `/thinking`, `/t`)
- `/fast status|on|off` (omettere l'argomento mostra lo stato effettivo corrente della modalità fast)
- `/verbose on|full|off` (alias: `/v`)
- `/reasoning on|off|stream` (alias: `/reason`; quando è attivo, invia un messaggio separato prefissato `Reasoning:`; `stream` = solo bozza Telegram)
- `/elevated on|off|ask|full` (alias: `/elev`; `full` salta le approvazioni exec)
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` (invia `/exec` per mostrare il valore corrente)
- `/model <name>` (alias: `/models`; oppure `/<alias>` da `agents.defaults.models.*.alias`)
- `/queue <mode>` (più opzioni come `debounce:2s cap:25 drop:summarize`; invia `/queue` per vedere le impostazioni correnti)
- `/bash <command>` (solo host; alias per `! <command>`; richiede `commands.bash: true` + allowlist `tools.elevated`)
- `/dreaming [on|off|status|help]` (attiva/disattiva dreaming globale o mostra lo stato; consulta [Dreaming](/concepts/dreaming))
- i built-in core provengono da `src/auto-reply/commands-registry.shared.ts`
- i comandi dock generati provengono da `src/auto-reply/commands-registry.data.ts`
- i comandi dei plugin provengono dalle chiamate `registerCommand()` dei plugin
- la disponibilità effettiva sul tuo gateway dipende comunque dai flag di configurazione, dalla superficie del canale e dai plugin installati/abilitati
Solo testo:
### Comandi built-in core
- `/compact [instructions]` (consulta [/concepts/compaction](/it/concepts/compaction))
- `! <command>` (solo host; uno alla volta; usa `!poll` + `!stop` per job di lunga durata)
- `!poll` (controlla output / stato; accetta `sessionId` opzionale; funziona anche `/bash poll`)
- `!stop` (interrompe il job bash in esecuzione; accetta `sessionId` opzionale; funziona anche `/bash stop`)
Comandi built-in disponibili oggi:
- `/new [model]` avvia una nuova sessione; `/reset` è l'alias di reset.
- `/compact [instructions]` compatta il contesto della sessione. Vedi [/concepts/compaction](/it/concepts/compaction).
- `/stop` interrompe l'esecuzione corrente.
- `/session idle <duration|off>` e `/session max-age <duration|off>` gestiscono la scadenza del binding del thread.
- `/think <off|minimal|low|medium|high|xhigh>` imposta il livello di thinking. Alias: `/thinking`, `/t`.
- `/verbose on|off|full` attiva/disattiva l'output verboso. Alias: `/v`.
- `/fast [status|on|off]` mostra o imposta la modalità veloce.
- `/reasoning [on|off|stream]` attiva/disattiva la visibilità del reasoning. Alias: `/reason`.
- `/elevated [on|off|ask|full]` attiva/disattiva la modalità elevata. Alias: `/elev`.
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` mostra o imposta i valori predefiniti di exec.
- `/model [name|#|status]` mostra o imposta il modello.
- `/models [provider] [page] [limit=<n>|size=<n>|all]` elenca i provider o i modelli di un provider.
- `/queue <mode>` gestisce il comportamento della coda (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) più opzioni come `debounce:2s cap:25 drop:summarize`.
- `/help` mostra il riepilogo breve della guida.
- `/commands` mostra il catalogo dei comandi generato.
- `/tools [compact|verbose]` mostra cosa può usare in questo momento l'agente corrente.
- `/status` mostra lo stato del runtime, incluso l'uso/quota del provider quando disponibile.
- `/tasks` elenca le attività in background attive/recenti per la sessione corrente.
- `/context [list|detail|json]` spiega come viene assemblato il contesto.
- `/export-session [path]` esporta la sessione corrente in HTML. Alias: `/export`.
- `/whoami` mostra il tuo ID mittente. Alias: `/id`.
- `/skill <name> [input]` esegue una skill per nome.
- `/allowlist [list|add|remove] ...` gestisce le voci della allowlist. Solo testo.
- `/approve <id> <decision>` risolve le richieste di approvazione exec.
- `/btw <question>` pone una domanda laterale senza modificare il contesto futuro della sessione. Vedi [/tools/btw](/it/tools/btw).
- `/subagents list|kill|log|info|send|steer|spawn` gestisce le esecuzioni dei sub-agent per la sessione corrente.
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` gestisce le sessioni ACP e le opzioni del runtime.
- `/focus <target>` collega il thread Discord corrente o il topic/conversation Telegram a un target di sessione.
- `/unfocus` rimuove il binding corrente.
- `/agents` elenca gli agenti collegati al thread per la sessione corrente.
- `/kill <id|#|all>` interrompe uno o tutti i sub-agent in esecuzione.
- `/steer <id|#> <message>` invia indicazioni a un sub-agent in esecuzione. Alias: `/tell`.
- `/config show|get|set|unset` legge o scrive `openclaw.json`. Solo proprietario. Richiede `commands.config: true`.
- `/mcp show|get|set|unset` legge o scrive la configurazione del server MCP gestita da OpenClaw sotto `mcp.servers`. Solo proprietario. Richiede `commands.mcp: true`.
- `/plugins list|inspect|show|get|install|enable|disable` ispeziona o modifica lo stato dei plugin. `/plugin` è un alias. Solo proprietario per le scritture. Richiede `commands.plugins: true`.
- `/debug show|set|unset|reset` gestisce gli override di configurazione solo runtime. Solo proprietario. Richiede `commands.debug: true`.
- `/usage off|tokens|full|cost` controlla il piè di pagina di utilizzo per risposta oppure stampa un riepilogo locale dei costi.
- `/tts on|off|status|provider|limit|summary|audio|help` controlla TTS. Vedi [/tools/tts](/it/tools/tts).
- `/restart` riavvia OpenClaw quando abilitato. Predefinito: abilitato; imposta `commands.restart: false` per disabilitarlo.
- `/activation mention|always` imposta la modalità di attivazione del gruppo.
- `/send on|off|inherit` imposta la policy di invio. Solo proprietario.
- `/bash <command>` esegue un comando shell sull'host. Solo testo. Alias: `! <command>`. Richiede `commands.bash: true` più le allowlist di `tools.elevated`.
- `!poll [sessionId]` controlla un job bash in background.
- `!stop [sessionId]` arresta un job bash in background.
### Comandi dock generati
I comandi dock vengono generati dai plugin canale con supporto per i comandi nativi. Set bundled attuale:
- `/dock-discord` (alias: `/dock_discord`)
- `/dock-mattermost` (alias: `/dock_mattermost`)
- `/dock-slack` (alias: `/dock_slack`)
- `/dock-telegram` (alias: `/dock_telegram`)
### Comandi dei plugin bundled
I plugin bundled possono aggiungere altri comandi slash. Comandi bundled attuali in questo repo:
- `/dreaming [on|off|status|help]` attiva/disattiva il memory dreaming. Vedi [Dreaming](/it/concepts/dreaming).
- `/pair [qr|status|pending|approve|cleanup|notify]` gestisce il flusso di abbinamento/configurazione del dispositivo. Vedi [Pairing](/it/channels/pairing).
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` abilita temporaneamente i comandi del nodo telefono ad alto rischio.
- `/voice status|list [limit]|set <voiceId|name>` gestisce la configurazione della voce Talk. Su Discord, il nome del comando nativo è `/talkvoice`.
- `/card ...` invia preset di rich card LINE. Vedi [LINE](/it/channels/line).
- Comandi solo QQBot:
- `/bot-ping`
- `/bot-version`
- `/bot-help`
- `/bot-upgrade`
- `/bot-logs`
### Comandi skill dinamici
Le skill invocabili dall'utente sono esposte anche come comandi slash:
- `/skill <name> [input]` funziona sempre come entrypoint generico.
- le skill possono anche comparire come comandi diretti come `/prose` quando la skill/il plugin li registra.
- la registrazione nativa dei comandi skill è controllata da `commands.nativeSkills` e `channels.<provider>.commands.nativeSkills`.
Note:
- I comandi accettano un `:` opzionale tra comando e argomenti (ad esempio `/think: high`, `/send: on`, `/help:`).
- `/new <model>` accetta un alias modello, `provider/model` o un nome provider (corrispondenza fuzzy); se non c'è corrispondenza, il testo viene trattato come corpo del messaggio.
- Per il dettaglio completo dell'utilizzo per provider, usa `openclaw status --usage`.
- I comandi accettano un `:` facoltativo tra il comando e gli argomenti (ad esempio `/think: high`, `/send: on`, `/help:`).
- `/new <model>` accetta un alias di modello, `provider/model` o un nome provider (corrispondenza fuzzy); se non c'è corrispondenza, il testo viene trattato come corpo del messaggio.
- Per il dettaglio completo dell'utilizzo del provider, usa `openclaw status --usage`.
- `/allowlist add|remove` richiede `commands.config=true` e rispetta `configWrites` del canale.
- Nei canali multi-account, anche `/allowlist --account <id>` con target di configurazione e `/config set channels.<provider>.accounts.<id>...` rispettano `configWrites` dell'account di destinazione.
- `/usage` controlla il footer di utilizzo per risposta; `/usage cost` stampa un riepilogo locale dei costi dai log di sessione OpenClaw.
- Nei canali multi-account, anche `/allowlist --account <id>` mirato alla configurazione e `/config set channels.<provider>.accounts.<id>...` rispettano `configWrites` dell'account di destinazione.
- `/usage` controlla il piè di pagina di utilizzo per risposta; `/usage cost` stampa un riepilogo locale dei costi dai log di sessione OpenClaw.
- `/restart` è abilitato per impostazione predefinita; imposta `commands.restart: false` per disabilitarlo.
- `/plugins install <spec>` accetta le stesse specifiche di plugin di `openclaw plugins install`: percorso/archivio locale, pacchetto npm o `clawhub:<pkg>`.
- `/plugins enable|disable` aggiorna la configurazione del plugin e può richiedere un riavvio.
- Comando nativo solo Discord: `/vc join|leave|status` controlla i canali vocali (richiede `channels.discord.voice` e comandi nativi; non disponibile come testo).
- I comandi di binding dei thread Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) richiedono che i binding effettivi dei thread siano abilitati (`session.threadBindings.enabled` e/o `channels.discord.threadBindings.enabled`).
- Riferimento dei comandi ACP e comportamento runtime: [ACP Agents](/it/tools/acp-agents).
- `/verbose` è pensato per il debug e per una visibilità aggiuntiva; mantienilo **disattivato** nell'uso normale.
- `/fast on|off` rende persistente un override di sessione. Usa l'opzione `inherit` nell'interfaccia Sessions per cancellarlo e tornare ai valori predefiniti della configurazione.
- `/fast` è specifico del provider: OpenAI/OpenAI Codex lo mappano a `service_tier=priority` sugli endpoint nativi Responses, mentre le richieste Anthropic pubbliche dirette, incluso il traffico autenticato OAuth inviato a `api.anthropic.com`, lo mappano a `service_tier=auto` o `standard_only`. Consulta [OpenAI](/it/providers/openai) e [Anthropic](/it/providers/anthropic).
- I riepiloghi dei guasti degli strumenti vengono comunque mostrati quando rilevanti, ma il testo dettagliato del guasto viene incluso solo quando `/verbose` è `on` o `full`.
- I comandi di binding del thread Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) richiedono che i binding del thread effettivi siano abilitati (`session.threadBindings.enabled` e/o `channels.discord.threadBindings.enabled`).
- Riferimento dei comandi ACP e comportamento del runtime: [ACP Agents](/it/tools/acp-agents).
- `/verbose` è pensato per il debug e per una visibilità aggiuntiva; tienilo **off** nell'uso normale.
- `/fast on|off` rende persistente un override della sessione. Usa l'opzione `inherit` dell'interfaccia Sessions per cancellarlo e tornare ai valori predefiniti della configurazione.
- `/fast` è specifico del provider: OpenAI/OpenAI Codex lo mappano a `service_tier=priority` sugli endpoint nativi Responses, mentre le richieste Anthropic pubbliche dirette, incluso il traffico autenticato OAuth inviato a `api.anthropic.com`, lo mappano a `service_tier=auto` o `standard_only`. Vedi [OpenAI](/it/providers/openai) e [Anthropic](/it/providers/anthropic).
- I riepiloghi degli errori degli strumenti vengono comunque mostrati quando pertinenti, ma il testo dettagliato dell'errore viene incluso solo quando `/verbose` è `on` o `full`.
- `/reasoning` (e `/verbose`) sono rischiosi in contesti di gruppo: possono rivelare reasoning interno o output degli strumenti che non intendevi esporre. È preferibile lasciarli disattivati, soprattutto nelle chat di gruppo.
- `/model` rende persistente immediatamente il nuovo modello di sessione.
- Se l'agent è inattivo, l'esecuzione successiva lo usa subito.
- Se è già attiva un'esecuzione, OpenClaw contrassegna un cambio live come in sospeso e riavvia nel nuovo modello solo in un punto di retry pulito.
- Se è già iniziata l'attività degli strumenti o l'output della risposta, il cambio in sospeso può restare in coda fino a una successiva opportunità di retry o al turno utente successivo.
- `/model` rende immediatamente persistente il nuovo modello di sessione.
- Se l'agente è inattivo, la prossima esecuzione lo usa subito.
- Se un'esecuzione è già attiva, OpenClaw contrassegna un cambio live come in sospeso e riavvia nel nuovo modello solo in un punto di retry pulito.
- Se l'attività degli strumenti o l'output della risposta sono già iniziati, il cambio in sospeso può restare in coda fino a una successiva opportunità di retry o al turno utente successivo.
- **Percorso rapido:** i messaggi composti solo da comandi provenienti da mittenti in allowlist vengono gestiti immediatamente (saltano coda + modello).
- **Controllo delle menzioni nei gruppi:** i messaggi composti solo da comandi provenienti da mittenti in allowlist bypassano i requisiti di menzione.
- **Scorciatoie inline (solo mittenti in allowlist):** alcuni comandi funzionano anche quando sono incorporati in un normale messaggio e vengono rimossi prima che il modello veda il testo rimanente.
- **Blocco per menzione nei gruppi:** i messaggi composti solo da comandi provenienti da mittenti in allowlist saltano i requisiti di menzione.
- **Scorciatoie inline (solo mittenti in allowlist):** alcuni comandi funzionano anche quando incorporati in un messaggio normale e vengono rimossi prima che il modello veda il testo rimanente.
- Esempio: `hey /status` attiva una risposta di stato e il testo rimanente continua nel flusso normale.
- Attualmente: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
- I messaggi composti solo da comandi non autorizzati vengono ignorati silenziosamente e i token inline `/...` vengono trattati come testo normale.
- **Comandi Skill:** le Skills `user-invocable` vengono esposte come slash command. I nomi vengono sanitizzati in `a-z0-9_` (massimo 32 caratteri); le collisioni ricevono suffissi numerici (ad esempio `_2`).
- `/skill <name> [input]` esegue una Skill per nome (utile quando i limiti dei comandi nativi impediscono comandi per-Skill).
- Per impostazione predefinita, i comandi Skill vengono inoltrati al modello come richiesta normale.
- Le Skills possono facoltativamente dichiarare `command-dispatch: tool` per instradare il comando direttamente a uno strumento (deterministico, senza modello).
- Esempio: `/prose` (plugin OpenProse) — consulta [OpenProse](/it/prose).
- **Argomenti dei comandi nativi:** Discord usa autocomplete per le opzioni dinamiche (e menu a pulsanti quando ometti gli argomenti richiesti). Telegram e Slack mostrano un menu a pulsanti quando un comando supporta scelte e ometti l'argomento.
- I messaggi composti solo da comandi non autorizzati vengono ignorati silenziosamente, e i token inline `/...` vengono trattati come testo normale.
- **Comandi skill:** le skill `user-invocable` sono esposte come comandi slash. I nomi vengono sanitizzati in `a-z0-9_` (massimo 32 caratteri); i conflitti ricevono suffissi numerici (ad esempio `_2`).
- `/skill <name> [input]` esegue una skill per nome (utile quando i limiti dei comandi nativi impediscono comandi per singola skill).
- Per impostazione predefinita, i comandi skill vengono inoltrati al modello come richiesta normale.
- Le skill possono facoltativamente dichiarare `command-dispatch: tool` per instradare il comando direttamente a uno strumento (deterministico, senza modello).
- Esempio: `/prose` (plugin OpenProse) — vedi [OpenProse](/it/prose).
- **Argomenti dei comandi nativi:** Discord usa l'autocomplete per le opzioni dinamiche (e menu a pulsanti quando ometti argomenti obbligatori). Telegram e Slack mostrano un menu a pulsanti quando un comando supporta scelte e ometti l'argomento.
## `/tools`
`/tools` risponde a una domanda runtime, non a una domanda di configurazione: **cosa può usare questo agent in questo momento in
`/tools` risponde a una domanda di runtime, non a una domanda di configurazione: **cosa questo agente può usare in questo momento in
questa conversazione**.
- Il valore predefinito di `/tools` è compatto e ottimizzato per una scansione rapida.
- `/tools verbose` aggiunge brevi descrizioni.
- Le superfici di comando nativo che supportano argomenti espongono lo stesso selettore di modalità `compact|verbose`.
- I risultati hanno ambito di sessione, quindi cambiare agent, canale, thread, autorizzazione del mittente o modello può
- Le superfici dei comandi nativi che supportano argomenti espongono lo stesso cambio di modalità come `compact|verbose`.
- I risultati sono limitati alla sessione, quindi cambiare agente, canale, thread, autorizzazione del mittente o modello può
cambiare l'output.
- `/tools` include gli strumenti realmente raggiungibili a runtime, inclusi strumenti core, strumenti
di plugin connessi e strumenti posseduti dal canale.
- `/tools` include gli strumenti effettivamente raggiungibili a runtime, inclusi strumenti core, strumenti dei
plugin connessi e strumenti posseduti dal canale.
Per modificare profili e override, usa il pannello Tools della Control UI o le superfici di configurazione/catalogo invece
di trattare `/tools` come un catalogo statico.
Per la modifica di profili e override, usa il pannello Tools della Control UI o le superfici config/catalogo
invece di trattare `/tools` come un catalogo statico.
## Superfici di utilizzo (cosa appare dove)
## Superfici di utilizzo (cosa compare dove)
- **Utilizzo/quota del provider** (esempio: “Claude 80% rimasto”) appare in `/status` per il provider del modello corrente quando il tracciamento dell'utilizzo è abilitato. OpenClaw normalizza le finestre dei provider in `% rimasto`; per MiniMax, i campi percentuali solo-rimanente vengono invertiti prima della visualizzazione, e le risposte `model_remains` privilegiano la voce del modello chat più un'etichetta del piano taggata sul modello.
- Le righe **token/cache** in `/status` possono fare fallback all'ultima voce di utilizzo nella trascrizione quando lo snapshot live della sessione è scarso. I valori live esistenti diversi da zero continuano comunque ad avere la precedenza e il fallback della trascrizione può anche recuperare l'etichetta del modello runtime attivo più un totale più grande orientato al prompt quando i totali archiviati mancano o sono inferiori.
- **Token/costo per risposta** è controllato da `/usage off|tokens|full` (aggiunto alle normali risposte).
- `/model status` riguarda **modelli/autenticazione/endpoint**, non l'utilizzo.
- **Uso/quota del provider** (esempio: “Claude 80% left”) compare in `/status` per il provider del modello corrente quando il tracciamento dell'utilizzo è abilitato. OpenClaw normalizza le finestre dei provider in `% left`; per MiniMax, i campi percentuali solo-rimanenti vengono invertiti prima della visualizzazione, e le risposte `model_remains` preferiscono la voce del modello di chat più un'etichetta del piano con tag del modello.
- **Righe token/cache** in `/status` possono ripiegare sull'ultima voce di utilizzo della trascrizione quando lo snapshot live della sessione è scarno. I valori live non zero esistenti continuano comunque a prevalere, e il fallback alla trascrizione può anche recuperare l'etichetta del modello runtime attivo più un totale più ampio orientato al prompt quando i totali memorizzati mancano o sono inferiori.
- **Token/costo per risposta** è controllato da `/usage off|tokens|full` (aggiunto alle risposte normali).
- `/model status` riguarda **modelli/auth/endpoint**, non l'utilizzo.
## Selezione del modello (`/model`)
@ -212,13 +251,13 @@ Esempi:
Note:
- `/model` e `/model list` mostrano un selettore compatto numerato (famiglia di modelli + provider disponibili).
- Su Discord, `/model` e `/models` aprono un selettore interattivo con menu a discesa di provider e modello più un passaggio Submit.
- `/model <#>` seleziona da quel selettore (e privilegia il provider corrente quando possibile).
- `/model status` mostra la vista dettagliata, inclusi endpoint provider configurato (`baseUrl`) e modalità API (`api`) quando disponibili.
- Su Discord, `/model` e `/models` aprono un selettore interattivo con menu a discesa per provider e modello più un passaggio Submit.
- `/model <#>` seleziona da quel selettore (e preferisce il provider corrente quando possibile).
- `/model status` mostra la vista dettagliata, incluso l'endpoint provider configurato (`baseUrl`) e la modalità API (`api`) quando disponibili.
## Override di debug
`/debug` consente di impostare override di configurazione **solo runtime** (in memoria, non su disco). Solo proprietario. Disabilitato per impostazione predefinita; abilitalo con `commands.debug: true`.
`/debug` ti permette di impostare override di configurazione **solo runtime** (in memoria, non su disco). Solo proprietario. Disabilitato per impostazione predefinita; abilitalo con `commands.debug: true`.
Esempi:
@ -235,7 +274,7 @@ Note:
- Gli override si applicano immediatamente alle nuove letture della configurazione, ma **non** scrivono in `openclaw.json`.
- Usa `/debug reset` per cancellare tutti gli override e tornare alla configurazione su disco.
## Aggiornamenti di configurazione
## Aggiornamenti della configurazione
`/config` scrive nella configurazione su disco (`openclaw.json`). Solo proprietario. Disabilitato per impostazione predefinita; abilitalo con `commands.config: true`.
@ -251,12 +290,12 @@ Esempi:
Note:
- La configurazione viene convalidata prima della scrittura; le modifiche non valide vengono rifiutate.
- Gli aggiornamenti `/config` persistono tra i riavvii.
- La configurazione viene validata prima della scrittura; le modifiche non valide vengono rifiutate.
- Gli aggiornamenti di `/config` persistono dopo i riavvii.
## Aggiornamenti MCP
`/mcp` scrive le definizioni dei server MCP gestite da OpenClaw sotto `mcp.servers`. Solo proprietario. Disabilitato per impostazione predefinita; abilitalo con `commands.mcp: true`.
`/mcp` scrive le definizioni del server MCP gestite da OpenClaw sotto `mcp.servers`. Solo proprietario. Disabilitato per impostazione predefinita; abilitalo con `commands.mcp: true`.
Esempi:
@ -269,12 +308,12 @@ Esempi:
Note:
- `/mcp` archivia la configurazione nella configurazione OpenClaw, non nelle impostazioni di progetto possedute da Pi.
- Gli adapter runtime decidono quali trasporti sono effettivamente eseguibili.
- `/mcp` memorizza la configurazione nella configurazione OpenClaw, non nelle impostazioni di progetto possedute da Pi.
- Gli adapter di runtime decidono quali transport sono effettivamente eseguibili.
## Aggiornamenti dei plugin
`/plugins` consente agli operatori di ispezionare i plugin rilevati e di attivare/disattivare l'abilitazione nella configurazione. I flussi in sola lettura possono usare `/plugin` come alias. Disabilitato per impostazione predefinita; abilitalo con `commands.plugins: true`.
`/plugins` permette agli operatori di ispezionare i plugin rilevati e attivare/disattivare l'abilitazione nella configurazione. I flussi di sola lettura possono usare `/plugin` come alias. Disabilitato per impostazione predefinita; abilitalo con `commands.plugins: true`.
Esempi:
@ -288,35 +327,35 @@ Esempi:
Note:
- `/plugins list` e `/plugins show` usano la reale discovery dei plugin rispetto al workspace corrente più la configurazione su disco.
- `/plugins list` e `/plugins show` usano il rilevamento reale dei plugin rispetto al workspace corrente più la configurazione su disco.
- `/plugins enable|disable` aggiorna solo la configurazione del plugin; non installa né disinstalla i plugin.
- Dopo modifiche di abilitazione/disabilitazione, riavvia il gateway per applicarle.
## Note sulle superfici
- **Comandi testuali** vengono eseguiti nella normale sessione chat (i DM condividono `main`, i gruppi hanno la propria sessione).
- **Comandi testuali** vengono eseguiti nella normale sessione di chat (i DM condividono `main`, i gruppi hanno la propria sessione).
- **Comandi nativi** usano sessioni isolate:
- Discord: `agent:<agentId>:discord:slash:<userId>`
- Slack: `agent:<agentId>:slack:slash:<userId>` (prefisso configurabile tramite `channels.slack.slashCommand.sessionPrefix`)
- Telegram: `telegram:slash:<userId>` (indirizza la sessione chat tramite `CommandTargetSessionKey`)
- **`/stop`** prende di mira la sessione chat attiva così può interrompere l'esecuzione corrente.
- **Slack:** `channels.slack.slashCommand` è ancora supportato per un singolo comando in stile `/openclaw`. Se abiliti `commands.native`, devi creare uno slash command Slack per ogni comando integrato (stessi nomi di `/help`). I menu degli argomenti dei comandi per Slack vengono forniti come pulsanti Block Kit effimeri.
- Eccezione nativa Slack: registra `/agentstatus` (non `/status`) perché Slack riserva `/status`. Il testo `/status` continua a funzionare nei messaggi Slack.
- Telegram: `telegram:slash:<userId>` (destina la sessione di chat tramite `CommandTargetSessionKey`)
- **`/stop`** punta alla sessione di chat attiva così da poter interrompere l'esecuzione corrente.
- **Slack:** `channels.slack.slashCommand` è ancora supportato per un singolo comando in stile `/openclaw`. Se abiliti `commands.native`, devi creare un comando slash Slack per ogni comando built-in (con gli stessi nomi di `/help`). I menu argomenti dei comandi per Slack vengono consegnati come pulsanti Block Kit effimeri.
- Eccezione nativa Slack: registra `/agentstatus` (non `/status`) perché Slack riserva `/status`. Il testo `/status` continua comunque a funzionare nei messaggi Slack.
## Domande laterali BTW
`/btw` è una rapida **domanda laterale** sulla sessione corrente.
A differenza della normale chat:
A differenza della chat normale:
- usa la sessione corrente come contesto di sfondo,
- viene eseguita come chiamata one-shot separata **senza strumenti**,
- viene eseguita come chiamata separata **senza strumenti** e one-shot,
- non modifica il contesto futuro della sessione,
- non viene scritta nella cronologia della trascrizione,
- viene consegnata come risultato laterale live invece che come normale messaggio dell'assistente.
Questo rende `/btw` utile quando vuoi un chiarimento temporaneo mentre il task principale
continua.
Questo rende `/btw` utile quando vuoi un chiarimento temporaneo mentre
l'attività principale continua.
Esempio:
@ -324,5 +363,5 @@ Esempio:
/btw cosa stiamo facendo in questo momento?
```
Consulta [BTW Side Questions](/it/tools/btw) per il comportamento completo e i
Vedi [BTW Side Questions](/it/tools/btw) per il comportamento completo e i
dettagli UX del client.

View File

@ -1,15 +1,15 @@
---
read_when:
- Abilitazione della sintesi vocale per le risposte
- Configurazione di provider o limiti TTS
- Configurazione dei provider TTS o dei limiti
- Uso dei comandi /tts
summary: Sintesi vocale (TTS) per le risposte in uscita
title: Sintesi vocale
x-i18n:
generated_at: "2026-04-05T14:08:22Z"
generated_at: "2026-04-08T06:01:52Z"
model: gpt-5.4
provider: openai
source_hash: 8487c8acef7585bd4eb5e3b39e2a063ebc6b5f0103524abdcbadd3a7781ffc46
source_hash: 6e0fbcaf61282733c134f682e05a71f94d2169c03a85131ce9ad233c71a1e533
source_path: tools/tts.md
workflow: 15
---
@ -28,14 +28,14 @@ Funziona ovunque OpenClaw possa inviare audio.
### Note sulla sintesi vocale Microsoft
Il provider di sintesi vocale Microsoft bundled attualmente usa il servizio TTS
neurale online di Microsoft Edge tramite la libreria `node-edge-tts`. È un servizio hosted (non
Il provider di sintesi vocale Microsoft bundled usa attualmente il servizio TTS neurale
online di Microsoft Edge tramite la libreria `node-edge-tts`. È un servizio ospitato (non
locale), usa endpoint Microsoft e non richiede una chiave API.
`node-edge-tts` espone opzioni di configurazione della sintesi e formati di output, ma
`node-edge-tts` espone opzioni di configurazione della sintesi vocale e formati di output, ma
non tutte le opzioni sono supportate dal servizio. La configurazione legacy e l'input direttiva
che usa `edge` continuano a funzionare e vengono normalizzati in `microsoft`.
che usa `edge` continuano a funzionare e vengono normalizzati a `microsoft`.
Poiché questo percorso è un servizio web pubblico senza SLA o quota pubblicati,
Poiché questo percorso è un servizio web pubblico senza uno SLA o una quota pubblicati,
consideralo best-effort. Se hai bisogno di limiti garantiti e supporto, usa OpenAI
o ElevenLabs.
@ -49,31 +49,31 @@ Se vuoi usare OpenAI, ElevenLabs o MiniMax:
La sintesi vocale Microsoft **non** richiede una chiave API.
Se sono configurati più provider, viene usato prima il provider selezionato e gli altri diventano opzioni di fallback.
Se sono configurati più provider, il provider selezionato viene usato per primo e gli altri sono opzioni di fallback.
Il riepilogo automatico usa il `summaryModel` configurato (o `agents.defaults.model.primary`),
quindi anche quel provider deve essere autenticato se abiliti i riepiloghi.
## Link ai servizi
- [Guida OpenAI Text-to-Speech](https://platform.openai.com/docs/guides/text-to-speech)
- [Riferimento API OpenAI Audio](https://platform.openai.com/docs/api-reference/audio)
- [Riferimento API Audio di OpenAI](https://platform.openai.com/docs/api-reference/audio)
- [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech)
- [Autenticazione ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication)
- [API MiniMax T2A v2](https://platform.minimaxi.com/document/T2A%20V2)
- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts)
- [Formati di output Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)
- [Formati di output di Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)
## È abilitato per impostazione predefinita?
No. L'autoTTS è **disattivato** per impostazione predefinita. Abilitalo nella configurazione con
`messages.tts.auto` o per sessione con `/tts always` (alias: `/tts on`).
`messages.tts.auto` oppure localmente con `/tts on`.
Quando `messages.tts.provider` non è impostato, OpenClaw sceglie il primo
provider di sintesi vocale configurato nell'ordine di selezione automatica del registro.
## Configurazione
La configurazione TTS si trova sotto `messages.tts` in `openclaw.json`.
La configurazione TTS si trova in `messages.tts` in `openclaw.json`.
Lo schema completo è in [Configurazione del Gateway](/it/gateway/configuration).
### Configurazione minima (abilitazione + provider)
@ -130,7 +130,7 @@ Lo schema completo è in [Configurazione del Gateway](/it/gateway/configuration)
}
```
### Microsoft primario (nessuna chiave API)
### Microsoft primario (senza chiave API)
```json5
{
@ -208,7 +208,7 @@ Lo schema completo è in [Configurazione del Gateway](/it/gateway/configuration)
}
```
### Rispondere con audio solo dopo un messaggio vocale in entrata
### Rispondi con audio solo dopo un messaggio vocale in ingresso
```json5
{
@ -220,7 +220,7 @@ Lo schema completo è in [Configurazione del Gateway](/it/gateway/configuration)
}
```
### Disabilitare il riepilogo automatico per risposte lunghe
### Disabilitare il riepilogo automatico per le risposte lunghe
```json5
{
@ -232,7 +232,7 @@ Lo schema completo è in [Configurazione del Gateway](/it/gateway/configuration)
}
```
Quindi esegui:
Poi esegui:
```
/tts summary off
@ -241,25 +241,25 @@ Quindi esegui:
### Note sui campi
- `auto`: modalità autoTTS (`off`, `always`, `inbound`, `tagged`).
- `inbound` invia audio solo dopo un messaggio vocale in entrata.
- `inbound` invia audio solo dopo un messaggio vocale in ingresso.
- `tagged` invia audio solo quando la risposta include tag `[[tts]]`.
- `enabled`: interruttore legacy (doctor lo migra in `auto`).
- `mode`: `"final"` (predefinito) o `"all"` (include risposte di strumenti/blocchi).
- `mode`: `"final"` (predefinito) oppure `"all"` (include risposte di strumenti/blocchi).
- `provider`: ID del provider di sintesi vocale come `"elevenlabs"`, `"microsoft"`, `"minimax"` o `"openai"` (il fallback è automatico).
- Se `provider` **non è impostato**, OpenClaw usa il primo provider di sintesi vocale configurato nell'ordine di selezione automatica del registro.
- Il legacy `provider: "edge"` continua a funzionare e viene normalizzato in `microsoft`.
- `summaryModel`: modello economico facoltativo per il riepilogo automatico; il valore predefinito è `agents.defaults.model.primary`.
- Il valore legacy `provider: "edge"` continua a funzionare e viene normalizzato a `microsoft`.
- `summaryModel`: modello economico facoltativo per il riepilogo automatico; per impostazione predefinita usa `agents.defaults.model.primary`.
- Accetta `provider/model` o un alias di modello configurato.
- `modelOverrides`: consente al modello di emettere direttive TTS (attivo per impostazione predefinita).
- `allowProvider` è `false` per impostazione predefinita (il cambio provider è facoltativo).
- `providers.<id>`: impostazioni gestite dal provider, con chiave sull'ID del provider di sintesi vocale.
- I blocchi provider legacy diretti (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) vengono migrati automaticamente in `messages.tts.providers.<id>` al caricamento.
- `maxTextLength`: limite rigido per l'input TTS (caratteri). `/tts audio` fallisce se viene superato.
- `allowProvider` per impostazione predefinita è `false` (il cambio provider richiede opt-in).
- `providers.<id>`: impostazioni di proprietà del provider indicizzate per ID provider di sintesi vocale.
- I blocchi provider legacy diretti (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) vengono migrati automaticamente a `messages.tts.providers.<id>` al caricamento.
- `maxTextLength`: limite rigido per l'input TTS (caratteri). `/tts audio` non riesce se viene superato.
- `timeoutMs`: timeout della richiesta (ms).
- `prefsPath`: sovrascrive il percorso JSON locale delle preferenze (provider/limite/riepilogo).
- `prefsPath`: sostituisce il percorso del file JSON delle preferenze locali (provider/limite/riepilogo).
- I valori `apiKey` usano come fallback le variabili d'ambiente (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`).
- `providers.elevenlabs.baseUrl`: sovrascrive l'URL base dell'API ElevenLabs.
- `providers.openai.baseUrl`: sovrascrive l'endpoint OpenAI TTS.
- `providers.elevenlabs.baseUrl`: sostituisce l'URL di base dell'API ElevenLabs.
- `providers.openai.baseUrl`: sostituisce l'endpoint TTS OpenAI.
- Ordine di risoluzione: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1`
- I valori non predefiniti vengono trattati come endpoint TTS compatibili con OpenAI, quindi sono accettati nomi personalizzati di modello e voce.
- `providers.elevenlabs.voiceSettings`:
@ -269,21 +269,21 @@ Quindi esegui:
- `providers.elevenlabs.applyTextNormalization`: `auto|on|off`
- `providers.elevenlabs.languageCode`: ISO 639-1 a 2 lettere (per esempio `en`, `de`)
- `providers.elevenlabs.seed`: intero `0..4294967295` (determinismo best-effort)
- `providers.minimax.baseUrl`: sovrascrive l'URL base dell'API MiniMax (predefinito `https://api.minimax.io`, env: `MINIMAX_API_HOST`).
- `providers.minimax.baseUrl`: sostituisce l'URL di base dell'API MiniMax (predefinito `https://api.minimax.io`, env: `MINIMAX_API_HOST`).
- `providers.minimax.model`: modello TTS (predefinito `speech-2.8-hd`, env: `MINIMAX_TTS_MODEL`).
- `providers.minimax.voiceId`: identificatore voce (predefinito `English_expressive_narrator`, env: `MINIMAX_TTS_VOICE_ID`).
- `providers.minimax.speed`: velocità di riproduzione `0.5..2.0` (predefinito 1.0).
- `providers.minimax.voiceId`: identificatore della voce (predefinito `English_expressive_narrator`, env: `MINIMAX_TTS_VOICE_ID`).
- `providers.minimax.speed`: velocità di riproduzione `0.5..2.0` (predefinita 1.0).
- `providers.minimax.vol`: volume `(0, 10]` (predefinito 1.0; deve essere maggiore di 0).
- `providers.minimax.pitch`: variazione di tono `-12..12` (predefinito 0).
- `providers.minimax.pitch`: variazione di tono `-12..12` (predefinita 0).
- `providers.microsoft.enabled`: consente l'uso della sintesi vocale Microsoft (predefinito `true`; nessuna chiave API).
- `providers.microsoft.voice`: nome della voce neurale Microsoft (per esempio `en-US-MichelleNeural`).
- `providers.microsoft.lang`: codice lingua (per esempio `en-US`).
- `providers.microsoft.outputFormat`: formato di output Microsoft (per esempio `audio-24khz-48kbitrate-mono-mp3`).
- Vedi i formati di output Microsoft Speech per i valori validi; non tutti i formati sono supportati dal trasporto bundled basato su Edge.
- Vedi i formati di output di Microsoft Speech per i valori validi; non tutti i formati sono supportati dal trasporto bundled basato su Edge.
- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: stringhe percentuali (per esempio `+10%`, `-5%`).
- `providers.microsoft.saveSubtitles`: scrive sottotitoli JSON accanto al file audio.
- `providers.microsoft.proxy`: URL proxy per le richieste di sintesi vocale Microsoft.
- `providers.microsoft.timeoutMs`: override del timeout richiesta (ms).
- `providers.microsoft.proxy`: URL del proxy per le richieste di sintesi vocale Microsoft.
- `providers.microsoft.timeoutMs`: override del timeout della richiesta (ms).
- `edge.*`: alias legacy per le stesse impostazioni Microsoft.
## Override guidati dal modello (attivi per impostazione predefinita)
@ -291,14 +291,14 @@ Quindi esegui:
Per impostazione predefinita, il modello **può** emettere direttive TTS per una singola risposta.
Quando `messages.tts.auto` è `tagged`, queste direttive sono necessarie per attivare l'audio.
Quando è abilitato, il modello può emettere direttive `[[tts:...]]` per sovrascrivere la voce
Quando è abilitato, il modello può emettere direttive `[[tts:...]]` per sostituire la voce
per una singola risposta, più un blocco facoltativo `[[tts:text]]...[[/tts:text]]` per
fornire tag espressivi (risate, indicazioni di canto, ecc.) che devono comparire solo
nell'audio.
Le direttive `provider=...` vengono ignorate a meno che `modelOverrides.allowProvider: true`.
Payload di risposta di esempio:
Esempio di payload di risposta:
```
Here you go.
@ -307,11 +307,11 @@ Here you go.
[[tts:text]](laughs) Read the song once more.[[/tts:text]]
```
Chiavi di direttiva disponibili (quando abilitate):
Chiavi direttiva disponibili (quando abilitate):
- `provider` (ID provider di sintesi vocale registrato, per esempio `openai`, `elevenlabs`, `minimax` o `microsoft`; richiede `allowProvider: true`)
- `voice` (voce OpenAI) o `voiceId` (ElevenLabs / MiniMax)
- `model` (modello OpenAI TTS, ID modello ElevenLabs o modello MiniMax)
- `voice` (voce OpenAI) oppure `voiceId` (ElevenLabs / MiniMax)
- `model` (modello TTS OpenAI, model id ElevenLabs o modello MiniMax)
- `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost`
- `vol` / `volume` (volume MiniMax, 0-10)
- `pitch` (tono MiniMax, da -12 a 12)
@ -333,7 +333,7 @@ Disabilita tutti gli override del modello:
}
```
Allowlist facoltativa (abilita il cambio provider mantenendo configurabili gli altri controlli):
Allowlist facoltativa (abilita il cambio provider mantenendo configurabili gli altri parametri):
```json5
{
@ -351,76 +351,74 @@ Allowlist facoltativa (abilita il cambio provider mantenendo configurabili gli a
## Preferenze per utente
I comandi slash scrivono override locali in `prefsPath` (predefinito:
`~/.openclaw/settings/tts.json`, sovrascrivibile con `OPENCLAW_TTS_PREFS` o
I comandi slash scrivono gli override locali in `prefsPath` (predefinito:
`~/.openclaw/settings/tts.json`, sostituibile con `OPENCLAW_TTS_PREFS` o
`messages.tts.prefsPath`).
Campi memorizzati:
- `enabled`
- `provider`
- `maxLength` (soglia di riepilogo; predefinito 1500 caratteri)
- `maxLength` (soglia del riepilogo; predefinita 1500 caratteri)
- `summarize` (predefinito `true`)
Questi campi sovrascrivono `messages.tts.*` per quell'host.
Questi sostituiscono `messages.tts.*` per quell'host.
## Formati di output (fissi)
- **Feishu / Matrix / Telegram / WhatsApp**: messaggio vocale Opus (`opus_48000_64` da ElevenLabs, `opus` da OpenAI).
- 48kHz / 64kbps è un buon compromesso per i messaggi vocali.
- **Altri canali**: MP3 (`mp3_44100_128` da ElevenLabs, `mp3` da OpenAI).
- 44.1kHz / 128kbps è il bilanciamento predefinito per la chiarezza del parlato.
- **MiniMax**: MP3 (`speech-2.8-hd`, frequenza di campionamento 32kHz). Il formato nota vocale non è supportato nativamente; usa OpenAI o ElevenLabs per messaggi vocali Opus garantiti.
- 44,1kHz / 128kbps è il bilanciamento predefinito per la chiarezza del parlato.
- **MiniMax**: MP3 (modello `speech-2.8-hd`, frequenza di campionamento 32kHz). Il formato per note vocali non è supportato in modo nativo; usa OpenAI o ElevenLabs per messaggi vocali Opus garantiti.
- **Microsoft**: usa `microsoft.outputFormat` (predefinito `audio-24khz-48kbitrate-mono-mp3`).
- Il trasporto bundled accetta un `outputFormat`, ma non tutti i formati sono disponibili dal servizio.
- I valori del formato di output seguono i formati di output Microsoft Speech (inclusi Ogg/WebM Opus).
- I valori del formato di output seguono i formati di output di Microsoft Speech (inclusi Ogg/WebM Opus).
- Telegram `sendVoice` accetta OGG/MP3/M4A; usa OpenAI/ElevenLabs se hai bisogno
di messaggi vocali Opus garantiti.
- Se il formato di output Microsoft configurato fallisce, OpenClaw riprova con MP3.
I formati di output OpenAI/ElevenLabs sono fissi per canale (vedi sopra).
## Comportamento auto-TTS
## Comportamento dell'auto-TTS
Quando è abilitato, OpenClaw:
- salta il TTS se la risposta contiene già media o una direttiva `MEDIA:`.
- salta il TTS se la risposta contiene già contenuti multimediali o una direttiva `MEDIA:`.
- salta le risposte molto brevi (< 10 caratteri).
- riassume le risposte lunghe quando abilitato usando `agents.defaults.model.primary` (o `summaryModel`).
- riepiloga le risposte lunghe quando abilitato usando `agents.defaults.model.primary` (o `summaryModel`).
- allega l'audio generato alla risposta.
Se la risposta supera `maxLength` e il riepilogo è disattivato (o manca una chiave API per il
Se la risposta supera `maxLength` e il riepilogo è disattivato (o non c'è una chiave API per il
modello di riepilogo), l'audio
viene saltato e viene inviata la normale risposta testuale.
## Diagramma di flusso
## Diagramma del flusso
```
Reply -> TTS enabled?
no -> invia testo
yes -> ha media / MEDIA: / è breve?
yes -> invia testo
no -> lunghezza > limite?
no -> TTS -> allega audio
yes -> riepilogo abilitato?
no -> invia testo
yes -> riepiloga (summaryModel o agents.defaults.model.primary)
-> TTS -> allega audio
no -> send text
yes -> has media / MEDIA: / short?
yes -> send text
no -> length > limit?
no -> TTS -> attach audio
yes -> summary enabled?
no -> send text
yes -> summarize (summaryModel or agents.defaults.model.primary)
-> TTS -> attach audio
```
## Uso dei comandi slash
Esiste un solo comando: `/tts`.
Vedi [Comandi slash](/tools/slash-commands) per i dettagli di abilitazione.
Vedi [Comandi slash](/it/tools/slash-commands) per i dettagli sull'abilitazione.
Nota Discord: `/tts` è un comando Discord integrato, quindi OpenClaw registra
Nota su Discord: `/tts` è un comando integrato di Discord, quindi OpenClaw registra
`/voice` come comando nativo lì. Il testo `/tts ...` continua a funzionare.
```
/tts off
/tts always
/tts inbound
/tts tagged
/tts on
/tts status
/tts provider openai
/tts limit 2000
@ -430,24 +428,26 @@ Nota Discord: `/tts` è un comando Discord integrato, quindi OpenClaw registra
Note:
- I comandi richiedono un mittente autorizzato (continuano ad applicarsi le regole allowlist/proprietario).
- `commands.text` o la registrazione del comando nativo devono essere abilitati.
- `off|always|inbound|tagged` sono interruttori per sessione (`/tts on` è un alias di `/tts always`).
- I comandi richiedono un mittente autorizzato (si applicano comunque le regole di allowlist/proprietario).
- `commands.text` o la registrazione dei comandi nativi devono essere abilitati.
- La configurazione `messages.tts.auto` accetta `off|always|inbound|tagged`.
- `/tts on` scrive la preferenza TTS locale su `always`; `/tts off` la scrive su `off`.
- Usa la configurazione quando vuoi i valori predefiniti `inbound` o `tagged`.
- `limit` e `summary` vengono memorizzati nelle preferenze locali, non nella configurazione principale.
- `/tts audio` genera una risposta audio una tantum (non abilita/disabilita il TTS).
- `/tts audio` genera una risposta audio una tantum (non attiva il TTS).
- `/tts status` include la visibilità del fallback per l'ultimo tentativo:
- fallback riuscito: `Fallback: <primary> -> <used>` più `Attempts: ...`
- errore: `Error: ...` più `Attempts: ...`
- diagnostica dettagliata: `Attempt details: provider:outcome(reasonCode) latency`
- Gli errori API OpenAI ed ElevenLabs ora includono dettagli dell'errore provider analizzati e request id (quando restituito dal provider), che vengono mostrati negli errori/log TTS.
- I fallimenti API di OpenAI ed ElevenLabs ora includono il dettaglio di errore del provider analizzato e l'ID richiesta (quando restituito dal provider), che viene mostrato negli errori/log TTS.
## Strumento agente
Lo strumento `tts` converte il testo in sintesi vocale e restituisce un allegato audio per
Lo strumento `tts` converte il testo in parlato e restituisce un allegato audio per
la consegna della risposta. Quando il canale è Feishu, Matrix, Telegram o WhatsApp,
l'audio viene recapitato come messaggio vocale invece che come allegato file.
l'audio viene consegnato come messaggio vocale anziché come allegato file.
## RPC del Gateway
## Gateway RPC
Metodi Gateway: