chore(i18n): refresh it translations
This commit is contained in:
parent
f368abe421
commit
5b10b3888e
@ -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)
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 pi‑ai. 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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
@ -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)_
|
||||
|
||||
370
docs/it/plugins/memory-wiki.md
Normal file
370
docs/it/plugins/memory-wiki.md
Normal 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)
|
||||
@ -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).
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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'auto‑TTS è **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à auto‑TTS (`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:
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user