chore(i18n): refresh it translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
a486cb68c6
commit
ca0ac11940
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Configurazione del canale BlueBubbles
|
||||
- Risoluzione dei problemi di abbinamento del Webhook
|
||||
- Risoluzione dei problemi di associazione del Webhook
|
||||
- Configurazione di iMessage su macOS
|
||||
summary: iMessage tramite server macOS BlueBubbles (invio/ricezione REST, digitazione, reazioni, abbinamento, azioni avanzate).
|
||||
summary: iMessage tramite server macOS BlueBubbles (invio/ricezione REST, digitazione, reazioni, associazione, azioni avanzate).
|
||||
title: BlueBubbles
|
||||
x-i18n:
|
||||
generated_at: "2026-04-21T08:21:16Z"
|
||||
generated_at: "2026-04-21T13:35:25Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b3d8d617fc86ca1b191ff4dd2ae26b464e4d3f456a79c67b484a3a76d75de0d2
|
||||
source_hash: 30ce50ae8a17140b42fa410647c367e0eefdffb1646b1ff92d8e1af63f2e1155
|
||||
source_path: channels/bluebubbles.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -20,19 +20,18 @@ Stato: plugin incluso che comunica con il server macOS BlueBubbles tramite HTTP.
|
||||
|
||||
## Plugin incluso
|
||||
|
||||
Le versioni correnti di OpenClaw includono BlueBubbles, quindi le normali build pacchettizzate non
|
||||
richiedono un passaggio separato `openclaw plugins install`.
|
||||
Le versioni correnti di OpenClaw includono BlueBubbles, quindi le normali build pacchettizzate non richiedono un passaggio separato `openclaw plugins install`.
|
||||
|
||||
## Panoramica
|
||||
|
||||
- Viene eseguito su macOS tramite l'app helper BlueBubbles ([bluebubbles.app](https://bluebubbles.app)).
|
||||
- Consigliato/testato: macOS Sequoia (15). macOS Tahoe (26) funziona; la modifica al momento non funziona su Tahoe e gli aggiornamenti dell'icona del gruppo possono risultare riusciti ma non sincronizzarsi.
|
||||
- Funziona su macOS tramite l'app helper BlueBubbles ([bluebubbles.app](https://bluebubbles.app)).
|
||||
- Consigliato/testato: macOS Sequoia (15). macOS Tahoe (26) funziona; al momento la modifica dei messaggi è non funzionante su Tahoe e gli aggiornamenti delle icone di gruppo possono risultare riusciti senza però sincronizzarsi.
|
||||
- OpenClaw comunica con esso tramite la sua API REST (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
|
||||
- I messaggi in arrivo arrivano tramite Webhook; le risposte in uscita, gli indicatori di digitazione, le conferme di lettura e i tapback sono chiamate REST.
|
||||
- Gli allegati e gli sticker vengono acquisiti come contenuti multimediali in entrata (e mostrati all'agente quando possibile).
|
||||
- L'abbinamento/allowlist funziona allo stesso modo degli altri canali (`/channels/pairing` ecc.) con `channels.bluebubbles.allowFrom` + codici di abbinamento.
|
||||
- Le reazioni vengono esposte come eventi di sistema proprio come in Slack/Telegram, così gli agenti possono "menzionarle" prima di rispondere.
|
||||
- Funzionalità avanzate: modifica, annullamento invio, risposte in thread, effetti dei messaggi, gestione dei gruppi.
|
||||
- Gli allegati e gli sticker vengono acquisiti come contenuti multimediali in ingresso (e mostrati all'agente quando possibile).
|
||||
- L'associazione/lista di elementi consentiti funziona nello stesso modo degli altri canali (`/channels/pairing` ecc.) con `channels.bluebubbles.allowFrom` + codici di associazione.
|
||||
- Le reazioni vengono mostrate come eventi di sistema proprio come in Slack/Telegram, così gli agenti possono "menzionarle" prima di rispondere.
|
||||
- Funzionalità avanzate: modifica, annullamento dell'invio, risposte in thread, effetti del messaggio, gestione dei gruppi.
|
||||
|
||||
## Avvio rapido
|
||||
|
||||
@ -53,18 +52,18 @@ richiedono un passaggio separato `openclaw plugins install`.
|
||||
}
|
||||
```
|
||||
|
||||
4. Punta i Webhook BlueBubbles al tuo Gateway (esempio: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
|
||||
5. Avvia il Gateway; registrerà il gestore del Webhook e inizierà l'abbinamento.
|
||||
4. Indirizza i Webhook di BlueBubbles al tuo Gateway (esempio: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
|
||||
5. Avvia il Gateway; registrerà il gestore del Webhook e inizierà l'associazione.
|
||||
|
||||
Nota sulla sicurezza:
|
||||
|
||||
- Imposta sempre una password per il Webhook.
|
||||
- L'autenticazione del Webhook è sempre obbligatoria. OpenClaw rifiuta le richieste Webhook BlueBubbles a meno che non includano una password/guid che corrisponda a `channels.bluebubbles.password` (ad esempio `?password=<password>` o `x-password`), indipendentemente dalla topologia loopback/proxy.
|
||||
- L'autenticazione tramite password viene controllata prima di leggere/analizzare i corpi completi dei Webhook.
|
||||
- L'autenticazione del Webhook è sempre obbligatoria. OpenClaw rifiuta le richieste Webhook di BlueBubbles a meno che non includano una password/guid che corrisponda a `channels.bluebubbles.password` (ad esempio `?password=<password>` o `x-password`), indipendentemente dalla topologia loopback/proxy.
|
||||
- L'autenticazione tramite password viene verificata prima di leggere/analizzare interamente i corpi delle richieste Webhook.
|
||||
|
||||
## Mantenere attiva Messages.app (configurazioni VM / headless)
|
||||
## Mantenere attivo Messages.app (configurazioni VM / headless)
|
||||
|
||||
Alcune configurazioni macOS VM / always-on possono far sì che Messages.app vada in “idle” (gli eventi in arrivo si fermano finché l'app non viene aperta/portata in primo piano). Una soluzione semplice consiste nel **dare un colpetto a Messages ogni 5 minuti** usando un AppleScript + LaunchAgent.
|
||||
Alcune configurazioni macOS VM / always-on possono portare Messages.app a diventare “inattiva” (gli eventi in ingresso si interrompono finché l'app non viene aperta/portata in primo piano). Una semplice soluzione alternativa consiste nel **sollecitare Messages ogni 5 minuti** usando un AppleScript + LaunchAgent.
|
||||
|
||||
### 1) Salva l'AppleScript
|
||||
|
||||
@ -126,8 +125,8 @@ Salvalo come:
|
||||
|
||||
Note:
|
||||
|
||||
- Viene eseguito **ogni 300 secondi** e **all'accesso**.
|
||||
- La prima esecuzione può attivare i prompt macOS di **Automation** (`osascript` → Messages). Approvali nella stessa sessione utente che esegue il LaunchAgent.
|
||||
- Questo viene eseguito **ogni 300 secondi** e **all'accesso**.
|
||||
- La prima esecuzione può attivare richieste macOS di **Automazione** (`osascript` → Messages). Approvatele nella stessa sessione utente che esegue il LaunchAgent.
|
||||
|
||||
Caricalo:
|
||||
|
||||
@ -146,11 +145,11 @@ openclaw onboard
|
||||
|
||||
La procedura guidata richiede:
|
||||
|
||||
- **URL del server** (obbligatorio): indirizzo del server BlueBubbles (es. `http://192.168.1.100:1234`)
|
||||
- **Password** (obbligatoria): password API dalle impostazioni di BlueBubbles Server
|
||||
- **Percorso Webhook** (facoltativo): predefinito `/bluebubbles-webhook`
|
||||
- **URL del server** (obbligatorio): indirizzo del server BlueBubbles (ad es. `http://192.168.1.100:1234`)
|
||||
- **Password** (obbligatoria): password API dalle impostazioni del server BlueBubbles
|
||||
- **Percorso del Webhook** (facoltativo): valore predefinito `/bluebubbles-webhook`
|
||||
- **Criterio DM**: pairing, allowlist, open o disabled
|
||||
- **Allow list**: numeri di telefono, email o destinazioni chat
|
||||
- **Lista consentita**: numeri di telefono, email o destinazioni chat
|
||||
|
||||
Puoi anche aggiungere BlueBubbles tramite CLI:
|
||||
|
||||
@ -158,16 +157,16 @@ Puoi anche aggiungere BlueBubbles tramite CLI:
|
||||
openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>
|
||||
```
|
||||
|
||||
## Controllo accessi (DM + gruppi)
|
||||
## Controllo degli accessi (DM + gruppi)
|
||||
|
||||
DM:
|
||||
|
||||
- Predefinito: `channels.bluebubbles.dmPolicy = "pairing"`.
|
||||
- I mittenti sconosciuti ricevono un codice di abbinamento; i messaggi vengono ignorati finché non vengono approvati (i codici scadono dopo 1 ora).
|
||||
- I mittenti sconosciuti ricevono un codice di associazione; i messaggi vengono ignorati finché non vengono approvati (i codici scadono dopo 1 ora).
|
||||
- Approva tramite:
|
||||
- `openclaw pairing list bluebubbles`
|
||||
- `openclaw pairing approve bluebubbles <CODE>`
|
||||
- L'abbinamento è lo scambio di token predefinito. Dettagli: [Pairing](/it/channels/pairing)
|
||||
- L'associazione è lo scambio di token predefinito. Dettagli: [Pairing](/it/channels/pairing)
|
||||
|
||||
Gruppi:
|
||||
|
||||
@ -176,10 +175,10 @@ Gruppi:
|
||||
|
||||
### Arricchimento dei nomi dei contatti (macOS, facoltativo)
|
||||
|
||||
I Webhook di gruppo BlueBubbles spesso includono solo gli indirizzi grezzi dei partecipanti. Se invece vuoi che il contesto `GroupMembers` mostri i nomi dei contatti locali, puoi attivare facoltativamente l'arricchimento dai Contatti locali su macOS:
|
||||
I Webhook dei gruppi BlueBubbles spesso includono solo indirizzi grezzi dei partecipanti. Se invece vuoi che il contesto `GroupMembers` mostri i nomi dei contatti locali, puoi attivare facoltativamente l'arricchimento dai Contatti locali su macOS:
|
||||
|
||||
- `channels.bluebubbles.enrichGroupParticipantsFromContacts = true` abilita la ricerca. Predefinito: `false`.
|
||||
- Le ricerche vengono eseguite solo dopo che accesso al gruppo, autorizzazione dei comandi e mention gating hanno permesso il passaggio del messaggio.
|
||||
- Le ricerche vengono eseguite solo dopo che l'accesso al gruppo, l'autorizzazione ai comandi e il filtro delle menzioni hanno consentito il passaggio del messaggio.
|
||||
- Vengono arricchiti solo i partecipanti telefonici senza nome.
|
||||
- I numeri di telefono grezzi restano il fallback quando non viene trovata alcuna corrispondenza locale.
|
||||
|
||||
@ -193,13 +192,13 @@ I Webhook di gruppo BlueBubbles spesso includono solo gli indirizzi grezzi dei p
|
||||
}
|
||||
```
|
||||
|
||||
### Mention gating (gruppi)
|
||||
### Filtro delle menzioni (gruppi)
|
||||
|
||||
BlueBubbles supporta il mention gating per le chat di gruppo, in linea con il comportamento di iMessage/WhatsApp:
|
||||
BlueBubbles supporta il filtro delle menzioni per le chat di gruppo, in linea con il comportamento di iMessage/WhatsApp:
|
||||
|
||||
- Usa `agents.list[].groupChat.mentionPatterns` (oppure `messages.groupChat.mentionPatterns`) per rilevare le menzioni.
|
||||
- Usa `agents.list[].groupChat.mentionPatterns` (o `messages.groupChat.mentionPatterns`) per rilevare le menzioni.
|
||||
- Quando `requireMention` è abilitato per un gruppo, l'agente risponde solo quando viene menzionato.
|
||||
- I comandi di controllo inviati da mittenti autorizzati aggirano il mention gating.
|
||||
- I comandi di controllo provenienti da mittenti autorizzati bypassano il filtro delle menzioni.
|
||||
|
||||
Configurazione per gruppo:
|
||||
|
||||
@ -210,7 +209,7 @@ Configurazione per gruppo:
|
||||
groupPolicy: "allowlist",
|
||||
groupAllowFrom: ["+15555550123"],
|
||||
groups: {
|
||||
"*": { requireMention: true }, // predefinito per tutti i gruppi
|
||||
"*": { requireMention: true }, // valore predefinito per tutti i gruppi
|
||||
"iMessage;-;chat123": { requireMention: false }, // override per un gruppo specifico
|
||||
},
|
||||
},
|
||||
@ -218,15 +217,15 @@ Configurazione per gruppo:
|
||||
}
|
||||
```
|
||||
|
||||
### Command gating
|
||||
### Filtro dei comandi
|
||||
|
||||
- I comandi di controllo (es. `/config`, `/model`) richiedono autorizzazione.
|
||||
- Usa `allowFrom` e `groupAllowFrom` per determinare l'autorizzazione dei comandi.
|
||||
- I mittenti autorizzati possono eseguire i comandi di controllo anche senza menzionare nei gruppi.
|
||||
- I comandi di controllo (ad es. `/config`, `/model`) richiedono autorizzazione.
|
||||
- Usa `allowFrom` e `groupAllowFrom` per determinare l'autorizzazione ai comandi.
|
||||
- I mittenti autorizzati possono eseguire comandi di controllo anche senza menzionare nei gruppi.
|
||||
|
||||
### Prompt di sistema per gruppo
|
||||
|
||||
Ogni voce sotto `channels.bluebubbles.groups.*` accetta una stringa `systemPrompt` facoltativa. Il valore viene iniettato nel prompt di sistema dell'agente a ogni turno che gestisce un messaggio in quel gruppo, così puoi impostare regole di persona o comportamento per gruppo senza modificare i prompt dell'agente:
|
||||
Ogni voce sotto `channels.bluebubbles.groups.*` accetta una stringa facoltativa `systemPrompt`. Il valore viene inserito nel prompt di sistema dell'agente a ogni turno che gestisce un messaggio in quel gruppo, così puoi impostare regole di comportamento o persona specifiche per gruppo senza modificare i prompt dell'agente:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -242,11 +241,11 @@ Ogni voce sotto `channels.bluebubbles.groups.*` accetta una stringa `systemPromp
|
||||
}
|
||||
```
|
||||
|
||||
La chiave corrisponde a qualunque valore BlueBubbles riporti come `chatGuid` / `chatIdentifier` / `chatId` numerico per il gruppo, e una voce jolly `"*"` fornisce un valore predefinito per ogni gruppo senza una corrispondenza esatta (lo stesso schema usato da `requireMention` e dai criteri degli strumenti per gruppo). Le corrispondenze esatte hanno sempre la precedenza sul jolly. I DM ignorano questo campo; usa invece la personalizzazione del prompt a livello agente o account.
|
||||
La chiave corrisponde a qualunque valore BlueBubbles riporti come `chatGuid` / `chatIdentifier` / `chatId` numerico per il gruppo, e una voce jolly `"*"` fornisce un valore predefinito per ogni gruppo senza una corrispondenza esatta (lo stesso schema usato da `requireMention` e dai criteri degli strumenti per gruppo). Le corrispondenze esatte hanno sempre la precedenza sul jolly. I DM ignorano questo campo; usa invece la personalizzazione del prompt a livello di agente o di account.
|
||||
|
||||
#### Esempio pratico: risposte in thread e reazioni tapback (Private API)
|
||||
|
||||
Con la BlueBubbles Private API abilitata, i messaggi in entrata arrivano con ID messaggio brevi (ad esempio `[[reply_to:5]]`) e l'agente può chiamare `action=reply` per rispondere in thread a un messaggio specifico oppure `action=react` per aggiungere un tapback. Un `systemPrompt` per gruppo è un modo affidabile per fare in modo che l'agente scelga lo strumento corretto:
|
||||
Con la Private API di BlueBubbles abilitata, i messaggi in ingresso arrivano con ID messaggio brevi (ad esempio `[[reply_to:5]]`) e l'agente può chiamare `action=reply` per creare un thread su un messaggio specifico oppure `action=react` per aggiungere un tapback. Un `systemPrompt` per gruppo è un modo affidabile per far sì che l'agente scelga lo strumento corretto:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -256,12 +255,12 @@ Con la BlueBubbles Private API abilitata, i messaggi in entrata arrivano con ID
|
||||
"iMessage;+;chat-family": {
|
||||
systemPrompt: [
|
||||
"Quando rispondi in questo gruppo, chiama sempre action=reply con il",
|
||||
"messageId [[reply_to:N]] dal contesto in modo che la tua risposta venga messa in thread",
|
||||
"messageId [[reply_to:N]] dal contesto così la tua risposta verrà inserita in thread",
|
||||
"sotto il messaggio che l'ha attivata. Non inviare mai un nuovo messaggio scollegato.",
|
||||
"",
|
||||
"Per brevi conferme ('ok', 'ricevuto', 'ci penso io'), usa",
|
||||
"action=react con un'emoji tapback appropriata (❤️, 👍, 😂, ‼️, ❓)",
|
||||
"invece di inviare una risposta di testo.",
|
||||
"invece di inviare una risposta testuale.",
|
||||
].join(" "),
|
||||
},
|
||||
},
|
||||
@ -270,20 +269,20 @@ Con la BlueBubbles Private API abilitata, i messaggi in entrata arrivano con ID
|
||||
}
|
||||
```
|
||||
|
||||
Le reazioni tapback e le risposte in thread richiedono entrambe la BlueBubbles Private API; consulta [Azioni avanzate](#azioni-avanzate) e [ID messaggio](#message-ids-short-vs-full) per i meccanismi sottostanti.
|
||||
Sia le reazioni tapback sia le risposte in thread richiedono la Private API di BlueBubbles; vedi [Azioni avanzate](#advanced-actions) e [ID messaggio](#message-ids-short-vs-full) per i meccanismi sottostanti.
|
||||
|
||||
## Binding conversazione ACP
|
||||
## Associazioni di conversazione ACP
|
||||
|
||||
Le chat BlueBubbles possono essere trasformate in workspace ACP persistenti senza cambiare il livello di trasporto.
|
||||
Le chat BlueBubbles possono essere trasformate in spazi di lavoro ACP durevoli senza cambiare il livello di trasporto.
|
||||
|
||||
Flusso rapido per l'operatore:
|
||||
Flusso rapido per operatori:
|
||||
|
||||
- Esegui `/acp spawn codex --bind here` all'interno del DM o del gruppo consentito.
|
||||
- I messaggi futuri nella stessa conversazione BlueBubbles verranno instradati alla sessione ACP generata.
|
||||
- I messaggi successivi nella stessa conversazione BlueBubbles verranno instradati alla sessione ACP avviata.
|
||||
- `/new` e `/reset` reimpostano sul posto la stessa sessione ACP associata.
|
||||
- `/acp close` chiude la sessione ACP e rimuove il binding.
|
||||
- `/acp close` chiude la sessione ACP e rimuove l'associazione.
|
||||
|
||||
Sono supportati anche i binding persistenti configurati tramite voci `bindings[]` di primo livello con `type: "acp"` e `match.channel: "bluebubbles"`.
|
||||
Sono supportate anche associazioni persistenti configurate tramite voci `bindings[]` di primo livello con `type: "acp"` e `match.channel: "bluebubbles"`.
|
||||
|
||||
`match.peer.id` può usare qualsiasi formato di destinazione BlueBubbles supportato:
|
||||
|
||||
@ -292,7 +291,7 @@ Sono supportati anche i binding persistenti configurati tramite voci `bindings[]
|
||||
- `chat_guid:<guid>`
|
||||
- `chat_identifier:<identifier>`
|
||||
|
||||
Per binding di gruppo stabili, preferisci `chat_id:*` o `chat_identifier:*`.
|
||||
Per associazioni di gruppo stabili, preferisci `chat_id:*` o `chat_identifier:*`.
|
||||
|
||||
Esempio:
|
||||
|
||||
@ -324,13 +323,13 @@ Esempio:
|
||||
}
|
||||
```
|
||||
|
||||
Consulta [ACP Agents](/it/tools/acp-agents) per il comportamento condiviso dei binding ACP.
|
||||
Vedi [ACP Agents](/it/tools/acp-agents) per il comportamento condiviso delle associazioni ACP.
|
||||
|
||||
## Digitazione + conferme di lettura
|
||||
|
||||
- **Indicatori di digitazione**: inviati automaticamente prima e durante la generazione della risposta.
|
||||
- **Conferme di lettura**: controllate da `channels.bluebubbles.sendReadReceipts` (predefinito: `true`).
|
||||
- **Indicatori di digitazione**: OpenClaw invia eventi di inizio digitazione; BlueBubbles cancella automaticamente la digitazione all'invio o al timeout (l'arresto manuale tramite DELETE non è affidabile).
|
||||
- **Indicatori di digitazione**: OpenClaw invia eventi di inizio digitazione; BlueBubbles cancella automaticamente lo stato di digitazione all'invio o al timeout (l'interruzione manuale tramite DELETE non è affidabile).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -352,16 +351,16 @@ BlueBubbles supporta azioni avanzate sui messaggi quando abilitate nella configu
|
||||
bluebubbles: {
|
||||
actions: {
|
||||
reactions: true, // tapback (predefinito: true)
|
||||
edit: true, // modifica i messaggi inviati (macOS 13+, non funzionante su macOS 26 Tahoe)
|
||||
edit: true, // modifica i messaggi inviati (macOS 13+, non funziona su macOS 26 Tahoe)
|
||||
unsend: true, // annulla l'invio dei messaggi (macOS 13+)
|
||||
reply: true, // risposte in thread tramite GUID del messaggio
|
||||
sendWithEffect: true, // effetti dei messaggi (slam, loud, ecc.)
|
||||
renameGroup: true, // rinomina le chat di gruppo
|
||||
setGroupIcon: true, // imposta l'icona/foto della chat di gruppo (instabile su macOS 26 Tahoe)
|
||||
setGroupIcon: true, // imposta icona/foto della chat di gruppo (instabile su macOS 26 Tahoe)
|
||||
addParticipant: true, // aggiungi partecipanti ai gruppi
|
||||
removeParticipant: true, // rimuovi partecipanti dai gruppi
|
||||
leaveGroup: true, // abbandona le chat di gruppo
|
||||
sendAttachment: true, // invia allegati/media
|
||||
sendAttachment: true, // invia allegati/contenuti multimediali
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -376,13 +375,13 @@ Azioni disponibili:
|
||||
- **reply**: risponde a un messaggio specifico (`messageId`, `text`, `to`)
|
||||
- **sendWithEffect**: invia con effetto iMessage (`text`, `to`, `effectId`)
|
||||
- **renameGroup**: rinomina una chat di gruppo (`chatGuid`, `displayName`)
|
||||
- **setGroupIcon**: imposta l'icona/foto di una chat di gruppo (`chatGuid`, `media`) — instabile su macOS 26 Tahoe (l'API può restituire successo ma l'icona non si sincronizza).
|
||||
- **setGroupIcon**: imposta l'icona/foto di una chat di gruppo (`chatGuid`, `media`) — instabile su macOS 26 Tahoe (l'API può restituire esito positivo ma l'icona non si sincronizza).
|
||||
- **addParticipant**: aggiunge qualcuno a un gruppo (`chatGuid`, `address`)
|
||||
- **removeParticipant**: rimuove qualcuno da un gruppo (`chatGuid`, `address`)
|
||||
- **leaveGroup**: abbandona una chat di gruppo (`chatGuid`)
|
||||
- **upload-file**: invia media/file (`to`, `buffer`, `filename`, `asVoice`)
|
||||
- Memo vocali: imposta `asVoice: true` con audio **MP3** o **CAF** per inviare come messaggio vocale iMessage. BlueBubbles converte MP3 → CAF quando invia memo vocali.
|
||||
- Alias legacy: `sendAttachment` continua a funzionare, ma `upload-file` è il nome di azione canonico.
|
||||
- **upload-file**: invia contenuti multimediali/file (`to`, `buffer`, `filename`, `asVoice`)
|
||||
- Memo vocali: imposta `asVoice: true` con audio **MP3** o **CAF** per inviare un messaggio vocale iMessage. BlueBubbles converte MP3 → CAF quando invia memo vocali.
|
||||
- Alias legacy: `sendAttachment` continua a funzionare, ma `upload-file` è il nome canonico dell'azione.
|
||||
|
||||
### ID messaggio (brevi vs completi)
|
||||
|
||||
@ -390,19 +389,116 @@ OpenClaw può mostrare ID messaggio _brevi_ (ad es. `1`, `2`) per risparmiare to
|
||||
|
||||
- `MessageSid` / `ReplyToId` possono essere ID brevi.
|
||||
- `MessageSidFull` / `ReplyToIdFull` contengono gli ID completi del provider.
|
||||
- Gli ID brevi sono in memoria; possono scadere al riavvio o con l'espulsione dalla cache.
|
||||
- Le azioni accettano `messageId` brevi o completi, ma gli ID brevi genereranno un errore se non sono più disponibili.
|
||||
- Gli ID brevi sono in memoria; possono scadere al riavvio o con lo svuotamento della cache.
|
||||
- Le azioni accettano `messageId` brevi o completi, ma gli ID brevi genereranno errore se non sono più disponibili.
|
||||
|
||||
Usa gli ID completi per automazioni persistenti e archiviazione:
|
||||
Usa gli ID completi per automazioni e archiviazione durevoli:
|
||||
|
||||
- Template: `{{MessageSidFull}}`, `{{ReplyToIdFull}}`
|
||||
- Contesto: `MessageSidFull` / `ReplyToIdFull` nei payload in entrata
|
||||
- Contesto: `MessageSidFull` / `ReplyToIdFull` nei payload in ingresso
|
||||
|
||||
Consulta [Configuration](/it/gateway/configuration) per le variabili dei template.
|
||||
Vedi [Configurazione](/it/gateway/configuration) per le variabili dei template.
|
||||
|
||||
## Coalescenza dei DM con invio suddiviso (comando + URL in un'unica composizione)
|
||||
|
||||
Quando un utente digita un comando e un URL insieme in iMessage — ad esempio `Dump https://example.com/article` — Apple suddivide l'invio in **due consegne Webhook separate**:
|
||||
|
||||
1. Un messaggio di testo (`"Dump"`).
|
||||
2. Un balloon di anteprima URL (`"https://..."`) con immagini di anteprima OG come allegati.
|
||||
|
||||
I due Webhook arrivano a OpenClaw a distanza di ~0,8-2,0 s nella maggior parte delle configurazioni. Senza coalescenza, l'agente riceve solo il comando nel turno 1, risponde (spesso "mandami l'URL") e vede l'URL solo nel turno 2 — a quel punto il contesto del comando è già perso.
|
||||
|
||||
`channels.bluebubbles.coalesceSameSenderDms` consente a un DM di unire Webhook consecutivi dello stesso mittente in un unico turno agente. Le chat di gruppo continuano a essere indicizzate per messaggio così da preservare la struttura multiutente dei turni.
|
||||
|
||||
### Quando abilitarlo
|
||||
|
||||
Abilitalo quando:
|
||||
|
||||
- Distribuisci Skills che si aspettano `command + payload` in un unico messaggio (dump, paste, save, queue, ecc.).
|
||||
- I tuoi utenti incollano URL, immagini o contenuti lunghi insieme ai comandi.
|
||||
- Puoi accettare la latenza aggiuntiva del turno DM (vedi sotto).
|
||||
|
||||
Lascialo disabilitato quando:
|
||||
|
||||
- Ti serve la latenza minima dei comandi per trigger DM a parola singola.
|
||||
- Tutti i tuoi flussi sono comandi one-shot senza payload successivi.
|
||||
|
||||
### Abilitazione
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
bluebubbles: {
|
||||
coalesceSameSenderDms: true, // attiva esplicitamente (predefinito: false)
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Con il flag attivo e senza un `messages.inbound.byChannel.bluebubbles` esplicito, la finestra di debounce si amplia a **2500 ms** (il valore predefinito senza coalescenza è 500 ms). Serve una finestra più ampia: la cadenza di invio suddiviso di Apple di 0,8-2,0 s non rientra nel valore predefinito più stretto.
|
||||
|
||||
Per regolare tu stesso la finestra:
|
||||
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
inbound: {
|
||||
byChannel: {
|
||||
// 2500 ms funziona nella maggior parte delle configurazioni; aumenta a 4000 ms se il tuo Mac è lento
|
||||
// o sotto pressione di memoria (in questi casi il ritardo osservato può superare i 2 s).
|
||||
bluebubbles: 2500,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Compromessi
|
||||
|
||||
- **Latenza aggiuntiva per i comandi di controllo nei DM.** Con il flag attivo, i messaggi di comando di controllo nei DM (come `Dump`, `Save`, ecc.) ora attendono fino alla finestra di debounce prima dell'invio, nel caso stia arrivando un Webhook di payload. I comandi nelle chat di gruppo continuano a essere inviati subito.
|
||||
- **L'output unito è limitato** — il testo unito è limitato a 4000 caratteri con un marcatore esplicito `…[truncated]`; gli allegati sono limitati a 20; le voci sorgente sono limitate a 10 (oltre quel numero vengono mantenuti il primo e il più recente). Ogni `messageId` sorgente raggiunge comunque la deduplica in ingresso, quindi un successivo replay MessagePoller di un singolo evento viene riconosciuto come duplicato.
|
||||
- **Attivazione esplicita, per canale.** Gli altri canali (Telegram, WhatsApp, Slack, …) non sono interessati.
|
||||
|
||||
### Scenari e cosa vede l'agente
|
||||
|
||||
| L'utente compone | Apple consegna | Flag disattivato (predefinito) | Flag attivo + finestra 2500 ms |
|
||||
| ------------------------------------------------------------------ | ------------------------- | --------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| `Dump https://example.com` (un solo invio) | 2 Webhook a ~1 s di distanza | Due turni agente: solo "Dump", poi URL | Un turno: testo unito `Dump https://example.com` |
|
||||
| `Save this 📎image.jpg caption` (allegato + testo) | 2 Webhook | Due turni | Un turno: testo + immagine |
|
||||
| `/status` (comando autonomo) | 1 Webhook | Invio immediato | **Attende fino alla finestra, poi invia** |
|
||||
| URL incollato da solo | 1 Webhook | Invio immediato | Invio immediato (una sola voce nel bucket) |
|
||||
| Testo + URL inviati come due messaggi deliberatamente separati, a minuti di distanza | 2 Webhook fuori finestra | Due turni | Due turni (la finestra scade tra i due) |
|
||||
| Raffica rapida (>10 piccoli DM nella finestra) | N Webhook | N turni | Un turno, output limitato (primo + più recente, con limiti su testo/allegati) |
|
||||
|
||||
### Risoluzione dei problemi della coalescenza degli invii suddivisi
|
||||
|
||||
Se il flag è attivo e gli invii suddivisi arrivano ancora come due turni, controlla ogni livello:
|
||||
|
||||
1. **Configurazione realmente caricata.**
|
||||
|
||||
```
|
||||
grep coalesceSameSenderDms ~/.openclaw/openclaw.json
|
||||
```
|
||||
|
||||
Poi `openclaw gateway restart` — il flag viene letto alla creazione del registro di debounce.
|
||||
|
||||
2. **Finestra di debounce sufficientemente ampia per la tua configurazione.** Controlla il log del server BlueBubbles in `~/Library/Logs/bluebubbles-server/main.log`:
|
||||
|
||||
```
|
||||
grep -E "Dispatching event to webhook" main.log | tail -20
|
||||
```
|
||||
|
||||
Misura il ritardo tra l'invio del testo stile `"Dump"` e il successivo invio `"https://..."; Attachments:`. Aumenta `messages.inbound.byChannel.bluebubbles` in modo da coprire comodamente quel ritardo.
|
||||
|
||||
3. **I timestamp JSONL della sessione ≠ arrivo del Webhook.** I timestamp degli eventi di sessione (`~/.openclaw/agents/<id>/sessions/*.jsonl`) riflettono il momento in cui il Gateway consegna un messaggio all'agente, **non** quando il Webhook è arrivato. Un secondo messaggio in coda etichettato `[Queued messages while agent was busy]` significa che il primo turno era ancora in esecuzione quando è arrivato il secondo Webhook — il bucket di coalescenza era già stato svuotato. Regola la finestra usando il log del server BB, non il log di sessione.
|
||||
|
||||
4. **Pressione di memoria che rallenta l'invio della risposta.** Su macchine più piccole (8 GB), i turni dell'agente possono richiedere abbastanza tempo da far svuotare il bucket di coalescenza prima che la risposta sia completata, e l'URL arriva come secondo turno in coda. Controlla `memory_pressure` e `ps -o rss -p $(pgrep openclaw-gateway)`; se il Gateway supera ~500 MB RSS e il compressore è attivo, chiudi altri processi pesanti oppure passa a un host più grande.
|
||||
|
||||
5. **Gli invii con citazione di risposta seguono un percorso diverso.** Se l'utente ha toccato `Dump` come **risposta** a un balloon URL esistente (iMessage mostra un badge "1 Reply" sulla bolla Dump), l'URL si trova in `replyToBody`, non in un secondo Webhook. La coalescenza non si applica — è un aspetto di Skill/prompt, non del debounce.
|
||||
|
||||
## Streaming a blocchi
|
||||
|
||||
Controlla se le risposte vengono inviate come singolo messaggio o trasmesse in streaming a blocchi:
|
||||
Controlla se le risposte vengono inviate come un unico messaggio o in streaming a blocchi:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -416,35 +512,36 @@ Controlla se le risposte vengono inviate come singolo messaggio o trasmesse in s
|
||||
|
||||
## Media + limiti
|
||||
|
||||
- Gli allegati in entrata vengono scaricati e memorizzati nella cache dei media.
|
||||
- Limite media tramite `channels.bluebubbles.mediaMaxMb` per i media in entrata e in uscita (predefinito: 8 MB).
|
||||
- Gli allegati in ingresso vengono scaricati e memorizzati nella cache dei media.
|
||||
- Limite dei media tramite `channels.bluebubbles.mediaMaxMb` per i media in ingresso e in uscita (predefinito: 8 MB).
|
||||
- Il testo in uscita viene suddiviso in blocchi secondo `channels.bluebubbles.textChunkLimit` (predefinito: 4000 caratteri).
|
||||
|
||||
## Riferimento configurazione
|
||||
|
||||
Configurazione completa: [Configuration](/it/gateway/configuration)
|
||||
Configurazione completa: [Configurazione](/it/gateway/configuration)
|
||||
|
||||
Opzioni del provider:
|
||||
|
||||
- `channels.bluebubbles.enabled`: abilita/disabilita il canale.
|
||||
- `channels.bluebubbles.serverUrl`: URL di base dell'API REST BlueBubbles.
|
||||
- `channels.bluebubbles.serverUrl`: URL di base della REST API di BlueBubbles.
|
||||
- `channels.bluebubbles.password`: password API.
|
||||
- `channels.bluebubbles.webhookPath`: percorso dell'endpoint Webhook (predefinito: `/bluebubbles-webhook`).
|
||||
- `channels.bluebubbles.dmPolicy`: `pairing | allowlist | open | disabled` (predefinito: `pairing`).
|
||||
- `channels.bluebubbles.allowFrom`: allowlist DM (handle, email, numeri E.164, `chat_id:*`, `chat_guid:*`).
|
||||
- `channels.bluebubbles.groupPolicy`: `open | allowlist | disabled` (predefinito: `allowlist`).
|
||||
- `channels.bluebubbles.groupAllowFrom`: allowlist mittenti di gruppo.
|
||||
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: su macOS, arricchisce facoltativamente i partecipanti di gruppo senza nome dai Contatti locali dopo il superamento dei controlli. Predefinito: `false`.
|
||||
- `channels.bluebubbles.groupAllowFrom`: allowlist dei mittenti dei gruppi.
|
||||
- `channels.bluebubbles.enrichGroupParticipantsFromContacts`: su macOS, arricchisce facoltativamente i partecipanti di gruppo senza nome dai Contatti locali dopo il superamento dei controlli di accesso. Predefinito: `false`.
|
||||
- `channels.bluebubbles.groups`: configurazione per gruppo (`requireMention`, ecc.).
|
||||
- `channels.bluebubbles.sendReadReceipts`: invia conferme di lettura (predefinito: `true`).
|
||||
- `channels.bluebubbles.blockStreaming`: abilita lo streaming a blocchi (predefinito: `false`; richiesto per le risposte in streaming).
|
||||
- `channels.bluebubbles.textChunkLimit`: dimensione dei blocchi in uscita in caratteri (predefinito: 4000).
|
||||
- `channels.bluebubbles.sendTimeoutMs`: timeout per richiesta in ms per gli invii di testo in uscita tramite `/api/v1/message/text` (predefinito: 30000). Aumentalo su configurazioni macOS 26 in cui gli invii iMessage Private API possono bloccarsi per oltre 60 secondi all'interno del framework iMessage; ad esempio `45000` o `60000`. Sonde, ricerche chat, reazioni, modifiche e controlli di integrità mantengono attualmente il timeout più breve di 10 s; l'estensione della copertura a reazioni e modifiche è prevista in seguito. Override per account: `channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`.
|
||||
- `channels.bluebubbles.chunkMode`: `length` (predefinito) divide solo quando viene superato `textChunkLimit`; `newline` divide sulle righe vuote (confini dei paragrafi) prima della suddivisione per lunghezza.
|
||||
- `channels.bluebubbles.mediaMaxMb`: limite dei media in entrata/uscita in MB (predefinito: 8).
|
||||
- `channels.bluebubbles.mediaLocalRoots`: allowlist esplicita di directory locali assolute consentite per i percorsi media locali in uscita. L'invio di percorsi locali è negato per impostazione predefinita se questo non è configurato. Override per account: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`.
|
||||
- `channels.bluebubbles.sendTimeoutMs`: timeout per richiesta in ms per l'invio del testo in uscita tramite `/api/v1/message/text` (predefinito: 30000). Aumentalo su configurazioni macOS 26 in cui gli invii iMessage con Private API possono bloccarsi per oltre 60 secondi all'interno del framework iMessage; ad esempio `45000` o `60000`. Le probe, le ricerche chat, le reazioni, le modifiche e i controlli di integrità mantengono attualmente il valore predefinito più breve di 10 s; l'estensione della copertura a reazioni e modifiche è prevista come seguito. Override per account: `channels.bluebubbles.accounts.<accountId>.sendTimeoutMs`.
|
||||
- `channels.bluebubbles.chunkMode`: `length` (predefinito) suddivide solo quando supera `textChunkLimit`; `newline` suddivide sulle righe vuote (confini dei paragrafi) prima della suddivisione per lunghezza.
|
||||
- `channels.bluebubbles.mediaMaxMb`: limite dei media in ingresso/uscita in MB (predefinito: 8).
|
||||
- `channels.bluebubbles.mediaLocalRoots`: allowlist esplicita di directory locali assolute consentite per i percorsi di media locali in uscita. Per impostazione predefinita, gli invii da percorsi locali vengono rifiutati finché questa opzione non viene configurata. Override per account: `channels.bluebubbles.accounts.<accountId>.mediaLocalRoots`.
|
||||
- `channels.bluebubbles.coalesceSameSenderDms`: unisce Webhook DM consecutivi dello stesso mittente in un unico turno agente, così l'invio suddiviso testo+URL di Apple arriva come un singolo messaggio (predefinito: `false`). Vedi [Coalescenza dei DM con invio suddiviso](#coalescing-split-send-dms-command--url-in-one-composition) per scenari, regolazione della finestra e compromessi. Quando è abilitato senza un `messages.inbound.byChannel.bluebubbles` esplicito, amplia la finestra predefinita di debounce in ingresso da 500 ms a 2500 ms.
|
||||
- `channels.bluebubbles.historyLimit`: numero massimo di messaggi di gruppo per il contesto (0 disabilita).
|
||||
- `channels.bluebubbles.dmHistoryLimit`: limite cronologia DM.
|
||||
- `channels.bluebubbles.dmHistoryLimit`: limite della cronologia DM.
|
||||
- `channels.bluebubbles.actions`: abilita/disabilita azioni specifiche.
|
||||
- `channels.bluebubbles.accounts`: configurazione multi-account.
|
||||
|
||||
@ -461,31 +558,32 @@ Preferisci `chat_guid` per un instradamento stabile:
|
||||
- `chat_id:123`
|
||||
- `chat_identifier:...`
|
||||
- Handle diretti: `+15555550123`, `user@example.com`
|
||||
- Se un handle diretto non ha una chat DM esistente, OpenClaw ne creerà una tramite `POST /api/v1/chat/new`. Questo richiede che la BlueBubbles Private API sia abilitata.
|
||||
- Se un handle diretto non ha una chat DM esistente, OpenClaw ne creerà una tramite `POST /api/v1/chat/new`. Questo richiede che la Private API di BlueBubbles sia abilitata.
|
||||
|
||||
## Sicurezza
|
||||
|
||||
- Le richieste Webhook vengono autenticate confrontando i parametri di query o gli header `guid`/`password` con `channels.bluebubbles.password`.
|
||||
- Mantieni segreti la password API e l'endpoint Webhook (trattali come credenziali).
|
||||
- Non esiste alcuna bypass localhost per l'autenticazione Webhook BlueBubbles. Se fai da proxy al traffico Webhook, mantieni la password BlueBubbles nella richiesta end-to-end. `gateway.trustedProxies` non sostituisce qui `channels.bluebubbles.password`. Consulta [Gateway security](/it/gateway/security#reverse-proxy-configuration).
|
||||
- Abilita HTTPS + regole firewall sul server BlueBubbles se lo esponi fuori dalla LAN.
|
||||
- Non esiste alcuna eccezione localhost per l'autenticazione Webhook di BlueBubbles. Se instradi il traffico Webhook tramite proxy, mantieni la password BlueBubbles nella richiesta end-to-end. `gateway.trustedProxies` qui non sostituisce `channels.bluebubbles.password`. Vedi [Sicurezza del Gateway](/it/gateway/security#reverse-proxy-configuration).
|
||||
- Abilita HTTPS + regole firewall sul server BlueBubbles se lo esponi fuori dalla tua LAN.
|
||||
|
||||
## Risoluzione dei problemi
|
||||
|
||||
- Se gli eventi di digitazione/lettura smettono di funzionare, controlla i log Webhook BlueBubbles e verifica che il percorso del Gateway corrisponda a `channels.bluebubbles.webhookPath`.
|
||||
- I codici di abbinamento scadono dopo un'ora; usa `openclaw pairing list bluebubbles` e `openclaw pairing approve bluebubbles <code>`.
|
||||
- Le reazioni richiedono la BlueBubbles private API (`POST /api/v1/message/react`); assicurati che la versione del server la esponga.
|
||||
- Modifica/annullamento invio richiedono macOS 13+ e una versione compatibile del server BlueBubbles. Su macOS 26 (Tahoe), la modifica al momento non funziona a causa di cambiamenti della private API.
|
||||
- Gli aggiornamenti dell'icona del gruppo possono essere instabili su macOS 26 (Tahoe): l'API può restituire successo ma la nuova icona non si sincronizza.
|
||||
- OpenClaw nasconde automaticamente le azioni note come non funzionanti in base alla versione macOS del server BlueBubbles. Se la modifica compare ancora su macOS 26 (Tahoe), disabilitala manualmente con `channels.bluebubbles.actions.edit=false`.
|
||||
- Se gli eventi di digitazione/lettura smettono di funzionare, controlla i log Webhook di BlueBubbles e verifica che il percorso del Gateway corrisponda a `channels.bluebubbles.webhookPath`.
|
||||
- I codici di associazione scadono dopo un'ora; usa `openclaw pairing list bluebubbles` e `openclaw pairing approve bluebubbles <code>`.
|
||||
- Le reazioni richiedono la private API di BlueBubbles (`POST /api/v1/message/react`); assicurati che la versione del server la esponga.
|
||||
- Modifica/annullamento dell'invio richiedono macOS 13+ e una versione del server BlueBubbles compatibile. Su macOS 26 (Tahoe), la modifica è attualmente non funzionante a causa di cambiamenti della private API.
|
||||
- Gli aggiornamenti dell'icona di gruppo possono essere instabili su macOS 26 (Tahoe): l'API può restituire esito positivo ma la nuova icona non si sincronizza.
|
||||
- OpenClaw nasconde automaticamente le azioni note come non funzionanti in base alla versione macOS del server BlueBubbles. Se la modifica appare ancora su macOS 26 (Tahoe), disabilitala manualmente con `channels.bluebubbles.actions.edit=false`.
|
||||
- `coalesceSameSenderDms` è abilitato ma gli invii suddivisi (ad esempio `Dump` + URL) arrivano ancora come due turni: consulta la checklist di [risoluzione dei problemi della coalescenza degli invii suddivisi](#split-send-coalescing-troubleshooting) — le cause comuni sono una finestra di debounce troppo stretta, timestamp del log di sessione interpretati erroneamente come arrivo del Webhook, oppure un invio con citazione di risposta (che usa `replyToBody`, non un secondo Webhook).
|
||||
- Per informazioni su stato/integrità: `openclaw status --all` oppure `openclaw status --deep`.
|
||||
|
||||
Per il riferimento generale al flusso dei canali, consulta [Channels](/it/channels) e la guida [Plugins](/it/tools/plugin).
|
||||
Per il riferimento generale sul flusso dei canali, vedi [Canali](/it/channels) e la guida [Plugins](/it/tools/plugin).
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Channels Overview](/it/channels) — tutti i canali supportati
|
||||
- [Pairing](/it/channels/pairing) — autenticazione DM e flusso di abbinamento
|
||||
- [Groups](/it/channels/groups) — comportamento delle chat di gruppo e mention gating
|
||||
- [Channel Routing](/it/channels/channel-routing) — instradamento delle sessioni per i messaggi
|
||||
- [Security](/it/gateway/security) — modello di accesso e hardening
|
||||
- [Panoramica dei canali](/it/channels) — tutti i canali supportati
|
||||
- [Pairing](/it/channels/pairing) — autenticazione DM e flusso di associazione
|
||||
- [Gruppi](/it/channels/groups) — comportamento della chat di gruppo e filtro delle menzioni
|
||||
- [Instradamento dei canali](/it/channels/channel-routing) — instradamento della sessione per i messaggi
|
||||
- [Sicurezza](/it/gateway/security) — modello di accesso e hardening
|
||||
|
||||
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- Configurazione di Slack o debug della modalità socket/HTTP di Slack
|
||||
summary: Configurazione e comportamento in fase di esecuzione di Slack (Socket Mode + URL delle richieste HTTP)
|
||||
- Configurare Slack o eseguire il debug della modalità socket/HTTP di Slack
|
||||
summary: Configurazione di Slack e comportamento in fase di esecuzione (Socket Mode + URL di richiesta HTTP)
|
||||
title: Slack
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T08:07:55Z"
|
||||
generated_at: "2026-04-21T13:35:23Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 4b80c1a612b8815c46c675b688639c207a481f367075996dde3858a83637313b
|
||||
source_hash: 2fe3c3c344e1c20c09b29773f4f68d2790751e76d8bbaa3c6157e3ff75978acf
|
||||
source_path: channels/slack.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Slack
|
||||
|
||||
Stato: pronto per la produzione per DM + canali tramite integrazioni dell'app Slack. La modalità predefinita è Socket Mode; sono supportati anche gli URL delle richieste HTTP.
|
||||
Stato: pronto per la produzione per DM + canali tramite integrazioni dell'app Slack. La modalità predefinita è Socket Mode; sono supportate anche le URL di richiesta HTTP.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Associazione" icon="link" href="/it/channels/pairing">
|
||||
Le DM di Slack usano per impostazione predefinita la modalità di associazione.
|
||||
<Card title="Abbinamento" icon="link" href="/it/channels/pairing">
|
||||
Le DM di Slack usano per impostazione predefinita la modalità di abbinamento.
|
||||
</Card>
|
||||
<Card title="Comandi slash" icon="terminal" href="/it/tools/slash-commands">
|
||||
Comportamento nativo dei comandi e catalogo dei comandi.
|
||||
</Card>
|
||||
<Card title="Risoluzione dei problemi del canale" icon="wrench" href="/it/channels/troubleshooting">
|
||||
Diagnostica cross-channel e procedure di riparazione.
|
||||
Diagnostica tra canali e playbook di riparazione.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -37,7 +37,7 @@ 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 uno spazio di lavoro per la tua app
|
||||
- incolla il [manifest di esempio](#manifest-and-scope-checklist) qui sotto e continua con la creazione
|
||||
- incolla il [manifesto di esempio](#manifest-and-scope-checklist) qui sotto e continua con la creazione
|
||||
- genera un **App-Level Token** (`xapp-...`) con `connections:write`
|
||||
- installa l'app e copia il **Bot Token** (`xoxb-...`) mostrato
|
||||
</Step>
|
||||
@ -57,7 +57,7 @@ Stato: pronto per la produzione per DM + canali tramite integrazioni dell'app Sl
|
||||
}
|
||||
```
|
||||
|
||||
Fallback tramite variabili d'ambiente (solo account predefinito):
|
||||
Variabili d'ambiente di fallback (solo account predefinito):
|
||||
|
||||
```bash
|
||||
SLACK_APP_TOKEN=xapp-...
|
||||
@ -66,7 +66,7 @@ SLACK_BOT_TOKEN=xoxb-...
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Avvia il gateway">
|
||||
<Step title="Avvia il Gateway">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -77,13 +77,13 @@ openclaw gateway
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="URL delle richieste HTTP">
|
||||
<Tab title="URL di richiesta HTTP">
|
||||
<Steps>
|
||||
<Step title="Crea una nuova app Slack">
|
||||
Nelle impostazioni dell'app Slack premi il pulsante **[Create New App](https://api.slack.com/apps/new)**:
|
||||
|
||||
- scegli **from a manifest** e seleziona uno spazio di lavoro per la tua app
|
||||
- incolla il [manifest di esempio](#manifest-and-scope-checklist) e aggiorna gli URL prima della creazione
|
||||
- incolla il [manifesto di esempio](#manifest-and-scope-checklist) e aggiorna le URL prima della creazione
|
||||
- salva il **Signing Secret** per la verifica delle richieste
|
||||
- installa l'app e copia il **Bot Token** (`xoxb-...`) mostrato
|
||||
|
||||
@ -106,14 +106,14 @@ openclaw gateway
|
||||
```
|
||||
|
||||
<Note>
|
||||
Usa percorsi webhook univoci per HTTP multi-account
|
||||
Usa percorsi Webhook univoci per HTTP multi-account
|
||||
|
||||
Assegna a ogni account un `webhookPath` distinto (predefinito `/slack/events`) in modo che le registrazioni non entrino in conflitto.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Avvia il gateway">
|
||||
<Step title="Avvia il Gateway">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -125,7 +125,7 @@ openclaw gateway
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Checklist di manifest e ambiti
|
||||
## Checklist di manifesto e ambiti
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Socket Mode (predefinita)">
|
||||
@ -134,7 +134,7 @@ openclaw gateway
|
||||
{
|
||||
"display_information": {
|
||||
"name": "OpenClaw",
|
||||
"description": "Connettore Slack per OpenClaw"
|
||||
"description": "Slack connector for OpenClaw"
|
||||
},
|
||||
"features": {
|
||||
"bot_user": {
|
||||
@ -148,7 +148,7 @@ openclaw gateway
|
||||
"slash_commands": [
|
||||
{
|
||||
"command": "/openclaw",
|
||||
"description": "Invia un messaggio a OpenClaw",
|
||||
"description": "Send a message to OpenClaw",
|
||||
"should_escape": false
|
||||
}
|
||||
]
|
||||
@ -205,13 +205,13 @@ openclaw gateway
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="URL delle richieste HTTP">
|
||||
<Tab title="URL di richiesta HTTP">
|
||||
|
||||
```json
|
||||
{
|
||||
"display_information": {
|
||||
"name": "OpenClaw",
|
||||
"description": "Connettore Slack per OpenClaw"
|
||||
"description": "Slack connector for OpenClaw"
|
||||
},
|
||||
"features": {
|
||||
"bot_user": {
|
||||
@ -225,7 +225,7 @@ openclaw gateway
|
||||
"slash_commands": [
|
||||
{
|
||||
"command": "/openclaw",
|
||||
"description": "Invia un messaggio a OpenClaw",
|
||||
"description": "Send a message to OpenClaw",
|
||||
"should_escape": false,
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
}
|
||||
@ -289,19 +289,19 @@ openclaw gateway
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Impostazioni aggiuntive del manifest
|
||||
### Impostazioni aggiuntive del manifesto
|
||||
|
||||
Mostra funzionalità diverse che estendono i valori predefiniti sopra.
|
||||
Espongono diverse funzionalità che estendono i valori predefiniti sopra indicati.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Comandi slash nativi facoltativi">
|
||||
|
||||
È possibile usare più [comandi slash nativi](#commands-and-slash-behavior) al posto di un singolo comando configurato, con alcune particolarità:
|
||||
È possibile usare più [comandi slash nativi](#commands-and-slash-behavior) invece di un singolo comando configurato, con alcune sfumature:
|
||||
|
||||
- Usa `/agentstatus` invece di `/status` perché il comando `/status` è riservato.
|
||||
- Non è possibile rendere disponibili più di 25 comandi slash contemporaneamente.
|
||||
|
||||
Sostituisci la sezione `features.slash_commands` esistente con un sottoinsieme dei [comandi disponibili](/it/tools/slash-commands#command-list):
|
||||
Sostituisci la sezione esistente `features.slash_commands` con un sottoinsieme dei [comandi disponibili](/it/tools/slash-commands#command-list):
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Socket Mode (predefinita)">
|
||||
@ -310,117 +310,117 @@ Mostra funzionalità diverse che estendono i valori predefiniti sopra.
|
||||
"slash_commands": [
|
||||
{
|
||||
"command": "/new",
|
||||
"description": "Avvia una nuova sessione",
|
||||
"description": "Start a new session",
|
||||
"usage_hint": "[model]"
|
||||
},
|
||||
{
|
||||
"command": "/reset",
|
||||
"description": "Reimposta la sessione corrente"
|
||||
"description": "Reset the current session"
|
||||
},
|
||||
{
|
||||
"command": "/compact",
|
||||
"description": "Compatta il contesto della sessione",
|
||||
"description": "Compact the session context",
|
||||
"usage_hint": "[instructions]"
|
||||
},
|
||||
{
|
||||
"command": "/stop",
|
||||
"description": "Interrompi l'esecuzione corrente"
|
||||
"description": "Stop the current run"
|
||||
},
|
||||
{
|
||||
"command": "/session",
|
||||
"description": "Gestisci la scadenza del binding del thread",
|
||||
"description": "Manage thread-binding expiry",
|
||||
"usage_hint": "idle <duration|off> or max-age <duration|off>"
|
||||
},
|
||||
{
|
||||
"command": "/think",
|
||||
"description": "Imposta il livello di ragionamento",
|
||||
"usage_hint": "<off|minimal|low|medium|high|xhigh>"
|
||||
"description": "Set the thinking level",
|
||||
"usage_hint": "<level>"
|
||||
},
|
||||
{
|
||||
"command": "/verbose",
|
||||
"description": "Attiva o disattiva l'output dettagliato",
|
||||
"description": "Toggle verbose output",
|
||||
"usage_hint": "on|off|full"
|
||||
},
|
||||
{
|
||||
"command": "/fast",
|
||||
"description": "Mostra o imposta la modalità rapida",
|
||||
"description": "Show or set fast mode",
|
||||
"usage_hint": "[status|on|off]"
|
||||
},
|
||||
{
|
||||
"command": "/reasoning",
|
||||
"description": "Attiva o disattiva la visibilità del ragionamento",
|
||||
"description": "Toggle reasoning visibility",
|
||||
"usage_hint": "[on|off|stream]"
|
||||
},
|
||||
{
|
||||
"command": "/elevated",
|
||||
"description": "Attiva o disattiva la modalità elevata",
|
||||
"description": "Toggle elevated mode",
|
||||
"usage_hint": "[on|off|ask|full]"
|
||||
},
|
||||
{
|
||||
"command": "/exec",
|
||||
"description": "Mostra o imposta i valori predefiniti di exec",
|
||||
"description": "Show or set exec defaults",
|
||||
"usage_hint": "host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>"
|
||||
},
|
||||
{
|
||||
"command": "/model",
|
||||
"description": "Mostra o imposta il modello",
|
||||
"description": "Show or set the model",
|
||||
"usage_hint": "[name|#|status]"
|
||||
},
|
||||
{
|
||||
"command": "/models",
|
||||
"description": "Elenca i provider o i modelli per un provider",
|
||||
"description": "List providers or models for a provider",
|
||||
"usage_hint": "[provider] [page] [limit=<n>|size=<n>|all]"
|
||||
},
|
||||
{
|
||||
"command": "/help",
|
||||
"description": "Mostra il riepilogo sintetico della guida"
|
||||
"description": "Show the short help summary"
|
||||
},
|
||||
{
|
||||
"command": "/commands",
|
||||
"description": "Mostra il catalogo dei comandi generato"
|
||||
"description": "Show the generated command catalog"
|
||||
},
|
||||
{
|
||||
"command": "/tools",
|
||||
"description": "Mostra cosa può usare in questo momento l'agente corrente",
|
||||
"description": "Show what the current agent can use right now",
|
||||
"usage_hint": "[compact|verbose]"
|
||||
},
|
||||
{
|
||||
"command": "/agentstatus",
|
||||
"description": "Mostra lo stato di runtime, incluso l'uso/quota del provider quando disponibile"
|
||||
"description": "Show runtime status, including provider usage/quota when available"
|
||||
},
|
||||
{
|
||||
"command": "/tasks",
|
||||
"description": "Elenca le attività in background attive/recenti per la sessione corrente"
|
||||
"description": "List active/recent background tasks for the current session"
|
||||
},
|
||||
{
|
||||
"command": "/context",
|
||||
"description": "Spiega come viene assemblato il contesto",
|
||||
"description": "Explain how context is assembled",
|
||||
"usage_hint": "[list|detail|json]"
|
||||
},
|
||||
{
|
||||
"command": "/whoami",
|
||||
"description": "Mostra la tua identità mittente"
|
||||
"description": "Show your sender identity"
|
||||
},
|
||||
{
|
||||
"command": "/skill",
|
||||
"description": "Esegui una skill per nome",
|
||||
"description": "Run a skill by name",
|
||||
"usage_hint": "<name> [input]"
|
||||
},
|
||||
{
|
||||
"command": "/btw",
|
||||
"description": "Fai una domanda laterale senza modificare il contesto della sessione",
|
||||
"description": "Ask a side question without changing session context",
|
||||
"usage_hint": "<question>"
|
||||
},
|
||||
{
|
||||
"command": "/usage",
|
||||
"description": "Controlla il piè di pagina dell'utilizzo o mostra il riepilogo dei costi",
|
||||
"description": "Control the usage footer or show cost summary",
|
||||
"usage_hint": "off|tokens|full|cost"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab title="URL delle richieste HTTP">
|
||||
<Tab title="URL di richiesta HTTP">
|
||||
|
||||
```json
|
||||
"slash_commands": [
|
||||
@ -449,13 +449,13 @@ Mostra funzionalità diverse che estendono i valori predefiniti sopra.
|
||||
{
|
||||
"command": "/session",
|
||||
"description": "Gestisci la scadenza del binding del thread",
|
||||
"usage_hint": "idle <duration|off> or max-age <duration|off>",
|
||||
"usage_hint": "idle <duration|off> o max-age <duration|off>",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/think",
|
||||
"description": "Imposta il livello di ragionamento",
|
||||
"usage_hint": "<off|minimal|low|medium|high|xhigh>",
|
||||
"description": "Imposta il livello di pensiero",
|
||||
"usage_hint": "<level>",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
@ -502,7 +502,7 @@ Mostra funzionalità diverse che estendono i valori predefiniti sopra.
|
||||
},
|
||||
{
|
||||
"command": "/help",
|
||||
"description": "Mostra il riepilogo sintetico della guida",
|
||||
"description": "Mostra il breve riepilogo della guida",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
@ -512,13 +512,13 @@ Mostra funzionalità diverse che estendono i valori predefiniti sopra.
|
||||
},
|
||||
{
|
||||
"command": "/tools",
|
||||
"description": "Mostra cosa può usare in questo momento l'agente corrente",
|
||||
"description": "Mostra ciò che l'agente corrente può usare in questo momento",
|
||||
"usage_hint": "[compact|verbose]",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/agentstatus",
|
||||
"description": "Mostra lo stato di runtime, incluso l'uso/quota del provider quando disponibile",
|
||||
"description": "Mostra lo stato di runtime, incluso l'uso/la quota del provider quando disponibile",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
@ -545,13 +545,13 @@ Mostra funzionalità diverse che estendono i valori predefiniti sopra.
|
||||
},
|
||||
{
|
||||
"command": "/btw",
|
||||
"description": "Fai una domanda laterale senza modificare il contesto della sessione",
|
||||
"description": "Fai una domanda secondaria senza modificare il contesto della sessione",
|
||||
"usage_hint": "<question>",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/usage",
|
||||
"description": "Controlla il piè di pagina dell'utilizzo o mostra il riepilogo dei costi",
|
||||
"description": "Controlla il piè di pagina di utilizzo o mostra il riepilogo dei costi",
|
||||
"usage_hint": "off|tokens|full|cost",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
}
|
||||
@ -562,7 +562,7 @@ Mostra funzionalità diverse che estendono i valori predefiniti sopra.
|
||||
</Tabs>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Ambiti di authoring facoltativi (operazioni di scrittura)">
|
||||
<Accordion title="Ambiti di attribuzione facoltativi (operazioni di scrittura)">
|
||||
Aggiungi l'ambito bot `chat:write.customize` se vuoi che i messaggi in uscita usino l'identità dell'agente attivo (nome utente e icona personalizzati) invece dell'identità predefinita dell'app Slack.
|
||||
|
||||
Se usi un'icona emoji, Slack si aspetta la sintassi `:emoji_name:`.
|
||||
@ -577,57 +577,57 @@ Mostra funzionalità diverse che estendono i valori predefiniti sopra.
|
||||
- `reactions:read`
|
||||
- `pins:read`
|
||||
- `emoji:read`
|
||||
- `search:read` (se dipendi dalle letture della ricerca Slack)
|
||||
- `search:read` (se dipendi dalle letture di ricerca di Slack)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Modello dei token
|
||||
|
||||
- `botToken` + `appToken` sono obbligatori per Socket Mode.
|
||||
- `botToken` + `appToken` sono richiesti per Socket Mode.
|
||||
- La modalità HTTP richiede `botToken` + `signingSecret`.
|
||||
- `botToken`, `appToken`, `signingSecret` e `userToken` accettano stringhe
|
||||
in chiaro oppure oggetti SecretRef.
|
||||
in chiaro o oggetti SecretRef.
|
||||
- I token di configurazione hanno la precedenza sul fallback env.
|
||||
- Il fallback env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` si applica solo all'account predefinito.
|
||||
- `userToken` (`xoxp-...`) è solo di configurazione (nessun fallback env) e usa come impostazione predefinita il comportamento di sola lettura (`userTokenReadOnly: true`).
|
||||
- `userToken` (`xoxp-...`) è solo di configurazione (nessun fallback env) e per impostazione predefinita usa un comportamento di sola lettura (`userTokenReadOnly: true`).
|
||||
|
||||
Comportamento dell'istantanea di stato:
|
||||
|
||||
- L'ispezione dell'account Slack tiene traccia dei campi `*Source` e `*Status`
|
||||
- L'ispezione dell'account Slack traccia i campi `*Source` e `*Status`
|
||||
per credenziale (`botToken`, `appToken`, `signingSecret`, `userToken`).
|
||||
- Lo stato è `available`, `configured_unavailable` oppure `missing`.
|
||||
- Lo stato è `available`, `configured_unavailable` o `missing`.
|
||||
- `configured_unavailable` significa che l'account è configurato tramite SecretRef
|
||||
o un'altra origine di segreti non inline, ma il percorso corrente di comando/runtime
|
||||
non è riuscito a risolvere il valore effettivo.
|
||||
o un'altra origine di segreto non inline, ma il percorso corrente di comando/runtime
|
||||
non ha potuto risolvere il valore effettivo.
|
||||
- In modalità HTTP, è incluso `signingSecretStatus`; in Socket Mode, la
|
||||
coppia richiesta è `botTokenStatus` + `appTokenStatus`.
|
||||
|
||||
<Tip>
|
||||
Per le letture di azioni/directory, il token utente può avere la priorità quando configurato. Per le scritture, il token bot resta preferito; le scritture con token utente sono consentite solo quando `userTokenReadOnly: false` e il token bot non è disponibile.
|
||||
Per le azioni/letture di 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.
|
||||
</Tip>
|
||||
|
||||
## Azioni e gate
|
||||
## Azioni e controlli
|
||||
|
||||
Le azioni Slack sono controllate da `channels.slack.actions.*`.
|
||||
|
||||
Gruppi di azioni disponibili negli strumenti Slack correnti:
|
||||
Gruppi di azioni disponibili negli strumenti Slack attuali:
|
||||
|
||||
| Group | Default |
|
||||
| ---------- | ------- |
|
||||
| messages | enabled |
|
||||
| reactions | enabled |
|
||||
| pins | enabled |
|
||||
| memberInfo | enabled |
|
||||
| emojiList | enabled |
|
||||
| messaggi | abilitato |
|
||||
| reazioni | abilitato |
|
||||
| pin | abilitato |
|
||||
| infoMembro | abilitato |
|
||||
| elencoEmoji | abilitato |
|
||||
|
||||
Le azioni correnti sui messaggi Slack includono `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` ed `emoji-list`.
|
||||
Le attuali azioni 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
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Criterio DM">
|
||||
`channels.slack.dmPolicy` controlla l'accesso DM (legacy: `channels.slack.dm.policy`):
|
||||
`channels.slack.dmPolicy` controlla l'accesso ai DM (legacy: `channels.slack.dm.policy`):
|
||||
|
||||
- `pairing` (predefinito)
|
||||
- `allowlist`
|
||||
@ -639,35 +639,35 @@ Le azioni correnti sui messaggi Slack includono `send`, `upload-file`, `download
|
||||
- `dm.enabled` (predefinito true)
|
||||
- `channels.slack.allowFrom` (preferito)
|
||||
- `dm.allowFrom` (legacy)
|
||||
- `dm.groupEnabled` (DM di gruppo predefinite false)
|
||||
- `dm.groupEnabled` (DM di gruppo predefiniti false)
|
||||
- `dm.groupChannels` (allowlist MPIM facoltativa)
|
||||
|
||||
Precedenza multi-account:
|
||||
|
||||
- `channels.slack.accounts.default.allowFrom` si applica solo all'account `default`.
|
||||
- Gli account con nome ereditano `channels.slack.allowFrom` quando il 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 nelle DM usa `openclaw pairing approve slack <code>`.
|
||||
L'abbinamento nei DM usa `openclaw pairing approve slack <code>`.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Criterio canale">
|
||||
`channels.slack.groupPolicy` controlla la gestione dei canali:
|
||||
<Tab title="Criterio del canale">
|
||||
`channels.slack.groupPolicy` controlla la gestione del canale:
|
||||
|
||||
- `open`
|
||||
- `allowlist`
|
||||
- `disabled`
|
||||
|
||||
L'allowlist dei canali si trova sotto `channels.slack.channels` e dovrebbe usare ID canale stabili.
|
||||
L'allowlist dei canali si trova in `channels.slack.channels` e dovrebbe usare ID 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 runtime: se `channels.slack` manca completamente (configurazione solo env), il runtime usa il fallback `groupPolicy="allowlist"` e registra un avviso (anche se `channels.defaults.groupPolicy` è impostato).
|
||||
|
||||
Risoluzione nome/ID:
|
||||
|
||||
- le voci dell'allowlist dei canali e dell'allowlist DM vengono risolte all'avvio quando l'accesso ai token lo consente
|
||||
- le voci dell'allowlist dei canali e dell'allowlist DM vengono risolte all'avvio quando l'accesso token lo consente
|
||||
- le voci non risolte del nome canale vengono mantenute come configurate ma ignorate per l'instradamento per impostazione predefinita
|
||||
- l'autorizzazione in ingresso e l'instradamento dei canali usano per impostazione predefinita prima gli ID; la corrispondenza diretta di username/slug richiede `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
- l'autorizzazione in ingresso e l'instradamento del canale sono per impostazione predefinita ID-first; la corrispondenza diretta con username/slug richiede `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
|
||||
</Tab>
|
||||
|
||||
@ -688,7 +688,7 @@ Le azioni correnti sui messaggi Slack includono `send`, `upload-file`, `download
|
||||
- `skills`
|
||||
- `systemPrompt`
|
||||
- `tools`, `toolsBySender`
|
||||
- formato della chiave `toolsBySender`: `id:`, `e164:`, `username:`, `name:` oppure wildcard `"*"`
|
||||
- formato della chiave `toolsBySender`: `id:`, `e164:`, `username:`, `name:` o wildcard `"*"`
|
||||
(le chiavi legacy senza prefisso continuano a essere mappate solo a `id:`)
|
||||
|
||||
</Tab>
|
||||
@ -696,13 +696,13 @@ Le azioni correnti sui messaggi Slack includono `send`, `upload-file`, `download
|
||||
|
||||
## Thread, sessioni e tag di risposta
|
||||
|
||||
- Le DM vengono instradate come `direct`; i canali come `channel`; gli MPIM come `group`.
|
||||
- Con il valore predefinito `session.dmScope=main`, le DM di Slack confluiscono nella sessione principale dell'agente.
|
||||
- Sessioni canale: `agent:<agentId>:slack:channel:<channelId>`.
|
||||
- I DM vengono 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.
|
||||
- Il valore predefinito di `channels.slack.thread.historyScope` è `thread`; il valore predefinito di `thread.inheritParent` è `false`.
|
||||
- Il valore predefinito di `channels.slack.thread.historyScope` è `thread`; quello 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 del thread in modo che il bot risponda solo a menzioni esplicite `@bot` all'interno dei thread, anche quando il bot ha già partecipato al thread. Senza questa impostazione, le risposte in un thread a cui il bot ha partecipato aggirano il gate `requireMention`.
|
||||
- `channels.slack.thread.requireExplicitMention` (predefinito `false`): quando è `true`, sopprime le menzioni implicite nei thread, così il bot risponde 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 il bot ha partecipato bypassano il controllo `requireMention`.
|
||||
|
||||
Controlli del threading delle risposte:
|
||||
|
||||
@ -715,9 +715,9 @@ Sono supportati 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 sono comunque rispettati in modalità `"off"`. La differenza riflette i modelli di threading delle piattaforme: i thread di Slack nascondono i messaggi dal canale, mentre le risposte di Telegram restano visibili nel flusso principale della chat.
|
||||
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.
|
||||
|
||||
@ -726,31 +726,31 @@ Ordine di risoluzione:
|
||||
- `channels.slack.accounts.<accountId>.ackReaction`
|
||||
- `channels.slack.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- fallback dell'emoji dell'identità dell'agente (`agents.list[].identity.emoji`, altrimenti "👀")
|
||||
- fallback all'emoji dell'identità dell'agente (`agents.list[].identity.emoji`, altrimenti "👀")
|
||||
|
||||
Note:
|
||||
|
||||
- Slack si aspetta shortcode (ad esempio `"eyes"`).
|
||||
- Usa `""` per disabilitare la reazione per l'account Slack o a livello globale.
|
||||
- Usa `""` per disabilitare la reazione per l'account Slack o globalmente.
|
||||
|
||||
## Streaming del testo
|
||||
|
||||
`channels.slack.streaming` controlla il comportamento dell'anteprima live:
|
||||
|
||||
- `off`: disabilita lo streaming dell'anteprima live.
|
||||
- `partial` (predefinito): sostituisce il testo di anteprima con l'ultimo output parziale.
|
||||
- `partial` (predefinito): sostituisce il testo di anteprima con l'output parziale più recente.
|
||||
- `block`: aggiunge aggiornamenti di anteprima a blocchi.
|
||||
- `progress`: mostra il testo di stato dell'avanzamento durante la generazione, quindi invia il testo finale.
|
||||
|
||||
`channels.slack.streaming.nativeTransport` controlla lo streaming di testo nativo di Slack quando `channels.slack.streaming.mode` è `partial` (predefinito: `true`).
|
||||
`channels.slack.streaming.nativeTransport` controlla lo streaming nativo del testo di Slack quando `channels.slack.streaming.mode` è `partial` (predefinito: `true`).
|
||||
|
||||
- Per lo streaming di testo nativo devono essere disponibili un thread di risposta e lo stato del thread assistant di Slack. La selezione del thread continua comunque a seguire `replyToMode`.
|
||||
- Per visualizzare lo streaming nativo del testo e lo stato del thread assistant di Slack deve essere disponibile un thread di risposta. La selezione del thread continua comunque a seguire `replyToMode`.
|
||||
- Le radici di canali e chat di gruppo possono comunque usare la normale anteprima bozza quando lo streaming nativo non è disponibile.
|
||||
- Le DM Slack di livello superiore restano fuori thread per impostazione predefinita, quindi non mostrano l'anteprima in stile thread; usa risposte nel thread o `typingReaction` se vuoi un avanzamento visibile in quel caso.
|
||||
- I media e i payload non testuali usano il fallback alla consegna normale.
|
||||
- Le DM Slack di primo livello restano fuori thread per impostazione predefinita, quindi non mostrano l'anteprima in stile thread; usa risposte nei thread o `typingReaction` se vuoi un avanzamento visibile lì.
|
||||
- I contenuti multimediali e i payload non testuali usano il fallback alla consegna normale.
|
||||
- Se lo streaming fallisce a metà risposta, OpenClaw usa il fallback alla consegna normale per i payload rimanenti.
|
||||
|
||||
Usa l'anteprima bozza invece dello streaming di testo nativo di Slack:
|
||||
Usa l'anteprima bozza invece dello streaming nativo del testo di Slack:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -767,13 +767,13 @@ Usa l'anteprima bozza invece dello streaming di testo nativo di Slack:
|
||||
|
||||
Chiavi legacy:
|
||||
|
||||
- `channels.slack.streamMode` (`replace | status_final | append`) viene migrato automaticamente a `channels.slack.streaming.mode`.
|
||||
- il valore booleano `channels.slack.streaming` viene migrato automaticamente a `channels.slack.streaming.mode` e `channels.slack.streaming.nativeTransport`.
|
||||
- il valore legacy `channels.slack.nativeStreaming` viene migrato automaticamente a `channels.slack.streaming.nativeTransport`.
|
||||
- `channels.slack.streamMode` (`replace | status_final | append`) viene migrato automaticamente in `channels.slack.streaming.mode`.
|
||||
- il booleano `channels.slack.streaming` viene migrato automaticamente in `channels.slack.streaming.mode` e `channels.slack.streaming.nativeTransport`.
|
||||
- la chiave legacy `channels.slack.nativeStreaming` viene migrata automaticamente in `channels.slack.streaming.nativeTransport`.
|
||||
|
||||
## Fallback della reazione di digitazione
|
||||
|
||||
`typingReaction` aggiunge una reazione temporanea al messaggio Slack in ingresso mentre OpenClaw elabora una risposta, quindi la rimuove quando l'esecuzione termina. Questo è particolarmente utile al di fuori delle risposte nei thread, che usano un indicatore di stato predefinito "sta scrivendo...".
|
||||
`typingReaction` aggiunge una reazione temporanea al messaggio Slack in ingresso mentre OpenClaw elabora una risposta, quindi la rimuove al termine dell'esecuzione. Questo è particolarmente utile al di fuori delle risposte nei thread, che usano un indicatore di stato predefinito "sta scrivendo...".
|
||||
|
||||
Ordine di risoluzione:
|
||||
|
||||
@ -783,15 +783,15 @@ Ordine di risoluzione:
|
||||
Note:
|
||||
|
||||
- Slack si aspetta shortcode (ad esempio `"hourglass_flowing_sand"`).
|
||||
- La reazione è best-effort e la pulizia viene tentata automaticamente al termine della risposta o del percorso di errore.
|
||||
- La reazione è best-effort e la pulizia viene tentata 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 tramite token) e scritti nello store dei media quando il recupero riesce e i limiti di dimensione lo consentono.
|
||||
Gli allegati file di Slack vengono scaricati da URL private ospitate da Slack (flusso di richiesta autenticato tramite token) e scritti nell'archivio media quando il recupero ha esito positivo e i limiti di dimensione lo consentono.
|
||||
|
||||
Il limite predefinito della dimensione in ingresso a runtime è `20MB`, salvo override con `channels.slack.mediaMaxMb`.
|
||||
Il limite di dimensione in ingresso a runtime è per impostazione predefinita `20MB`, salvo override con `channels.slack.mediaMaxMb`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -805,17 +805,17 @@ Note:
|
||||
<Accordion title="Destinazioni di consegna">
|
||||
Destinazioni esplicite preferite:
|
||||
|
||||
- `user:<id>` per le DM
|
||||
- `user:<id>` per i DM
|
||||
- `channel:<id>` per i canali
|
||||
|
||||
Le DM di Slack vengono aperte 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
|
||||
|
||||
I comandi slash compaiono in Slack come un singolo comando configurato oppure come più comandi nativi. Configura `channels.slack.slashCommand` per modificare i valori predefiniti dei comandi:
|
||||
I comandi slash appaiono in Slack come un singolo comando configurato o come più comandi nativi. Configura `channels.slack.slashCommand` per modificare i valori predefiniti del comando:
|
||||
|
||||
- `enabled: false`
|
||||
- `name: "openclaw"`
|
||||
@ -826,7 +826,7 @@ I comandi slash compaiono in Slack come un singolo comando configurato oppure co
|
||||
/openclaw /help
|
||||
```
|
||||
|
||||
I comandi nativi richiedono [impostazioni aggiuntive del manifest](#additional-manifest-settings) nella tua app Slack e vengono abilitati con `channels.slack.commands.native: true` oppure `commands.native: true` nelle configurazioni globali.
|
||||
I comandi nativi richiedono [impostazioni aggiuntive del manifesto](#additional-manifest-settings) nella tua app Slack e vengono invece abilitati con `channels.slack.commands.native: true` o `commands.native: true` nelle configurazioni globali.
|
||||
|
||||
- La modalità automatica dei comandi nativi è **disattivata** per Slack, quindi `commands.native: "auto"` non abilita i comandi nativi di Slack.
|
||||
|
||||
@ -834,12 +834,12 @@ I comandi nativi richiedono [impostazioni aggiuntive del manifest](#additional-m
|
||||
/help
|
||||
```
|
||||
|
||||
I menu argomento dei comandi nativi usano una strategia di rendering adattiva che mostra una finestra modale di conferma prima di inviare il valore dell'opzione selezionata:
|
||||
I menu nativi degli argomenti usano una strategia di rendering adattiva che mostra un modal di conferma prima di inviare il valore dell'opzione selezionata:
|
||||
|
||||
- fino a 5 opzioni: blocchi pulsante
|
||||
- 6-100 opzioni: menu di selezione statico
|
||||
- più di 100 opzioni: selezione esterna con filtro asincrono delle opzioni quando sono disponibili gestori delle opzioni di interattività
|
||||
- limiti Slack superati: i valori delle opzioni codificati usano il fallback ai pulsanti
|
||||
- fino a 5 opzioni: blocchi di pulsanti
|
||||
- 6-100 opzioni: menu statico di selezione
|
||||
- più di 100 opzioni: selezione esterna con filtro asincrono delle opzioni quando sono disponibili gestori per le opzioni di interattività
|
||||
- superati i limiti di Slack: i valori di opzione codificati usano il fallback ai pulsanti
|
||||
|
||||
```txt
|
||||
/think
|
||||
@ -849,7 +849,7 @@ Le sessioni slash usano chiavi isolate come `agent:<agentId>:slack:slash:<userId
|
||||
|
||||
## Risposte interattive
|
||||
|
||||
Slack può visualizzare controlli di risposta interattivi creati dall'agente, ma questa funzionalità è disabilitata per impostazione predefinita.
|
||||
Slack può renderizzare controlli di risposta interattivi creati dall'agente, ma questa funzionalità è disabilitata per impostazione predefinita.
|
||||
|
||||
Abilitala globalmente:
|
||||
|
||||
@ -892,20 +892,20 @@ Queste direttive vengono compilate in Slack Block Kit e instradano clic o selezi
|
||||
|
||||
Note:
|
||||
|
||||
- Si tratta di un'interfaccia specifica di Slack. Gli altri canali non traducono le direttive Slack Block Kit nei propri sistemi di pulsanti.
|
||||
- Si tratta di UI specifica di Slack. Gli altri canali non traducono le direttive Slack Block Kit nei propri sistemi di pulsanti.
|
||||
- I valori di callback interattivi sono token opachi generati da OpenClaw, non valori grezzi creati dall'agente.
|
||||
- Se i blocchi interattivi generati superano i limiti di Slack Block Kit, OpenClaw usa il fallback alla risposta testuale originale invece di inviare un payload `blocks` non valido.
|
||||
- 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 e interazioni interattivi, invece di usare il fallback alla Web UI o al terminale.
|
||||
|
||||
- Le approvazioni exec usano `channels.slack.execApprovals.*` per l'instradamento nativo DM/canale.
|
||||
- Anche le approvazioni dei plugin possono risolversi tramite la stessa superficie di pulsanti nativi Slack quando la richiesta arriva già in Slack e il tipo di ID approvazione è `plugin:`.
|
||||
- L'autorizzazione dell'approvatore continua a essere applicata: solo gli utenti identificati come approvatori possono approvare o rifiutare richieste tramite Slack.
|
||||
- Le approvazioni exec usano `channels.slack.execApprovals.*` per l'instradamento nativo in DM/canale.
|
||||
- Le approvazioni 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 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 dei pulsanti di approvazione degli altri canali. Quando `interactivity` è abilitato nelle impostazioni della tua app Slack, i prompt di approvazione vengono visualizzati come pulsanti Block Kit direttamente nella conversazione.
|
||||
Quando questi pulsanti sono presenti, rappresentano l'esperienza utente principale per l'approvazione; OpenClaw
|
||||
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 renderizzati come pulsanti Block Kit direttamente nella conversazione.
|
||||
Quando questi pulsanti sono presenti, rappresentano 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.
|
||||
|
||||
@ -916,9 +916,9 @@ Percorso di configurazione:
|
||||
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, predefinito: `dm`)
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
Slack abilita automaticamente le approvazioni exec native quando `enabled` non è impostato oppure è `"auto"` e viene risolto almeno un
|
||||
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 vengono risolti approvatori.
|
||||
Imposta `enabled: true` per forzare l'attivazione delle approvazioni native quando gli approvatori vengono risolti.
|
||||
|
||||
Comportamento predefinito senza configurazione esplicita delle approvazioni exec Slack:
|
||||
|
||||
@ -931,7 +931,7 @@ Comportamento predefinito senza configurazione esplicita delle approvazioni exec
|
||||
```
|
||||
|
||||
La configurazione nativa esplicita di Slack è necessaria solo quando vuoi sovrascrivere gli approvatori, aggiungere filtri o
|
||||
abilitare la consegna alla chat di origine:
|
||||
attivare la consegna nella chat di origine:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -948,35 +948,35 @@ abilitare la consegna alla chat di origine:
|
||||
```
|
||||
|
||||
L'inoltro condiviso `approvals.exec` è separato. Usalo solo quando i prompt di approvazione exec devono essere instradati anche
|
||||
ad altre chat o a destinazioni esplicite fuori banda. Anche l'inoltro condiviso `approvals.plugin` è
|
||||
separato; i pulsanti nativi di Slack possono comunque risolvere le approvazioni dei plugin quando tali richieste arrivano già
|
||||
verso altre chat o destinazioni esplicite fuori banda. Anche l'inoltro condiviso `approvals.plugin` è
|
||||
separato; i pulsanti nativi di Slack possono comunque risolvere le approvazioni Plugin quando tali richieste arrivano già
|
||||
in Slack.
|
||||
|
||||
Anche `/approve` nella stessa chat funziona nei canali e nelle DM di Slack che supportano già i comandi. Vedi [Exec approvals](/it/tools/exec-approvals) per il modello completo di inoltro delle approvazioni.
|
||||
Anche `/approve` nella stessa chat funziona in canali e DM Slack che supportano già 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 le trasmissioni dei thread vengono mappate in eventi di sistema.
|
||||
- Gli eventi di aggiunta/rimozione delle reazioni vengono mappati in eventi di sistema.
|
||||
- Gli eventi di ingresso/uscita dei membri, creazione/rinomina dei canali e aggiunta/rimozione dei pin vengono mappati in eventi di sistema.
|
||||
- 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 membri, creazione/rinomina canale e aggiunta/rimozione 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 vengono trattati come contesto non attendibile e possono essere inseriti nel contesto di instradamento.
|
||||
- Il messaggio iniziale del thread e il seeding iniziale del contesto della cronologia del thread vengono filtrati dalle allowlist dei mittenti configurate quando applicabile.
|
||||
- Le azioni dei blocchi e le interazioni modali emettono eventi di sistema strutturati `Slack interaction: ...` con campi payload ricchi:
|
||||
- azioni dei blocchi: valori selezionati, etichette, valori del selettore e metadati `workflow_*`
|
||||
- eventi modali `view_submission` e `view_closed` con metadati del canale instradato e input del modulo
|
||||
- I metadati di topic/purpose del canale vengono trattati come contesto non attendibile e possono essere iniettati nel contesto di instradamento.
|
||||
- Il thread starter e il seeding iniziale del contesto della cronologia del thread vengono filtrati tramite le allowlist di mittenti configurate quando applicabile.
|
||||
- Le azioni sui blocchi e le interazioni con i modal emettono eventi di sistema strutturati `Slack interaction: ...` con campi payload avanzati:
|
||||
- azioni sui blocchi: valori selezionati, etichette, valori dei picker e metadati `workflow_*`
|
||||
- eventi modal `view_submission` e `view_closed` con metadati del canale instradato e input del modulo
|
||||
|
||||
## Riferimenti alla configurazione
|
||||
## Puntatori al riferimento della configurazione
|
||||
|
||||
Riferimento principale:
|
||||
|
||||
- [Riferimento alla configurazione - Slack](/it/gateway/configuration-reference#slack)
|
||||
- [Riferimento della 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; lascialo disattivato salvo necessità)
|
||||
- accesso canali: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
|
||||
- interruttore di compatibilità: `dangerouslyAllowNameMatching` (solo emergenza; 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`, `streaming.nativeTransport`
|
||||
- operazioni/funzionalità: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
|
||||
@ -988,7 +988,7 @@ Riferimento principale:
|
||||
Controlla, in ordine:
|
||||
|
||||
- `groupPolicy`
|
||||
- allowlist dei canali (`channels.slack.channels`)
|
||||
- allowlist del canale (`channels.slack.channels`)
|
||||
- `requireMention`
|
||||
- allowlist `users` per canale
|
||||
|
||||
@ -1006,8 +1006,8 @@ openclaw doctor
|
||||
Controlla:
|
||||
|
||||
- `channels.slack.dm.enabled`
|
||||
- `channels.slack.dmPolicy` (o legacy `channels.slack.dm.policy`)
|
||||
- approvazioni di associazione / voci allowlist
|
||||
- `channels.slack.dmPolicy` (o il legacy `channels.slack.dm.policy`)
|
||||
- approvazioni di abbinamento / voci allowlist
|
||||
|
||||
```bash
|
||||
openclaw pairing list slack
|
||||
@ -1015,10 +1015,10 @@ openclaw pairing list slack
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Socket Mode non si connette">
|
||||
<Accordion title="Socket mode non si connette">
|
||||
Verifica i token bot + app e l'abilitazione di Socket Mode nelle impostazioni dell'app Slack.
|
||||
|
||||
Se `openclaw channels status --probe --json` mostra `botTokenStatus` oppure
|
||||
Se `openclaw channels status --probe --json` mostra `botTokenStatus` o
|
||||
`appTokenStatus: "configured_unavailable"`, l'account Slack è
|
||||
configurato ma il runtime corrente non è riuscito a risolvere il valore
|
||||
supportato da SecretRef.
|
||||
@ -1030,19 +1030,19 @@ openclaw pairing list slack
|
||||
|
||||
- signing secret
|
||||
- percorso webhook
|
||||
- URL delle richieste Slack (Eventi + Interattività + Slash Commands)
|
||||
- URL di richiesta Slack (Eventi + Interattività + comandi slash)
|
||||
- `webhookPath` univoco per ogni account HTTP
|
||||
|
||||
Se `signingSecretStatus: "configured_unavailable"` compare nelle istantanee
|
||||
dell'account, l'account HTTP è configurato ma il runtime corrente non è
|
||||
riuscito a risolvere il signing secret supportato da SecretRef.
|
||||
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>
|
||||
|
||||
<Accordion title="I comandi nativi/slash non si attivano">
|
||||
Verifica se intendevi usare:
|
||||
|
||||
- modalità comandi nativi (`channels.slack.commands.native: true`) con comandi slash corrispondenti registrati in Slack
|
||||
- modalità comandi nativi (`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 canali/utenti.
|
||||
@ -1052,7 +1052,7 @@ openclaw pairing list slack
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Associazione](/it/channels/pairing)
|
||||
- [Abbinamento](/it/channels/pairing)
|
||||
- [Gruppi](/it/channels/groups)
|
||||
- [Sicurezza](/it/gateway/security)
|
||||
- [Instradamento dei canali](/it/channels/channel-routing)
|
||||
|
||||
@ -1,55 +1,55 @@
|
||||
---
|
||||
read_when:
|
||||
- Spiegare come i messaggi in ingresso diventano risposte
|
||||
- Spiegazione di come i messaggi in entrata diventano risposte
|
||||
- Chiarire sessioni, modalità di accodamento o comportamento dello streaming
|
||||
- Documentare la visibilità del ragionamento e le implicazioni d'uso
|
||||
summary: Flusso dei messaggi, sessioni, accodamento e visibilità del ragionamento
|
||||
title: Messaggi
|
||||
x-i18n:
|
||||
generated_at: "2026-04-21T08:22:16Z"
|
||||
generated_at: "2026-04-21T13:35:26Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: ddf88b91f3489bfdfb4a84f8a287a1ec0b0d71a765dfe27c666c6f43d0145022
|
||||
source_hash: 4f535d01872e7fcf0f3d99a5c5ac01feddbf7fb562ff61d9ccdf18f109f9922f
|
||||
source_path: concepts/messages.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Messaggi
|
||||
|
||||
Questa pagina collega il modo in cui OpenClaw gestisce i messaggi in ingresso, le sessioni, l'accodamento,
|
||||
Questa pagina collega tra loro il modo in cui OpenClaw gestisce i messaggi in entrata, le sessioni, l'accodamento,
|
||||
lo streaming e la visibilità del ragionamento.
|
||||
|
||||
## Flusso dei messaggi (alto livello)
|
||||
## Flusso dei messaggi (panoramica di alto livello)
|
||||
|
||||
```
|
||||
Messaggio in ingresso
|
||||
-> routing/binding -> chiave di sessione
|
||||
-> coda (se un'esecuzione è attiva)
|
||||
-> esecuzione dell'agente (streaming + strumenti)
|
||||
-> risposte in uscita (limiti del canale + suddivisione in blocchi)
|
||||
Inbound message
|
||||
-> routing/bindings -> session key
|
||||
-> queue (if a run is active)
|
||||
-> agent run (streaming + tools)
|
||||
-> outbound replies (channel limits + chunking)
|
||||
```
|
||||
|
||||
Le impostazioni principali si trovano nella configurazione:
|
||||
Le principali opzioni di configurazione si trovano in:
|
||||
|
||||
- `messages.*` per prefissi, accodamento e comportamento nei gruppi.
|
||||
- `messages.*` per prefissi, accodamento e comportamento dei gruppi.
|
||||
- `agents.defaults.*` per i valori predefiniti di block streaming e chunking.
|
||||
- Override di canale (`channels.whatsapp.*`, `channels.telegram.*`, ecc.) per limiti e toggle dello streaming.
|
||||
- Override del canale (`channels.whatsapp.*`, `channels.telegram.*`, ecc.) per limiti e interruttori dello streaming.
|
||||
|
||||
Vedi [Configuration](/it/gateway/configuration) per lo schema completo.
|
||||
|
||||
## Deduplica in ingresso
|
||||
## Deduplicazione in entrata
|
||||
|
||||
I canali possono riconsegnare lo stesso messaggio dopo le riconnessioni. OpenClaw mantiene una
|
||||
cache di breve durata indicizzata per canale/account/peer/sessione/id messaggio in modo che le consegne
|
||||
duplicate non attivino un'altra esecuzione dell'agente.
|
||||
cache di breve durata indicizzata per channel/account/peer/session/message id, in modo che le consegne duplicate
|
||||
non attivino un'altra esecuzione dell'agente.
|
||||
|
||||
## Debouncing in ingresso
|
||||
## Debouncing in entrata
|
||||
|
||||
Messaggi rapidi e consecutivi dello **stesso mittente** possono essere raggruppati in un singolo
|
||||
turno dell'agente tramite `messages.inbound`. Il debouncing è applicato per canale + conversazione
|
||||
e usa il messaggio più recente per il threading/le ID della risposta.
|
||||
Messaggi rapidi e consecutivi provenienti dallo **stesso mittente** possono essere raggruppati in un singolo
|
||||
turno dell'agente tramite `messages.inbound`. Il debouncing è applicato per channel + conversation
|
||||
e usa il messaggio più recente per threading/ID della risposta.
|
||||
|
||||
Config (valore globale predefinito + override per canale):
|
||||
Configurazione (valore predefinito globale + override per canale):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -68,57 +68,57 @@ Config (valore globale predefinito + override per canale):
|
||||
|
||||
Note:
|
||||
|
||||
- Il debounce si applica ai messaggi **solo testo**; media/allegati vengono inviati immediatamente.
|
||||
- I comandi di controllo bypassano il debouncing così restano autonomi.
|
||||
- Il debounce si applica ai messaggi **solo testo**; contenuti multimediali/allegati vengono inviati immediatamente.
|
||||
- I comandi di controllo bypassano il debouncing così da rimanere autonomi — **tranne** quando un canale abilita esplicitamente la coalescenza dei DM dello stesso mittente (ad esempio [BlueBubbles `coalesceSameSenderDms`](/it/channels/bluebubbles#coalescing-split-send-dms-command--url-in-one-composition)), dove i comandi DM attendono all'interno della finestra di debounce così che un payload split-send possa unirsi allo stesso turno dell'agente.
|
||||
|
||||
## Sessioni e dispositivi
|
||||
|
||||
Le sessioni sono di proprietà del Gateway, non dei client.
|
||||
|
||||
- Le chat dirette confluiscono nella chiave di sessione principale dell'agente.
|
||||
- Gruppi/canali ottengono le proprie chiavi di sessione.
|
||||
- L'archivio delle sessioni e le trascrizioni si trovano sull'host del Gateway.
|
||||
- I gruppi/canali hanno le proprie chiavi di sessione.
|
||||
- L'archivio delle sessioni e le trascrizioni risiedono sull'host del Gateway.
|
||||
|
||||
Più dispositivi/canali possono mappare alla stessa sessione, ma la cronologia non viene
|
||||
sincronizzata completamente su tutti i client. Raccomandazione: usa un dispositivo primario
|
||||
per le conversazioni lunghe per evitare contesti divergenti. La Control UI e la TUI mostrano sempre
|
||||
la trascrizione della sessione supportata dal Gateway, quindi sono la fonte di verità.
|
||||
Più dispositivi/canali possono essere mappati alla stessa sessione, ma la cronologia non viene
|
||||
sincronizzata completamente con tutti i client. Raccomandazione: usa un solo dispositivo principale per le conversazioni lunghe
|
||||
per evitare contesti divergenti. La Control UI e la TUI mostrano sempre la
|
||||
trascrizione della sessione supportata dal Gateway, quindi sono la fonte di verità.
|
||||
|
||||
Dettagli: [Session management](/it/concepts/session).
|
||||
|
||||
## Corpi in ingresso e contesto della cronologia
|
||||
## Corpi in entrata e contesto della cronologia
|
||||
|
||||
OpenClaw separa il **corpo del prompt** dal **corpo del comando**:
|
||||
|
||||
- `Body`: testo del prompt inviato all'agente. Può includere envelope del canale e
|
||||
wrapper facoltativi della cronologia.
|
||||
- `CommandBody`: testo utente grezzo per l'analisi di direttive/comandi.
|
||||
wrapper della cronologia opzionali.
|
||||
- `CommandBody`: testo utente grezzo per il parsing di direttive/comandi.
|
||||
- `RawBody`: alias legacy per `CommandBody` (mantenuto per compatibilità).
|
||||
|
||||
Quando un canale fornisce cronologia, usa un wrapper condiviso:
|
||||
Quando un canale fornisce la cronologia, usa un wrapper condiviso:
|
||||
|
||||
- `[Chat messages since your last reply - for context]`
|
||||
- `[Current message - respond to this]`
|
||||
|
||||
Per le **chat non dirette** (gruppi/canali/stanze), il **corpo del messaggio corrente** viene prefissato con
|
||||
Per le **chat non dirette** (gruppi/canali/stanze), il **corpo del messaggio corrente** è prefissato con
|
||||
l'etichetta del mittente (lo stesso stile usato per le voci della cronologia). Questo mantiene coerenti
|
||||
nel prompt dell'agente i messaggi in tempo reale e quelli in coda/cronologia.
|
||||
nell'agente prompt i messaggi in tempo reale e quelli in coda/cronologia.
|
||||
|
||||
I buffer della cronologia sono **solo pending**: includono i messaggi di gruppo che _non_ hanno
|
||||
attivato un'esecuzione (per esempio, messaggi soggetti al gating delle menzioni) ed **escludono** i messaggi
|
||||
I buffer della cronologia sono **solo pending**: includono i messaggi dei gruppi che _non_
|
||||
hanno attivato un'esecuzione (per esempio, messaggi soggetti a mention gating) ed **escludono** i messaggi
|
||||
già presenti nella trascrizione della sessione.
|
||||
|
||||
La rimozione delle direttive si applica solo alla sezione del **messaggio corrente** così la cronologia
|
||||
resta intatta. I canali che avvolgono la cronologia dovrebbero impostare `CommandBody` (o
|
||||
La rimozione delle direttive si applica solo alla sezione del **messaggio corrente** così che la cronologia
|
||||
rimanga intatta. I canali che incapsulano la cronologia dovrebbero impostare `CommandBody` (o
|
||||
`RawBody`) sul testo originale del messaggio e mantenere `Body` come prompt combinato.
|
||||
I buffer della cronologia sono configurabili tramite `messages.groupChat.historyLimit` (valore
|
||||
globale predefinito) e override per canale come `channels.slack.historyLimit` o
|
||||
I buffer della cronologia sono configurabili tramite `messages.groupChat.historyLimit` (valore predefinito
|
||||
globale) e override per canale come `channels.slack.historyLimit` o
|
||||
`channels.telegram.accounts.<id>.historyLimit` (imposta `0` per disabilitare).
|
||||
|
||||
## Accodamento e followup
|
||||
|
||||
Se un'esecuzione è già attiva, i messaggi in ingresso possono essere accodati, indirizzati
|
||||
all'esecuzione corrente oppure raccolti per un turno di followup.
|
||||
Se un'esecuzione è già attiva, i messaggi in entrata possono essere accodati, instradati verso l'esecuzione
|
||||
corrente oppure raccolti per un turno di followup.
|
||||
|
||||
- Configura tramite `messages.queue` (e `messages.queue.byChannel`).
|
||||
- Modalità: `interrupt`, `steer`, `followup`, `collect`, più le varianti backlog.
|
||||
@ -128,16 +128,16 @@ Dettagli: [Queueing](/it/concepts/queue).
|
||||
## Streaming, chunking e batching
|
||||
|
||||
Il block streaming invia risposte parziali mentre il modello produce blocchi di testo.
|
||||
Il chunking rispetta i limiti di testo del canale ed evita di dividere codice racchiuso da fence.
|
||||
Il chunking rispetta i limiti di testo del canale ed evita di spezzare blocchi di codice fenced.
|
||||
|
||||
Impostazioni chiave:
|
||||
Impostazioni principali:
|
||||
|
||||
- `agents.defaults.blockStreamingDefault` (`on|off`, predefinito off)
|
||||
- `agents.defaults.blockStreamingDefault` (`on|off`, disattivato per impostazione predefinita)
|
||||
- `agents.defaults.blockStreamingBreak` (`text_end|message_end`)
|
||||
- `agents.defaults.blockStreamingChunk` (`minChars|maxChars|breakPreference`)
|
||||
- `agents.defaults.blockStreamingCoalesce` (batching basato sull'inattività)
|
||||
- `agents.defaults.humanDelay` (pausa simile a quella umana tra le risposte a blocchi)
|
||||
- Override di canale: `*.blockStreaming` e `*.blockStreamingCoalesce` (i canali non Telegram richiedono `*.blockStreaming: true` esplicito)
|
||||
- Override del canale: `*.blockStreaming` e `*.blockStreamingCoalesce` (i canali non Telegram richiedono `*.blockStreaming: true` esplicito)
|
||||
|
||||
Dettagli: [Streaming + chunking](/it/concepts/streaming).
|
||||
|
||||
@ -155,28 +155,28 @@ Dettagli: [Thinking + reasoning directives](/it/tools/thinking) e [Token use](/i
|
||||
|
||||
La formattazione dei messaggi in uscita è centralizzata in `messages`:
|
||||
|
||||
- `messages.responsePrefix`, `channels.<channel>.responsePrefix` e `channels.<channel>.accounts.<id>.responsePrefix` (cascata del prefisso in uscita), più `channels.whatsapp.messagePrefix` (prefisso in ingresso di WhatsApp)
|
||||
- Threading della risposta tramite `replyToMode` e valori predefiniti per canale
|
||||
- `messages.responsePrefix`, `channels.<channel>.responsePrefix` e `channels.<channel>.accounts.<id>.responsePrefix` (cascata del prefisso in uscita), oltre a `channels.whatsapp.messagePrefix` (prefisso in entrata di WhatsApp)
|
||||
- Reply threading tramite `replyToMode` e valori predefiniti per canale
|
||||
|
||||
Dettagli: [Configuration](/it/gateway/configuration-reference#messages) e documentazione dei canali.
|
||||
|
||||
## Risposte silenziose
|
||||
|
||||
Il token silenzioso esatto `NO_REPLY` / `no_reply` significa “non consegnare una risposta visibile all'utente”.
|
||||
OpenClaw risolve questo comportamento in base al tipo di conversazione:
|
||||
Il token silenzioso esatto `NO_REPLY` / `no_reply` significa “non inviare una risposta visibile all'utente”.
|
||||
OpenClaw applica questo comportamento in base al tipo di conversazione:
|
||||
|
||||
- Le conversazioni dirette non consentono il silenzio per impostazione predefinita e riscrivono una
|
||||
risposta silenziosa pura in un breve fallback visibile.
|
||||
- Gruppi/canali consentono il silenzio per impostazione predefinita.
|
||||
- Le conversazioni dirette non consentono il silenzio per impostazione predefinita e riscrivono una risposta silenziosa pura
|
||||
in un breve fallback visibile.
|
||||
- I gruppi/canali consentono il silenzio per impostazione predefinita.
|
||||
- L'orchestrazione interna consente il silenzio per impostazione predefinita.
|
||||
|
||||
I valori predefiniti si trovano in `agents.defaults.silentReply` e
|
||||
`agents.defaults.silentReplyRewrite`; `surfaces.<id>.silentReply` e
|
||||
`surfaces.<id>.silentReplyRewrite` possono sostituirli per superficie.
|
||||
`surfaces.<id>.silentReplyRewrite` possono sostituirli per singola surface.
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Streaming](/it/concepts/streaming) — consegna dei messaggi in tempo reale
|
||||
- [Retry](/it/concepts/retry) — comportamento di nuovo tentativo nella consegna dei messaggi
|
||||
- [Retry](/it/concepts/retry) — comportamento di ritentativo della consegna dei messaggi
|
||||
- [Queue](/it/concepts/queue) — coda di elaborazione dei messaggi
|
||||
- [Channels](/it/channels) — integrazioni con le piattaforme di messaggistica
|
||||
- [Channels](/it/channels) — integrazioni con piattaforme di messaggistica
|
||||
|
||||
@ -1,39 +1,41 @@
|
||||
---
|
||||
read_when:
|
||||
- Hai bisogno di un riferimento per la configurazione dei modelli provider per provider
|
||||
- È necessaria una guida di riferimento per la configurazione dei modelli provider per provider
|
||||
- Vuoi configurazioni di esempio o comandi di onboarding CLI per i provider di modelli
|
||||
summary: Panoramica dei provider di modelli con configurazioni di esempio e flussi CLI
|
||||
summary: Panoramica del provider del modello con configurazioni di esempio + flussi CLI
|
||||
title: Provider di modelli
|
||||
x-i18n:
|
||||
generated_at: "2026-04-21T08:22:15Z"
|
||||
generated_at: "2026-04-21T13:35:23Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e433dfd51d1721832480089cb35ab1243e5c873a587f9968e14744840cb912cf
|
||||
source_hash: 6732ab672757579c09395583a0f7d110348c909d4e4ab1d2accad68ad054c636
|
||||
source_path: concepts/model-providers.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Provider di modelli
|
||||
|
||||
Questa pagina copre i **provider di LLM/modelli** (non i canali di chat come WhatsApp/Telegram).
|
||||
Per le regole di selezione dei modelli, consulta [/concepts/models](/it/concepts/models).
|
||||
Questa pagina tratta i **provider di LLM/modelli** (non i canali 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 la allowlist.
|
||||
- Se imposti `agents.defaults.models`, questo diventa l'allowlist.
|
||||
- Helper CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
|
||||
- Le regole di fallback del runtime, le probe di cooldown e la persistenza degli override di sessione sono documentate in [/concepts/model-failover](/it/concepts/model-failover).
|
||||
- `models.providers.*.models[].contextWindow` è metadato nativo del modello; `models.providers.*.models[].contextTokens` è il limite effettivo del runtime.
|
||||
- I plugin provider possono iniettare cataloghi di modelli tramite `registerProvider({ catalog })`;
|
||||
OpenClaw unisce quell'output in `models.providers` prima di scrivere
|
||||
- Le regole di runtime di fallback, le probe di cooldown e la persistenza delle override 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 del runtime.
|
||||
- I Plugin provider possono iniettare cataloghi di modelli tramite `registerProvider({ catalog })`;
|
||||
OpenClaw unisce questo output in `models.providers` prima di scrivere
|
||||
`models.json`.
|
||||
- I manifest dei provider possono dichiarare `providerAuthEnvVars` e
|
||||
`providerAuthAliases` così le probe di autenticazione generiche basate su env e le varianti dei provider
|
||||
non devono caricare il runtime del plugin. La mappa rimanente delle variabili env del core ora è
|
||||
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 possedere il comportamento runtime del provider tramite
|
||||
non devono caricare il runtime del Plugin. La mappa rimanente delle env var nel core ora serve
|
||||
solo per i provider non-Plugin/core e per alcuni casi di precedenza generica come
|
||||
l'onboarding Anthropic con priorità API key.
|
||||
- I Plugin provider possono anche possedere il comportamento runtime del provider tramite
|
||||
`normalizeModelId`, `normalizeTransport`, `normalizeConfig`,
|
||||
`applyNativeStreamingUsageCompat`, `resolveConfigApiKey`,
|
||||
`resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`,
|
||||
@ -47,167 +49,167 @@ Per le regole di selezione dei modelli, consulta [/concepts/models](/it/concepts
|
||||
`buildAuthDoctorHint`,
|
||||
`matchesContextOverflowError`, `classifyFailoverReason`,
|
||||
`isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`,
|
||||
`augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`,
|
||||
`supportsAdaptiveThinking`, `supportsMaxThinking`,
|
||||
`resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`,
|
||||
`augmentModelCatalog`, `resolveThinkingProfile`, `isBinaryThinking`,
|
||||
`supportsXHighThinking`, `resolveDefaultThinkingLevel`,
|
||||
`applyConfigDefaults`, `isModernModelRef`,
|
||||
`prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, e
|
||||
`onModelSelected`.
|
||||
- Nota: `capabilities` del runtime provider è metadato condiviso del runner (famiglia del provider,
|
||||
peculiarità di transcript/tooling, suggerimenti per transport/cache). Non è la
|
||||
- Nota: `capabilities` del runtime del provider sono metadati condivisi del runner (famiglia del provider,
|
||||
particolarità di trascrizione/tooling, suggerimenti su transport/cache). Non è la
|
||||
stessa cosa del [modello di capability pubblico](/it/plugins/architecture#public-capability-model)
|
||||
che descrive ciò che un plugin registra (inferenza testuale, voce, ecc.).
|
||||
- Il provider `codex` incluso è abbinato all'harness agente Codex incluso.
|
||||
Usa `codex/gpt-*` quando vuoi login gestito da Codex, individuazione dei modelli,
|
||||
ripresa nativa dei thread ed esecuzione app-server. I riferimenti semplici `openai/gpt-*`
|
||||
continuano a usare il provider OpenAI e il normale transport provider di OpenClaw.
|
||||
che descrive ciò che un Plugin registra (inferenza testuale, voce, ecc.).
|
||||
- Il provider `codex` incluso è abbinato all'harness dell'agente Codex incluso.
|
||||
Usa `codex/gpt-*` quando vuoi login gestito da Codex, rilevamento dei modelli,
|
||||
ripresa nativa dei thread ed esecuzione app-server. I riferimenti semplici `openai/gpt-*` continuano
|
||||
a usare il provider OpenAI e il normale transport provider di OpenClaw.
|
||||
Le distribuzioni solo-Codex possono disabilitare il fallback automatico a PI con
|
||||
`agents.defaults.embeddedHarness.fallback: "none"`; consulta
|
||||
`agents.defaults.embeddedHarness.fallback: "none"`; vedi
|
||||
[Codex Harness](/it/plugins/codex-harness).
|
||||
|
||||
## Comportamento del provider posseduto dal Plugin
|
||||
## Comportamento del provider gestito dal Plugin
|
||||
|
||||
I plugin provider ora possono possedere 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 possiede i flussi di onboarding/login
|
||||
- `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 possiede etichette di scelta auth,
|
||||
alias legacy, suggerimenti di allowlist per l'onboarding e voci di configurazione nei selettori di onboarding/modelli
|
||||
- `wizard.setup` / `wizard.modelPicker`: il provider gestisce etichette di scelta auth,
|
||||
alias legacy, suggerimenti per l'allowlist di onboarding e voci di configurazione nei selettori di onboarding/modello
|
||||
- `catalog`: il provider appare in `models.providers`
|
||||
- `normalizeModelId`: il provider normalizza gli ID di modello legacy/preview prima di
|
||||
lookup o canonicalizzazione
|
||||
- `normalizeTransport`: il provider normalizza `api` / `baseUrl` della famiglia transport
|
||||
- `normalizeModelId`: il provider normalizza gli id di modello legacy/preview prima
|
||||
della ricerca o della canonicalizzazione
|
||||
- `normalizeTransport`: il provider normalizza `api` / `baseUrl` della famiglia di transport
|
||||
prima dell'assemblaggio generico del modello; OpenClaw controlla prima il provider corrispondente,
|
||||
poi altri plugin provider con hook compatibili finché uno non modifica davvero
|
||||
il transport
|
||||
- `normalizeConfig`: il provider normalizza la configurazione `models.providers.<id>` prima che
|
||||
il runtime la usi; OpenClaw controlla prima il provider corrispondente, poi altri
|
||||
plugin provider con hook compatibili finché uno non modifica davvero la configurazione. Se nessun
|
||||
hook provider riscrive la configurazione, gli helper inclusi della famiglia Google continuano comunque a
|
||||
normalizzare le voci provider Google supportate.
|
||||
- `applyNativeStreamingUsageCompat`: il provider applica riscritture di compatibilità native di streaming-usage guidate dall'endpoint per i provider di configurazione
|
||||
poi altri Plugin provider con hook compatibili 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 altri
|
||||
Plugin provider con hook compatibili finché uno non modifica effettivamente la configurazione. Se nessun
|
||||
hook del provider riscrive la configurazione, gli helper inclusi della famiglia Google continuano comunque
|
||||
a normalizzare le voci supportate dei provider Google.
|
||||
- `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 con marker env per i provider di configurazione
|
||||
senza forzare il caricamento completo dell'autenticazione runtime. `amazon-bedrock` ha anche un
|
||||
resolver 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à dell'autenticazione locale/self-hosted o di altra autenticazione supportata da configurazione senza persistere segreti in chiaro
|
||||
- `shouldDeferSyntheticProfileAuth`: il provider può contrassegnare i placeholder di profilo sintetico memorizzati
|
||||
come con precedenza inferiore rispetto all'autenticazione supportata da env/configurazione
|
||||
- `resolveDynamicModel`: il provider accetta ID modello non ancora presenti nel
|
||||
catalogo statico locale
|
||||
- `prepareDynamicModel`: il provider richiede un aggiornamento dei metadati prima di riprovare
|
||||
resolver integrato per marker env AWS qui, anche se l'autenticazione runtime di Bedrock usa
|
||||
la catena predefinita dell'AWS SDK.
|
||||
- `resolveSyntheticAuth`: il provider può esporre la disponibilità di autenticazione locale/self-hosted o di altro tipo
|
||||
basata su configurazione senza persistere segreti in chiaro
|
||||
- `shouldDeferSyntheticProfileAuth`: il provider può contrassegnare i placeholder di profili sintetici archiviati
|
||||
come a priorità inferiore 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 richiede riscritture di transport o URL di base
|
||||
- `contributeResolvedModelCompat`: il provider contribuisce con flag di compatibilità per i propri
|
||||
- `normalizeResolvedModel`: il provider richiede riscritture di transport o base URL
|
||||
- `contributeResolvedModelCompat`: il provider contribuisce flag di compatibilità per i propri
|
||||
modelli vendor anche quando arrivano tramite un altro transport compatibile
|
||||
- `capabilities`: il provider pubblica peculiarità di transcript/tooling/famiglia provider
|
||||
- `capabilities`: il provider pubblica particolarità di trascrizione/tooling/famiglia provider
|
||||
- `normalizeToolSchemas`: il provider pulisce gli schemi degli strumenti prima che il
|
||||
runner incorporato li veda
|
||||
- `inspectToolSchemas`: il provider espone avvisi di schema specifici del transport
|
||||
- `inspectToolSchemas`: il provider espone avvisi sugli schemi specifici del transport
|
||||
dopo la normalizzazione
|
||||
- `resolveReasoningOutputMode`: il provider sceglie contratti di output del reasoning
|
||||
- `resolveReasoningOutputMode`: il provider sceglie contratti di output del ragionamento
|
||||
nativi o con tag
|
||||
- `prepareExtraParams`: il provider imposta valori predefiniti o normalizza parametri di richiesta per modello
|
||||
- `createStreamFn`: il provider sostituisce il normale percorso stream 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 per turno
|
||||
- `resolveWebSocketSessionPolicy`: il provider fornisce header nativi di sessione WebSocket
|
||||
o policy di cooldown della sessione
|
||||
- `createEmbeddingProvider`: il provider possiede il comportamento degli embedding di memoria quando
|
||||
appartiene al plugin provider invece che allo switchboard embedding del core
|
||||
- `formatApiKey`: il provider formatta i profili auth memorizzati nella stringa
|
||||
`apiKey` del runtime attesa dal transport
|
||||
- `refreshOAuth`: il provider possiede il refresh OAuth quando i refresher condivisi
|
||||
`pi-ai` non sono sufficienti
|
||||
- `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 del transport nativo per turno
|
||||
- `resolveWebSocketSessionPolicy`: il provider fornisce header di sessione WebSocket nativa
|
||||
o una policy di cooldown della sessione
|
||||
- `createEmbeddingProvider`: il provider gestisce il comportamento degli embedding della memoria quando
|
||||
appartiene al Plugin provider invece che allo switchboard embedding del core
|
||||
- `formatApiKey`: il provider formatta i profili auth archiviati nella stringa
|
||||
runtime `apiKey` 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
|
||||
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 raw specifici del provider del transport/API
|
||||
a motivi di failover come rate limit o sovraccarico
|
||||
- `isCacheTtlEligible`: il provider decide quali ID modello upstream supportano il TTL della prompt-cache
|
||||
- `buildMissingAuthMessage`: il provider sostituisce l'errore generico dell'auth-store
|
||||
- `classifyFailoverReason`: il provider mappa errori raw di transport/API specifici del provider
|
||||
a motivi di failover come rate limit o overload
|
||||
- `isCacheTtlEligible`: il provider decide quali id di modelli upstream supportano il TTL della cache dei prompt
|
||||
- `buildMissingAuthMessage`: il provider sostituisce l'errore generico dell'archivio auth
|
||||
con un suggerimento di recupero specifico del provider
|
||||
- `suppressBuiltInModel`: il provider nasconde righe upstream obsolete e può restituire un
|
||||
errore posseduto dal vendor per fallimenti di risoluzione diretta
|
||||
- `augmentModelCatalog`: il provider aggiunge righe sintetiche/finali del catalogo dopo
|
||||
discovery e unione della configurazione
|
||||
- `isBinaryThinking`: il provider possiede l'esperienza utente thinking binaria on/off
|
||||
- `supportsXHighThinking`: il provider abilita `xhigh` per modelli selezionati
|
||||
- `supportsAdaptiveThinking`: il provider abilita `adaptive` per modelli selezionati
|
||||
- `supportsMaxThinking`: il provider abilita `max` per modelli selezionati
|
||||
- `resolveDefaultThinkingLevel`: il provider possiede la policy predefinita `/think` per una
|
||||
famiglia di modelli
|
||||
- `applyConfigDefaults`: il provider applica valori globali predefiniti specifici del provider
|
||||
durante la materializzazione della configurazione in base a modalità auth, env o famiglia di modelli
|
||||
- `isModernModelRef`: il provider possiede la corrispondenza dei modelli preferiti per live/smoke
|
||||
errore gestito dal vendor per fallimenti di risoluzione diretta
|
||||
- `augmentModelCatalog`: il provider aggiunge righe di catalogo sintetiche/finali dopo
|
||||
il rilevamento e l'unione della configurazione
|
||||
- `resolveThinkingProfile`: il provider gestisce l'esatto insieme di livelli `/think`,
|
||||
eventuali etichette di visualizzazione e il livello predefinito per un modello selezionato
|
||||
- `isBinaryThinking`: hook di compatibilità per UX thinking binaria on/off
|
||||
- `supportsXHighThinking`: hook di compatibilità per modelli `xhigh` selezionati
|
||||
- `resolveDefaultThinkingLevel`: hook di compatibilità per la policy predefinita di `/think`
|
||||
- `applyConfigDefaults`: il provider applica valori predefiniti globali specifici del provider
|
||||
durante la materializzazione della configurazione in base alla modalità auth, all'env o alla famiglia di modelli
|
||||
- `isModernModelRef`: il provider gestisce la corrispondenza 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 usage/quota per `/usage`
|
||||
e superfici correlate di stato/reporting
|
||||
- `fetchUsageSnapshot`: il provider possiede il recupero/parsing dell'endpoint di usage mentre
|
||||
il core continua a possedere il guscio di riepilogo e la formattazione
|
||||
a breve durata
|
||||
- `resolveUsageAuth`: il provider risolve le credenziali di uso/quota per `/usage`
|
||||
e relative superfici di stato/reporting
|
||||
- `fetchUsageSnapshot`: il provider gestisce il recupero/parsing dell'endpoint di uso mentre
|
||||
il core continua a gestire la shell di riepilogo e la formattazione
|
||||
- `onModelSelected`: il provider esegue effetti collaterali post-selezione come
|
||||
telemetria o bookkeeping di sessione posseduto dal provider
|
||||
telemetria o bookkeeping di sessione gestito dal provider
|
||||
|
||||
Esempi inclusi attuali:
|
||||
|
||||
- `anthropic`: fallback forward-compat per Claude 4.6, suggerimenti per la riparazione dell'autenticazione, recupero dell'endpoint di usage, metadati cache-TTL/famiglia provider e valori predefiniti di configurazione globale sensibili all'autenticazione
|
||||
- `amazon-bedrock`: riconoscimento dell'overflow del contesto posseduto dal provider e classificazione dei motivi di failover per errori specifici di Bedrock come throttle/not-ready, più la famiglia condivisa `anthropic-by-model` per guardrail della replay-policy solo-Claude sul traffico Anthropic
|
||||
- `anthropic-vertex`: guardrail della replay-policy solo-Claude sul traffico di messaggi Anthropic
|
||||
- `openrouter`: ID modello pass-through, wrapper delle richieste, suggerimenti sulle capability del provider, sanificazione della thought-signature Gemini sul traffico Gemini via proxy, injection del reasoning via proxy attraverso la famiglia stream `openrouter-thinking`, inoltro dei metadati di routing e policy cache-TTL
|
||||
- `github-copilot`: onboarding/login del dispositivo, fallback forward-compat del modello, suggerimenti per transcript Claude-thinking, scambio di token runtime e recupero dell'endpoint di usage
|
||||
- `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 per thinking/modelli live, normalizzazione degli alias dei token di usage (`input` / `output` e famiglie `prompt` / `completion`), la famiglia stream condivisa `openai-responses-defaults` per wrapper nativi OpenAI/Codex, metadati della 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 Gemini 3.1, validazione replay nativa Gemini, sanificazione del bootstrap replay, modalità di output del reasoning con tag, corrispondenza dei modelli moderni, registrazione inclusa del provider di generazione immagini per modelli Gemini image-preview e registrazione inclusa del provider di generazione video per modelli Veo; inoltre l'OAuth Gemini CLI possiede la formattazione dei token del profilo auth, il parsing dei token di usage e il recupero dell'endpoint quota per le superfici di usage
|
||||
- `moonshot`: transport condiviso, normalizzazione del payload thinking posseduta dal plugin
|
||||
- `kilocode`: transport condiviso, header di richiesta posseduti dal plugin, normalizzazione del payload reasoning, sanificazione della thought-signature proxy-Gemini e policy cache-TTL
|
||||
- `zai`: fallback forward-compat GLM-5, valori predefiniti `tool_stream`, policy cache-TTL, policy binary-thinking/live-model e autenticazione usage + recupero quota; gli ID sconosciuti `glm-5*` vengono sintetizzati dal template incluso `glm-4.7`
|
||||
- `xai`: normalizzazione nativa del transport Responses, riscritture alias `/fast` per varianti veloci Grok, `tool_stream` predefinito, pulizia di schema strumenti / payload reasoning specifica xAI e registrazione inclusa del provider di generazione video per `grok-imagine-video`
|
||||
- `mistral`: metadati delle capability posseduti dal plugin
|
||||
- `opencode` e `opencode-go`: metadati delle capability posseduti dal plugin più sanificazione della thought-signature proxy-Gemini
|
||||
- `alibaba`: catalogo di generazione video posseduto dal plugin per riferimenti diretti ai modelli Wan come `alibaba/wan2.6-t2v`
|
||||
- `byteplus`: cataloghi posseduti 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 modelli video di terze parti ospitati, registrazione del provider di generazione immagini per modelli immagine FLUX e registrazione inclusa del provider di generazione video per modelli video di terze parti ospitati
|
||||
- `anthropic`: fallback forward-compat per Claude 4.6, suggerimenti di riparazione auth, recupero dell'endpoint di utilizzo, metadati cache-TTL/famiglia provider e valori predefiniti globali della configurazione sensibili all'auth
|
||||
- `amazon-bedrock`: corrispondenza degli overflow di contesto gestita dal provider 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 protezioni della replay-policy solo-Claude sul traffico Anthropic
|
||||
- `anthropic-vertex`: protezioni della replay-policy solo-Claude sul traffico dei messaggi Anthropic
|
||||
- `openrouter`: id modello pass-through, wrapper delle richieste, hint sulle capability del provider, sanificazione della thought-signature di Gemini sul traffico Gemini via proxy, iniezione del reasoning via proxy tramite la famiglia di stream `openrouter-thinking`, inoltro dei metadati di routing e policy cache-TTL
|
||||
- `github-copilot`: onboarding/login del dispositivo, fallback forward-compat del modello, hint di trascrizione Claude-thinking, scambio di token runtime e recupero dell'endpoint di utilizzo
|
||||
- `openai`: fallback forward-compat per GPT-5.4, normalizzazione diretta del transport OpenAI, hint di auth mancante consapevoli di Codex, soppressione di Spark, righe di catalogo sintetiche OpenAI/Codex, policy di thinking/modelli live, normalizzazione degli alias dei token di utilizzo (`input` / `output` e famiglie `prompt` / `completion`), la famiglia di stream condivisa `openai-responses-defaults` per i wrapper nativi OpenAI/Codex, metadati della 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 bootstrap replay, modalità di output reasoning con tag, corrispondenza dei modelli moderni, registrazione inclusa del provider di generazione immagini per i modelli Gemini image-preview e registrazione inclusa del provider di generazione video per i modelli Veo; inoltre Gemini CLI OAuth gestisce la formattazione dei token del profilo auth, il parsing dei token di utilizzo e il recupero 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 reasoning, sanificazione della thought-signature di Gemini via proxy e policy cache-TTL
|
||||
- `zai`: fallback forward-compat per GLM-5, valori predefiniti `tool_stream`, policy cache-TTL, policy di binary-thinking/modelli live e auth di utilizzo + recupero quota; gli id sconosciuti `glm-5*` vengono sintetizzati a partire dal template incluso `glm-4.7`
|
||||
- `xai`: normalizzazione nativa del transport Responses, riscritture degli alias `/fast` per le varianti veloci di Grok, `tool_stream` predefinito, pulizia di tool-schema/payload reasoning specifica di 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 di Gemini via proxy
|
||||
- `alibaba`: catalogo di generazione video gestito dal Plugin per riferimenti diretti ai modelli Wan come `alibaba/wan2.6-t2v`
|
||||
- `byteplus`: cataloghi gestiti dal Plugin più registrazione inclusa del provider di generazione video per i modelli Seedance text-to-video/image-to-video
|
||||
- `fal`: registrazione inclusa del provider di generazione video per modelli video di terze parti ospitati, registrazione inclusa del provider di generazione immagini per i modelli immagine FLUX più registrazione inclusa del provider di generazione video per modelli video di terze parti ospitati
|
||||
- `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`,
|
||||
`stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` e `volcengine`:
|
||||
solo cataloghi posseduti dal plugin
|
||||
- `qwen`: cataloghi posseduti dal plugin per modelli testuali più registrazioni condivise di provider per comprensione media e generazione video per le sue superfici multimodali; la generazione video Qwen usa gli endpoint video DashScope Standard con modelli Wan inclusi come `wan2.6-t2v` e `wan2.7-r2v`
|
||||
- `runway`: registrazione del provider di generazione video posseduta dal plugin per modelli nativi Runway basati su task come `gen4.5`
|
||||
- `minimax`: cataloghi posseduti 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 auth/snapshot per usage
|
||||
- `together`: cataloghi posseduti dal plugin più registrazione inclusa del provider di generazione video per modelli video Wan
|
||||
- `xiaomi`: cataloghi posseduti dal plugin più logica auth/snapshot per usage
|
||||
solo cataloghi gestiti dal Plugin
|
||||
- `qwen`: cataloghi gestiti dal Plugin per i modelli testuali più registrazioni condivise dei provider di comprensione dei media e generazione video per le sue superfici multimodali; la generazione video Qwen usa gli endpoint video DashScope Standard 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 di Runway come `gen4.5`
|
||||
- `minimax`: cataloghi gestiti dal Plugin, registrazione inclusa del provider di generazione video per i modelli video Hailuo, registrazione inclusa del provider di generazione immagini per `image-01`, selezione ibrida della replay-policy Anthropic/OpenAI e logica auth/snapshot di utilizzo
|
||||
- `together`: cataloghi gestiti dal Plugin più registrazione inclusa del provider di generazione video per i modelli video Wan
|
||||
- `xiaomi`: cataloghi gestiti dal Plugin più logica auth/snapshot di utilizzo
|
||||
|
||||
Il plugin `openai` incluso ora possiede entrambi gli ID provider: `openai` e
|
||||
Il Plugin `openai` incluso 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 appartiene a una superficie di estensione separata e più profonda.
|
||||
Questo copre i provider che rientrano ancora nei transport normali di OpenClaw. Un provider
|
||||
che necessita di un esecutore di richieste completamente personalizzato è una superficie di estensione
|
||||
separata e più profonda.
|
||||
|
||||
## Rotazione delle chiavi API
|
||||
## Rotazione delle API key
|
||||
|
||||
- Supporta la rotazione generica del provider per provider selezionati.
|
||||
- Configura più chiavi tramite:
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (singolo override live, priorità massima)
|
||||
- `<PROVIDER>_API_KEYS` (elenco separato da virgole o punti e virgola)
|
||||
- `<PROVIDER>_API_KEYS` (elenco separato da virgole o punto e virgola)
|
||||
- `<PROVIDER>_API_KEY` (chiave primaria)
|
||||
- `<PROVIDER>_API_KEY_*` (elenco numerato, ad esempio `<PROVIDER>_API_KEY_1`)
|
||||
- Per i provider Google, anche `GOOGLE_API_KEY` è incluso come fallback.
|
||||
- L'ordine di selezione delle chiavi preserva la priorità ed elimina i duplicati.
|
||||
- Le richieste vengono ritentate con la chiave successiva solo in caso di risposte di rate limit (per
|
||||
- `<PROVIDER>_API_KEY_*` (elenco numerato, 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 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).
|
||||
- Gli errori non dovuti a rate limit falliscono immediatamente; non viene tentata alcuna rotazione delle chiavi.
|
||||
`workers_ai ... quota limit exceeded` o messaggi periodici di limite di utilizzo).
|
||||
- I fallimenti diversi dal 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 e scegliere un modello.
|
||||
OpenClaw viene distribuito con il catalogo pi-ai. Questi provider non richiedono alcuna
|
||||
configurazione `models.providers`; basta impostare l'auth e scegliere un modello.
|
||||
|
||||
### OpenAI
|
||||
|
||||
@ -217,16 +219,16 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere
|
||||
- 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"` oppure `"auto"`)
|
||||
- Il warm-up di OpenAI Responses WebSocket è abilitato per impostazione predefinita tramite `params.openaiWsWarmup` (`true`/`false`)
|
||||
- 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 direct `openai/*` Responses a `service_tier=priority` su `api.openai.com`
|
||||
- Usa `params.serviceTier` quando vuoi un tier 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
|
||||
ai proxy generici compatibili con OpenAI
|
||||
- I percorsi OpenAI nativi mantengono anche `store` di Responses, suggerimenti prompt-cache e
|
||||
modellazione del payload reasoning-compat OpenAI; i percorsi proxy no
|
||||
- `/fast` e `params.fastMode` mappano le richieste dirette `openai/*` Responses a `service_tier=priority` su `api.openai.com`
|
||||
- Usa `params.serviceTier` quando vuoi un tier esplicito invece dell'interruttore condiviso `/fast`
|
||||
- Gli header nascosti di attribuzione OpenClaw (`originator`, `version`,
|
||||
`User-Agent`) si applicano solo al traffico OpenAI nativo verso `api.openai.com`, non ai
|
||||
proxy generici compatibili con OpenAI
|
||||
- Le route OpenAI native mantengono anche `store` di Responses, hint per la cache dei prompt e
|
||||
il shaping del payload di compatibilità reasoning di OpenAI; le route proxy no
|
||||
- `openai/gpt-5.3-codex-spark` è intenzionalmente soppresso in OpenClaw perché l'API OpenAI live lo rifiuta; Spark è trattato come solo-Codex
|
||||
|
||||
```json5
|
||||
@ -242,9 +244,9 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere
|
||||
- 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 Anthropic `service_tier` (`auto` vs `standard_only`)
|
||||
- Nota Anthropic: il personale Anthropic ci ha comunicato che l'uso in stile Claude CLI di OpenClaw è nuovamente consentito, quindi OpenClaw tratta il riutilizzo di Claude CLI e l'uso di `claude -p` come autorizzati per questa integrazione, salvo pubblicazione di una nuova policy da parte di Anthropic.
|
||||
- Il setup-token Anthropic rimane disponibile come percorso token supportato da OpenClaw, ma OpenClaw ora preferisce il riutilizzo di Claude CLI e `claude -p` quando disponibili.
|
||||
- Le richieste pubbliche dirette ad Anthropic supportano anche l'interruttore condiviso `/fast` e `params.fastMode`, incluso il traffico autenticato con API key e OAuth inviato a `api.anthropic.com`; OpenClaw lo mappa a Anthropic `service_tier` (`auto` vs `standard_only`)
|
||||
- Nota Anthropic: il personale Anthropic ci ha detto che l'uso in stile Claude CLI di OpenClaw è di nuovo consentito, quindi OpenClaw considera il riuso di Claude CLI e l'uso di `claude -p` come autorizzati per questa integrazione, 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
|
||||
{
|
||||
@ -257,17 +259,17 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere
|
||||
- Provider: `openai-codex`
|
||||
- Auth: OAuth (ChatGPT)
|
||||
- Modello di esempio: `openai-codex/gpt-5.4`
|
||||
- CLI: `openclaw onboard --auth-choice openai-codex` oppure `openclaw models auth login --provider openai-codex`
|
||||
- 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"` oppure `"auto"`)
|
||||
- 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`,
|
||||
- Gli header nascosti di attribuzione OpenClaw (`originator`, `version`,
|
||||
`User-Agent`) vengono allegati solo al traffico Codex nativo verso
|
||||
`chatgpt.com/backend-api`, non ai proxy generici compatibili con OpenAI
|
||||
- Condivide lo stesso toggle `/fast` e la 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 dalle entitlement
|
||||
- `openai-codex/gpt-5.4` mantiene `contextWindow = 1050000` nativo e un valore predefinito runtime `contextTokens = 272000`; sostituisci il limite runtime con `models.providers.openai-codex.models[].contextTokens`
|
||||
- Nota di policy: OAuth OpenAI Codex è esplicitamente supportato per strumenti/workflow esterni come OpenClaw.
|
||||
- Condivide lo stesso interruttore `/fast` e la configurazione `params.fastMode` di `openai/*` diretto; OpenClaw lo mappa a `service_tier=priority`
|
||||
- `openai-codex/gpt-5.3-codex-spark` rimane disponibile quando il catalogo OAuth di Codex lo espone; dipende dalle autorizzazioni
|
||||
- `openai-codex/gpt-5.4` mantiene `contextWindow = 1050000` nativo e un `contextTokens = 272000` runtime predefinito; esegui l'override del limite runtime con `models.providers.openai-codex.models[].contextTokens`
|
||||
- Nota sulla policy: OpenAI Codex OAuth è esplicitamente supportato per strumenti/workflow esterni come OpenClaw.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -289,17 +291,17 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere
|
||||
|
||||
### Altre opzioni ospitate in stile abbonamento
|
||||
|
||||
- [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 con chiave API
|
||||
- [GLM Models](/it/providers/glm): endpoint Z.AI Coding Plan o API generiche
|
||||
- [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 via OAuth o API key
|
||||
- [GLM Models](/it/providers/glm): endpoint Z.AI Coding Plan o API generici
|
||||
|
||||
### OpenCode
|
||||
|
||||
- Auth: `OPENCODE_API_KEY` (oppure `OPENCODE_ZEN_API_KEY`)
|
||||
- Auth: `OPENCODE_API_KEY` (o `OPENCODE_ZEN_API_KEY`)
|
||||
- Provider runtime Zen: `opencode`
|
||||
- Provider runtime Go: `opencode-go`
|
||||
- Modelli di esempio: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5`
|
||||
- CLI: `openclaw onboard --auth-choice opencode-zen` oppure `openclaw onboard --auth-choice opencode-go`
|
||||
- CLI: `openclaw onboard --auth-choice opencode-zen` o `openclaw onboard --auth-choice opencode-go`
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -307,34 +309,34 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere
|
||||
}
|
||||
```
|
||||
|
||||
### Google Gemini (chiave API)
|
||||
### Google Gemini (API key)
|
||||
|
||||
- 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` (singolo override)
|
||||
- Modelli di esempio: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview`
|
||||
- Compatibilità: la configurazione legacy OpenClaw che usa `google/gemini-3.1-flash-preview` viene normalizzata in `google/gemini-3-flash-preview`
|
||||
- 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`
|
||||
(oppure il legacy `cached_content`) per inoltrare un handle
|
||||
nativo del provider `cachedContents/...`; gli hit della cache Gemini emergono come `cacheRead` in OpenClaw
|
||||
- Le esecuzioni dirette Gemini accettano anche `agents.defaults.models["google/<model>"].params.cachedContent`
|
||||
(o il legacy `cached_content`) per inoltrare un handle nativo del provider
|
||||
`cachedContents/...`; gli hit della cache Gemini vengono esposti come `cacheRead` di OpenClaw
|
||||
|
||||
### 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 l'uso di client di terze parti. Consulta i termini di Google e usa un account non critico se scegli di procedere.
|
||||
- Gemini CLI OAuth è distribuito come parte del plugin `google` incluso.
|
||||
- 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 dell'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 viene distribuito come parte del Plugin `google` incluso.
|
||||
- Installa prima Gemini CLI:
|
||||
- `brew install gemini-cli`
|
||||
- oppure `npm install -g @google/gemini-cli`
|
||||
- Abilita: `openclaw plugins enable google`
|
||||
- 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 Gateway.
|
||||
- Se le richieste falliscono dopo il login, imposta `GOOGLE_CLOUD_PROJECT` o `GOOGLE_CLOUD_PROJECT_ID` sull'host Gateway.
|
||||
- Le risposte JSON di Gemini CLI vengono analizzate da `response`; usage ricade su
|
||||
- Nota: **non** incolli un client id o un secret in `openclaw.json`. Il flusso di login CLI archivia
|
||||
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'utilizzo usa come fallback
|
||||
`stats`, con `stats.cached` normalizzato in `cacheRead` di OpenClaw.
|
||||
|
||||
### Z.AI (GLM)
|
||||
@ -359,46 +361,44 @@ configurazione `models.providers`; basta impostare l'autenticazione e scegliere
|
||||
- Auth: `KILOCODE_API_KEY`
|
||||
- Modello di esempio: `kilocode/kilo/auto`
|
||||
- CLI: `openclaw onboard --auth-choice kilocode-api-key`
|
||||
- URL di base: `https://api.kilo.ai/api/gateway/`
|
||||
- Il catalogo di fallback statico 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`; il rilevamento 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,
|
||||
non codificato rigidamente in OpenClaw.
|
||||
non codificato in modo statico in OpenClaw.
|
||||
|
||||
Consulta [/providers/kilocode](/it/providers/kilocode) per i dettagli di configurazione.
|
||||
Vedi [/providers/kilocode](/it/providers/kilocode) per i dettagli di configurazione.
|
||||
|
||||
### Altri plugin provider inclusi
|
||||
### Altri Plugin provider inclusi
|
||||
|
||||
- OpenRouter: `openrouter` (`OPENROUTER_API_KEY`)
|
||||
- Modello di esempio: `openrouter/auto`
|
||||
- OpenClaw applica gli header di attribuzione app documentati di OpenRouter solo quando
|
||||
- OpenClaw applica gli header di attribuzione dell'app documentati da OpenRouter solo quando
|
||||
la richiesta punta effettivamente a `openrouter.ai`
|
||||
- I marker `cache_control` specifici di Anthropic per OpenRouter sono ugualmente limitati a
|
||||
percorsi OpenRouter verificati, non a URL proxy arbitrari
|
||||
- OpenRouter rimane sul percorso in stile proxy compatibile con OpenAI, quindi la
|
||||
modellazione della richiesta solo-nativa OpenAI (`serviceTier`, `store` di Responses,
|
||||
suggerimenti prompt-cache, payload OpenAI reasoning-compat) non viene inoltrata
|
||||
- I riferimenti OpenRouter supportati da Gemini mantengono solo la sanificazione della thought-signature proxy-Gemini;
|
||||
la validazione replay Gemini nativa e le riscritture bootstrap restano disattivate
|
||||
- I marker `cache_control` specifici di Anthropic per OpenRouter sono analogamente limitati
|
||||
a route OpenRouter verificate, non a URL proxy arbitrarie
|
||||
- OpenRouter rimane sul percorso in stile proxy compatibile con OpenAI, quindi il shaping nativo delle richieste solo-OpenAI (`serviceTier`, `store` di Responses,
|
||||
hint per la cache dei prompt, payload di compatibilità reasoning di OpenAI) non viene inoltrato
|
||||
- I ref OpenRouter basati su Gemini mantengono solo la sanificazione della thought-signature di Gemini via proxy;
|
||||
la validazione nativa del replay Gemini e le riscritture bootstrap restano disattivate
|
||||
- Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`)
|
||||
- Modello di esempio: `kilocode/kilo/auto`
|
||||
- I riferimenti Kilo supportati da Gemini mantengono lo stesso percorso di
|
||||
sanificazione della thought-signature proxy-Gemini; `kilocode/kilo/auto` e altri suggerimenti
|
||||
proxy-reasoning-non-supportato saltano l'iniezione di reasoning via proxy
|
||||
- MiniMax: `minimax` (chiave API) e `minimax-portal` (OAuth)
|
||||
- I ref Kilo basati su Gemini mantengono lo stesso percorso di sanificazione della thought-signature di Gemini via proxy; `kilocode/kilo/auto` e altri hint proxy-reasoning-non-supportato
|
||||
saltano l'iniezione del reasoning via proxy
|
||||
- MiniMax: `minimax` (API key) 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` oppure `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 incluso mantiene i riferimenti chat
|
||||
solo testo finché quella configurazione provider non viene materializzata
|
||||
- Modello di esempio: `minimax/MiniMax-M2.7` o `minimax-portal/MiniMax-M2.7`
|
||||
- La configurazione onboarding/API key di MiniMax scrive definizioni esplicite del modello M2.7 con
|
||||
`input: ["text", "image"]`; il catalogo del provider incluso mantiene i ref chat
|
||||
solo testo finché quella configurazione del provider non viene materializzata
|
||||
- Moonshot: `moonshot` (`MOONSHOT_API_KEY`)
|
||||
- Modello di esempio: `moonshot/kimi-k2.6`
|
||||
- Kimi Coding: `kimi` (`KIMI_API_KEY` oppure `KIMICODE_API_KEY`)
|
||||
- Kimi Coding: `kimi` (`KIMI_API_KEY` o `KIMICODE_API_KEY`)
|
||||
- Modello di esempio: `kimi/kimi-code`
|
||||
- Qianfan: `qianfan` (`QIANFAN_API_KEY`)
|
||||
- Modello di esempio: `qianfan/deepseek-v3.2`
|
||||
- Qwen Cloud: `qwen` (`QWEN_API_KEY`, `MODELSTUDIO_API_KEY` oppure `DASHSCOPE_API_KEY`)
|
||||
- Qwen Cloud: `qwen` (`QWEN_API_KEY`, `MODELSTUDIO_API_KEY` o `DASHSCOPE_API_KEY`)
|
||||
- Modello di esempio: `qwen/qwen3.5-plus`
|
||||
- NVIDIA: `nvidia` (`NVIDIA_API_KEY`)
|
||||
- Modello di esempio: `nvidia/nvidia/llama-3.1-nemotron-70b-instruct`
|
||||
@ -410,7 +410,7 @@ Consulta [/providers/kilocode](/it/providers/kilocode) per i dettagli di configu
|
||||
- Xiaomi: `xiaomi` (`XIAOMI_API_KEY`)
|
||||
- Modello di esempio: `xiaomi/mimo-v2-flash`
|
||||
- Vercel AI Gateway: `vercel-ai-gateway` (`AI_GATEWAY_API_KEY`)
|
||||
- Hugging Face Inference: `huggingface` (`HUGGINGFACE_HUB_TOKEN` oppure `HF_TOKEN`)
|
||||
- Hugging Face Inference: `huggingface` (`HUGGINGFACE_HUB_TOKEN` o `HF_TOKEN`)
|
||||
- Cloudflare AI Gateway: `cloudflare-ai-gateway` (`CLOUDFLARE_AI_GATEWAY_API_KEY`)
|
||||
- Volcengine: `volcengine` (`VOLCANO_ENGINE_API_KEY`)
|
||||
- Modello di esempio: `volcengine-plan/ark-code-latest`
|
||||
@ -418,7 +418,7 @@ Consulta [/providers/kilocode](/it/providers/kilocode) per i dettagli di configu
|
||||
- Modello di esempio: `byteplus-plan/ark-code-latest`
|
||||
- xAI: `xai` (`XAI_API_KEY`)
|
||||
- Le richieste xAI native incluse usano il percorso xAI Responses
|
||||
- `/fast` oppure `params.fastMode: true` riscrivono `grok-3`, `grok-3-mini`,
|
||||
- `/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
|
||||
@ -428,32 +428,31 @@ Consulta [/providers/kilocode](/it/providers/kilocode) per i dettagli di configu
|
||||
- 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`.
|
||||
- URL di base compatibile con OpenAI: `https://api.cerebras.ai/v1`.
|
||||
- I modelli GLM su Cerebras usano gli id `zai-glm-4.7` e `zai-glm-4.6`.
|
||||
- URL base compatibile con OpenAI: `https://api.cerebras.ai/v1`.
|
||||
- GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`)
|
||||
- Modello di esempio Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Consulta [Hugging Face (Inference)](/it/providers/huggingface).
|
||||
- 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).
|
||||
|
||||
## Provider tramite `models.providers` (personalizzato/base URL)
|
||||
## Provider tramite `models.providers` (URL personalizzato/base)
|
||||
|
||||
Usa `models.providers` (oppure `models.json`) per aggiungere provider **personalizzati** o
|
||||
Usa `models.providers` (o `models.json`) per aggiungere provider **personalizzati** o
|
||||
proxy compatibili con OpenAI/Anthropic.
|
||||
|
||||
Molti dei plugin provider inclusi qui sotto pubblicano già un catalogo predefinito.
|
||||
Usa voci esplicite `models.providers.<id>` solo quando vuoi sovrascrivere
|
||||
l'URL di base, gli header o l'elenco dei modelli predefinito.
|
||||
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 l'elenco dei modelli predefinito.
|
||||
|
||||
### Moonshot AI (Kimi)
|
||||
|
||||
Moonshot è distribuito come plugin provider incluso. Usa il provider integrato per
|
||||
Moonshot viene distribuito come Plugin provider incluso. Usa il provider integrato per
|
||||
impostazione predefinita e aggiungi una voce esplicita `models.providers.moonshot` solo quando
|
||||
devi sovrascrivere l'URL di base 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.6`
|
||||
- CLI: `openclaw onboard --auth-choice moonshot-api-key` oppure `openclaw onboard --auth-choice moonshot-api-key-cn`
|
||||
- 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"
|
||||
|
||||
@ -501,7 +500,7 @@ Kimi Coding usa l'endpoint compatibile con Anthropic di Moonshot AI:
|
||||
}
|
||||
```
|
||||
|
||||
Il legacy `kimi/k2p5` continua a essere accettato come ID modello di compatibilità.
|
||||
Il legacy `kimi/k2p5` continua a essere accettato come id modello di compatibilità.
|
||||
|
||||
### Volcano Engine (Doubao)
|
||||
|
||||
@ -520,11 +519,11 @@ 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 contemporaneamente.
|
||||
L'onboarding usa per impostazione predefinita la superficie coding, ma il catalogo generale `volcengine/*`
|
||||
viene registrato nello stesso momento.
|
||||
|
||||
Nei selettori di onboarding/configurazione del modello, la scelta auth Volcengine preferisce entrambe
|
||||
le righe `volcengine/*` e `volcengine-plan/*`. Se quei modelli non sono ancora caricati,
|
||||
Nei selettori di onboarding/configurazione del modello, la scelta auth di Volcengine preferisce sia le righe
|
||||
`volcengine/*` sia `volcengine-plan/*`. Se questi modelli non sono ancora caricati,
|
||||
OpenClaw ripiega sul catalogo non filtrato invece di mostrare un selettore
|
||||
vuoto limitato al provider.
|
||||
|
||||
@ -562,10 +561,10 @@ 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 contemporaneamente.
|
||||
viene registrato nello stesso momento.
|
||||
|
||||
Nei selettori di onboarding/configurazione del modello, la scelta auth BytePlus preferisce entrambe
|
||||
le righe `byteplus/*` e `byteplus-plan/*`. Se quei modelli non sono ancora caricati,
|
||||
Nei selettori di onboarding/configurazione del modello, la scelta auth di BytePlus preferisce sia le righe
|
||||
`byteplus/*` sia `byteplus-plan/*`. Se questi modelli non sono ancora caricati,
|
||||
OpenClaw ripiega sul catalogo non filtrato invece di mostrare un selettore
|
||||
vuoto limitato al provider.
|
||||
|
||||
@ -617,33 +616,33 @@ MiniMax viene configurato tramite `models.providers` perché usa endpoint person
|
||||
|
||||
- MiniMax OAuth (globale): `--auth-choice minimax-global-oauth`
|
||||
- MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth`
|
||||
- Chiave API MiniMax (globale): `--auth-choice minimax-global-api`
|
||||
- Chiave API MiniMax (CN): `--auth-choice minimax-cn-api`
|
||||
- API key MiniMax (globale): `--auth-choice minimax-global-api`
|
||||
- API key MiniMax (CN): `--auth-choice minimax-cn-api`
|
||||
- Auth: `MINIMAX_API_KEY` per `minimax`; `MINIMAX_OAUTH_TOKEN` oppure
|
||||
`MINIMAX_API_KEY` per `minimax-portal`
|
||||
|
||||
Consulta [/providers/minimax](/it/providers/minimax) per i dettagli di configurazione, le opzioni dei modelli e gli snippet di configurazione.
|
||||
Vedi [/providers/minimax](/it/providers/minimax) per i dettagli di configurazione, le opzioni di modello e gli snippet di configurazione.
|
||||
|
||||
Nel percorso di streaming compatibile con Anthropic di MiniMax, OpenClaw disabilita il thinking per
|
||||
impostazione predefinita a meno che tu non lo imposti esplicitamente, e `/fast on` riscrive
|
||||
Sul percorso di streaming compatibile con Anthropic di MiniMax, OpenClaw disabilita thinking per
|
||||
impostazione predefinita a meno che non lo imposti esplicitamente, e `/fast on` riscrive
|
||||
`MiniMax-M2.7` in `MiniMax-M2.7-highspeed`.
|
||||
|
||||
Suddivisione delle capability posseduta dal plugin:
|
||||
Suddivisione delle capability gestita dal Plugin:
|
||||
|
||||
- I valori predefiniti testo/chat restano su `minimax/MiniMax-M2.7`
|
||||
- La generazione di immagini è `minimax/image-01` oppure `minimax-portal/image-01`
|
||||
- La comprensione delle immagini è `MiniMax-VL-01` posseduto dal plugin su entrambi i percorsi auth MiniMax
|
||||
- La ricerca web resta sull'ID provider `minimax`
|
||||
- I valori predefiniti text/chat restano su `minimax/MiniMax-M2.7`
|
||||
- La generazione di immagini è `minimax/image-01` o `minimax-portal/image-01`
|
||||
- La comprensione delle immagini è `MiniMax-VL-01` gestita dal Plugin su entrambi i percorsi auth MiniMax
|
||||
- La ricerca web resta sull'id provider `minimax`
|
||||
|
||||
### LM Studio
|
||||
|
||||
LM Studio è distribuito come plugin provider incluso che usa l'API nativa:
|
||||
LM Studio viene distribuito come Plugin provider incluso che usa l'API nativa:
|
||||
|
||||
- Provider: `lmstudio`
|
||||
- Auth: `LM_API_TOKEN`
|
||||
- URL di base predefinito per l'inferenza: `http://localhost:1234/v1`
|
||||
- URL base predefinito per l'inferenza: `http://localhost:1234/v1`
|
||||
|
||||
Poi imposta un modello (sostituiscilo con uno degli ID restituiti da `http://localhost:1234/api/v1/models`):
|
||||
Poi imposta un modello (sostituisci con uno degli ID restituiti da `http://localhost:1234/api/v1/models`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -654,15 +653,15 @@ Poi imposta un modello (sostituiscilo con uno degli ID restituiti da `http://loc
|
||||
```
|
||||
|
||||
OpenClaw usa `/api/v1/models` e `/api/v1/models/load` nativi di LM Studio
|
||||
per discovery + auto-load, con `/v1/chat/completions` per l'inferenza per impostazione predefinita.
|
||||
Consulta [/providers/lmstudio](/it/providers/lmstudio) per configurazione e risoluzione dei problemi.
|
||||
per rilevamento + caricamento automatico, con `/v1/chat/completions` per l'inferenza per impostazione predefinita.
|
||||
Vedi [/providers/lmstudio](/it/providers/lmstudio) per configurazione e risoluzione dei problemi.
|
||||
|
||||
### Ollama
|
||||
|
||||
Ollama è distribuito come plugin provider incluso e usa l'API nativa di Ollama:
|
||||
Ollama viene distribuito come Plugin provider incluso e usa l'API nativa di Ollama:
|
||||
|
||||
- Provider: `ollama`
|
||||
- Auth: non richiesta (server locale)
|
||||
- Auth: nessuna richiesta (server locale)
|
||||
- Modello di esempio: `ollama/llama3.3`
|
||||
- Installazione: [https://ollama.com/download](https://ollama.com/download)
|
||||
|
||||
@ -679,26 +678,27 @@ ollama pull llama3.3
|
||||
}
|
||||
```
|
||||
|
||||
Ollama viene rilevato localmente su `http://127.0.0.1:11434` quando effettui l'opt-in con
|
||||
`OLLAMA_API_KEY`, e il plugin provider incluso aggiunge Ollama direttamente a
|
||||
`openclaw onboard` e al selettore di modelli. Consulta [/providers/ollama](/it/providers/ollama)
|
||||
Ollama viene rilevato localmente su `http://127.0.0.1:11434` quando scegli di abilitarlo con
|
||||
`OLLAMA_API_KEY`, e il Plugin provider incluso aggiunge Ollama direttamente a
|
||||
`openclaw onboard` e al selettore del modello. Vedi [/providers/ollama](/it/providers/ollama)
|
||||
per onboarding, modalità cloud/locale e configurazione personalizzata.
|
||||
|
||||
### vLLM
|
||||
|
||||
vLLM è distribuito come plugin provider incluso per server locali/self-hosted compatibili con OpenAI:
|
||||
vLLM viene distribuito come Plugin provider incluso per server locali/self-hosted
|
||||
compatibili con OpenAI:
|
||||
|
||||
- Provider: `vllm`
|
||||
- Auth: opzionale (dipende dal tuo server)
|
||||
- URL di base predefinito: `http://127.0.0.1:8000/v1`
|
||||
- URL base predefinito: `http://127.0.0.1:8000/v1`
|
||||
|
||||
Per effettuare l'opt-in all'auto-discovery in locale (qualsiasi valore va bene se il tuo server non impone l'autenticazione):
|
||||
Per abilitare il rilevamento automatico in locale (qualsiasi valore va bene se il tuo server non impone auth):
|
||||
|
||||
```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
|
||||
{
|
||||
@ -708,24 +708,25 @@ Poi imposta un modello (sostituiscilo con uno degli ID restituiti da `/v1/models
|
||||
}
|
||||
```
|
||||
|
||||
Consulta [/providers/vllm](/it/providers/vllm) per i dettagli.
|
||||
Vedi [/providers/vllm](/it/providers/vllm) per i dettagli.
|
||||
|
||||
### SGLang
|
||||
|
||||
SGLang è distribuito come plugin provider incluso per server self-hosted veloci compatibili con OpenAI:
|
||||
SGLang viene distribuito come Plugin provider incluso per server self-hosted veloci
|
||||
compatibili con OpenAI:
|
||||
|
||||
- Provider: `sglang`
|
||||
- Auth: opzionale (dipende dal tuo server)
|
||||
- URL di base predefinito: `http://127.0.0.1:30000/v1`
|
||||
- URL base predefinito: `http://127.0.0.1:30000/v1`
|
||||
|
||||
Per effettuare l'opt-in all'auto-discovery in locale (qualsiasi valore va bene se il tuo server non
|
||||
impone l'autenticazione):
|
||||
Per abilitare il rilevamento automatico in locale (qualsiasi valore va bene se il tuo server non
|
||||
impone auth):
|
||||
|
||||
```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
|
||||
{
|
||||
@ -735,7 +736,7 @@ Poi imposta un modello (sostituiscilo con uno degli ID restituiti da `/v1/models
|
||||
}
|
||||
```
|
||||
|
||||
Consulta [/providers/sglang](/it/providers/sglang) per i dettagli.
|
||||
Vedi [/providers/sglang](/it/providers/sglang) per i dettagli.
|
||||
|
||||
### Proxy locali (LM Studio, vLLM, LiteLLM, ecc.)
|
||||
|
||||
@ -746,7 +747,7 @@ Esempio (compatibile con OpenAI):
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "lmstudio/my-local-model" },
|
||||
models: { "lmstudio/my-local-model": { alias: "Local" } },
|
||||
models: { "lmstudio/my-local-model": { alias: "Locale" } },
|
||||
},
|
||||
},
|
||||
models: {
|
||||
@ -758,7 +759,7 @@ Esempio (compatibile con OpenAI):
|
||||
models: [
|
||||
{
|
||||
id: "my-local-model",
|
||||
name: "Local Model",
|
||||
name: "Modello locale",
|
||||
reasoning: false,
|
||||
input: ["text"],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
@ -774,17 +775,17 @@ Esempio (compatibile con OpenAI):
|
||||
|
||||
Note:
|
||||
|
||||
- Per i provider personalizzati, `reasoning`, `input`, `cost`, `contextWindow` e `maxTokens` sono opzionali.
|
||||
Se omessi, OpenClaw usa per impostazione predefinita:
|
||||
- Per i provider personalizzati, `reasoning`, `input`, `cost`, `contextWindow` e `maxTokens` sono facoltativi.
|
||||
Se omessi, OpenClaw usa i 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 compatibili con OpenAI in stile proxy saltano anche la modellazione della richiesta solo-nativa OpenAI: niente `service_tier`, niente `store` di Responses, niente suggerimenti prompt-cache, niente modellazione del payload OpenAI reasoning-compat e nessun header nascosto di attribuzione OpenClaw.
|
||||
- Se `baseUrl` è vuoto/omesso, OpenClaw mantiene il comportamento predefinito di OpenAI (che risolve in `api.openai.com`).
|
||||
- Per `api: "openai-completions"` su endpoint non nativi (qualsiasi `baseUrl` non vuoto il cui host non sia `api.openai.com`), OpenClaw forza `compat.supportsDeveloperRole: false` per evitare errori 400 del provider dovuti a ruoli `developer` non supportati.
|
||||
- Le route compatibili con OpenAI in stile proxy saltano anche lo shaping nativo delle richieste solo-OpenAI: niente `service_tier`, niente `store` di Responses, niente hint per la cache dei prompt, niente shaping del payload di compatibilità reasoning di OpenAI e nessun header nascosto di attribuzione OpenClaw.
|
||||
- Se `baseUrl` è vuoto/omesso, OpenClaw mantiene il comportamento OpenAI predefinito (che risolve in `api.openai.com`).
|
||||
- Per sicurezza, un `compat.supportsDeveloperRole: true` esplicito viene comunque sovrascritto sugli endpoint `openai-completions` non nativi.
|
||||
|
||||
## Esempi CLI
|
||||
@ -795,11 +796,11 @@ openclaw models set opencode/claude-opus-4-6
|
||||
openclaw models list
|
||||
```
|
||||
|
||||
Consulta anche: [/gateway/configuration](/it/gateway/configuration) per esempi completi di configurazione.
|
||||
Vedi anche: [/gateway/configuration](/it/gateway/configuration) per esempi completi di configurazione.
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Models](/it/concepts/models) — configurazione dei modelli e alias
|
||||
- [Model Failover](/it/concepts/model-failover) — catene di fallback e comportamento di retry
|
||||
- [Models](/it/concepts/models) — configurazione del modello e alias
|
||||
- [Model Failover](/it/concepts/model-failover) — catene di fallback e comportamento dei retry
|
||||
- [Configuration Reference](/it/gateway/configuration-reference#agent-defaults) — chiavi di configurazione del modello
|
||||
- [Providers](/it/providers) — guide di configurazione per provider
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Stai creando un nuovo plugin provider di modelli
|
||||
- Vuoi aggiungere a OpenClaw un proxy compatibile con OpenAI o un LLM personalizzato
|
||||
- Devi comprendere l'autenticazione del provider, i cataloghi e gli hook runtime
|
||||
- Vuoi aggiungere un proxy compatibile con OpenAI o un LLM personalizzato a OpenClaw
|
||||
- Devi comprendere l'autenticazione del provider, i cataloghi e gli hook di runtime
|
||||
sidebarTitle: Provider Plugins
|
||||
summary: Guida passo passo per creare un plugin provider di modelli per OpenClaw
|
||||
title: Creare plugin provider di modelli
|
||||
summary: Guida passo passo alla creazione di un plugin provider di modelli per OpenClaw
|
||||
title: Creazione di plugin provider
|
||||
x-i18n:
|
||||
generated_at: "2026-04-21T08:27:24Z"
|
||||
generated_at: "2026-04-21T13:35:30Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 459761118c7394c1643c170edfec97c87e1c6323b436183b53ad7a2fed783b04
|
||||
source_hash: 08494658def4a003a1e5752f68d9232bfbbbf76348cf6f319ea1a6855c2ae439
|
||||
source_path: plugins/sdk-provider-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Creare plugin provider di modelli
|
||||
# Creazione di plugin provider
|
||||
|
||||
Questa guida illustra come creare un plugin provider che aggiunge un provider di modelli
|
||||
(LLM) a OpenClaw. Alla fine avrai un provider con catalogo modelli,
|
||||
Questa guida illustra la creazione di un plugin provider che aggiunge un provider
|
||||
di modelli (LLM) a OpenClaw. Alla fine avrai un provider con un catalogo di modelli,
|
||||
autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
|
||||
<Info>
|
||||
Se non hai mai creato prima alcun plugin OpenClaw, leggi prima
|
||||
[Getting Started](/it/plugins/building-plugins) per la struttura di base del pacchetto
|
||||
e la configurazione del manifest.
|
||||
Se non hai mai creato prima un plugin OpenClaw, leggi prima
|
||||
[Introduzione](/it/plugins/building-plugins) per la struttura di base del
|
||||
pacchetto e la configurazione del manifest.
|
||||
</Info>
|
||||
|
||||
<Tip>
|
||||
I plugin provider aggiungono modelli al normale ciclo di inferenza di OpenClaw. Se il modello
|
||||
deve essere eseguito tramite un demone agente nativo che possiede thread, Compaction o eventi
|
||||
degli strumenti, abbina il provider a un [agent harness](/it/plugins/sdk-agent-harness)
|
||||
invece di inserire nel core i dettagli del protocollo del demone.
|
||||
deve essere eseguito tramite un demone agente nativo che gestisce thread,
|
||||
Compaction o eventi degli strumenti, abbina il provider a un [agent harness](/it/plugins/sdk-agent-harness)
|
||||
invece di inserire i dettagli del protocollo del demone nel core.
|
||||
</Tip>
|
||||
|
||||
## Procedura dettagliata
|
||||
## Procedura guidata
|
||||
|
||||
<Steps>
|
||||
<a id="step-1-package-and-manifest"></a>
|
||||
@ -96,11 +96,11 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Il manifest dichiara `providerAuthEnvVars` in modo che OpenClaw possa rilevare
|
||||
Il manifest dichiara `providerAuthEnvVars` così OpenClaw può rilevare
|
||||
le credenziali senza caricare il runtime del tuo plugin. Aggiungi `providerAuthAliases`
|
||||
quando una variante del provider deve riutilizzare l'autenticazione di un altro id provider. `modelSupport`
|
||||
è facoltativo e consente a OpenClaw di caricare automaticamente il tuo plugin provider a partire da ID modello
|
||||
abbreviati come `acme-large` prima che esistano hook runtime. Se pubblichi il
|
||||
è facoltativo e consente a OpenClaw di caricare automaticamente il tuo plugin provider a partire da
|
||||
id modello abbreviati come `acme-large` prima che esistano hook di runtime. Se pubblichi il
|
||||
provider su ClawHub, i campi `openclaw.compat` e `openclaw.build`
|
||||
sono obbligatori in `package.json`.
|
||||
|
||||
@ -116,7 +116,7 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
export default definePluginEntry({
|
||||
id: "acme-ai",
|
||||
name: "Acme AI",
|
||||
description: "Provider di modelli Acme AI",
|
||||
description: "Acme AI model provider",
|
||||
register(api) {
|
||||
api.registerProvider({
|
||||
id: "acme-ai",
|
||||
@ -128,12 +128,12 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
createProviderApiKeyAuthMethod({
|
||||
providerId: "acme-ai",
|
||||
methodId: "api-key",
|
||||
label: "Chiave API Acme AI",
|
||||
hint: "Chiave API dalla dashboard Acme AI",
|
||||
label: "Acme AI API key",
|
||||
hint: "API key from your Acme AI dashboard",
|
||||
optionKey: "acmeAiApiKey",
|
||||
flagName: "--acme-ai-api-key",
|
||||
envVar: "ACME_AI_API_KEY",
|
||||
promptMessage: "Inserisci la tua chiave API Acme AI",
|
||||
promptMessage: "Enter your Acme AI API key",
|
||||
defaultModel: "acme-ai/acme-large",
|
||||
}),
|
||||
],
|
||||
@ -178,12 +178,12 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
});
|
||||
```
|
||||
|
||||
Questo è un provider funzionante. Ora gli utenti possono
|
||||
Questo è un provider funzionante. Gli utenti ora possono
|
||||
`openclaw onboard --acme-ai-api-key <key>` e selezionare
|
||||
`acme-ai/acme-large` come modello.
|
||||
|
||||
Se il provider upstream usa token di controllo diversi da quelli di OpenClaw, aggiungi una
|
||||
piccola trasformazione bidirezionale del testo invece di sostituire il percorso di stream:
|
||||
piccola trasformazione bidirezionale del testo invece di sostituire il percorso di streaming:
|
||||
|
||||
```typescript
|
||||
api.registerTextTransforms({
|
||||
@ -201,11 +201,11 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
```
|
||||
|
||||
`input` riscrive il prompt di sistema finale e il contenuto dei messaggi di testo prima
|
||||
del trasporto. `output` riscrive i delta di testo dell'assistente e il testo finale prima
|
||||
che OpenClaw analizzi i propri marker di controllo o il recapito sul canale.
|
||||
del trasporto. `output` riscrive i delta di testo dell'assistente e il testo finale prima che
|
||||
OpenClaw analizzi i propri marcatori di controllo o la consegna al canale.
|
||||
|
||||
Per i provider inclusi che registrano solo un provider testuale con autenticazione a chiave API
|
||||
più un singolo runtime basato su catalogo, preferisci l'helper più ristretto
|
||||
Per i provider inclusi che registrano solo un provider di testo con autenticazione tramite chiave API
|
||||
più un singolo runtime basato su catalogo, preferisci l'helper più specifico
|
||||
`defineSingleProviderPluginEntry(...)`:
|
||||
|
||||
```typescript
|
||||
@ -214,19 +214,19 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
export default defineSingleProviderPluginEntry({
|
||||
id: "acme-ai",
|
||||
name: "Acme AI",
|
||||
description: "Provider di modelli Acme AI",
|
||||
description: "Acme AI model provider",
|
||||
provider: {
|
||||
label: "Acme AI",
|
||||
docsPath: "/providers/acme-ai",
|
||||
auth: [
|
||||
{
|
||||
methodId: "api-key",
|
||||
label: "Chiave API Acme AI",
|
||||
hint: "Chiave API dalla dashboard Acme AI",
|
||||
label: "Acme AI API key",
|
||||
hint: "API key from your Acme AI dashboard",
|
||||
optionKey: "acmeAiApiKey",
|
||||
flagName: "--acme-ai-api-key",
|
||||
envVar: "ACME_AI_API_KEY",
|
||||
promptMessage: "Inserisci la tua chiave API Acme AI",
|
||||
promptMessage: "Enter your Acme AI API key",
|
||||
defaultModel: "acme-ai/acme-large",
|
||||
},
|
||||
],
|
||||
@ -241,28 +241,29 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
});
|
||||
```
|
||||
|
||||
Se il tuo flusso di autenticazione deve anche applicare patch a `models.providers.*`, alias e
|
||||
al modello predefinito dell'agente durante l'onboarding, usa gli helper preset da
|
||||
`openclaw/plugin-sdk/provider-onboard`. Gli helper più ristretti sono
|
||||
Se il tuo flusso di autenticazione deve anche correggere `models.providers.*`, alias e
|
||||
il modello predefinito dell'agente durante l'onboarding, usa gli helper preset da
|
||||
`openclaw/plugin-sdk/provider-onboard`. Gli helper più specifici sono
|
||||
`createDefaultModelPresetAppliers(...)`,
|
||||
`createDefaultModelsPresetAppliers(...)` e
|
||||
`createModelCatalogPresetAppliers(...)`.
|
||||
|
||||
Quando l'endpoint nativo di un provider supporta blocchi di utilizzo in streaming sul
|
||||
Quando un endpoint nativo del provider supporta blocchi di utilizzo in streaming sul
|
||||
normale trasporto `openai-completions`, preferisci gli helper di catalogo condivisi in
|
||||
`openclaw/plugin-sdk/provider-catalog-shared` invece di hardcodare controlli sull'id del provider. `supportsNativeStreamingUsageCompat(...)` e
|
||||
`applyProviderNativeStreamingUsageCompat(...)` rilevano il supporto dalla mappa delle capacità dell'endpoint, così anche endpoint nativi in stile Moonshot/DashScope possono aderire pur usando
|
||||
un id provider personalizzato in un plugin.
|
||||
`openclaw/plugin-sdk/provider-catalog-shared` invece di codificare controlli basati su id provider.
|
||||
`supportsNativeStreamingUsageCompat(...)` e
|
||||
`applyProviderNativeStreamingUsageCompat(...)` rilevano il supporto dalla mappa delle capacità dell'endpoint,
|
||||
così gli endpoint nativi in stile Moonshot/DashScope possono comunque aderire anche quando un plugin usa un id provider personalizzato.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Aggiungi la risoluzione dinamica dei modelli">
|
||||
Se il tuo provider accetta ID modello arbitrari (come un proxy o un router),
|
||||
Se il tuo provider accetta id modello arbitrari, come un proxy o un router,
|
||||
aggiungi `resolveDynamicModel`:
|
||||
|
||||
```typescript
|
||||
api.registerProvider({
|
||||
// ... id, label, auth, catalog come sopra
|
||||
// ... id, label, auth, catalog from above
|
||||
|
||||
resolveDynamicModel: (ctx) => ({
|
||||
id: ctx.modelId,
|
||||
@ -279,17 +280,17 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
});
|
||||
```
|
||||
|
||||
Se la risoluzione richiede una chiamata di rete, usa `prepareDynamicModel` per il warm-up
|
||||
asincrono — `resolveDynamicModel` viene eseguito di nuovo dopo il completamento.
|
||||
Se la risoluzione richiede una chiamata di rete, usa `prepareDynamicModel` per il
|
||||
warm-up asincrono — `resolveDynamicModel` viene eseguito di nuovo al termine.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Aggiungi hook runtime (se necessario)">
|
||||
La maggior parte dei provider richiede solo `catalog` + `resolveDynamicModel`. Aggiungi hook
|
||||
in modo incrementale in base alle necessità del tuo provider.
|
||||
<Step title="Aggiungi hook di runtime, se necessario">
|
||||
La maggior parte dei provider richiede solo `catalog` + `resolveDynamicModel`. Aggiungi gli hook
|
||||
in modo incrementale in base alle esigenze del tuo provider.
|
||||
|
||||
I builder helper condivisi ora coprono le famiglie più comuni di replay/compatibilità strumenti,
|
||||
quindi i plugin di solito non devono collegare a mano ciascun hook uno per uno:
|
||||
I builder di helper condivisi ora coprono le famiglie più comuni di replay/compatibilità strumenti,
|
||||
quindi di solito i plugin non devono collegare manualmente ogni hook uno per uno:
|
||||
|
||||
```typescript
|
||||
import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared";
|
||||
@ -309,17 +310,17 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
});
|
||||
```
|
||||
|
||||
Famiglie replay disponibili oggi:
|
||||
Famiglie di replay disponibili oggi:
|
||||
|
||||
| Famiglia | Cosa collega |
|
||||
| --- | --- |
|
||||
| `openai-compatible` | Policy di replay condivisa in stile OpenAI per trasporti compatibili con OpenAI, inclusa sanificazione dei tool-call-id, correzioni dell'ordine assistant-first e validazione generica dei turni Gemini dove il trasporto la richiede |
|
||||
| `anthropic-by-model` | Policy di replay compatibile con Claude scelta in base a `modelId`, così i trasporti Anthropic-message ricevono la pulizia dei blocchi di thinking specifica di Claude solo quando il modello risolto è davvero un id Claude |
|
||||
| `google-gemini` | Policy di replay nativa Gemini più sanificazione del bootstrap replay e modalità di output di reasoning con tag |
|
||||
| `passthrough-gemini` | Sanificazione della thought-signature Gemini per modelli Gemini eseguiti tramite trasporti proxy compatibili con OpenAI; non abilita la validazione di replay nativa Gemini né le riscritture bootstrap |
|
||||
| `hybrid-anthropic-openai` | Policy ibrida per provider che mescolano superfici di modello Anthropic-message e OpenAI-compatible in un unico plugin; l'eliminazione facoltativa dei blocchi di thinking solo-Claude resta limitata al lato Anthropic |
|
||||
| `openai-compatible` | Policy di replay condivisa in stile OpenAI per trasporti compatibili con OpenAI, inclusa la sanificazione di tool-call-id, le correzioni dell'ordinamento assistant-first e la validazione generica dei turni Gemini dove il trasporto la richiede |
|
||||
| `anthropic-by-model` | Policy di replay compatibile con Claude scelta in base a `modelId`, così i trasporti di messaggi Anthropic ricevono la pulizia dei blocchi di thinking specifica per Claude solo quando il modello risolto è effettivamente un id Claude |
|
||||
| `google-gemini` | Policy di replay Gemini nativa più sanificazione del replay bootstrap e modalità di output del ragionamento con tag |
|
||||
| `passthrough-gemini` | Sanificazione della thought signature Gemini per modelli Gemini eseguiti tramite trasporti proxy compatibili con OpenAI; non abilita la validazione nativa del replay Gemini né le riscritture bootstrap |
|
||||
| `hybrid-anthropic-openai` | Policy ibrida per provider che combinano superfici di modelli di messaggi Anthropic e compatibili con OpenAI in un unico plugin; l'eliminazione facoltativa dei blocchi di thinking solo-Claude resta limitata al lato Anthropic |
|
||||
|
||||
Esempi inclusi reali:
|
||||
Esempi reali inclusi:
|
||||
|
||||
- `google` e `google-gemini-cli`: `google-gemini`
|
||||
- `openrouter`, `kilocode`, `opencode` e `opencode-go`: `passthrough-gemini`
|
||||
@ -327,19 +328,19 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
- `minimax`: `hybrid-anthropic-openai`
|
||||
- `moonshot`, `ollama`, `xai` e `zai`: `openai-compatible`
|
||||
|
||||
Famiglie stream disponibili oggi:
|
||||
Famiglie di stream disponibili oggi:
|
||||
|
||||
| Famiglia | Cosa collega |
|
||||
| --- | --- |
|
||||
| `google-thinking` | Normalizzazione del payload di thinking Gemini sul percorso di stream condiviso |
|
||||
| `kilocode-thinking` | Wrapper di reasoning Kilo sul percorso di stream proxy condiviso, con `kilo/auto` e ID di reasoning proxy non supportati che saltano il thinking iniettato |
|
||||
| `moonshot-thinking` | Mappatura del payload binary native-thinking di Moonshot da config + livello `/think` |
|
||||
| `minimax-fast-mode` | Riscrittura del modello fast-mode di MiniMax sul percorso di stream condiviso |
|
||||
| `openai-responses-defaults` | Wrapper nativi condivisi OpenAI/Codex Responses: header di attribuzione, `/fast`/`serviceTier`, verbosità del testo, ricerca web nativa di Codex, modellazione del payload compatibile con reasoning e gestione del contesto Responses |
|
||||
| `openrouter-thinking` | Wrapper di reasoning OpenRouter per route proxy, con skip di modello non supportato/`auto` gestiti centralmente |
|
||||
| `tool-stream-default-on` | Wrapper `tool_stream` attivo di default per provider come Z.AI che vogliono lo streaming degli strumenti salvo disabilitazione esplicita |
|
||||
| `kilocode-thinking` | Wrapper di ragionamento Kilo sul percorso di stream proxy condiviso, con `kilo/auto` e id di ragionamento proxy non supportati che saltano il thinking iniettato |
|
||||
| `moonshot-thinking` | Mappatura del payload binario di native-thinking Moonshot da config + livello `/think` |
|
||||
| `minimax-fast-mode` | Riscrittura del modello MiniMax fast-mode sul percorso di stream condiviso |
|
||||
| `openai-responses-defaults` | Wrapper condivisi nativi OpenAI/Codex Responses: header di attribuzione, `/fast`/`serviceTier`, verbosità del testo, ricerca web nativa Codex, modellazione del payload compatibile con il ragionamento e gestione del contesto Responses |
|
||||
| `openrouter-thinking` | Wrapper di ragionamento OpenRouter per percorsi proxy, con salti per modelli non supportati/`auto` gestiti centralmente |
|
||||
| `tool-stream-default-on` | Wrapper `tool_stream` attivo per impostazione predefinita per provider come Z.AI che vogliono lo streaming degli strumenti salvo esplicita disattivazione |
|
||||
|
||||
Esempi inclusi reali:
|
||||
Esempi reali inclusi:
|
||||
|
||||
- `google` e `google-gemini-cli`: `google-thinking`
|
||||
- `kilocode`: `kilocode-thinking`
|
||||
@ -349,25 +350,25 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
- `openrouter`: `openrouter-thinking`
|
||||
- `zai`: `tool-stream-default-on`
|
||||
|
||||
`openclaw/plugin-sdk/provider-model-shared` esporta anche l'enum della famiglia
|
||||
replay più gli helper condivisi a partire dai quali tali famiglie sono costruite. Export
|
||||
pubblici comuni includono:
|
||||
`openclaw/plugin-sdk/provider-model-shared` esporta anche l'enum
|
||||
della famiglia di replay più gli helper condivisi su cui si basano tali famiglie. Le esportazioni
|
||||
pubbliche comuni includono:
|
||||
|
||||
- `ProviderReplayFamily`
|
||||
- `buildProviderReplayFamilyHooks(...)`
|
||||
- builder replay condivisi come `buildOpenAICompatibleReplayPolicy(...)`,
|
||||
- builder di replay condivisi come `buildOpenAICompatibleReplayPolicy(...)`,
|
||||
`buildAnthropicReplayPolicyForModel(...)`,
|
||||
`buildGoogleGeminiReplayPolicy(...)` e
|
||||
`buildHybridAnthropicOrOpenAIReplayPolicy(...)`
|
||||
- helper replay Gemini come `sanitizeGoogleGeminiReplayHistory(...)`
|
||||
- helper di replay Gemini come `sanitizeGoogleGeminiReplayHistory(...)`
|
||||
e `resolveTaggedReasoningOutputMode()`
|
||||
- helper per endpoint/modello come `resolveProviderEndpoint(...)`,
|
||||
- helper di endpoint/modello come `resolveProviderEndpoint(...)`,
|
||||
`normalizeProviderId(...)`, `normalizeGooglePreviewModelId(...)` e
|
||||
`normalizeNativeXaiModelId(...)`
|
||||
|
||||
`openclaw/plugin-sdk/provider-stream` espone sia il builder di famiglia sia
|
||||
gli helper wrapper pubblici che tali famiglie riusano. Export pubblici
|
||||
comuni includono:
|
||||
`openclaw/plugin-sdk/provider-stream` espone sia il builder della famiglia sia
|
||||
gli helper wrapper pubblici riutilizzati da quelle famiglie. Le esportazioni
|
||||
pubbliche comuni includono:
|
||||
|
||||
- `ProviderStreamFamily`
|
||||
- `buildProviderStreamFamilyHooks(...)`
|
||||
@ -381,49 +382,49 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
- wrapper condivisi proxy/provider come `createOpenRouterWrapper(...)`,
|
||||
`createToolStreamWrapper(...)` e `createMinimaxFastModeWrapper(...)`
|
||||
|
||||
Alcuni helper di stream restano intenzionalmente locali al provider. Esempio incluso
|
||||
attuale: `@openclaw/anthropic-provider` esporta
|
||||
Alcuni helper di stream restano intenzionalmente locali al provider. Esempio
|
||||
incluso attuale: `@openclaw/anthropic-provider` esporta
|
||||
`wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
|
||||
`resolveAnthropicFastMode`, `resolveAnthropicServiceTier` e i
|
||||
builder wrapper Anthropic di livello inferiore dalla sua seam pubblica `api.ts` /
|
||||
`contract-api.ts`. Questi helper restano specifici di Anthropic perché
|
||||
codificano anche la gestione Claude OAuth beta e il gating `context1m`.
|
||||
builder di wrapper Anthropic di livello inferiore dal proprio seam pubblico `api.ts` /
|
||||
`contract-api.ts`. Questi helper restano specifici per Anthropic perché
|
||||
codificano anche la gestione beta di Claude OAuth e il gating `context1m`.
|
||||
|
||||
Anche altri provider inclusi mantengono locali wrapper specifici del trasporto quando
|
||||
Anche altri provider inclusi mantengono wrapper specifici del trasporto a livello locale quando
|
||||
il comportamento non è condivisibile in modo pulito tra famiglie. Esempio attuale: il
|
||||
plugin xAI incluso mantiene la modellazione nativa xAI Responses nel proprio
|
||||
`wrapStreamFn`, inclusi riscritture alias `/fast`, `tool_stream` predefinito,
|
||||
pulizia strict-tool non supportata e rimozione del payload di reasoning
|
||||
specifica xAI.
|
||||
`wrapStreamFn`, inclusi riscritture degli alias `/fast`, `tool_stream` predefinito,
|
||||
pulizia degli strict-tool non supportati e rimozione del payload di ragionamento
|
||||
specifica di xAI.
|
||||
|
||||
`openclaw/plugin-sdk/provider-tools` attualmente espone una famiglia condivisa
|
||||
di schema strumenti più helper condivisi di schema/compatibilità:
|
||||
per lo schema degli strumenti più helper condivisi di schema/compatibilità:
|
||||
|
||||
- `ProviderToolCompatFamily` documenta oggi l'inventario delle famiglie condivise.
|
||||
- `buildProviderToolCompatFamilyHooks("gemini")` collega la pulizia
|
||||
dello schema Gemini + diagnostica per provider che necessitano di schema strumenti compatibile con Gemini.
|
||||
- `buildProviderToolCompatFamilyHooks("gemini")` collega la pulizia dello schema Gemini
|
||||
+ la diagnostica per i provider che necessitano di schemi strumenti sicuri per Gemini.
|
||||
- `normalizeGeminiToolSchemas(...)` e `inspectGeminiToolSchemas(...)`
|
||||
sono i corrispondenti helper pubblici di base per gli schemi Gemini.
|
||||
sono i relativi helper pubblici sottostanti per gli schemi Gemini.
|
||||
- `resolveXaiModelCompatPatch()` restituisce la patch di compatibilità xAI inclusa:
|
||||
`toolSchemaProfile: "xai"`, keyword di schema non supportate, supporto nativo
|
||||
`web_search` e decodifica degli argomenti di chiamata strumenti con entità HTML.
|
||||
`toolSchemaProfile: "xai"`, parole chiave di schema non supportate, supporto nativo
|
||||
`web_search` e decodifica degli argomenti di chiamata strumento con entità HTML.
|
||||
- `applyXaiModelCompat(model)` applica la stessa patch di compatibilità xAI a un
|
||||
modello risolto prima che raggiunga il runner.
|
||||
|
||||
Esempio incluso reale: il plugin xAI usa `normalizeResolvedModel` più
|
||||
`contributeResolvedModelCompat` per mantenere quei metadati di compatibilità di proprietà del
|
||||
provider invece di hardcodare le regole xAI nel core.
|
||||
Esempio reale incluso: il plugin xAI usa `normalizeResolvedModel` più
|
||||
`contributeResolvedModelCompat` per mantenere quei metadati di compatibilità sotto la responsabilità del
|
||||
provider invece di codificare regole xAI nel core.
|
||||
|
||||
Lo stesso pattern package-root supporta anche altri provider inclusi:
|
||||
Lo stesso pattern di package-root supporta anche altri provider inclusi:
|
||||
|
||||
- `@openclaw/openai-provider`: `api.ts` esporta builder provider,
|
||||
helper per modelli predefiniti e builder provider realtime
|
||||
- `@openclaw/openrouter-provider`: `api.ts` esporta il builder provider
|
||||
- `@openclaw/openai-provider`: `api.ts` esporta builder di provider,
|
||||
helper per i modelli predefiniti e builder di provider realtime
|
||||
- `@openclaw/openrouter-provider`: `api.ts` esporta il builder del provider
|
||||
più helper di onboarding/configurazione
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Scambio token">
|
||||
Per provider che richiedono uno scambio token prima di ogni chiamata di inferenza:
|
||||
<Tab title="Scambio di token">
|
||||
Per i provider che richiedono uno scambio di token prima di ogni chiamata di inferenza:
|
||||
|
||||
```typescript
|
||||
prepareRuntimeAuth: async (ctx) => {
|
||||
@ -437,7 +438,7 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Header personalizzati">
|
||||
Per provider che richiedono header di richiesta personalizzati o modifiche al body:
|
||||
Per i provider che richiedono header di richiesta personalizzati o modifiche al body:
|
||||
|
||||
```typescript
|
||||
// wrapStreamFn restituisce uno StreamFn derivato da ctx.streamFn
|
||||
@ -455,7 +456,7 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Identità del trasporto nativo">
|
||||
Per provider che richiedono header o metadati nativi di richiesta/sessione su
|
||||
Per i provider che richiedono header o metadati nativi di richiesta/sessione su
|
||||
trasporti HTTP o WebSocket generici:
|
||||
|
||||
```typescript
|
||||
@ -477,7 +478,7 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Utilizzo e fatturazione">
|
||||
Per provider che espongono dati di utilizzo/fatturazione:
|
||||
Per i provider che espongono dati di utilizzo/fatturazione:
|
||||
|
||||
```typescript
|
||||
resolveUsageAuth: async (ctx) => {
|
||||
@ -497,78 +498,77 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
| # | Hook | Quando usarlo |
|
||||
| --- | --- | --- |
|
||||
| 1 | `catalog` | Catalogo modelli o valori predefiniti di base URL |
|
||||
| 2 | `applyConfigDefaults` | Valori globali predefiniti di proprietà del provider durante la materializzazione della configurazione |
|
||||
| 3 | `normalizeModelId` | Pulizia di alias legacy/preview dei model-id prima del lookup |
|
||||
| 2 | `applyConfigDefaults` | Valori predefiniti globali del provider durante la materializzazione della configurazione |
|
||||
| 3 | `normalizeModelId` | Pulizia di alias legacy/preview degli id modello prima della ricerca |
|
||||
| 4 | `normalizeTransport` | Pulizia di `api` / `baseUrl` della famiglia provider prima dell'assemblaggio generico del modello |
|
||||
| 5 | `normalizeConfig` | Normalizza la configurazione `models.providers.<id>` |
|
||||
| 6 | `applyNativeStreamingUsageCompat` | Riscritture di compatibilità native di streaming-usage per provider di configurazione |
|
||||
| 7 | `resolveConfigApiKey` | Risoluzione auth dei marker env di proprietà del provider |
|
||||
| 8 | `resolveSyntheticAuth` | Auth sintetica locale/self-hosted o basata su config |
|
||||
| 9 | `shouldDeferSyntheticProfileAuth` | Abbassa la priorità dei placeholder di profilo memorizzato sintetico rispetto all'auth env/config |
|
||||
| 10 | `resolveDynamicModel` | Accetta ID modello upstream arbitrari |
|
||||
| 6 | `applyNativeStreamingUsageCompat` | Riscritture di compatibilità native per streaming-usage per provider configurati |
|
||||
| 7 | `resolveConfigApiKey` | Risoluzione dell'autenticazione dei marker env gestita dal provider |
|
||||
| 8 | `resolveSyntheticAuth` | Autenticazione sintetica locale/self-hosted o basata su config |
|
||||
| 9 | `shouldDeferSyntheticProfileAuth` | Abbassa la priorità dei placeholder sintetici dei profili memorizzati rispetto all'autenticazione env/config |
|
||||
| 10 | `resolveDynamicModel` | Accetta id modello upstream arbitrari |
|
||||
| 11 | `prepareDynamicModel` | Recupero asincrono dei metadati prima della risoluzione |
|
||||
| 12 | `normalizeResolvedModel` | Riscritture di trasporto prima del runner |
|
||||
| 12 | `normalizeResolvedModel` | Riscritture del trasporto prima del runner |
|
||||
|
||||
Note sul fallback runtime:
|
||||
Note sul fallback di runtime:
|
||||
|
||||
- `normalizeConfig` controlla prima il provider corrispondente, poi altri
|
||||
plugin provider compatibili con hook finché uno non modifica davvero la configurazione.
|
||||
Se nessun hook provider riscrive una voce di configurazione supportata della famiglia Google, si applica comunque il normalizzatore di configurazione Google incluso.
|
||||
- `resolveConfigApiKey` usa l'hook provider quando esposto. Il percorso incluso
|
||||
`amazon-bedrock` ha qui anche un resolver integrato dei marker env AWS,
|
||||
anche se l'auth runtime di Bedrock continua comunque a usare la catena
|
||||
predefinita dell'SDK AWS.
|
||||
- `normalizeConfig` controlla prima il provider corrispondente, poi gli altri
|
||||
plugin provider con capacità di hook finché uno non modifica effettivamente la configurazione.
|
||||
Se nessun hook provider riscrive una voce di configurazione supportata della famiglia Google, continua comunque ad applicarsi
|
||||
il normalizzatore di configurazione Google incluso.
|
||||
- `resolveConfigApiKey` usa l'hook provider quando disponibile. Anche il percorso incluso
|
||||
`amazon-bedrock` ha qui un resolver integrato di marker env AWS,
|
||||
anche se l'autenticazione runtime Bedrock continua comunque a usare la catena predefinita dell'AWS SDK.
|
||||
| 13 | `contributeResolvedModelCompat` | Flag di compatibilità per modelli vendor dietro un altro trasporto compatibile |
|
||||
| 14 | `capabilities` | Vecchio bag statico di capability; solo compatibilità |
|
||||
| 15 | `normalizeToolSchemas` | Pulizia degli schemi strumenti di proprietà del provider prima della registrazione |
|
||||
| 16 | `inspectToolSchemas` | Diagnostica degli schemi strumenti di proprietà del provider |
|
||||
| 17 | `resolveReasoningOutputMode` | Contratto di output del reasoning con tag o nativo |
|
||||
| 14 | `capabilities` | Vecchio contenitore statico di capacità; solo compatibilità |
|
||||
| 15 | `normalizeToolSchemas` | Pulizia dello schema strumenti gestita dal provider prima della registrazione |
|
||||
| 16 | `inspectToolSchemas` | Diagnostica dello schema strumenti gestita dal provider |
|
||||
| 17 | `resolveReasoningOutputMode` | Contratto di output del ragionamento con tag o nativo |
|
||||
| 18 | `prepareExtraParams` | Parametri di richiesta predefiniti |
|
||||
| 19 | `createStreamFn` | Trasporto StreamFn completamente personalizzato |
|
||||
| 20 | `wrapStreamFn` | Wrapper di header/body personalizzati sul normale percorso di stream |
|
||||
| 20 | `wrapStreamFn` | Wrapper personalizzati di header/body sul normale percorso di stream |
|
||||
| 21 | `resolveTransportTurnState` | Header/metadati nativi per turno |
|
||||
| 22 | `resolveWebSocketSessionPolicy` | Header di sessione WS nativi/cool-down |
|
||||
| 23 | `formatApiKey` | Forma personalizzata del token runtime |
|
||||
| 24 | `refreshOAuth` | Refresh OAuth personalizzato |
|
||||
| 25 | `buildAuthDoctorHint` | Indicazioni di riparazione auth |
|
||||
| 26 | `matchesContextOverflowError` | Rilevamento overflow di proprietà del provider |
|
||||
| 27 | `classifyFailoverReason` | Classificazione di rate-limit/overload di proprietà del provider |
|
||||
| 28 | `isCacheTtlEligible` | Gating TTL della prompt cache |
|
||||
| 29 | `buildMissingAuthMessage` | Suggerimento personalizzato per auth mancante |
|
||||
| 25 | `buildAuthDoctorHint` | Indicazioni per la riparazione dell'autenticazione |
|
||||
| 26 | `matchesContextOverflowError` | Rilevamento dell'overflow gestito dal provider |
|
||||
| 27 | `classifyFailoverReason` | Classificazione di rate-limit/sovraccarico gestita dal provider |
|
||||
| 28 | `isCacheTtlEligible` | Gating TTL della cache dei prompt |
|
||||
| 29 | `buildMissingAuthMessage` | Suggerimento personalizzato per autenticazione mancante |
|
||||
| 30 | `suppressBuiltInModel` | Nasconde righe upstream obsolete |
|
||||
| 31 | `augmentModelCatalog` | Righe sintetiche di forward-compatibilità |
|
||||
| 32 | `isBinaryThinking` | Thinking binario on/off |
|
||||
| 33 | `supportsXHighThinking` | Supporto al reasoning `xhigh` |
|
||||
| 34 | `supportsAdaptiveThinking` | Supporto al thinking adattivo |
|
||||
| 35 | `supportsMaxThinking` | Supporto al reasoning `max` |
|
||||
| 36 | `resolveDefaultThinkingLevel` | Policy predefinita `/think` |
|
||||
| 37 | `isModernModelRef` | Corrispondenza dei modelli live/smoke |
|
||||
| 38 | `prepareRuntimeAuth` | Scambio token prima dell'inferenza |
|
||||
| 39 | `resolveUsageAuth` | Parsing personalizzato delle credenziali di utilizzo |
|
||||
| 40 | `fetchUsageSnapshot` | Endpoint di utilizzo personalizzato |
|
||||
| 41 | `createEmbeddingProvider` | Adapter di embedding di proprietà del provider per memory/search |
|
||||
| 42 | `buildReplayPolicy` | Policy personalizzata di replay/Compaction della trascrizione |
|
||||
| 43 | `sanitizeReplayHistory` | Riscritture replay specifiche del provider dopo la pulizia generica |
|
||||
| 44 | `validateReplayTurns` | Validazione rigorosa dei turni replay prima del runner incorporato |
|
||||
| 45 | `onModelSelected` | Callback post-selezione (ad es. telemetria) |
|
||||
| 31 | `augmentModelCatalog` | Righe sintetiche di forward-compat |
|
||||
| 32 | `resolveThinkingProfile` | Insieme di opzioni `/think` specifico del modello |
|
||||
| 33 | `isBinaryThinking` | Compatibilità on/off del thinking binario |
|
||||
| 34 | `supportsXHighThinking` | Compatibilità del supporto al ragionamento `xhigh` |
|
||||
| 35 | `resolveDefaultThinkingLevel` | Compatibilità della policy `/think` predefinita |
|
||||
| 36 | `isModernModelRef` | Corrispondenza del modello live/smoke |
|
||||
| 37 | `prepareRuntimeAuth` | Scambio di token prima dell'inferenza |
|
||||
| 38 | `resolveUsageAuth` | Parsing personalizzato delle credenziali di utilizzo |
|
||||
| 39 | `fetchUsageSnapshot` | Endpoint di utilizzo personalizzato |
|
||||
| 40 | `createEmbeddingProvider` | Adattatore embedding gestito dal provider per memoria/ricerca |
|
||||
| 41 | `buildReplayPolicy` | Policy personalizzata di replay/Compaction della trascrizione |
|
||||
| 42 | `sanitizeReplayHistory` | Riscritture di replay specifiche del provider dopo la pulizia generica |
|
||||
| 43 | `validateReplayTurns` | Validazione rigorosa dei turni di replay prima del runner incorporato |
|
||||
| 44 | `onModelSelected` | Callback post-selezione, ad esempio telemetria |
|
||||
|
||||
Nota sul tuning dei prompt:
|
||||
Nota sull'ottimizzazione dei prompt:
|
||||
|
||||
- `resolveSystemPromptContribution` consente a un provider di iniettare
|
||||
indicazioni del prompt di sistema sensibili alla cache per una famiglia di modelli. Preferiscilo a
|
||||
`before_prompt_build` quando il comportamento appartiene a una famiglia provider/modello
|
||||
indicazioni del prompt di sistema compatibili con la cache per una famiglia di modelli. Preferiscilo a
|
||||
`before_prompt_build` quando il comportamento appartiene a una singola famiglia provider/modello
|
||||
e deve preservare la suddivisione cache stabile/dinamica.
|
||||
|
||||
Per descrizioni dettagliate ed esempi reali, vedi
|
||||
[Internals: Provider Runtime Hooks](/it/plugins/architecture#provider-runtime-hooks).
|
||||
[Interni: Hook di runtime del provider](/it/plugins/architecture#provider-runtime-hooks).
|
||||
</Accordion>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Aggiungi capacità extra (opzionale)">
|
||||
<Step title="Aggiungi capacità extra, facoltative">
|
||||
<a id="step-5-add-extra-capabilities"></a>
|
||||
Un plugin provider può registrare speech, trascrizione realtime, voce realtime,
|
||||
comprensione dei media, generazione di immagini, generazione video, web fetch
|
||||
Un plugin provider può registrare sintesi vocale, trascrizione realtime, voce realtime,
|
||||
comprensione dei media, generazione di immagini, generazione di video, web fetch
|
||||
e web search insieme all'inferenza testuale:
|
||||
|
||||
```typescript
|
||||
@ -580,7 +580,7 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
label: "Acme Speech",
|
||||
isConfigured: ({ config }) => Boolean(config.messages?.tts),
|
||||
synthesize: async (req) => ({
|
||||
audioBuffer: Buffer.from(/* dati PCM */),
|
||||
audioBuffer: Buffer.from(/* PCM data */),
|
||||
outputFormat: "mp3",
|
||||
fileExtension: ".mp3",
|
||||
voiceCompatible: false,
|
||||
@ -617,14 +617,14 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
api.registerMediaUnderstandingProvider({
|
||||
id: "acme-ai",
|
||||
capabilities: ["image", "audio"],
|
||||
describeImage: async (req) => ({ text: "Una foto di..." }),
|
||||
transcribeAudio: async (req) => ({ text: "Trascrizione..." }),
|
||||
describeImage: async (req) => ({ text: "A photo of..." }),
|
||||
transcribeAudio: async (req) => ({ text: "Transcript..." }),
|
||||
});
|
||||
|
||||
api.registerImageGenerationProvider({
|
||||
id: "acme-ai",
|
||||
label: "Acme Images",
|
||||
generate: async (req) => ({ /* risultato immagine */ }),
|
||||
generate: async (req) => ({ /* image result */ }),
|
||||
});
|
||||
|
||||
api.registerVideoGenerationProvider({
|
||||
@ -677,19 +677,19 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw classifica questo come plugin **hybrid-capability**. Questo è il
|
||||
pattern consigliato per i plugin aziendali (un plugin per vendor). Vedi
|
||||
[Internals: Capability Ownership](/it/plugins/architecture#capability-ownership-model).
|
||||
OpenClaw lo classifica come plugin **hybrid-capability**. Questo è il
|
||||
pattern consigliato per i plugin aziendali, un plugin per vendor. Vedi
|
||||
[Interni: Proprietà delle capacità](/it/plugins/architecture#capability-ownership-model).
|
||||
|
||||
Per la generazione video, preferisci la forma delle capability sensibile alla modalità mostrata sopra:
|
||||
Per la generazione di video, preferisci la forma di capacità sensibile alla modalità mostrata sopra:
|
||||
`generate`, `imageToVideo` e `videoToVideo`. Campi aggregati piatti come
|
||||
`maxInputImages`, `maxInputVideos` e `maxDurationSeconds` non sono
|
||||
sufficienti per pubblicizzare in modo pulito il supporto alle modalità di trasformazione o le modalità disabilitate.
|
||||
|
||||
I provider di generazione musicale dovrebbero seguire lo stesso pattern:
|
||||
`generate` per la generazione basata solo su prompt ed `edit` per la generazione
|
||||
`generate` per la generazione basata solo su prompt e `edit` per la generazione
|
||||
basata su immagine di riferimento. Campi aggregati piatti come `maxInputImages`,
|
||||
`supportsLyrics` e `supportsFormat` non sono sufficienti per pubblicizzare il supporto a edit;
|
||||
`supportsLyrics` e `supportsFormat` non sono sufficienti per pubblicizzare il supporto alla modifica;
|
||||
i blocchi espliciti `generate` / `edit` sono il contratto previsto.
|
||||
|
||||
</Step>
|
||||
@ -698,11 +698,11 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
<a id="step-6-test"></a>
|
||||
```typescript src/provider.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
// Esporta il tuo oggetto di configurazione provider da index.ts o da un file dedicato
|
||||
// Export your provider config object from index.ts or a dedicated file
|
||||
import { acmeProvider } from "./provider.js";
|
||||
|
||||
describe("provider acme-ai", () => {
|
||||
it("risolve i modelli dinamici", () => {
|
||||
describe("acme-ai provider", () => {
|
||||
it("resolves dynamic models", () => {
|
||||
const model = acmeProvider.resolveDynamicModel!({
|
||||
modelId: "acme-beta-v3",
|
||||
} as any);
|
||||
@ -710,14 +710,14 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
expect(model.provider).toBe("acme-ai");
|
||||
});
|
||||
|
||||
it("restituisce il catalogo quando la chiave è disponibile", async () => {
|
||||
it("returns catalog when key is available", async () => {
|
||||
const result = await acmeProvider.catalog!.run({
|
||||
resolveProviderApiKey: () => ({ apiKey: "test-key" }),
|
||||
} as any);
|
||||
expect(result?.provider?.models).toHaveLength(2);
|
||||
});
|
||||
|
||||
it("restituisce un catalogo null quando non c'è la chiave", async () => {
|
||||
it("returns null catalog when no key", async () => {
|
||||
const result = await acmeProvider.catalog!.run({
|
||||
resolveProviderApiKey: () => ({ apiKey: undefined }),
|
||||
} as any);
|
||||
@ -731,29 +731,29 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli.
|
||||
|
||||
## Pubblica su ClawHub
|
||||
|
||||
I plugin provider si pubblicano nello stesso modo di qualsiasi altro plugin di codice esterno:
|
||||
I plugin provider si pubblicano allo stesso modo di qualsiasi altro plugin di codice esterno:
|
||||
|
||||
```bash
|
||||
clawhub package publish your-org/your-plugin --dry-run
|
||||
clawhub package publish your-org/your-plugin
|
||||
```
|
||||
|
||||
Non usare qui l'alias legacy di pubblicazione solo-Skills; i pacchetti plugin dovrebbero usare
|
||||
Non usare qui il vecchio alias di pubblicazione solo per Skills; i pacchetti plugin devono usare
|
||||
`clawhub package publish`.
|
||||
|
||||
## Struttura dei file
|
||||
|
||||
```
|
||||
<bundled-plugin-root>/acme-ai/
|
||||
├── package.json # metadati openclaw.providers
|
||||
├── openclaw.plugin.json # Manifest con metadati auth del provider
|
||||
├── package.json # Metadati openclaw.providers
|
||||
├── openclaw.plugin.json # Manifest con metadati di autenticazione del provider
|
||||
├── index.ts # definePluginEntry + registerProvider
|
||||
└── src/
|
||||
├── provider.test.ts # Test
|
||||
└── usage.ts # Endpoint di utilizzo (facoltativo)
|
||||
└── usage.ts # Endpoint di utilizzo, facoltativo
|
||||
```
|
||||
|
||||
## Riferimento dell'ordine del catalogo
|
||||
## Riferimento per l'ordine del catalogo
|
||||
|
||||
`catalog.order` controlla quando il tuo catalogo viene unito rispetto ai
|
||||
provider integrati:
|
||||
@ -761,13 +761,13 @@ provider integrati:
|
||||
| Ordine | Quando | Caso d'uso |
|
||||
| --------- | ------------- | ----------------------------------------------- |
|
||||
| `simple` | Primo passaggio | Provider semplici con chiave API |
|
||||
| `profile` | Dopo simple | Provider limitati da profili auth |
|
||||
| `profile` | Dopo simple | Provider vincolati ai profili di autenticazione |
|
||||
| `paired` | Dopo profile | Sintetizza più voci correlate |
|
||||
| `late` | Ultimo passaggio | Sovrascrive provider esistenti (vince in caso di collisione) |
|
||||
| `late` | Ultimo passaggio | Sovrascrive provider esistenti, vince in caso di collisione |
|
||||
|
||||
## Passaggi successivi
|
||||
|
||||
- [Plugin di canale](/it/plugins/sdk-channel-plugins) — se il tuo plugin fornisce anche un canale
|
||||
- [SDK Runtime](/it/plugins/sdk-runtime) — helper `api.runtime` (TTS, search, subagent)
|
||||
- [Panoramica SDK](/it/plugins/sdk-overview) — riferimento completo agli import dei sotto-percorsi
|
||||
- [Internals dei plugin](/it/plugins/architecture#provider-runtime-hooks) — dettagli degli hook ed esempi inclusi
|
||||
- [Runtime SDK](/it/plugins/sdk-runtime) — helper `api.runtime`, TTS, search, subagent
|
||||
- [Panoramica dell'SDK](/it/plugins/sdk-overview) — riferimento completo per le importazioni dei sottopercorsi
|
||||
- [Interni dei plugin](/it/plugins/architecture#provider-runtime-hooks) — dettagli degli hook ed esempi inclusi
|
||||
|
||||
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- Vuoi attivare esecuzioni dell'agente da script o dalla riga di comando
|
||||
- Hai bisogno di recapitare in modo programmatico le risposte dell'agente a un canale di chat
|
||||
summary: Esegui turni dell'agente dalla CLI e, facoltativamente, recapita le risposte ai canali
|
||||
title: Agent Send
|
||||
- Vuoi attivare le esecuzioni dell'agente dagli script o dalla riga di comando
|
||||
- Devi recapitare programmaticamente le risposte dell'agente a un canale di chat
|
||||
summary: Esegui i turni dell'agente dalla CLI e, facoltativamente, recapita le risposte ai canali
|
||||
title: Invio dell'agente
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T14:05:18Z"
|
||||
generated_at: "2026-04-21T13:35:25Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 42ea2977e89fb28d2afd07e5f6b1560ad627aea8b72fde36d8e324215c710afc
|
||||
source_hash: 0550ad38efb2711f267a62b905fd150987a98801247de780ed3df97f27245704
|
||||
source_path: tools/agent-send.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Agent Send
|
||||
# Invio dell'agente
|
||||
|
||||
`openclaw agent` esegue un singolo turno dell'agente dalla riga di comando senza richiedere
|
||||
un messaggio di chat in ingresso. Usalo per flussi di lavoro con script, test e
|
||||
un messaggio di chat in ingresso. Usalo per flussi di lavoro scriptati, test e
|
||||
recapito programmatico.
|
||||
|
||||
## Avvio rapido
|
||||
## Guida rapida
|
||||
|
||||
<Steps>
|
||||
<Step title="Esegui un semplice turno dell'agente">
|
||||
@ -31,15 +31,15 @@ recapito programmatico.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Scegli come destinazione un agente o una sessione specifici">
|
||||
<Step title="Indirizza a un agente o a una sessione specifici">
|
||||
```bash
|
||||
# Scegli come destinazione un agente specifico
|
||||
# Target a specific agent
|
||||
openclaw agent --agent ops --message "Summarize logs"
|
||||
|
||||
# Scegli come destinazione un numero di telefono (deriva la chiave di sessione)
|
||||
# Target a phone number (derives session key)
|
||||
openclaw agent --to +15555550123 --message "Status update"
|
||||
|
||||
# Riutilizza una sessione esistente
|
||||
# Reuse an existing session
|
||||
openclaw agent --session-id abc123 --message "Continue the task"
|
||||
```
|
||||
|
||||
@ -47,10 +47,10 @@ recapito programmatico.
|
||||
|
||||
<Step title="Recapita la risposta a un canale">
|
||||
```bash
|
||||
# Recapita a WhatsApp (canale predefinito)
|
||||
# Deliver to WhatsApp (default channel)
|
||||
openclaw agent --to +15555550123 --message "Report ready" --deliver
|
||||
|
||||
# Recapita a Slack
|
||||
# Deliver to Slack
|
||||
openclaw agent --agent ops --message "Generate report" \
|
||||
--deliver --reply-channel slack --reply-to "#reports"
|
||||
```
|
||||
@ -63,45 +63,45 @@ recapito programmatico.
|
||||
| Flag | Descrizione |
|
||||
| ----------------------------- | ----------------------------------------------------------- |
|
||||
| `--message \<text\>` | Messaggio da inviare (obbligatorio) |
|
||||
| `--to \<dest\>` | Deriva la chiave di sessione da una destinazione (telefono, id chat) |
|
||||
| `--agent \<id\>` | Sceglie come destinazione un agente configurato (usa la sua sessione `main`) |
|
||||
| `--to \<dest\>` | Ricava la chiave di sessione da una destinazione (telefono, id chat) |
|
||||
| `--agent \<id\>` | Indirizza a un agente configurato (usa la sua sessione `main`) |
|
||||
| `--session-id \<id\>` | Riutilizza una sessione esistente tramite id |
|
||||
| `--local` | Forza il runtime incorporato locale (salta il Gateway) |
|
||||
| `--local` | Forza il runtime embedded locale (salta il Gateway) |
|
||||
| `--deliver` | Invia la risposta a un canale di chat |
|
||||
| `--channel \<name\>` | Canale di recapito (whatsapp, telegram, discord, slack, ecc.) |
|
||||
| `--reply-to \<target\>` | Override della destinazione di recapito |
|
||||
| `--reply-channel \<name\>` | Override del canale di recapito |
|
||||
| `--reply-account \<id\>` | Override dell'id account di recapito |
|
||||
| `--thinking \<level\>` | Imposta il livello di thinking (off, minimal, low, medium, high, xhigh) |
|
||||
| `--verbose \<on\|full\|off\>` | Imposta il livello di dettaglio |
|
||||
| `--reply-to \<target\>` | Sostituzione della destinazione di recapito |
|
||||
| `--reply-channel \<name\>` | Sostituzione del canale di recapito |
|
||||
| `--reply-account \<id\>` | Sostituzione dell'id account di recapito |
|
||||
| `--thinking \<level\>` | Imposta il livello di thinking per il profilo modello selezionato |
|
||||
| `--verbose \<on\|full\|off\>` | Imposta il livello di verbosità |
|
||||
| `--timeout \<seconds\>` | Sostituisce il timeout dell'agente |
|
||||
| `--json` | Produce JSON strutturato |
|
||||
|
||||
## Comportamento
|
||||
|
||||
- Per impostazione predefinita, la CLI passa **attraverso il Gateway**. Aggiungi `--local` per forzare
|
||||
il runtime incorporato sulla macchina corrente.
|
||||
- Se il Gateway non è raggiungibile, la CLI **ripiega** sull'esecuzione incorporata locale.
|
||||
- Selezione della sessione: `--to` deriva la chiave di sessione (le destinazioni di gruppo/canale
|
||||
preservano l'isolamento; le chat dirette confluiscono in `main`).
|
||||
- I flag thinking e verbose persistono nell'archivio delle sessioni.
|
||||
- Output: testo semplice per impostazione predefinita, oppure `--json` per payload strutturato + metadati.
|
||||
- Per impostazione predefinita, la CLI passa **attraverso il Gateway**. Aggiungi `--local` per forzare il
|
||||
runtime embedded sulla macchina corrente.
|
||||
- Se il Gateway non è raggiungibile, la CLI **ripiega** sull'esecuzione embedded locale.
|
||||
- Selezione della sessione: `--to` ricava la chiave di sessione (le destinazioni di gruppo/canale
|
||||
preservano l'isolamento; le chat dirette convergono su `main`).
|
||||
- I flag thinking e verbose vengono mantenuti nell'archivio sessioni.
|
||||
- Output: testo normale per impostazione predefinita, oppure `--json` per payload strutturato + metadati.
|
||||
|
||||
## Esempi
|
||||
|
||||
```bash
|
||||
# Turno semplice con output JSON
|
||||
# Simple turn with JSON output
|
||||
openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json
|
||||
|
||||
# Turno con livello di thinking
|
||||
# Turn with thinking level
|
||||
openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium
|
||||
|
||||
# Recapita a un canale diverso dalla sessione
|
||||
# Deliver to a different channel than the session
|
||||
openclaw agent --agent ops --message "Alert" --deliver --reply-channel telegram --reply-to "@admin"
|
||||
```
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Riferimento CLI dell'agente](/cli/agent)
|
||||
- [Sotto-agenti](/tools/subagents) — avvio in background di sotto-agenti
|
||||
- [Riferimento della CLI dell'agente](/cli/agent)
|
||||
- [Sub-agents](/it/tools/subagents) — generazione di sub-agent in background
|
||||
- [Sessioni](/it/concepts/session) — come funzionano le chiavi di sessione
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Usare o configurare i comandi di chat
|
||||
- Debug dell’instradamento dei comandi o dei permessi
|
||||
- Usare o configurare i comandi della chat
|
||||
- Debug del routing dei comandi o delle autorizzazioni
|
||||
summary: 'Comandi slash: testo vs nativi, configurazione e comandi supportati'
|
||||
title: Comandi slash
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T23:33:34Z"
|
||||
generated_at: "2026-04-21T13:35:26Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 9ef6f54500fa2ce3b873a8398d6179a0882b8bf6fba38f61146c64671055505e
|
||||
source_hash: d90ddee54af7c05b7fdf486590561084581d750e42cd14674d43bbdc0984df5d
|
||||
source_path: tools/slash-commands.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -16,21 +16,21 @@ 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 bash di chat solo host usa `! <cmd>` (con `/bash <cmd>` come alias).
|
||||
Il comando bash della chat solo host usa `! <cmd>` (con `/bash <cmd>` come alias).
|
||||
|
||||
Esistono due sistemi correlati:
|
||||
|
||||
- **Comandi**: messaggi autonomi `/...`.
|
||||
- **Comandi**: messaggi `/...` autonomi.
|
||||
- **Direttive**: `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
|
||||
- Le direttive vengono rimosse dal messaggio prima che il modello lo veda.
|
||||
- Nei normali messaggi di chat (non solo direttive), sono trattate come “hint inline” e **non** rendono persistenti le impostazioni della sessione.
|
||||
- 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 ai **mittenti autorizzati**. Se `commands.allowFrom` è impostato, è l’unica
|
||||
allowlist usata; altrimenti l’autorizzazione proviene dalle allowlist/associazioni del canale più `commands.useAccessGroups`.
|
||||
I mittenti non autorizzati vedono le direttive trattate come testo semplice.
|
||||
- Le direttive vengono applicate solo ai **mittenti autorizzati**. Se `commands.allowFrom` è impostato, è l'unica
|
||||
allowlist usata; altrimenti l'autorizzazione deriva dalle allowlist/associazione del canale più `commands.useAccessGroups`.
|
||||
I mittenti non autorizzati vedono le direttive trattate come testo normale.
|
||||
|
||||
Esistono anche alcune **scorciatoie inline** (solo mittenti autorizzati/in allowlist): `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
Vengono eseguite immediatamente, rimosse prima che il modello veda il messaggio e il testo rimanente continua nel flusso normale.
|
||||
Esistono anche alcune **scorciatoie inline** (solo per mittenti in allowlist/autorizzati): `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
Vengono eseguite immediatamente, rimosse prima che il modello veda il messaggio, e il testo rimanente continua nel normale flusso.
|
||||
|
||||
## Configurazione
|
||||
|
||||
@ -60,105 +60,107 @@ Vengono eseguite immediatamente, rimosse prima che il modello veda il messaggio
|
||||
```
|
||||
|
||||
- `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`.
|
||||
- Sulle superfici senza comandi nativi (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), i comandi testuali continuano a funzionare anche se lo imposti su `false`.
|
||||
- `commands.native` (predefinito `"auto"`) registra i comandi nativi.
|
||||
- Auto: attivo per Discord/Telegram; disattivato 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 sostituire il comportamento per provider (bool o `"auto"`).
|
||||
- `false` cancella all’avvio i comandi precedentemente registrati su Discord/Telegram. 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; disattivato 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 sostituire il comportamento per provider (bool o `"auto"`).
|
||||
- Auto: attivo per Discord/Telegram; disattivo per Slack (finché non aggiungi gli slash command); ignorato per i provider senza supporto nativo.
|
||||
- Imposta `channels.discord.commands.native`, `channels.telegram.commands.native` o `channels.slack.commands.native` per forzare il comportamento 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 forzare il comportamento per provider (bool o `"auto"`).
|
||||
- `commands.bash` (predefinito `false`) abilita `! <cmd>` per eseguire comandi shell host (`/bash <cmd>` è un alias; richiede le allowlist `tools.elevated`).
|
||||
- `commands.bashForegroundMs` (predefinito `2000`) controlla quanto tempo bash aspetta prima di passare alla modalità background (`0` passa immediatamente in background).
|
||||
- `commands.bashForegroundMs` (predefinito `2000`) controlla per quanto tempo bash aspetta prima di passare alla modalità in background (`0` manda subito 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` (rilevamento/stato dei plugin più controlli di installazione e abilitazione/disabilitazione).
|
||||
- `commands.mcp` (predefinito `false`) abilita `/mcp` (legge/scrive la configurazione MCP gestita da OpenClaw in `mcp.servers`).
|
||||
- `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.restart` (predefinito `true`) abilita `/restart` più le azioni dello strumento di riavvio del Gateway.
|
||||
- `commands.ownerAllowFrom` (facoltativo) imposta l’allowlist esplicita del proprietario per le superfici di comando/strumento riservate al proprietario. Questa è separata da `commands.allowFrom`.
|
||||
- `commands.ownerDisplay` controlla come gli ID del proprietario appaiono nel prompt di sistema: `raw` o `hash`.
|
||||
- `commands.restart` (predefinito `true`) abilita `/restart` più le azioni degli strumenti di riavvio del gateway.
|
||||
- `commands.ownerAllowFrom` (opzionale) imposta l'allowlist esplicita del proprietario per le superfici di comandi/strumenti riservate al proprietario. È separata da `commands.allowFrom`.
|
||||
- `commands.ownerDisplay` controlla come gli id del proprietario compaiono nel system prompt: `raw` o `hash`.
|
||||
- `commands.ownerDisplaySecret` imposta facoltativamente il segreto HMAC usato quando `commands.ownerDisplay="hash"`.
|
||||
- `commands.allowFrom` (facoltativo) imposta un’allowlist per provider per l’autorizzazione dei comandi. Quando configurata, è l’unica origine di autorizzazione per comandi e direttive (le allowlist/associazioni del canale e `commands.useAccessGroups` vengono ignorate). Usa `"*"` per un valore predefinito globale; le chiavi specifiche del provider hanno la precedenza.
|
||||
- `commands.useAccessGroups` (predefinito `true`) applica allowlist/policy per i comandi quando `commands.allowFrom` non è impostato.
|
||||
- `commands.allowFrom` (opzionale) imposta un'allowlist per provider per l'autorizzazione dei comandi. Quando è configurata, è l'
|
||||
unica fonte di autorizzazione per comandi e direttive (`commands.useAccessGroups`
|
||||
vengono ignorati). Usa `"*"` come impostazione globale predefinita; le chiavi specifiche del provider la sovrascrivono.
|
||||
- `commands.useAccessGroups` (predefinito `true`) applica allowlist/policy ai comandi quando `commands.allowFrom` non è impostato.
|
||||
|
||||
## Elenco dei comandi
|
||||
|
||||
Fonte di verità attuale:
|
||||
|
||||
- i built-in core provengono da `src/auto-reply/commands-registry.shared.ts`
|
||||
- i dock command generati provengono da `src/auto-reply/commands-registry.data.ts`
|
||||
- i comandi plugin provengono dalle chiamate plugin `registerCommand()`
|
||||
- l’effettiva disponibilità sul tuo Gateway dipende comunque da flag di configurazione, superficie del canale e plugin installati/abilitati
|
||||
- i built-in del 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 da flag di configurazione, superficie del canale e plugin installati/abilitati
|
||||
|
||||
### Comandi built-in core
|
||||
### Comandi built-in del core
|
||||
|
||||
Comandi built-in disponibili oggi:
|
||||
|
||||
- `/new [model]` avvia una nuova sessione; `/reset` è l’alias di reset.
|
||||
- `/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.
|
||||
- `/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 dettagliato. Alias: `/v`.
|
||||
- `/trace on|off` attiva/disattiva l’output di trace del plugin per la sessione corrente.
|
||||
- `/think <level>` imposta il livello di pensiero. Le opzioni provengono dal profilo provider del modello attivo; i livelli comuni sono `off`, `minimal`, `low`, `medium` e `high`, con livelli personalizzati come `xhigh`, `adaptive`, `max` o il solo binario `on` dove supportato. Alias: `/thinking`, `/t`.
|
||||
- `/verbose on|off|full` attiva o disattiva l'output verboso. Alias: `/v`.
|
||||
- `/trace on|off` attiva o disattiva l'output di trace del plugin per la sessione corrente.
|
||||
- `/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à elevated. Alias: `/elev`.
|
||||
- `/reasoning [on|off|stream]` attiva o disattiva la visibilità del reasoning. Alias: `/reason`.
|
||||
- `/elevated [on|off|ask|full]` attiva o disattiva la modalità elevated. 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 breve riepilogo della guida.
|
||||
- `/commands` mostra il catalogo comandi generato.
|
||||
- `/tools [compact|verbose]` mostra cosa l’agente corrente può usare in questo momento.
|
||||
- `/status` mostra lo stato runtime, incluso l’uso/quota del provider quando disponibile.
|
||||
- `/help` mostra il riepilogo sintetico 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'utilizzo/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`.
|
||||
- `/whoami` mostra il tuo id mittente. Alias: `/id`.
|
||||
- `/skill <name> [input]` esegue una skill per nome.
|
||||
- `/allowlist [list|add|remove] ...` gestisce le voci dell’allowlist. Solo testo.
|
||||
- `/approve <id> <decision>` risolve i prompt di approvazione exec.
|
||||
- `/allowlist [list|add|remove] ...` gestisce le voci dell'allowlist. Solo testuale.
|
||||
- `/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 sottoagenti 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 runtime.
|
||||
- `/focus <target>` collega il thread Discord o l’argomento/conversazione Telegram corrente a una destinazione 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 sottoagenti in esecuzione.
|
||||
- `/steer <id|#> <message>` invia steering a un sottoagente in esecuzione. Alias: `/tell`.
|
||||
- `/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 di runtime.
|
||||
- `/focus <target>` associa il thread Discord corrente o l'argomento/conversazione Telegram a un target di sessione.
|
||||
- `/unfocus` rimuove l'associazione corrente.
|
||||
- `/agents` elenca gli agent associati al thread per la sessione corrente.
|
||||
- `/kill <id|#|all>` interrompe uno o tutti i sub-agent in esecuzione.
|
||||
- `/steer <id|#> <message>` invia istruzioni 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 footer di utilizzo per risposta o stampa un riepilogo locale dei costi.
|
||||
- `/tts on|off|status|provider|limit|summary|audio|help` controlla TTS. Vedi [/tools/tts](/it/tools/tts).
|
||||
- `/mcp show|get|set|unset` legge o scrive la configurazione del server MCP gestita da OpenClaw in `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. Le scritture sono solo proprietario. Richiede `commands.plugins: true`.
|
||||
- `/debug show|set|unset|reset` gestisce 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 o stampa un riepilogo locale dei costi.
|
||||
- `/tts on|off|status|provider|limit|summary|audio|help` controlla il 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 host. Solo testo. Alias: `! <command>`. Richiede `commands.bash: true` più le allowlist `tools.elevated`.
|
||||
- `/bash <command>` esegue un comando shell host. Solo testuale. Alias: `! <command>`. Richiede `commands.bash: true` più le allowlist `tools.elevated`.
|
||||
- `!poll [sessionId]` controlla un job bash in background.
|
||||
- `!stop [sessionId]` interrompe un job bash in background.
|
||||
- `!stop [sessionId]` arresta un job bash in background.
|
||||
|
||||
### Dock command generati
|
||||
### Comandi dock generati
|
||||
|
||||
I dock command vengono generati dai plugin di canale con supporto per i comandi nativi. Set integrato attuale:
|
||||
I comandi dock sono generati dai plugin canale con supporto ai comandi nativi. Set incluso attuale:
|
||||
|
||||
- `/dock-discord` (alias: `/dock_discord`)
|
||||
- `/dock-mattermost` (alias: `/dock_mattermost`)
|
||||
- `/dock-slack` (alias: `/dock_slack`)
|
||||
- `/dock-telegram` (alias: `/dock_telegram`)
|
||||
|
||||
### Comandi dei plugin integrati
|
||||
### Comandi dei plugin inclusi
|
||||
|
||||
I plugin integrati possono aggiungere altri comandi slash. Comandi integrati attuali in questo repo:
|
||||
I plugin inclusi possono aggiungere altri slash command. Comandi inclusi attuali in questo repository:
|
||||
|
||||
- `/dreaming [on|off|status|help]` attiva/disattiva il dreaming della memoria. Vedi [Dreaming](/it/concepts/dreaming).
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` gestisce il flusso di pairing/configurazione del dispositivo. Vedi [Pairing](/it/channels/pairing).
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` arma temporaneamente i comandi ad alto rischio del Node telefonico.
|
||||
- `/dreaming [on|off|status|help]` attiva o disattiva il dreaming della memoria. Vedi [Dreaming](/it/concepts/dreaming).
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` gestisce il flusso di associazione/configurazione del dispositivo. Vedi [Pairing](/it/channels/pairing).
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` arma temporaneamente i comandi ad alto rischio del nodo telefonico.
|
||||
- `/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).
|
||||
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` ispeziona e controlla l’harness app-server Codex integrato. Vedi [Codex Harness](/it/plugins/codex-harness).
|
||||
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` ispeziona e controlla l'harness app-server Codex incluso. Vedi [Codex Harness](/it/plugins/codex-harness).
|
||||
- Comandi solo QQBot:
|
||||
- `/bot-ping`
|
||||
- `/bot-version`
|
||||
@ -168,70 +170,71 @@ I plugin integrati possono aggiungere altri comandi slash. Comandi integrati att
|
||||
|
||||
### Comandi skill dinamici
|
||||
|
||||
Le skill invocabili dall’utente sono esposte anche come comandi slash:
|
||||
Le skill invocabili dall'utente sono esposte anche come slash command:
|
||||
|
||||
- `/skill <name> [input]` funziona sempre come punto di ingresso generico.
|
||||
- le skill possono comparire anche come comandi diretti come `/prose` quando la skill/il plugin li registra.
|
||||
- le skill possono anche apparire 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 facoltativamente `:` tra il comando e gli argomenti (ad esempio `/think: high`, `/send: on`, `/help:`).
|
||||
- `/new <model>` accetta un alias di modello, `provider/model` oppure il nome di un provider (corrispondenza fuzzy); se non trova alcuna corrispondenza, il testo viene trattato come corpo del messaggio.
|
||||
- Per la ripartizione completa dell’utilizzo per provider, usa `openclaw status --usage`.
|
||||
- I comandi accettano facoltativamente un `:` tra il comando e gli argomenti (ad esempio `/think: high`, `/send: on`, `/help:`).
|
||||
- `/new <model>` accetta un alias di modello, `provider/model` o il nome di un provider (corrispondenza fuzzy); se non trova corrispondenze, 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>` orientato alla 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>` orientato 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 di OpenClaw.
|
||||
- `/restart` è abilitato per impostazione predefinita; imposta `commands.restart: false` per disabilitarlo.
|
||||
- `/plugins install <spec>` accetta le stesse specifiche plugin di `openclaw plugins install`: percorso/archivio locale, pacchetto npm oppure `clawhub:<pkg>`.
|
||||
- `/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 i comandi nativi; non disponibile come testo).
|
||||
- I comandi di binding del thread Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) richiedono che i thread binding effettivi siano abilitati (`session.threadBindings.enabled` e/o `channels.discord.threadBindings.enabled`).
|
||||
- Riferimento del comando ACP e comportamento runtime: [ACP Agents](/it/tools/acp-agents).
|
||||
- `/verbose` è pensato per il debug e una visibilità aggiuntiva; tienilo **disattivato** nell’uso normale.
|
||||
- `/trace` è più ristretto di `/verbose`: mostra solo righe di trace/debug gestite dal plugin e mantiene disattivato il normale rumore dettagliato di strumenti e stato.
|
||||
- `/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`. Vedi [OpenAI](/it/providers/openai) e [Anthropic](/it/providers/anthropic).
|
||||
- I riepiloghi degli errori degli strumenti vengono comunque mostrati quando rilevanti, ma il testo dettagliato dell’errore viene incluso solo quando `/verbose` è `on` o `full`.
|
||||
- `/reasoning`, `/verbose` e `/trace` sono rischiosi nelle impostazioni di gruppo: possono rivelare ragionamento interno, output degli strumenti o diagnostica dei plugin che non intendevi esporre. È preferibile lasciarli disattivati, soprattutto nelle chat di gruppo.
|
||||
- Comando nativo solo Discord: `/vc join|leave|status` controlla i canali vocali (richiede `channels.discord.voice` e i comandi nativi; non disponibile come comando testuale).
|
||||
- I comandi di binding dei thread di 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 del runtime: [ACP Agents](/it/tools/acp-agents).
|
||||
- `/verbose` è pensato per il debug e una visibilità aggiuntiva; mantienilo **disattivato** nell'uso normale.
|
||||
- `/trace` è più mirato di `/verbose`: mostra solo le righe di trace/debug possedute dal plugin e mantiene disattivo il normale output verboso di strumenti e stato.
|
||||
- `/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 dirette pubbliche ad Anthropic, 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 degli errori viene incluso solo quando `/verbose` è `on` o `full`.
|
||||
- `/reasoning`, `/verbose` e `/trace` sono rischiosi nei contesti di gruppo: possono rivelare reasoning interno, output degli strumenti o diagnostica dei plugin che non intendevi esporre. È preferibile lasciarli disattivati, soprattutto nelle chat di gruppo.
|
||||
- `/model` rende immediatamente persistente il nuovo modello di sessione.
|
||||
- Se l’agente è inattivo, l’esecuzione successiva 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 è già iniziato, il cambio in sospeso può restare in coda fino a una successiva opportunità di retry o al turno utente seguente.
|
||||
- **Percorso veloce:** i messaggi solo comando dai mittenti in allowlist vengono gestiti immediatamente (saltano coda + modello).
|
||||
- **Controllo menzione nei gruppi:** i messaggi solo comando dai mittenti in allowlist bypassano i requisiti di menzione.
|
||||
- Se l'agente è inattivo, l'esecuzione successiva lo usa subito.
|
||||
- Se è già in corso un'esecuzione, OpenClaw contrassegna un cambio live come in attesa 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 attesa può restare in coda fino a una successiva opportunità di retry o al turno utente seguente.
|
||||
- **Percorso rapido:** i messaggi composti solo da comandi provenienti da mittenti in allowlist vengono gestiti immediatamente (saltano coda + modello).
|
||||
- **Filtro per 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 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.
|
||||
- Esempio: `hey /status` attiva una risposta di stato e il testo rimanente continua nel normale flusso.
|
||||
- Attualmente: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
- I messaggi solo comando non autorizzati vengono ignorati silenziosamente e i token inline `/...` vengono trattati come testo semplice.
|
||||
- **Comandi Skill:** le skill `user-invocable` sono esposte come comandi slash. I nomi vengono sanificati 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 una normale richiesta.
|
||||
- Le skill possono dichiarare facoltativamente `command-dispatch: tool` per instradare il comando direttamente a uno strumento (deterministico, senza modello).
|
||||
- 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 slash command. I nomi vengono sanitizzati in `a-z0-9_` (massimo 32 caratteri); in caso di collisione 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 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’autocompletamento 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.
|
||||
- **Argomenti dei comandi nativi:** Discord usa l'autocompletamento 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 di runtime, non a una domanda di configurazione: **che cosa questo agente può usare adesso in
|
||||
`/tools` risponde a una domanda di runtime, non di configurazione: **che cosa questo agente può usare in questo momento in
|
||||
questa conversazione**.
|
||||
|
||||
- Il valore predefinito di `/tools` è compatto e ottimizzato per una scansione rapida.
|
||||
- Il valore predefinito di `/tools` è compatto e ottimizzato per una rapida scansione.
|
||||
- `/tools verbose` aggiunge brevi descrizioni.
|
||||
- Le superfici con comandi nativi che supportano argomenti espongono lo stesso cambio modalità `compact|verbose`.
|
||||
- I risultati valgono per la sessione, quindi cambiare agente, canale, thread, autorizzazione del mittente o modello può
|
||||
cambiare l’output.
|
||||
- `/tools` include gli strumenti realmente raggiungibili in fase di esecuzione, inclusi strumenti core, strumenti plugin connessi e strumenti gestiti dal canale.
|
||||
- Le superfici con comandi nativi che supportano argomenti espongono lo stesso cambio di modalità `compact|verbose`.
|
||||
- I risultati hanno ambito di sessione, quindi cambiare agente, canale, thread, autorizzazione del mittente o modello può
|
||||
modificare l'output.
|
||||
- `/tools` include gli strumenti realmente raggiungibili a runtime, inclusi gli strumenti core, gli strumenti dei
|
||||
plugin connessi e gli 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 modificare profili e override, usa il pannello Tools dell'interfaccia Control o le superfici config/catalogo invece
|
||||
di trattare `/tools` come un catalogo statico.
|
||||
|
||||
## Superfici di utilizzo (cosa compare dove)
|
||||
## Superfici di utilizzo (cosa appare dove)
|
||||
|
||||
- **Utilizzo/quota del provider** (esempio: “Claude 80% left”) compare in `/status` per il provider del modello corrente quando il monitoraggio dell’utilizzo è abilitato. OpenClaw normalizza le finestre del 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 chat più un’etichetta di piano con tag 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 esistenti diversi da zero mantengono comunque la precedenza e il fallback della trascrizione può anche recuperare l’etichetta del modello runtime attivo più un totale orientato al prompt più grande 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.
|
||||
- **Utilizzo/quota del provider** (esempio: “Claude 80% left”) appare 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 con solo il rimanente vengono invertiti prima della visualizzazione, e le risposte `model_remains` preferiscono la voce del modello chat più un'etichetta del piano con tag modello.
|
||||
- **Righe token/cache** in `/status` possono ricadere sull'ultima voce di utilizzo della trascrizione quando lo snapshot live della sessione è scarno. I valori live esistenti non nulli continuano comunque ad avere la precedenza, 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 normali risposte).
|
||||
- `/model status` riguarda **modelli/autenticazione/endpoint**, non l'utilizzo.
|
||||
|
||||
## Selezione del modello (`/model`)
|
||||
|
||||
@ -250,10 +253,10 @@ Esempi:
|
||||
|
||||
Note:
|
||||
|
||||
- `/model` e `/model list` mostrano un selettore compatto numerato (famiglia di modelli + provider disponibili).
|
||||
- `/model` e `/model list` mostrano un selettore compatto numerato (famiglia del modello + 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 preferisce il provider corrente quando possibile).
|
||||
- `/model status` mostra la vista dettagliata, inclusi endpoint del provider configurato (`baseUrl`) e modalità API (`api`) quando disponibili.
|
||||
- `/model status` mostra la vista dettagliata, incluso l'endpoint del provider configurato (`baseUrl`) e la modalità API (`api`) quando disponibili.
|
||||
|
||||
## Override di debug
|
||||
|
||||
@ -271,12 +274,12 @@ Esempi:
|
||||
|
||||
Note:
|
||||
|
||||
- Gli override si applicano immediatamente alle nuove letture di configurazione, ma **non** scrivono in `openclaw.json`.
|
||||
- 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.
|
||||
|
||||
## Output di trace del plugin
|
||||
## Output trace del plugin
|
||||
|
||||
`/trace` ti consente di attivare/disattivare **righe di trace/debug del plugin valide per la sessione** senza attivare la modalità verbose completa.
|
||||
`/trace` ti consente di attivare o disattivare le **righe di trace/debug del plugin con ambito di sessione** senza attivare la modalità verbose completa.
|
||||
|
||||
Esempi:
|
||||
|
||||
@ -288,12 +291,12 @@ Esempi:
|
||||
|
||||
Note:
|
||||
|
||||
- `/trace` senza argomento mostra lo stato di trace corrente della sessione.
|
||||
- `/trace on` abilita le righe di trace del plugin per la sessione corrente.
|
||||
- `/trace` senza argomenti mostra lo stato di trace della sessione corrente.
|
||||
- `/trace on` abilita le righe trace del plugin per la sessione corrente.
|
||||
- `/trace off` le disabilita di nuovo.
|
||||
- Le righe di trace del plugin possono comparire in `/status` e come messaggio diagnostico di follow-up dopo la normale risposta dell’assistente.
|
||||
- Le righe di trace del plugin possono apparire in `/status` e come messaggio diagnostico di follow-up dopo la normale risposta dell'assistente.
|
||||
- `/trace` non sostituisce `/debug`; `/debug` continua a gestire gli override di configurazione solo runtime.
|
||||
- `/trace` non sostituisce `/verbose`; il normale output dettagliato di strumenti/stato continua ad appartenere a `/verbose`.
|
||||
- `/trace` non sostituisce `/verbose`; il normale output verboso di strumenti/stato continua ad appartenere a `/verbose`.
|
||||
|
||||
## Aggiornamenti della configurazione
|
||||
|
||||
@ -316,7 +319,7 @@ Note:
|
||||
|
||||
## 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:
|
||||
|
||||
@ -329,12 +332,12 @@ Esempi:
|
||||
|
||||
Note:
|
||||
|
||||
- `/mcp` archivia la configurazione nella config di OpenClaw, non nelle impostazioni di progetto gestite da Pi.
|
||||
- Gli adapter runtime decidono quali trasporti siano effettivamente eseguibili.
|
||||
- `/mcp` memorizza la configurazione nella configurazione di OpenClaw, non nelle impostazioni del progetto possedute da Pi.
|
||||
- Gli adattatori di runtime decidono quali trasporti sono effettivamente eseguibili.
|
||||
|
||||
## Aggiornamenti dei plugin
|
||||
|
||||
`/plugins` consente agli operatori di ispezionare i plugin rilevati e attivarli/disattivarli nella configurazione. I flussi in sola lettura possono usare `/plugin` come alias. Disabilitato per impostazione predefinita; abilitalo con `commands.plugins: true`.
|
||||
`/plugins` consente agli operatori di ispezionare i plugin rilevati e attivare o disattivare l'abilitazione nella configurazione. I flussi in sola lettura possono usare `/plugin` come alias. Disabilitato per impostazione predefinita; abilitalo con `commands.plugins: true`.
|
||||
|
||||
Esempi:
|
||||
|
||||
@ -348,35 +351,34 @@ Esempi:
|
||||
|
||||
Note:
|
||||
|
||||
- `/plugins list` e `/plugins show` usano il vero rilevamento 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 plugin.
|
||||
- Dopo modifiche di abilitazione/disabilitazione, riavvia il Gateway per applicarle.
|
||||
- Dopo modifiche di abilitazione/disabilitazione, riavvia il gateway per applicarle.
|
||||
|
||||
## Note sulle superfici
|
||||
|
||||
- **Comandi testuali** vengono eseguiti nella normale sessione di chat (i DM condividono `main`, i gruppi hanno la propria sessione).
|
||||
- **Comandi testuali** vengono eseguiti nella normale sessione di chat (i messaggi diretti condividono `main`, i gruppi hanno una 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 di chat tramite `CommandTargetSessionKey`)
|
||||
- **`/stop`** indirizza la sessione di chat attiva in modo 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 (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 comunque a funzionare nei messaggi Slack.
|
||||
- Telegram: `telegram:slash:<userId>` (indirizza la sessione della chat tramite `CommandTargetSessionKey`)
|
||||
- **`/stop`** prende di mira la 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 uno slash command Slack per ogni comando built-in (con gli stessi nomi di `/help`). I menu argomento dei comandi per Slack vengono forniti come pulsanti Block Kit effimeri.
|
||||
- Eccezione nativa Slack: registra `/agentstatus` (non `/status`) perché Slack riserva `/status`. Il comando testuale `/status` continua comunque a funzionare nei messaggi Slack.
|
||||
|
||||
## Domande laterali BTW
|
||||
|
||||
`/btw` è una rapida **domanda laterale** sulla sessione corrente.
|
||||
|
||||
A differenza della chat normale:
|
||||
A differenza della normale chat:
|
||||
|
||||
- usa la sessione corrente come contesto di sfondo,
|
||||
- viene eseguita come chiamata separata una tantum **senza strumenti**,
|
||||
- viene eseguito come chiamata one-shot separata **senza strumenti**,
|
||||
- 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.
|
||||
- non viene scritto nella cronologia della trascrizione,
|
||||
- viene consegnato come risultato laterale live invece che come normale messaggio dell'assistente.
|
||||
|
||||
Questo rende `/btw` utile quando vuoi un chiarimento temporaneo mentre il compito principale
|
||||
continua.
|
||||
Questo rende `/btw` utile quando vuoi un chiarimento temporaneo mentre l'attività principale continua.
|
||||
|
||||
Esempio:
|
||||
|
||||
@ -384,5 +386,5 @@ Esempio:
|
||||
/btw cosa stiamo facendo in questo momento?
|
||||
```
|
||||
|
||||
Consulta [BTW Side Questions](/it/tools/btw) per il comportamento completo e i dettagli
|
||||
dell’esperienza client.
|
||||
Vedi [BTW Side Questions](/it/tools/btw) per il comportamento completo e i
|
||||
dettagli dell'esperienza utente del client.
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
---
|
||||
read_when:
|
||||
- Regolazione del parsing o dei valori predefiniti delle direttive thinking, modalità rapida o verbose
|
||||
- Regolazione dell'analisi delle direttive o dei valori predefiniti per thinking, modalità rapida o verbose
|
||||
summary: Sintassi delle direttive per /think, /fast, /verbose, /trace e visibilità del ragionamento
|
||||
title: Livelli di thinking
|
||||
x-i18n:
|
||||
generated_at: "2026-04-21T08:30:00Z"
|
||||
generated_at: "2026-04-21T13:35:41Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: edee9420e1cc3eccfa18d87061c4a4d6873e70cb51fff85305fafbcd6a5d6a7d
|
||||
source_hash: 1b0217f6e5a5cb3400090f31ad5271ca61848a40f77d3f942851e7c2f2352886
|
||||
source_path: tools/thinking.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -16,112 +16,116 @@ x-i18n:
|
||||
|
||||
## Cosa fa
|
||||
|
||||
- Direttiva inline in qualsiasi body in ingresso: `/t <level>`, `/think:<level>` oppure `/thinking <level>`.
|
||||
- Livelli, alias: `off | minimal | low | medium | high | xhigh | adaptive | max`
|
||||
- Direttiva inline in qualsiasi corpo in ingresso: `/t <level>`, `/think:<level>` o `/thinking <level>`.
|
||||
- Livelli (alias): `off | minimal | low | medium | high | xhigh | adaptive | max`
|
||||
- minimal → “think”
|
||||
- low → “think hard”
|
||||
- medium → “think harder”
|
||||
- high → “ultrathink”, budget massimo
|
||||
- xhigh → “ultrathink+”, effort per GPT-5.2 + modelli Codex e Anthropic Claude Opus 4.7
|
||||
- adaptive → thinking adattivo gestito dal provider, supportato per Claude 4.6 su Anthropic/Bedrock e Anthropic Claude Opus 4.7
|
||||
- max → ragionamento massimo del provider, attualmente Anthropic Claude Opus 4.7
|
||||
- high → “ultrathink” (budget massimo)
|
||||
- xhigh → “ultrathink+” (GPT-5.2 + modelli Codex e sforzo Anthropic Claude Opus 4.7)
|
||||
- adaptive → thinking adattivo gestito dal provider (supportato per Claude 4.6 su Anthropic/Bedrock e Anthropic Claude Opus 4.7)
|
||||
- max → ragionamento massimo del provider (attualmente Anthropic Claude Opus 4.7)
|
||||
- `x-high`, `x_high`, `extra-high`, `extra high` e `extra_high` vengono mappati a `xhigh`.
|
||||
- `highest` viene mappato a `high`.
|
||||
- Note sui provider:
|
||||
- `adaptive` viene pubblicizzato nei menu comandi e picker nativi solo per provider/modelli che dichiarano supporto al thinking adattivo. Resta accettato come direttiva digitata per compatibilità con configurazioni e alias esistenti.
|
||||
- `max` viene pubblicizzato nei menu comandi e picker nativi solo per provider/modelli che dichiarano supporto al thinking max. Le impostazioni `max` già memorizzate vengono rimappate al livello supportato più alto per il modello selezionato quando il modello non supporta `max`.
|
||||
- I menu e i selettori di thinking sono guidati dal profilo provider. I plugin provider dichiarano l'insieme esatto di livelli per il modello selezionato, incluse etichette come il valore binario `on`.
|
||||
- `adaptive`, `xhigh` e `max` vengono pubblicizzati solo per i profili provider/modello che li supportano. Le direttive digitate per livelli non supportati vengono rifiutate con le opzioni valide di quel modello.
|
||||
- I livelli non supportati già memorizzati, inclusi i vecchi valori `max` dopo un cambio di modello, vengono rimappati al livello supportato più alto per il modello selezionato.
|
||||
- I modelli Anthropic Claude 4.6 usano `adaptive` per impostazione predefinita quando non è impostato alcun livello di thinking esplicito.
|
||||
- Anthropic Claude Opus 4.7 non usa thinking adattivo per impostazione predefinita. Il valore predefinito effort della sua API resta di proprietà del provider a meno che tu non imposti esplicitamente un livello di thinking.
|
||||
- Anthropic Claude Opus 4.7 mappa `/think xhigh` al thinking adattivo più `output_config.effort: "xhigh"`, perché `/think` è una direttiva thinking e `xhigh` è l'impostazione effort di Opus 4.7.
|
||||
- Anthropic Claude Opus 4.7 espone anche `/think max`; viene mappato allo stesso percorso max gestito dal provider.
|
||||
- I modelli OpenAI GPT mappano `/think` tramite il supporto effort specifico per modello della Responses API. `/think off` invia `reasoning.effort: "none"` solo quando il modello di destinazione lo supporta; altrimenti OpenClaw omette il payload di reasoning disabilitato invece di inviare un valore non supportato.
|
||||
- MiniMax (`minimax/*`) sul percorso streaming compatibile Anthropic usa per impostazione predefinita `thinking: { type: "disabled" }` a meno che tu non imposti esplicitamente thinking nei params del modello o della richiesta. Questo evita delta `reasoning_content` trapelati dal formato stream Anthropic non nativo di MiniMax.
|
||||
- Z.AI (`zai/*`) supporta solo thinking binario, `on`/`off`. Qualsiasi livello diverso da `off` viene trattato come `on`, mappato a `low`.
|
||||
- Anthropic Claude Opus 4.7 non usa thinking adattivo per impostazione predefinita. Il valore predefinito dello sforzo API resta di proprietà del provider finché non imposti esplicitamente un livello di thinking.
|
||||
- Anthropic Claude Opus 4.7 mappa `/think xhigh` a thinking adattivo più `output_config.effort: "xhigh"`, perché `/think` è una direttiva di thinking e `xhigh` è l'impostazione di sforzo di Opus 4.7.
|
||||
- Anthropic Claude Opus 4.7 espone anche `/think max`; viene mappato allo stesso percorso di sforzo massimo di proprietà del provider.
|
||||
- I modelli OpenAI GPT mappano `/think` tramite il supporto allo sforzo specifico del modello nella Responses API. `/think off` invia `reasoning.effort: "none"` solo quando il modello di destinazione lo supporta; altrimenti OpenClaw omette il payload di reasoning disabilitato invece di inviare un valore non supportato.
|
||||
- MiniMax (`minimax/*`) sul percorso di streaming compatibile con Anthropic usa per impostazione predefinita `thinking: { type: "disabled" }` a meno che tu non imposti esplicitamente il thinking nei parametri del modello o della richiesta. Questo evita delta `reasoning_content` trapelati dal formato di stream Anthropic non nativo di MiniMax.
|
||||
- Z.AI (`zai/*`) supporta solo thinking binario (`on`/`off`). Qualsiasi livello diverso da `off` viene trattato come `on` (mappato a `low`).
|
||||
- Moonshot (`moonshot/*`) mappa `/think off` a `thinking: { type: "disabled" }` e qualsiasi livello diverso da `off` a `thinking: { type: "enabled" }`. Quando il thinking è abilitato, Moonshot accetta solo `tool_choice` `auto|none`; OpenClaw normalizza i valori incompatibili in `auto`.
|
||||
|
||||
## Ordine di risoluzione
|
||||
|
||||
1. Direttiva inline nel messaggio, vale solo per quel messaggio.
|
||||
2. Override di sessione, impostato inviando un messaggio contenente solo la direttiva.
|
||||
3. Valore predefinito per agente, `agents.list[].thinkingDefault` nella configurazione.
|
||||
4. Valore predefinito globale, `agents.defaults.thinkingDefault` nella configurazione.
|
||||
5. Fallback: `adaptive` per i modelli Anthropic Claude 4.6, `off` per Anthropic Claude Opus 4.7 se non configurato esplicitamente, `low` per altri modelli capaci di ragionamento, `off` altrimenti.
|
||||
1. Direttiva inline nel messaggio (si applica solo a quel messaggio).
|
||||
2. Sostituzione della sessione (impostata inviando un messaggio contenente solo una direttiva).
|
||||
3. Valore predefinito per agente (`agents.list[].thinkingDefault` nella configurazione).
|
||||
4. Valore predefinito globale (`agents.defaults.thinkingDefault` nella configurazione).
|
||||
5. Fallback: valore predefinito dichiarato dal provider quando disponibile, `low` per altri modelli del catalogo contrassegnati come capaci di reasoning, `off` altrimenti.
|
||||
|
||||
## Impostare un valore predefinito di sessione
|
||||
## Impostazione di un valore predefinito di sessione
|
||||
|
||||
- Invia un messaggio che sia **solo** la direttiva, spazi consentiti, per esempio `/think:medium` oppure `/t high`.
|
||||
- Questo resta valido per la sessione corrente, per mittente per impostazione predefinita; viene cancellato da `/think:off` o dal reset per inattività della sessione.
|
||||
- Viene inviata una risposta di conferma, `Thinking level set to high.` / `Thinking disabled.`. Se il livello non è valido, per esempio `/thinking big`, il comando viene rifiutato con un suggerimento e lo stato della sessione resta invariato.
|
||||
- Invia `/think` oppure `/think:` senza argomento per vedere il livello di thinking corrente.
|
||||
- Invia un messaggio che sia **solo** la direttiva (spazi consentiti), per esempio `/think:medium` o `/t high`.
|
||||
- Questo resta valido per la sessione corrente (per mittente per impostazione predefinita); viene cancellato con `/think:off` o con il reset per inattività della sessione.
|
||||
- Viene inviata una risposta di conferma (`Thinking level set to high.` / `Thinking disabled.`). Se il livello non è valido (per esempio `/thinking big`), il comando viene rifiutato con un suggerimento e lo stato della sessione resta invariato.
|
||||
- Invia `/think` (o `/think:`) senza argomento per vedere il livello di thinking corrente.
|
||||
|
||||
## Applicazione per agente
|
||||
|
||||
- **Embedded Pi**: il livello risolto viene passato al runtime dell'agente Pi in-process.
|
||||
- **Pi embedded**: il livello risolto viene passato al runtime dell'agente Pi in-process.
|
||||
|
||||
## Modalità rapida (`/fast`)
|
||||
|
||||
- Livelli: `on|off`.
|
||||
- Un messaggio contenente solo la direttiva attiva o disattiva un override di sessione della modalità rapida e risponde con `Fast mode enabled.` / `Fast mode disabled.`.
|
||||
- Invia `/fast` oppure `/fast status` senza modalità per vedere lo stato effettivo corrente della modalità rapida.
|
||||
- Un messaggio contenente solo la direttiva attiva o disattiva una sostituzione della modalità rapida di sessione e risponde con `Fast mode enabled.` / `Fast mode disabled.`.
|
||||
- Invia `/fast` (o `/fast status`) senza modalità per vedere lo stato effettivo corrente della modalità rapida.
|
||||
- OpenClaw risolve la modalità rapida in questo ordine:
|
||||
1. `/fast on|off` inline o solo-direttiva
|
||||
2. Override di sessione
|
||||
3. Valore predefinito per agente, `agents.list[].fastModeDefault`
|
||||
4. Config per modello: `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
1. `/fast on|off` inline/con sola direttiva
|
||||
2. Sostituzione della sessione
|
||||
3. Valore predefinito per agente (`agents.list[].fastModeDefault`)
|
||||
4. Configurazione per modello: `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
5. Fallback: `off`
|
||||
- Per `openai/*`, la modalità rapida viene mappata all'elaborazione prioritaria OpenAI inviando `service_tier=priority` sulle richieste Responses supportate.
|
||||
- Per `openai-codex/*`, la modalità rapida invia lo stesso flag `service_tier=priority` su Codex Responses. OpenClaw mantiene un unico toggle condiviso `/fast` per entrambi i percorsi auth.
|
||||
- Per `openai/*`, la modalità rapida viene mappata all'elaborazione prioritaria OpenAI inviando `service_tier=priority` nelle richieste Responses supportate.
|
||||
- Per `openai-codex/*`, la modalità rapida invia lo stesso flag `service_tier=priority` su Codex Responses. OpenClaw mantiene un unico interruttore `/fast` condiviso tra entrambi i percorsi di autenticazione.
|
||||
- Per le richieste pubbliche dirette `anthropic/*`, incluso il traffico autenticato OAuth inviato a `api.anthropic.com`, la modalità rapida viene mappata ai service tier Anthropic: `/fast on` imposta `service_tier=auto`, `/fast off` imposta `service_tier=standard_only`.
|
||||
- Per `minimax/*` sul percorso compatibile Anthropic, `/fast on`, oppure `params.fastMode: true`, riscrive `MiniMax-M2.7` in `MiniMax-M2.7-highspeed`.
|
||||
- I params espliciti del modello Anthropic `serviceTier` / `service_tier` sostituiscono il valore predefinito della modalità rapida quando sono impostati entrambi. OpenClaw continua comunque a saltare l'iniezione del service tier Anthropic per URL base proxy non Anthropic.
|
||||
- Per `minimax/*` sul percorso compatibile con Anthropic, `/fast on` (o `params.fastMode: true`) riscrive `MiniMax-M2.7` in `MiniMax-M2.7-highspeed`.
|
||||
- I parametri di modello espliciti Anthropic `serviceTier` / `service_tier` hanno la precedenza sul valore predefinito della modalità rapida quando entrambi sono impostati. OpenClaw continua comunque a saltare l'iniezione del service tier Anthropic per URL base proxy non Anthropic.
|
||||
|
||||
## Direttive verbose (`/verbose` oppure `/v`)
|
||||
## Direttive verbose (`/verbose` o `/v`)
|
||||
|
||||
- Livelli: `on`, minimale, `full`, `off`, predefinito.
|
||||
- Un messaggio contenente solo la direttiva attiva o disattiva verbose di sessione e risponde con `Verbose logging enabled.` / `Verbose logging disabled.`; i livelli non validi restituiscono un suggerimento senza cambiare stato.
|
||||
- `/verbose off` memorizza un override di sessione esplicito; cancellalo tramite la UI Sessions scegliendo `inherit`.
|
||||
- La direttiva inline vale solo per quel messaggio; altrimenti si applicano i valori predefiniti di sessione o globali.
|
||||
- Invia `/verbose` oppure `/verbose:` senza argomento per vedere il livello verbose corrente.
|
||||
- Quando verbose è attivo, gli agenti che emettono risultati di strumenti strutturati, Pi e altri agenti JSON, inviano ogni tool call come proprio messaggio solo-metadati, con prefisso `<emoji> <tool-name>: <arg>` quando disponibile, percorso o comando. Questi riepiloghi degli strumenti vengono inviati non appena ogni strumento inizia, come bolle separate, non come delta di streaming.
|
||||
- I riepiloghi dei fallimenti degli strumenti restano visibili in modalità normale, ma i suffissi del dettaglio di errore grezzo sono nascosti a meno che verbose non sia `on` o `full`.
|
||||
- Quando verbose è `full`, anche gli output degli strumenti vengono inoltrati dopo il completamento, bolla separata, troncata a una lunghezza sicura. Se attivi `/verbose on|full|off` mentre un'esecuzione è in corso, le bolle successive degli strumenti rispettano la nuova impostazione.
|
||||
- Livelli: `on` (minimo) | `full` | `off` (predefinito).
|
||||
- Un messaggio contenente solo la direttiva attiva o disattiva il verbose di sessione e risponde con `Verbose logging enabled.` / `Verbose logging disabled.`; i livelli non validi restituiscono un suggerimento senza cambiare stato.
|
||||
- `/verbose off` memorizza una sostituzione esplicita di sessione; cancellala tramite l'interfaccia Sessioni scegliendo `inherit`.
|
||||
- La direttiva inline influisce solo su quel messaggio; altrimenti si applicano i valori predefiniti di sessione/globali.
|
||||
- Invia `/verbose` (o `/verbose:`) senza argomento per vedere il livello verbose corrente.
|
||||
- Quando verbose è attivo, gli agenti che emettono risultati strutturati dei tool (Pi, altri agenti JSON) rimandano ogni chiamata di tool come proprio messaggio solo metadati, con prefisso `<emoji> <tool-name>: <arg>` quando disponibile (percorso/comando). Questi riepiloghi dei tool vengono inviati non appena ogni tool inizia (bolle separate), non come delta di streaming.
|
||||
- I riepiloghi dei fallimenti dei tool restano visibili in modalità normale, ma i suffissi con i dettagli grezzi degli errori sono nascosti a meno che verbose non sia `on` o `full`.
|
||||
- Quando verbose è `full`, anche gli output dei tool vengono inoltrati dopo il completamento (bolla separata, troncata a una lunghezza sicura). Se attivi `/verbose on|full|off` mentre un'esecuzione è in corso, le bolle dei tool successive rispettano la nuova impostazione.
|
||||
|
||||
## Direttive di trace del plugin (`/trace`)
|
||||
## Direttive di traccia dei plugin (`/trace`)
|
||||
|
||||
- Livelli: `on` | `off`, predefinito.
|
||||
- Un messaggio contenente solo la direttiva attiva o disattiva l'output trace del plugin per la sessione e risponde con `Plugin trace enabled.` / `Plugin trace disabled.`.
|
||||
- La direttiva inline vale solo per quel messaggio; altrimenti si applicano i valori predefiniti di sessione o globali.
|
||||
- Invia `/trace` oppure `/trace:` senza argomento per vedere il livello trace corrente.
|
||||
- `/trace` è più ristretto di `/verbose`: espone solo righe di trace/debug di proprietà del plugin, come i riepiloghi di debug di Active Memory.
|
||||
- Le righe di trace possono apparire in `/status` e come messaggio diagnostico di follow-up dopo la normale risposta dell'assistente.
|
||||
- Livelli: `on` | `off` (predefinito).
|
||||
- Un messaggio contenente solo la direttiva attiva o disattiva l'output di traccia dei plugin della sessione e risponde con `Plugin trace enabled.` / `Plugin trace disabled.`.
|
||||
- La direttiva inline influisce solo su quel messaggio; altrimenti si applicano i valori predefiniti di sessione/globali.
|
||||
- Invia `/trace` (o `/trace:`) senza argomento per vedere il livello di traccia corrente.
|
||||
- `/trace` è più ristretto di `/verbose`: espone solo righe di traccia/debug di proprietà dei plugin, come i riepiloghi di debug di Active Memory.
|
||||
- Le righe di traccia possono comparire in `/status` e come messaggio diagnostico di follow-up dopo la normale risposta dell'assistente.
|
||||
|
||||
## Visibilità del ragionamento (`/reasoning`)
|
||||
## Visibilità del reasoning (`/reasoning`)
|
||||
|
||||
- Livelli: `on|off|stream`.
|
||||
- Un messaggio contenente solo la direttiva attiva o disattiva la visualizzazione dei blocchi di thinking nelle risposte.
|
||||
- Quando è abilitato, il ragionamento viene inviato come **messaggio separato** con prefisso `Reasoning:`.
|
||||
- `stream`, solo Telegram: trasmette in streaming il ragionamento nella bolla di bozza di Telegram mentre la risposta viene generata, poi invia la risposta finale senza ragionamento.
|
||||
- Quando è abilitato, il reasoning viene inviato come **messaggio separato** con prefisso `Reasoning:`.
|
||||
- `stream` (solo Telegram): trasmette il reasoning nella bozza di Telegram mentre la risposta viene generata, poi invia la risposta finale senza reasoning.
|
||||
- Alias: `/reason`.
|
||||
- Invia `/reasoning` oppure `/reasoning:` senza argomento per vedere il livello di ragionamento corrente.
|
||||
- Ordine di risoluzione: direttiva inline, poi override di sessione, poi valore predefinito per agente, `agents.list[].reasoningDefault`, poi fallback, `off`.
|
||||
- Invia `/reasoning` (o `/reasoning:`) senza argomento per vedere il livello di reasoning corrente.
|
||||
- Ordine di risoluzione: direttiva inline, poi sostituzione della sessione, poi valore predefinito per agente (`agents.list[].reasoningDefault`), poi fallback (`off`).
|
||||
|
||||
## Correlati
|
||||
|
||||
- La documentazione della modalità elevata si trova in [Elevated mode](/it/tools/elevated).
|
||||
- La documentazione sulla modalità elevata si trova in [Modalità elevata](/it/tools/elevated).
|
||||
|
||||
## Heartbeat
|
||||
|
||||
- Il body del probe Heartbeat è il prompt Heartbeat configurato, predefinito: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`. Le direttive inline in un messaggio Heartbeat si applicano normalmente, ma evita di cambiare i valori predefiniti di sessione dagli Heartbeat.
|
||||
- La consegna di Heartbeat usa per impostazione predefinita solo il payload finale. Per inviare anche il messaggio separato `Reasoning:`, quando disponibile, imposta `agents.defaults.heartbeat.includeReasoning: true` oppure per agente `agents.list[].heartbeat.includeReasoning: true`.
|
||||
- Il corpo della probe Heartbeat è il prompt heartbeat configurato (predefinito: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Le direttive inline in un messaggio heartbeat si applicano come di consueto (ma evita di cambiare i valori predefiniti di sessione dai heartbeat).
|
||||
- Il recapito Heartbeat usa per impostazione predefinita solo il payload finale. Per inviare anche il messaggio separato `Reasoning:` (quando disponibile), imposta `agents.defaults.heartbeat.includeReasoning: true` o per agente `agents.list[].heartbeat.includeReasoning: true`.
|
||||
|
||||
## Web chat UI
|
||||
## Interfaccia web della chat
|
||||
|
||||
- Il selettore di thinking della web chat rispecchia all'apertura della pagina il livello memorizzato della sessione dall'archivio sessioni/configurazione in ingresso.
|
||||
- Scegliere un altro livello scrive immediatamente l'override di sessione tramite `sessions.patch`; non aspetta il prossimo invio e non è un override monouso `thinkingOnce`.
|
||||
- La prima opzione è sempre `Default (<resolved level>)`, dove il valore predefinito risolto deriva dal modello attivo della sessione: `adaptive` per Claude 4.6 su Anthropic, `off` per Anthropic Claude Opus 4.7 se non configurato, `low` per altri modelli capaci di ragionamento, `off` altrimenti.
|
||||
- Il picker resta consapevole del provider:
|
||||
- la maggior parte dei provider mostra `off | minimal | low | medium | high`
|
||||
- Anthropic/Bedrock Claude 4.6 mostra `off | minimal | low | medium | high | adaptive`
|
||||
- Anthropic Claude Opus 4.7 mostra `off | minimal | low | medium | high | xhigh | adaptive | max`
|
||||
- Z.AI mostra il binario `off | on`
|
||||
- `/think:<level>` continua a funzionare e aggiorna lo stesso livello di sessione memorizzato, così direttive chat e picker restano sincronizzati.
|
||||
- Il selettore thinking della chat web rispecchia il livello memorizzato della sessione dal relativo archivio/configurazione della sessione in ingresso quando la pagina viene caricata.
|
||||
- Scegliere un altro livello scrive immediatamente la sostituzione della sessione tramite `sessions.patch`; non aspetta l'invio successivo e non è una sostituzione una tantum `thinkingOnce`.
|
||||
- La prima opzione è sempre `Default (<resolved level>)`, dove il valore predefinito risolto proviene dal profilo thinking del provider del modello attivo della sessione.
|
||||
- Il selettore usa `thinkingOptions` restituito dalla riga di sessione del gateway. L'interfaccia browser non mantiene una propria lista regex dei provider; i plugin possiedono gli insiemi di livelli specifici del modello.
|
||||
- `/think:<level>` continua a funzionare e aggiorna lo stesso livello di sessione memorizzato, così le direttive della chat e il selettore restano sincronizzati.
|
||||
|
||||
## Profili provider
|
||||
|
||||
- I plugin provider possono esporre `resolveThinkingProfile(ctx)` per definire i livelli supportati dal modello e il valore predefinito.
|
||||
- Ogni livello del profilo ha un `id` canonico memorizzato (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` o `max`) e può includere una `label` di visualizzazione. I provider binari usano `{ id: "low", label: "on" }`.
|
||||
- Gli hook legacy pubblicati (`supportsXHighThinking`, `isBinaryThinking` e `resolveDefaultThinkingLevel`) restano come adattatori di compatibilità, ma i nuovi insiemi di livelli personalizzati devono usare `resolveThinkingProfile`.
|
||||
- Le righe Gateway espongono `thinkingOptions` e `thinkingDefault` affinché i client ACP/chat mostrino lo stesso profilo usato dalla convalida runtime.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user