diff --git a/docs/it/channels/bluebubbles.md b/docs/it/channels/bluebubbles.md index 3ce1331de..40a3e4ecf 100644 --- a/docs/it/channels/bluebubbles.md +++ b/docs/it/channels/bluebubbles.md @@ -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=`). -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=`). +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=` 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=` 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 ``` -## 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 ` -- 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:` - `chat_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//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..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..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..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..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 `. -- 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 `. +- 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 diff --git a/docs/it/channels/slack.md b/docs/it/channels/slack.md index 9522e0fab..1a66cd913 100644 --- a/docs/it/channels/slack.md +++ b/docs/it/channels/slack.md @@ -1,30 +1,30 @@ --- read_when: - - Configurazione di Slack o debug della modalità socket/HTTP di Slack -summary: Configurazione 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. - - Le DM di Slack usano per impostazione predefinita la modalità di associazione. + + Le DM di Slack usano per impostazione predefinita la modalità di abbinamento. Comportamento nativo dei comandi e catalogo dei comandi. - Diagnostica cross-channel e procedure di riparazione. + Diagnostica tra canali e playbook di riparazione. @@ -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 @@ -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-... - + ```bash openclaw gateway @@ -77,13 +77,13 @@ openclaw gateway - + Nelle impostazioni dell'app Slack premi il pulsante **[Create New App](https://api.slack.com/apps/new)**: - scegli **from a manifest** e seleziona 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 ``` - 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. - + ```bash openclaw gateway @@ -125,7 +125,7 @@ openclaw gateway -## Checklist di manifest e ambiti +## Checklist di manifesto e ambiti @@ -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 - + ```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 -### 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. - È 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): @@ -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 or max-age " }, { "command": "/think", - "description": "Imposta il livello di ragionamento", - "usage_hint": "" + "description": "Set the thinking level", + "usage_hint": "" }, { "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= security= ask= node=" }, { "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=|size=|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": " [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": "" }, { "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" } ] ``` - + ```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 or max-age ", + "usage_hint": "idle o max-age ", "url": "https://gateway-host.example.com/slack/events" }, { "command": "/think", - "description": "Imposta il livello di ragionamento", - "usage_hint": "", + "description": "Imposta il livello di pensiero", + "usage_hint": "", "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": "", "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. - + 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) ## 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`. -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. -## 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 - `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 `. + L'abbinamento nei DM usa `openclaw pairing approve slack `. - - `channels.slack.groupPolicy` controlla la gestione dei canali: + + `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` @@ -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:`) @@ -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::slack:channel:`. +- 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::slack:channel:`. - Le risposte nei thread possono creare suffissi di sessione del thread (`:thread:`) quando applicabile. -- Il valore predefinito di `channels.slack.thread.historyScope` è `thread`; il valore predefinito di `thread.inheritParent` è `false`. +- 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:]]` -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..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 - 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`. @@ -805,17 +805,17 @@ Note: Destinazioni esplicite preferite: - - `user:` per le DM + - `user:` per i DM - `channel:` 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. ## 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::slack:slash: - + 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. 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) diff --git a/docs/it/concepts/messages.md b/docs/it/concepts/messages.md index 158762d4a..a332261e2 100644 --- a/docs/it/concepts/messages.md +++ b/docs/it/concepts/messages.md @@ -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..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..responsePrefix` e `channels..accounts..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..responsePrefix` e `channels..accounts..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..silentReply` e -`surfaces..silentReplyRewrite` possono sostituirli per superficie. +`surfaces..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 diff --git a/docs/it/concepts/model-providers.md b/docs/it/concepts/model-providers.md index 65cb771a0..623ca02e9 100644 --- a/docs/it/concepts/model-providers.md +++ b/docs/it/concepts/model-providers.md @@ -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 `. -- 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.` 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.` 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__KEY` (singolo override live, priorità massima) - - `_API_KEYS` (elenco separato da virgole o punti e virgola) + - `_API_KEYS` (elenco separato da virgole o punto e virgola) - `_API_KEY` (chiave primaria) - - `_API_KEY_*` (elenco numerato, ad esempio `_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 + - `_API_KEY_*` (elenco numerato, per esempio `_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/"].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/"].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/"].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/"].params.transport` (`"sse"`, `"websocket"` oppure `"auto"`) +- Override per modello tramite `agents.defaults.models["openai-codex/"].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/"].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/"].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/"].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.` 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.` 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 diff --git a/docs/it/plugins/architecture.md b/docs/it/plugins/architecture.md index 0b4a39e31..654ea2cdf 100644 --- a/docs/it/plugins/architecture.md +++ b/docs/it/plugins/architecture.md @@ -1,108 +1,111 @@ --- read_when: - - Sviluppare o fare debug dei Plugin nativi di OpenClaw - - Capire il modello di capability dei Plugin o i confini di ownership - - Lavorare sulla pipeline di caricamento o sul registro dei Plugin - - Implementare hook runtime dei provider o Plugin di canale + - Creazione o debug di plugin nativi di OpenClaw + - Comprendere il modello di capacità del plugin o i confini di proprietà + - Lavorare sulla pipeline di caricamento del plugin o sul registro + - Implementare hook di runtime del provider o plugin di canale sidebarTitle: Internals -summary: 'Interni dei Plugin: modello di capability, ownership, contratti, pipeline di caricamento e helper runtime' -title: Interni dei Plugin +summary: 'Interni del Plugin: modello di capacità, proprietà, contratti, pipeline di caricamento e helper di runtime' +title: Interni del Plugin x-i18n: - generated_at: "2026-04-21T08:24:59Z" + generated_at: "2026-04-21T13:35:24Z" model: gpt-5.4 provider: openai - source_hash: 05b612f75189ba32f8c92e5a261241abdf9ad8d4a685c1d8da0cf9605d7158b7 + source_hash: 4b1fb42e659d4419033b317e88563a59b3ddbfad0523f32225c868c8e828fd16 source_path: plugins/architecture.md workflow: 15 --- -# Interni dei Plugin +# Interni del Plugin - Questo è il **riferimento architetturale approfondito**. Per guide pratiche, consulta: - - [Install and use plugins](/it/tools/plugin) — guida utente - - [Getting Started](/it/plugins/building-plugins) — primo tutorial sui Plugin - - [Channel Plugins](/it/plugins/sdk-channel-plugins) — crea un canale di messaggistica - - [Provider Plugins](/it/plugins/sdk-provider-plugins) — crea un provider di modelli - - [SDK Overview](/it/plugins/sdk-overview) — mappa degli import e API di registrazione + Questo è il **riferimento di architettura approfondito**. Per guide pratiche, vedi: + - [Installare e usare i plugin](/it/tools/plugin) — guida per l'utente + - [Per iniziare](/it/plugins/building-plugins) — primo tutorial sui plugin + - [Plugin di canale](/it/plugins/sdk-channel-plugins) — crea un canale di messaggistica + - [Plugin provider](/it/plugins/sdk-provider-plugins) — crea un provider di modelli + - [Panoramica dell'SDK](/it/plugins/sdk-overview) — mappa di importazione e API di registrazione -Questa pagina copre l'architettura interna del sistema di Plugin di OpenClaw. +Questa pagina copre l'architettura interna del sistema di plugin di OpenClaw. -## Modello di capability pubblico +## Modello pubblico delle capacità -Le capability sono il modello pubblico dei **Plugin nativi** all'interno di OpenClaw. Ogni -Plugin nativo di OpenClaw si registra rispetto a uno o più tipi di capability: +Le capacità sono il modello pubblico dei **plugin nativi** all'interno di OpenClaw. Ogni +plugin nativo di OpenClaw si registra rispetto a uno o più tipi di capacità: -| Capability | Metodo di registrazione | Plugin di esempio | -| ---------------------- | ----------------------------------------------- | ------------------------------------ | -| Inferenza testuale | `api.registerProvider(...)` | `openai`, `anthropic` | -| Backend di inferenza CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Voce | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Trascrizione realtime | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Voce realtime | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Comprensione media | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Generazione immagini | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Generazione musicale | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Generazione video | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Recupero web | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Ricerca web | `api.registerWebSearchProvider(...)` | `google` | -| Canale / messaggistica | `api.registerChannel(...)` | `msteams`, `matrix` | +| Capacità | Metodo di registrazione | Esempi di plugin | +| --------------------- | ------------------------------------------------- | ----------------------------------- | +| Inferenza di testo | `api.registerProvider(...)` | `openai`, `anthropic` | +| Backend di inferenza CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Voce | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Trascrizione in tempo reale | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Voce in tempo reale | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Comprensione dei contenuti multimediali | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Generazione di immagini | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Generazione di musica | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Generazione di video | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Recupero web | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Ricerca web | `api.registerWebSearchProvider(...)` | `google` | +| Canale / messaggistica | `api.registerChannel(...)` | `msteams`, `matrix` | -Un Plugin che registra zero capability ma fornisce hook, strumenti o -servizi è un Plugin **legacy solo-hook**. Questo pattern è ancora pienamente supportato. +Un plugin che registra zero capacità ma fornisce hook, strumenti o +servizi è un plugin **legacy solo hook**. Questo modello è ancora pienamente supportato. ### Posizione sulla compatibilità esterna -Il modello di capability è integrato nel core e usato oggi dai Plugin -nativi/inclusi, ma la compatibilità dei Plugin esterni richiede ancora un criterio più rigoroso di “è esportato, quindi è congelato”. +Il modello delle capacità è stato integrato nel core ed è usato oggi dai plugin +bundled/nativi, ma la compatibilità con i plugin esterni richiede ancora un criterio più rigoroso rispetto a "è +esportato, quindi è congelato". Indicazioni attuali: -- **Plugin esterni esistenti:** mantieni funzionanti le integrazioni basate su hook; trattale - come baseline di compatibilità -- **nuovi Plugin nativi/inclusi:** preferisci la registrazione esplicita delle capability rispetto a - reach-in specifici del vendor o a nuovi design solo-hook -- **Plugin esterni che adottano la registrazione di capability:** consentiti, ma considera le - superfici helper specifiche delle capability come in evoluzione salvo che la documentazione non contrassegni esplicitamente +- **plugin esterni esistenti:** mantenere funzionanti le integrazioni basate su hook; trattare + questo come riferimento di base per la compatibilità +- **nuovi plugin bundled/nativi:** preferire la registrazione esplicita delle capacità invece di + accessi specifici del fornitore o di nuovi design solo hook +- **plugin esterni che adottano la registrazione delle capacità:** consentiti, ma trattare le + superfici helper specifiche per capacità come in evoluzione a meno che la documentazione non indichi esplicitamente un contratto come stabile Regola pratica: -- le API di registrazione delle capability sono la direzione prevista -- gli hook legacy restano il percorso più sicuro senza rotture per i Plugin esterni durante +- le API di registrazione delle capacità sono la direzione prevista +- gli hook legacy restano il percorso più sicuro per evitare rotture nei plugin esterni durante la transizione -- i sottopercorsi helper esportati non sono tutti uguali; preferisci il contratto ristretto documentato, - non esportazioni helper incidentali +- i sottopercorsi helper esportati non sono tutti equivalenti; preferire il contratto + ristretto e documentato, non esportazioni helper incidentali -### Forme dei Plugin +### Forme dei plugin -OpenClaw classifica ogni Plugin caricato in una forma in base al suo effettivo +OpenClaw classifica ogni plugin caricato in una forma in base al suo effettivo comportamento di registrazione (non solo ai metadati statici): -- **plain-capability** -- registra esattamente un tipo di capability (per esempio un - Plugin solo-provider come `mistral`) -- **hybrid-capability** -- registra più tipi di capability (per esempio - `openai` possiede inferenza testuale, voce, comprensione media e generazione di immagini) -- **hook-only** -- registra solo hook (tipizzati o personalizzati), nessuna - capability, strumento, comando o servizio +- **plain-capability** -- registra esattamente un tipo di capacità (per esempio un + plugin solo provider come `mistral`) +- **hybrid-capability** -- registra più tipi di capacità (per esempio + `openai` gestisce inferenza di testo, voce, comprensione dei contenuti multimediali e generazione + di immagini) +- **hook-only** -- registra solo hook (tipizzati o personalizzati), nessuna capacità, + strumento, comando o servizio - **non-capability** -- registra strumenti, comandi, servizi o route ma nessuna - capability + capacità -Usa `openclaw plugins inspect ` per vedere la forma di un Plugin e la sua suddivisione delle capability. Consulta [CLI reference](/cli/plugins#inspect) per i dettagli. +Usa `openclaw plugins inspect ` per vedere la forma di un plugin e la suddivisione +delle capacità. Per i dettagli, vedi il [riferimento CLI](/cli/plugins#inspect). ### Hook legacy -L'hook `before_agent_start` resta supportato come percorso di compatibilità per -i Plugin solo-hook. Plugin reali legacy dipendono ancora da esso. +L'hook `before_agent_start` resta supportato come percorso di compatibilità per i +plugin solo hook. Plugin legacy reali dipendono ancora da esso. Direzione: - mantenerlo funzionante - documentarlo come legacy -- preferire `before_model_resolve` per il lavoro di override modello/provider +- preferire `before_model_resolve` per il lavoro di override di modello/provider - preferire `before_prompt_build` per il lavoro di mutazione del prompt -- rimuoverlo solo dopo che l'uso reale sarà diminuito e la copertura delle fixture avrà dimostrato la sicurezza della migrazione +- rimuoverlo solo dopo che l'utilizzo reale sarà diminuito e la copertura dei fixture dimostrerà la sicurezza della migrazione ### Segnali di compatibilità @@ -111,79 +114,82 @@ una di queste etichette: | Segnale | Significato | | ------------------------- | ------------------------------------------------------------ | -| **config valid** | La configurazione viene analizzata correttamente e i Plugin vengono risolti | -| **compatibility advisory** | Il Plugin usa un pattern supportato ma più vecchio (ad es. `hook-only`) | -| **legacy warning** | Il Plugin usa `before_agent_start`, che è deprecato | -| **hard error** | La configurazione non è valida o il Plugin non è stato caricato | +| **config valid** | La configurazione viene analizzata correttamente e i plugin vengono risolti | +| **compatibility advisory** | Il plugin usa un modello supportato ma più vecchio (ad es. `hook-only`) | +| **legacy warning** | Il plugin usa `before_agent_start`, che è deprecato | +| **hard error** | La configurazione non è valida o il plugin non è riuscito a caricarsi | -Né `hook-only` né `before_agent_start` romperanno oggi il tuo Plugin -- -`hook-only` è solo informativo, e `before_agent_start` genera soltanto un avviso. Questi +Né `hook-only` né `before_agent_start` romperanno il tuo plugin oggi -- +`hook-only` è informativo, e `before_agent_start` genera solo un avviso. Questi segnali compaiono anche in `openclaw status --all` e `openclaw plugins doctor`. ## Panoramica dell'architettura -Il sistema di Plugin di OpenClaw ha quattro livelli: +Il sistema di plugin di OpenClaw ha quattro livelli: -1. **Manifest + discovery** - OpenClaw trova i Plugin candidati dai percorsi configurati, dalle radici del workspace, - dalle radici globali delle estensioni e dalle estensioni incluse. La discovery legge prima - i manifest nativi `openclaw.plugin.json` più i manifest dei bundle supportati. +1. **Manifest + individuazione** + OpenClaw trova i plugin candidati a partire dai percorsi configurati, dalle radici dello spazio di lavoro, + dalle radici globali delle estensioni e dalle estensioni bundled. L'individuazione legge prima i manifest nativi + `openclaw.plugin.json` insieme ai manifest bundle supportati. 2. **Abilitazione + validazione** - Il core decide se un Plugin scoperto è abilitato, disabilitato, bloccato o + Il core decide se un plugin individuato è abilitato, disabilitato, bloccato o selezionato per uno slot esclusivo come la memoria. -3. **Caricamento runtime** - I Plugin nativi di OpenClaw vengono caricati in-process tramite jiti e registrano - capability in un registro centrale. I bundle compatibili vengono normalizzati in - record di registro senza importare codice runtime. -4. **Consumo della superficie** - Il resto di OpenClaw legge il registro per esporre strumenti, canali, configurazione dei provider, +3. **Caricamento a runtime** + I plugin nativi di OpenClaw vengono caricati in-process tramite jiti e registrano + le capacità in un registro centrale. I bundle compatibili vengono normalizzati in + record di registro senza importare codice di runtime. +4. **Utilizzo delle superfici** + Il resto di OpenClaw legge il registro per esporre strumenti, canali, configurazione del provider, hook, route HTTP, comandi CLI e servizi. -Per la CLI dei Plugin in particolare, la discovery dei comandi root è divisa in due fasi: +In particolare per la CLI dei plugin, l'individuazione dei comandi root è divisa in due fasi: - i metadati in fase di parsing provengono da `registerCli(..., { descriptors: [...] })` -- il vero modulo CLI del Plugin può restare lazy e registrarsi al primo richiamo +- il vero modulo CLI del plugin può restare lazy e registrarsi alla prima invocazione -Questo mantiene il codice CLI posseduto dal Plugin all'interno del Plugin stesso, consentendo comunque a OpenClaw +Questo mantiene il codice CLI posseduto dal plugin all'interno del plugin, consentendo comunque a OpenClaw di riservare i nomi dei comandi root prima del parsing. Il confine di progettazione importante: -- discovery + validazione della configurazione dovrebbero funzionare a partire dai **metadati di manifest/schema** - senza eseguire codice del Plugin -- il comportamento runtime nativo proviene dal percorso `register(api)` del modulo del Plugin +- l'individuazione + la validazione della configurazione dovrebbero funzionare a partire da **metadati di manifest/schema** + senza eseguire codice del plugin +- il comportamento nativo a runtime proviene dal percorso `register(api)` del modulo del plugin -Questa separazione consente a OpenClaw di validare la configurazione, spiegare i Plugin mancanti/disabilitati e -costruire suggerimenti UI/schema prima che il runtime completo sia attivo. +Questa divisione consente a OpenClaw di validare la configurazione, spiegare i plugin mancanti/disabilitati e +costruire suggerimenti per UI/schema prima che il runtime completo sia attivo. -### Plugin di canale e lo strumento message condiviso +### Plugin di canale e strumento `message` condiviso -I Plugin di canale non devono registrare uno strumento separato di invio/modifica/reazione per +I plugin di canale non devono registrare uno strumento separato di invio/modifica/reazione per le normali azioni di chat. OpenClaw mantiene un unico strumento `message` condiviso nel core, e -i Plugin di canale possiedono la discovery e l'esecuzione specifiche del canale dietro di esso. +i plugin di canale gestiscono l'individuazione e l'esecuzione specifiche del canale dietro di esso. Il confine attuale è: -- il core possiede l'host condiviso dello strumento `message`, il wiring del prompt, il - bookkeeping di sessione/thread e il dispatch di esecuzione -- i Plugin di canale possiedono la discovery delle azioni con scope, la discovery delle capability e qualsiasi frammento di schema specifico del canale -- i Plugin di canale possiedono la grammatica di conversazione di sessione specifica del provider, ad esempio - come gli ID di conversazione codificano gli ID dei thread o ereditano da conversazioni padre -- i Plugin di canale eseguono l'azione finale tramite il proprio adapter di azione +- il core gestisce l'host condiviso dello strumento `message`, il collegamento al prompt, la gestione di sessione/thread + e il dispatch dell'esecuzione +- i plugin di canale gestiscono l'individuazione delle azioni con ambito, l'individuazione delle capacità + ed eventuali frammenti di schema specifici del canale +- i plugin di canale gestiscono la grammatica di conversazione della sessione specifica del provider, ad esempio + il modo in cui gli ID conversazione codificano gli ID thread o ereditano dalle conversazioni padre +- i plugin di canale eseguono l'azione finale tramite il loro adapter di azione -Per i Plugin di canale, la superficie SDK è -`ChannelMessageActionAdapter.describeMessageTool(...)`. Questa chiamata di discovery unificata consente a un Plugin di restituire insieme le proprie azioni visibili, capability e contributi allo schema, così questi elementi non divergono. +Per i plugin di canale, la superficie SDK è +`ChannelMessageActionAdapter.describeMessageTool(...)`. Questa chiamata unificata di individuazione +consente a un plugin di restituire insieme le sue azioni visibili, capacità e contributi +di schema, così che questi elementi non divergano. -Quando un parametro dello strumento message specifico del canale trasporta una sorgente media come -un percorso locale o un URL media remoto, il Plugin dovrebbe anche restituire -`mediaSourceParams` da `describeMessageTool(...)`. Il core usa questo elenco esplicito -per applicare la normalizzazione dei percorsi sandbox e i suggerimenti di accesso ai media in uscita -senza codificare rigidamente nomi di parametri posseduti dal Plugin. -Preferisci mappe con scope per azione, non un unico elenco piatto per l'intero canale, così un -parametro media solo-profilo non viene normalizzato su azioni non correlate come +Quando un parametro dello strumento message specifico del canale contiene una sorgente multimediale come +un percorso locale o un URL remoto di contenuto multimediale, il plugin dovrebbe anche restituire +`mediaSourceParams` da `describeMessageTool(...)`. Il core usa questo elenco esplicito per applicare +la normalizzazione dei percorsi sandbox e gli hint di accesso ai contenuti multimediali in uscita +senza codificare rigidamente nomi di parametri posseduti dal plugin. +Preferire mappe con ambito di azione, non un unico elenco piatto a livello di canale, in modo che un +parametro multimediale solo profilo non venga normalizzato su azioni non correlate come `send`. -Il core passa lo scope runtime in quel passaggio di discovery. I campi importanti includono: +Il core passa l'ambito di runtime in questo passaggio di individuazione. I campi importanti includono: - `accountId` - `currentChannelId` @@ -192,115 +198,123 @@ Il core passa lo scope runtime in quel passaggio di discovery. I campi important - `sessionKey` - `sessionId` - `agentId` -- `requesterSenderId` in ingresso attendibile +- `requesterSenderId` inbound attendibile -Questo conta per i Plugin sensibili al contesto. Un canale può nascondere o esporre -azioni message in base all'account attivo, alla stanza/thread/message corrente o -all'identità attendibile del richiedente senza codificare rami specifici del canale nello strumento `message` del core. +Questo è importante per i plugin sensibili al contesto. Un canale può nascondere o esporre +azioni di messaggio in base all'account attivo, alla stanza/thread/messaggio corrente o +all'identità attendibile del richiedente, senza codificare rigidamente rami specifici del canale +nello strumento `message` del core. -Per questo le modifiche di routing dell'embedded-runner restano lavoro del Plugin: il runner è -responsabile dell'inoltro dell'identità corrente di chat/sessione nel confine di discovery del Plugin così lo strumento `message` condiviso espone la giusta superficie posseduta dal canale per il turno corrente. +Per questo motivo, le modifiche di instradamento dell'embedded runner restano lavoro del plugin: il runner è +responsabile di inoltrare l'identità corrente di chat/sessione nel confine di individuazione del plugin affinché +lo strumento `message` condiviso esponga la superficie corretta, posseduta dal canale, per il turno corrente. -Per gli helper di esecuzione posseduti dal canale, i Plugin inclusi dovrebbero mantenere il runtime di esecuzione -all'interno dei propri moduli di estensione. Il core non possiede più i runtime di azione message di Discord, +Per gli helper di esecuzione posseduti dal canale, i plugin bundled dovrebbero mantenere il runtime di esecuzione +all'interno dei propri moduli di estensione. Il core non gestisce più i runtime di azione dei messaggi di Discord, Slack, Telegram o WhatsApp sotto `src/agents/tools`. -Non pubblichiamo sottopercorsi separati `plugin-sdk/*-action-runtime`, e i Plugin inclusi -dovrebbero importare direttamente il proprio codice runtime locale dai moduli -posseduti dalla loro estensione. +Non pubblichiamo sottopercorsi separati `plugin-sdk/*-action-runtime`, e i plugin bundled +dovrebbero importare direttamente il proprio codice di runtime locale dai loro +moduli posseduti dall'estensione. -Lo stesso confine si applica in generale alle seam SDK nominate per provider: il core non dovrebbe +Lo stesso confine si applica in generale ai seam SDK con nome del provider: il core non dovrebbe importare barrel di convenienza specifici del canale per estensioni Slack, Discord, Signal, -WhatsApp o simili. Se il core ha bisogno di un comportamento, deve o consumare il barrel `api.ts` / `runtime-api.ts` del Plugin incluso o promuovere l'esigenza a una capability generica ristretta nello SDK condiviso. +WhatsApp o simili. Se il core ha bisogno di un comportamento, dovrebbe o consumare il +barrel `api.ts` / `runtime-api.ts` del plugin bundled oppure promuovere la necessità +a una capacità generica e ristretta nell'SDK condiviso. Per i sondaggi in particolare, esistono due percorsi di esecuzione: -- `outbound.sendPoll` è la baseline condivisa per i canali che rientrano nel modello - comune di sondaggio -- `actions.handleAction("poll")` è il percorso preferito per semantiche di sondaggio specifiche del canale o parametri extra del sondaggio +- `outbound.sendPoll` è il riferimento condiviso per i canali che rientrano nel modello comune di sondaggio +- `actions.handleAction("poll")` è il percorso preferito per semantiche di sondaggio specifiche del canale o parametri di sondaggio aggiuntivi -Il core ora rinvia il parsing condiviso dei sondaggi fino a dopo che il dispatch del sondaggio del Plugin ha rifiutato -l'azione, così i gestori di sondaggi posseduti dal Plugin possono accettare campi di sondaggio specifici del canale senza essere bloccati prima dal parser generico dei sondaggi. +Il core ora rimanda il parsing condiviso dei sondaggi fino a dopo che il dispatch del sondaggio del plugin +rifiuta l'azione, in modo che gli handler di sondaggi posseduti dal plugin possano accettare campi +di sondaggio specifici del canale senza essere bloccati prima dal parser di sondaggi generico. -Consulta [Load pipeline](#load-pipeline) per la sequenza di avvio completa. +Vedi [Pipeline di caricamento](#load-pipeline) per la sequenza completa di avvio. -## Modello di ownership delle capability +## Modello di proprietà delle capacità -OpenClaw tratta un Plugin nativo come il confine di ownership per una **azienda** o una -**funzionalità**, non come un contenitore eterogeneo di integrazioni non correlate. +OpenClaw tratta un plugin nativo come confine di proprietà per una **azienda** o una +**funzionalità**, non come un insieme eterogeneo di integrazioni non correlate. Questo significa: -- un Plugin aziendale dovrebbe di norma possedere tutte le superfici OpenClaw rivolte a quell'azienda -- un Plugin funzionale dovrebbe di norma possedere l'intera superficie della funzionalità che introduce -- i canali dovrebbero consumare capability condivise del core invece di reimplementare - ad hoc il comportamento del provider +- un plugin aziendale dovrebbe di norma possedere tutte le superfici di OpenClaw rivolte a quella stessa azienda +- un plugin di funzionalità dovrebbe di norma possedere l'intera superficie della funzionalità che introduce +- i canali dovrebbero consumare capacità core condivise invece di reimplementare in modo ad hoc il comportamento del provider Esempi: -- il plugin `openai` incluso possiede il comportamento del provider di modelli OpenAI e il comportamento OpenAI per voce + realtime-voice + comprensione media + generazione di immagini -- il plugin `elevenlabs` incluso possiede il comportamento voce di ElevenLabs -- il plugin `microsoft` incluso possiede il comportamento voce di Microsoft -- il plugin `google` incluso possiede il comportamento del provider di modelli Google più il comportamento Google per comprensione media + generazione di immagini + ricerca web -- il plugin `firecrawl` incluso possiede il comportamento web-fetch di Firecrawl -- i plugin inclusi `minimax`, `mistral`, `moonshot` e `zai` possiedono i loro backend di comprensione media -- il plugin `qwen` incluso possiede il comportamento del provider testuale Qwen più il comportamento di comprensione media e generazione video -- il plugin `voice-call` è un plugin funzionale: possiede transport di chiamata, strumenti, - CLI, route e bridging dei media stream Twilio, ma consuma capability condivise di voce - più realtime-transcription e realtime-voice invece di importare direttamente i plugin vendor +- il plugin bundled `openai` possiede il comportamento del provider di modelli OpenAI e il comportamento OpenAI per + voce + voce in tempo reale + comprensione dei contenuti multimediali + generazione di immagini +- il plugin bundled `elevenlabs` possiede il comportamento della voce ElevenLabs +- il plugin bundled `microsoft` possiede il comportamento della voce Microsoft +- il plugin bundled `google` possiede il comportamento del provider di modelli Google più il comportamento Google per + comprensione dei contenuti multimediali + generazione di immagini + ricerca web +- il plugin bundled `firecrawl` possiede il comportamento di recupero web Firecrawl +- i plugin bundled `minimax`, `mistral`, `moonshot` e `zai` possiedono i loro + backend di comprensione dei contenuti multimediali +- il plugin bundled `qwen` possiede il comportamento del provider di testo Qwen più + il comportamento di comprensione dei contenuti multimediali e generazione di video +- il plugin `voice-call` è un plugin di funzionalità: possiede trasporto delle chiamate, strumenti, + CLI, route e bridging del media-stream Twilio, ma consuma le capacità condivise di voce + più trascrizione in tempo reale e voce in tempo reale invece di + importare direttamente plugin di fornitori -Lo stato finale desiderato è: +Lo stato finale previsto è: -- OpenAI vive in un solo plugin anche se comprende modelli testuali, voce, immagini e - futuro video -- un altro vendor può fare lo stesso per la propria area di superficie -- i canali non si preoccupano di quale plugin vendor possieda il provider; consumano il - contratto di capability condiviso esposto dal core +- OpenAI vive in un unico plugin anche se copre modelli di testo, voce, immagini e + video futuri +- un altro fornitore può fare lo stesso per la propria area di superficie +- i canali non si preoccupano di quale plugin del fornitore possieda il provider; consumano il + contratto di capacità condiviso esposto dal core Questa è la distinzione chiave: -- **plugin** = confine di ownership +- **plugin** = confine di proprietà - **capability** = contratto del core che più plugin possono implementare o consumare Quindi, se OpenClaw aggiunge un nuovo dominio come il video, la prima domanda non è -“quale provider dovrebbe codificare rigidamente la gestione del video?” La prima domanda è “qual è -il contratto di capability video del core?” Una volta che quel contratto esiste, i plugin vendor -possono registrarsi rispetto a esso e i plugin canale/funzionalità possono consumarlo. +"quale provider dovrebbe codificare rigidamente la gestione del video?" La prima domanda è "qual è +il contratto di capacità video del core?" Una volta che quel contratto esiste, i plugin dei fornitori +possono registrarsi rispetto a esso e i plugin di canale/funzionalità possono consumarlo. -Se la capability non esiste ancora, la mossa giusta di solito è: +Se la capacità non esiste ancora, la mossa giusta di solito è: -1. definire la capability mancante nel core -2. esporla tramite l'API/runtime del plugin in modo tipizzato -3. collegare canali/funzionalità a quella capability -4. lasciare che i plugin vendor registrino le implementazioni +1. definire la capacità mancante nel core +2. esporla attraverso l'API/runtime del plugin in modo tipizzato +3. collegare canali/funzionalità a quella capacità +4. lasciare che i plugin dei fornitori registrino le implementazioni -Questo mantiene esplicita l'ownership evitando al contempo un comportamento del core che dipenda da un -singolo vendor o da un percorso di codice specifico per un singolo plugin. +Questo mantiene esplicita la proprietà evitando al tempo stesso un comportamento del core che dipende da un +singolo fornitore o da un percorso di codice una tantum specifico del plugin. -### Stratificazione delle capability +### Stratificazione delle capacità Usa questo modello mentale quando decidi dove deve stare il codice: -- **livello capability del core**: orchestrazione condivisa, policy, fallback, regole di - merge della configurazione, semantica di consegna e contratti tipizzati -- **livello plugin vendor**: API specifiche del vendor, autenticazione, cataloghi di modelli, sintesi vocale, - generazione di immagini, futuri backend video, endpoint di usage -- **livello plugin canale/funzionalità**: integrazione Slack/Discord/voice-call/ecc. - che consuma capability del core e le presenta su una superficie +- **livello di capacità del core**: orchestrazione condivisa, policy, fallback, regole di + unione della configurazione, semantica di consegna e contratti tipizzati +- **livello del plugin del fornitore**: API specifiche del fornitore, autenticazione, cataloghi di modelli, sintesi vocale, + generazione di immagini, backend video futuri, endpoint di utilizzo +- **livello del plugin di canale/funzionalità**: integrazione Slack/Discord/voice-call/ecc. + che consuma le capacità del core e le presenta su una superficie Per esempio, il TTS segue questa forma: -- il core possiede la policy TTS al momento della risposta, l'ordine di fallback, le preferenze e la consegna al canale +- il core possiede la policy TTS al momento della risposta, l'ordine di fallback, le preferenze e la consegna sul canale - `openai`, `elevenlabs` e `microsoft` possiedono le implementazioni di sintesi -- `voice-call` consuma l'helper runtime TTS della telefonia +- `voice-call` consuma l'helper di runtime TTS per la telefonia -Lo stesso pattern dovrebbe essere preferito per le capability future. +Lo stesso schema dovrebbe essere preferito per le capacità future. -### Esempio di plugin aziendale multi-capability +### Esempio di plugin aziendale multi-capacità -Un plugin aziendale dovrebbe risultare coeso dall'esterno. Se OpenClaw ha contratti condivisi -per modelli, voce, trascrizione realtime, voce realtime, comprensione media, -generazione di immagini, generazione video, web fetch e ricerca web, -un vendor può possedere tutte le sue superfici in un unico posto: +Un plugin aziendale dovrebbe apparire coeso dall'esterno. Se OpenClaw ha contratti condivisi +per modelli, voce, trascrizione in tempo reale, voce in tempo reale, comprensione dei contenuti multimediali, +generazione di immagini, generazione di video, recupero web e ricerca web, +un fornitore può possedere tutte le sue superfici in un unico posto: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -356,195 +370,197 @@ export default plugin; Ciò che conta non sono i nomi esatti degli helper. Conta la forma: -- un plugin possiede la superficie del vendor -- il core continua a possedere i contratti di capability -- i plugin canale e funzionalità consumano helper `api.runtime.*`, non codice vendor -- i test di contratto possono verificare che il plugin abbia registrato le capability che +- un plugin possiede la superficie del fornitore +- il core continua a possedere i contratti di capacità +- i plugin di canale e di funzionalità consumano gli helper `api.runtime.*`, non il codice del fornitore +- i test di contratto possono verificare che il plugin abbia registrato le capacità che dichiara di possedere -### Esempio di capability: comprensione video +### Esempio di capacità: comprensione video OpenClaw tratta già la comprensione di immagini/audio/video come un'unica -capability condivisa. Lo stesso modello di ownership si applica anche qui: +capacità condivisa. Lo stesso modello di proprietà si applica anche qui: -1. il core definisce il contratto di comprensione media -2. i plugin vendor registrano `describeImage`, `transcribeAudio` e - `describeVideo` secondo necessità -3. i plugin canale e funzionalità consumano il comportamento condiviso del core invece di - collegarsi direttamente al codice vendor +1. il core definisce il contratto di comprensione dei contenuti multimediali +2. i plugin dei fornitori registrano `describeImage`, `transcribeAudio` e + `describeVideo` a seconda dei casi +3. i plugin di canale e di funzionalità consumano il comportamento condiviso del core invece di + collegarsi direttamente al codice del fornitore -Questo evita di incorporare nel core le assunzioni video di un solo provider. Il plugin possiede -la superficie vendor; il core possiede il contratto di capability e il comportamento di fallback. +Questo evita di incorporare nel core le assunzioni video di un singolo fornitore. Il plugin possiede +la superficie del fornitore; il core possiede il contratto di capacità e il comportamento di fallback. -La generazione video usa già la stessa sequenza: il core possiede il contratto di -capability tipizzato e l'helper runtime, e i plugin vendor registrano +La generazione video usa già questa stessa sequenza: il core possiede il contratto di capacità +tipizzato e l'helper di runtime, e i plugin dei fornitori registrano implementazioni `api.registerVideoGenerationProvider(...)` rispetto a esso. -Ti serve una checklist concreta di rollout? Consulta +Hai bisogno di una checklist concreta di rollout? Vedi [Capability Cookbook](/it/plugins/architecture). ## Contratti e applicazione -La superficie API dei plugin è intenzionalmente tipizzata e centralizzata in +La superficie API del plugin è intenzionalmente tipizzata e centralizzata in `OpenClawPluginApi`. Questo contratto definisce i punti di registrazione supportati e -gli helper runtime su cui un plugin può fare affidamento. +gli helper di runtime su cui un plugin può fare affidamento. -Perché questo è importante: +Perché è importante: -- gli autori di plugin ottengono un unico standard interno stabile -- il core può rifiutare ownership duplicate come due plugin che registrano lo stesso - ID provider -- l'avvio può esporre diagnostica utilizzabile per registrazioni malformate -- i test di contratto possono applicare l'ownership dei plugin inclusi e prevenire derive silenziose +- gli autori di plugin hanno un unico standard interno stabile +- il core può rifiutare proprietà duplicate, ad esempio due plugin che registrano lo stesso + id provider +- l'avvio può mostrare diagnostiche utili per registrazioni malformate +- i test di contratto possono imporre la proprietà dei plugin bundled ed evitare derive silenziose -Esistono due livelli di applicazione: +Ci sono due livelli di applicazione: -1. **applicazione della registrazione runtime** - Il registro dei plugin valida le registrazioni mentre i plugin si caricano. Esempi: - ID provider duplicati, ID provider voce duplicati e registrazioni malformate - producono diagnostica dei plugin invece di comportamento indefinito. +1. **applicazione della registrazione a runtime** + Il registro dei plugin convalida le registrazioni mentre i plugin vengono caricati. Esempi: + id provider duplicati, id provider voce duplicati e registrazioni + malformate producono diagnostiche del plugin invece di un comportamento indefinito. 2. **test di contratto** - I plugin inclusi vengono acquisiti nei registri di contratto durante le esecuzioni di test così - OpenClaw può verificare esplicitamente l'ownership. Oggi questo è usato per provider di modelli, - provider voce, provider di ricerca web e ownership delle registrazioni incluse. + I plugin bundled vengono acquisiti nei registri di contratto durante le esecuzioni di test, così + OpenClaw può verificare esplicitamente la proprietà. Oggi questo è usato per i provider di modelli, + i provider voce, i provider di ricerca web e la proprietà di registrazione dei plugin bundled. -L'effetto pratico è che OpenClaw conosce, in anticipo, quale plugin possiede quale -superficie. Questo consente al core e ai canali di comporsi senza attriti perché l'ownership è +L'effetto pratico è che OpenClaw sa, fin da subito, quale plugin possiede quale +superficie. Questo consente al core e ai canali di comporsi senza attriti perché la proprietà è dichiarata, tipizzata e verificabile invece che implicita. -### Cosa deve stare in un contratto +### Cosa appartiene a un contratto -I buoni contratti dei plugin sono: +I buoni contratti di plugin sono: - tipizzati - piccoli -- specifici della capability +- specifici per capacità - posseduti dal core - riutilizzabili da più plugin -- consumabili da canali/funzionalità senza conoscenza del vendor +- consumabili da canali/funzionalità senza conoscenza del fornitore -I cattivi contratti dei plugin sono: +I cattivi contratti di plugin sono: -- policy specifiche del vendor nascoste nel core -- escape hatch una tantum di plugin che aggirano il registro -- codice del canale che entra direttamente in un'implementazione vendor -- oggetti runtime ad hoc che non fanno parte di `OpenClawPluginApi` o +- policy specifiche del fornitore nascoste nel core +- vie di fuga una tantum per plugin che aggirano il registro +- codice del canale che raggiunge direttamente un'implementazione del fornitore +- oggetti di runtime ad hoc che non fanno parte di `OpenClawPluginApi` o `api.runtime` -In caso di dubbio, alza il livello di astrazione: definisci prima la capability, poi -lascia che i plugin si innestino su di essa. +In caso di dubbio, aumenta il livello di astrazione: definisci prima la capacità, poi +lascia che i plugin vi si colleghino. ## Modello di esecuzione I plugin nativi di OpenClaw vengono eseguiti **in-process** con il Gateway. Non sono -sandboxati. Un plugin nativo caricato ha lo stesso confine di fiducia a livello di processo del codice core. +sandboxed. Un plugin nativo caricato ha lo stesso confine di trust a livello di processo del +codice core. Implicazioni: -- un plugin nativo può registrare strumenti, gestori di rete, hook e servizi -- un bug in un plugin nativo può mandare in crash o destabilizzare il gateway -- un plugin nativo malevolo equivale a esecuzione arbitraria di codice all'interno del processo OpenClaw +- un plugin nativo può registrare strumenti, handler di rete, hook e servizi +- un bug in un plugin nativo può causare il crash o destabilizzare il gateway +- un plugin nativo malevolo equivale a esecuzione arbitraria di codice all'interno + del processo OpenClaw I bundle compatibili sono più sicuri per impostazione predefinita perché OpenClaw attualmente li tratta -come pacchetti di metadati/contenuti. Nelle release attuali, questo significa per lo più -Skills inclusi. +come pacchetti di metadati/contenuti. Nelle release attuali, questo significa soprattutto +Skills bundled. -Usa allowlist e percorsi espliciti di installazione/caricamento per i plugin non inclusi. Tratta -i plugin del workspace come codice di sviluppo, non come impostazione predefinita di produzione. +Usa allowlist e percorsi espliciti di installazione/caricamento per i plugin non bundled. Tratta +i plugin dello spazio di lavoro come codice in fase di sviluppo, non come impostazioni predefinite di produzione. -Per i nomi dei pacchetti workspace inclusi, mantieni l'ID plugin ancorato al nome npm: +Per i nomi dei pacchetti workspace bundled, mantieni l'id del plugin ancorato al nome npm: `@openclaw/` per impostazione predefinita, oppure un suffisso tipizzato approvato come `-provider`, `-plugin`, `-speech`, `-sandbox` o `-media-understanding` quando -il pacchetto espone intenzionalmente un ruolo plugin più ristretto. +il pacchetto espone intenzionalmente un ruolo di plugin più ristretto. -Nota importante sulla fiducia: +Nota importante sul trust: -- `plugins.allow` accorda fiducia agli **ID plugin**, non alla provenienza della sorgente. -- Un plugin workspace con lo stesso ID di un plugin incluso ombreggia intenzionalmente - la copia inclusa quando quel plugin workspace è abilitato/in allowlist. -- Questo è normale e utile per sviluppo locale, test di patch e hotfix. +- `plugins.allow` si fida degli **id plugin**, non della provenienza della sorgente. +- Un plugin workspace con lo stesso id di un plugin bundled oscura intenzionalmente + la copia bundled quando quel plugin workspace è abilitato/in allowlist. +- Questo è normale e utile per lo sviluppo locale, i test di patch e gli hotfix. ## Confine di esportazione -OpenClaw esporta capability, non comodità di implementazione. +OpenClaw esporta capacità, non elementi di comodo dell'implementazione. -Mantieni pubblica la registrazione delle capability. Riduci le esportazioni helper non contrattuali: +Mantieni pubblica la registrazione delle capacità. Riduci le esportazioni helper non contrattuali: -- sottopercorsi helper specifici di plugin inclusi -- sottopercorsi di plumbing runtime non destinati a essere API pubbliche -- helper di convenienza specifici del vendor +- sottopercorsi helper specifici dei plugin bundled +- sottopercorsi di plumbing del runtime non destinati a essere API pubbliche +- helper di comodo specifici del fornitore - helper di setup/onboarding che sono dettagli di implementazione -Alcuni sottopercorsi helper dei plugin inclusi restano ancora nella mappa di esportazione SDK generata per compatibilità e manutenzione dei plugin inclusi. Esempi attuali includono +Alcuni sottopercorsi helper dei plugin bundled restano ancora nella mappa di esportazione +SDK generata per compatibilità e manutenzione dei plugin bundled. Esempi attuali includono `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` e diverse seam `plugin-sdk/matrix*`. Trattali come -esportazioni riservate di dettaglio implementativo, non come pattern SDK raccomandato per +`plugin-sdk/zalo-setup` e diversi seam `plugin-sdk/matrix*`. Trattali come +esportazioni riservate di dettaglio implementativo, non come schema SDK consigliato per nuovi plugin di terze parti. ## Pipeline di caricamento -All'avvio, OpenClaw esegue approssimativamente questo: +All'avvio, OpenClaw fa approssimativamente questo: -1. scopre le radici candidate dei plugin -2. legge i manifest nativi o dei bundle compatibili e i metadati dei pacchetti +1. individua le radici candidate dei plugin +2. legge i manifest nativi o i manifest dei bundle compatibili e i metadati del pacchetto 3. rifiuta i candidati non sicuri 4. normalizza la configurazione dei plugin (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. decide l'abilitazione per ciascun candidato +5. decide l'abilitazione per ogni candidato 6. carica i moduli nativi abilitati tramite jiti -7. chiama gli hook nativi `register(api)` (oppure `activate(api)` — un alias legacy) e raccoglie le registrazioni nel registro dei plugin -8. espone il registro alle superfici di comandi/runtime +7. chiama gli hook nativi `register(api)` (o `activate(api)` — un alias legacy) e raccoglie le registrazioni nel registro dei plugin +8. espone il registro ai comandi/alle superfici di runtime -`activate` è un alias legacy di `register` — il loader risolve ciò che è presente (`def.register ?? def.activate`) e lo chiama nello stesso punto. Tutti i plugin inclusi usano `register`; per i nuovi plugin preferisci `register`. +`activate` è un alias legacy per `register` — il loader risolve quello presente (`def.register ?? def.activate`) e lo chiama nello stesso punto. Tutti i plugin bundled usano `register`; per i nuovi plugin, preferisci `register`. -I gate di sicurezza avvengono **prima** dell'esecuzione runtime. I candidati vengono bloccati -quando l'entry esce dalla radice del plugin, il percorso è scrivibile da tutti, oppure la -ownership del percorso appare sospetta per i plugin non inclusi. +I gate di sicurezza avvengono **prima** dell'esecuzione a runtime. I candidati vengono bloccati +quando l'entry esce dalla root del plugin, il percorso è scrivibile da chiunque, oppure la proprietà del percorso appare sospetta per plugin non bundled. ### Comportamento manifest-first -Il manifest è la fonte di riferimento del control plane. OpenClaw lo usa per: +Il manifest è la fonte di verità del control plane. OpenClaw lo usa per: - identificare il plugin -- scoprire canali/Skills/schema di configurazione dichiarati o capability del bundle -- validare `plugins.entries..config` -- arricchire etichette/placeholder della UI di controllo +- individuare canali/Skills/schema di configurazione dichiarati o capacità del bundle +- convalidare `plugins.entries..config` +- arricchire etichette/segnaposto della Control UI - mostrare metadati di installazione/catalogo - preservare descrittori economici di attivazione e setup senza caricare il runtime del plugin -Per i plugin nativi, il modulo runtime è la parte di data plane. Registra -il comportamento reale come hook, strumenti, comandi o flussi provider. +Per i plugin nativi, il modulo di runtime è la parte data-plane. Registra il +comportamento effettivo come hook, strumenti, comandi o flussi del provider. I blocchi opzionali `activation` e `setup` del manifest restano nel control plane. -Sono descrittori solo-metadati per la pianificazione dell'attivazione e la discovery del setup; -non sostituiscono la registrazione runtime, `register(...)` o `setupEntry`. -I primi consumer di attivazione live ora usano suggerimenti di comandi, canali e provider del manifest +Sono descrittori solo metadati per la pianificazione dell'attivazione e l'individuazione del setup; +non sostituiscono la registrazione a runtime, `register(...)` o `setupEntry`. +I primi consumer di attivazione live ora usano gli hint di manifest per comandi, canali e provider per restringere il caricamento dei plugin prima della materializzazione più ampia del registro: -- il caricamento CLI si restringe ai plugin che possiedono il comando primario richiesto -- la risoluzione di setup/plugin del canale si restringe ai plugin che possiedono l'ID - canale richiesto -- la risoluzione esplicita di setup/runtime del provider si restringe ai plugin che possiedono - l'ID provider richiesto +- il caricamento della CLI si restringe ai plugin che possiedono il comando primario richiesto +- la risoluzione del setup/plugin del canale si restringe ai plugin che possiedono l'id + del canale richiesto +- la risoluzione esplicita del setup/runtime del provider si restringe ai plugin che possiedono l' + id provider richiesto -La discovery del setup ora preferisce ID posseduti dai descrittori come `setup.providers` e -`setup.cliBackends` per restringere i plugin candidati prima di ripiegare su -`setup-api` per i plugin che hanno ancora bisogno di hook runtime in fase di setup. Se più di -un plugin scoperto rivendica lo stesso ID normalizzato di provider setup o backend CLI, -la ricerca del setup rifiuta l'owner ambiguo invece di affidarsi all'ordine di discovery. +L'individuazione del setup ora preferisce gli id posseduti dai descrittori come `setup.providers` e +`setup.cliBackends` per restringere i plugin candidati prima di ricorrere a +`setup-api` per i plugin che richiedono ancora hook di runtime in fase di setup. Se più di +un plugin individuato rivendica lo stesso id normalizzato di provider di setup o backend CLI, +la ricerca del setup rifiuta il proprietario ambiguo invece di basarsi sull'ordine di individuazione. ### Cosa mette in cache il loader OpenClaw mantiene brevi cache in-process per: -- risultati della discovery +- risultati di individuazione - dati del registro dei manifest - registri dei plugin caricati -Queste cache riducono l'avvio bursty e il costo dei comandi ripetuti. È sicuro -considerarle cache di prestazioni a breve durata, non persistenza. +Queste cache riducono i picchi all'avvio e l'overhead dei comandi ripetuti. È corretto +considerarle come cache di prestazioni a breve durata, non come persistenza. Nota sulle prestazioni: @@ -555,7 +571,7 @@ Nota sulle prestazioni: ## Modello di registro -I plugin caricati non mutano direttamente globali core casuali. Si registrano in un +I plugin caricati non mutano direttamente variabili globali casuali del core. Si registrano in un registro centrale dei plugin. Il registro tiene traccia di: @@ -565,26 +581,26 @@ Il registro tiene traccia di: - hook legacy e hook tipizzati - canali - provider -- gestori RPC del Gateway +- handler RPC del Gateway - route HTTP - registrar CLI - servizi in background - comandi posseduti dal plugin -Le funzionalità del core leggono poi da quel registro invece di parlare direttamente con i moduli plugin. -Questo mantiene il caricamento unidirezionale: +Le funzionalità del core leggono quindi da quel registro invece di parlare direttamente ai moduli +del plugin. Questo mantiene il caricamento a senso unico: -- modulo plugin -> registrazione nel registro -- runtime core -> consumo del registro +- modulo del plugin -> registrazione nel registro +- runtime del core -> consumo del registro -Questa separazione è importante per la manutenibilità. Significa che la maggior parte delle superfici del core ha bisogno solo di un punto di integrazione: “leggi il registro”, non “crea casi speciali per ogni modulo plugin”. +Questa separazione è importante per la manutenibilità. Significa che la maggior parte delle superfici del core +ha bisogno di un solo punto di integrazione: "leggere il registro", non "gestire casi speciali per ogni modulo di plugin". ## Callback di binding della conversazione I plugin che associano una conversazione possono reagire quando un'approvazione viene risolta. -Usa `api.onConversationBindingResolved(...)` per ricevere una callback dopo che una richiesta di binding -è stata approvata o negata: +Usa `api.onConversationBindingResolved(...)` per ricevere una callback dopo che una richiesta di binding viene approvata o negata: ```ts export default { @@ -609,23 +625,23 @@ Campi del payload della callback: - `status`: `"approved"` oppure `"denied"` - `decision`: `"allow-once"`, `"allow-always"` oppure `"deny"` - `binding`: il binding risolto per le richieste approvate -- `request`: il riepilogo della richiesta originale, hint detach, sender id e - metadati della conversazione +- `request`: il riepilogo della richiesta originale, l'hint di scollegamento, l'id del mittente e + i metadati della conversazione Questa callback è solo di notifica. Non cambia chi è autorizzato ad associare una -conversazione e viene eseguita dopo che la gestione di approvazione del core è terminata. +conversazione, e viene eseguita dopo che la gestione dell'approvazione del core è terminata. -## Hook runtime del provider +## Hook di runtime del provider I plugin provider ora hanno due livelli: -- metadati del manifest: `providerAuthEnvVars` per lookup economico dell'autenticazione env del provider - prima del caricamento runtime, `providerAuthAliases` per varianti del provider che condividono - l'autenticazione, `channelEnvVars` per lookup economico di env/setup del canale prima del caricamento runtime, - più `providerAuthChoices` per etichette economiche di onboarding/scelta auth e - metadati dei flag CLI prima del caricamento runtime -- hook in fase di configurazione: `catalog` / legacy `discovery` più `applyConfigDefaults` -- hook runtime: `normalizeModelId`, `normalizeTransport`, +- metadati del manifest: `providerAuthEnvVars` per una ricerca economica dell'autenticazione del provider tramite env + prima del caricamento del runtime, `providerAuthAliases` per varianti di provider che condividono + l'autenticazione, `channelEnvVars` per una ricerca economica dell'env/setup del canale prima del caricamento del runtime, + più `providerAuthChoices` per etichette economiche di onboarding/scelta dell'autenticazione e + metadati dei flag CLI prima del caricamento del runtime +- hook in fase di configurazione: `catalog` / `discovery` legacy più `applyConfigDefaults` +- hook di runtime: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `resolveExternalAuthProfiles`, @@ -639,94 +655,94 @@ I plugin provider ora hanno due livelli: `buildAuthDoctorHint`, `matchesContextOverflowError`, `classifyFailoverReason`, `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, - `isBinaryThinking`, `supportsXHighThinking`, `supportsAdaptiveThinking`, - `supportsMaxThinking`, + `resolveThinkingProfile`, `isBinaryThinking`, `supportsXHighThinking`, `resolveDefaultThinkingLevel`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, `createEmbeddingProvider`, `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw continua a possedere il ciclo agente generico, il failover, la gestione del transcript e la -policy degli strumenti. Questi hook sono la superficie di estensione per il comportamento specifico del provider senza -richiedere un intero transport di inferenza personalizzato. +OpenClaw continua a possedere il loop generico dell'agente, il failover, la gestione delle trascrizioni e +la policy degli strumenti. Questi hook sono la superficie di estensione per il comportamento specifico del provider senza +richiedere un intero trasporto di inferenza personalizzato. -Usa `providerAuthEnvVars` del manifest quando il provider ha credenziali basate su env -che i percorsi generici di auth/status/model-picker devono vedere senza caricare il runtime del plugin. -Usa `providerAuthAliases` del manifest quando un ID provider deve riutilizzare -le variabili env, i profili auth, l'autenticazione supportata dalla configurazione e la scelta di onboarding con chiave API di un altro ID provider. Usa `providerAuthChoices` del manifest quando le -superfici CLI di onboarding/scelta auth devono conoscere l'ID di scelta del provider, le etichette di gruppo e il semplice wiring auth a un flag senza caricare il runtime del provider. Mantieni `envVars` del runtime provider per suggerimenti rivolti all'operatore come etichette di onboarding o variabili di setup OAuth -client-id/client-secret. +Usa il manifest `providerAuthEnvVars` quando il provider ha credenziali basate su env +che i percorsi generici di autenticazione/stato/selettore di modello devono vedere senza caricare il runtime del plugin. +Usa il manifest `providerAuthAliases` quando un id provider deve riutilizzare +le variabili env, i profili di autenticazione, l'autenticazione supportata dalla configurazione e la scelta di onboarding della chiave API di un altro id provider. +Usa il manifest `providerAuthChoices` quando le superfici CLI di onboarding/scelta dell'autenticazione +devono conoscere l'id di scelta del provider, le etichette di gruppo e il semplice wiring di autenticazione a flag singolo senza caricare il runtime del provider. +Mantieni `envVars` nel runtime del provider per hint rivolti all'operatore, come etichette di onboarding o variabili di setup per +client-id/client-secret OAuth. -Usa `channelEnvVars` del manifest quando un canale ha auth o setup guidati da env che -il fallback generico shell-env, i controlli config/status o i prompt di setup devono vedere +Usa il manifest `channelEnvVars` quando un canale ha autenticazione o setup guidati da env che +i fallback generici dell'env di shell, i controlli di configurazione/stato o i prompt di setup devono vedere senza caricare il runtime del canale. ### Ordine e utilizzo degli hook -Per i plugin modello/provider, OpenClaw chiama gli hook approssimativamente in questo ordine. -La colonna “Quando usarlo” è la guida rapida per decidere. +Per i plugin di modello/provider, OpenClaw chiama gli hook approssimativamente in questo ordine. +La colonna "When to use" è la guida rapida per decidere. | # | Hook | Cosa fa | Quando usarlo | -| --- | --------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Pubblica la configurazione del provider in `models.providers` durante la generazione di `models.json` | Il provider possiede un catalogo o valori predefiniti di URL di base | -| 2 | `applyConfigDefaults` | Applica valori predefiniti globali di configurazione posseduti dal provider durante la materializzazione della configurazione | I valori predefiniti dipendono dalla modalità auth, dall'env o dalla semantica della famiglia di modelli del provider | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Pubblica la configurazione del provider in `models.providers` durante la generazione di `models.json` | Il provider possiede un catalogo o valori predefiniti di base URL | +| 2 | `applyConfigDefaults` | Applica valori predefiniti globali della configurazione posseduti dal provider durante la materializzazione della configurazione | I valori predefiniti dipendono dalla modalità di autenticazione, dall'env o dalla semantica della famiglia di modelli del provider | | -- | _(built-in model lookup)_ | OpenClaw prova prima il normale percorso di registro/catalogo | _(non è un hook del plugin)_ | -| 3 | `normalizeModelId` | Normalizza alias legacy o preview degli ID modello prima del lookup | Il provider possiede la pulizia degli alias prima della risoluzione canonica del modello | -| 4 | `normalizeTransport` | Normalizza `api` / `baseUrl` della famiglia provider prima dell'assemblaggio generico del modello | Il provider possiede la pulizia del transport per ID provider personalizzati nella stessa famiglia di transport | -| 5 | `normalizeConfig` | Normalizza `models.providers.` prima della risoluzione runtime/provider | Il provider ha bisogno di una pulizia della configurazione che dovrebbe vivere con il plugin; gli helper inclusi della famiglia Google fungono anche da fallback per le voci di configurazione Google supportate | -| 6 | `applyNativeStreamingUsageCompat` | Applica riscritture di compatibilità native di streaming-usage ai provider di configurazione | Il provider ha bisogno di correzioni dei metadati native di streaming usage guidate dall'endpoint | -| 7 | `resolveConfigApiKey` | Risolve l'autenticazione con marker env per i provider di configurazione prima del caricamento dell'autenticazione runtime | Il provider possiede la risoluzione della chiave API con marker env; `amazon-bedrock` ha qui anche un resolver integrato per marker env AWS | -| 8 | `resolveSyntheticAuth` | Espone autenticazione locale/self-hosted o supportata dalla configurazione senza persistere testo in chiaro | Il provider può operare con un marker di credenziale sintetica/locale | -| 9 | `resolveExternalAuthProfiles` | Sovrappone profili auth esterni posseduti dal provider; il valore predefinito di `persistence` è `runtime-only` per credenziali possedute da CLI/app | Il provider riutilizza credenziali auth esterne senza persistere token di refresh copiati | -| 10 | `shouldDeferSyntheticProfileAuth` | Abbassa la precedenza dei placeholder di profilo sintetico memorizzati rispetto all'autenticazione supportata da env/configurazione | Il provider memorizza profili placeholder sintetici che non dovrebbero vincere la precedenza | -| 11 | `resolveDynamicModel` | Fallback sincrono per ID modello posseduti dal provider non ancora presenti nel registro locale | Il provider accetta ID modello upstream arbitrari | -| 12 | `prepareDynamicModel` | Warm-up asincrono, poi `resolveDynamicModel` viene eseguito di nuovo | Il provider ha bisogno di metadati di rete prima di risolvere ID sconosciuti | -| 13 | `normalizeResolvedModel` | Riscrittura finale prima che il runner incorporato usi il modello risolto | Il provider ha bisogno di riscritture del transport ma usa comunque un transport del core | -| 14 | `contributeResolvedModelCompat` | Contribuisce con flag di compatibilità per modelli vendor dietro un altro transport compatibile | Il provider riconosce i propri modelli su transport proxy senza assumere il controllo del provider | -| 15 | `capabilities` | Metadati transcript/tooling posseduti dal provider e usati dalla logica condivisa del core | Il provider ha bisogno di peculiarità transcript/famiglia provider | -| 16 | `normalizeToolSchemas` | Normalizza gli schemi degli strumenti prima che il runner incorporato li veda | Il provider ha bisogno di pulizia degli schemi della famiglia di transport | -| 17 | `inspectToolSchemas` | Espone diagnostica degli schemi posseduta dal provider dopo la normalizzazione | Il provider vuole avvisi sulle keyword senza insegnare al core regole specifiche del provider | -| 18 | `resolveReasoningOutputMode` | Seleziona il contratto di output del reasoning nativo o con tag | Il provider ha bisogno di output reasoning/finale con tag invece dei campi nativi | -| 19 | `prepareExtraParams` | Normalizzazione dei parametri di richiesta prima dei wrapper generici delle opzioni stream | Il provider ha bisogno di parametri di richiesta predefiniti o di pulizia dei parametri per provider | -| 20 | `createStreamFn` | Sostituisce completamente il normale percorso stream con un transport personalizzato | Il provider ha bisogno di un protocollo wire personalizzato, non solo di un wrapper | -| 21 | `wrapStreamFn` | Wrapper stream dopo l'applicazione dei wrapper generici | Il provider ha bisogno di wrapper di compatibilità per header/body/modello della richiesta senza un transport personalizzato | -| 22 | `resolveTransportTurnState` | Collega header o metadati nativi per turno al transport | Il provider vuole che i transport generici inviino l'identità nativa del turno del provider | -| 23 | `resolveWebSocketSessionPolicy` | Collega header WebSocket nativi o una policy di cooldown della sessione | Il provider vuole che i transport WS generici regolino header di sessione o policy di fallback | -| 24 | `formatApiKey` | Formatter del profilo auth: il profilo memorizzato diventa la stringa `apiKey` runtime | Il provider memorizza metadati auth extra e ha bisogno di una forma personalizzata per il token runtime | -| 25 | `refreshOAuth` | Override del refresh OAuth per endpoint di refresh personalizzati o policy di fallimento del refresh | Il provider non rientra nei refresher condivisi `pi-ai` | -| 26 | `buildAuthDoctorHint` | Suggerimento di riparazione aggiunto quando il refresh OAuth fallisce | Il provider ha bisogno di indicazioni di riparazione auth possedute dal provider dopo un fallimento del refresh | -| 27 | `matchesContextOverflowError` | Matcher posseduto dal provider per l'overflow della finestra di contesto | Il provider ha errori raw di overflow che le euristiche generiche non rileverebbero | -| 28 | `classifyFailoverReason` | Classificazione del motivo di failover posseduta dal provider | Il provider può mappare errori raw API/transport a rate limit/sovraccarico/ecc. | -| 29 | `isCacheTtlEligible` | Policy della prompt-cache per provider proxy/backhaul | Il provider ha bisogno di gating TTL della cache specifico per proxy | -| 30 | `buildMissingAuthMessage` | Sostituzione del messaggio generico di recupero missing-auth | Il provider ha bisogno di un suggerimento di recupero missing-auth specifico del provider | -| 31 | `suppressBuiltInModel` | Soppressione di modelli upstream obsoleti più suggerimento di errore facoltativo rivolto all'utente | Il provider ha bisogno di nascondere righe upstream obsolete o sostituirle con un suggerimento vendor | -| 32 | `augmentModelCatalog` | Righe di catalogo sintetiche/finali aggiunte dopo la discovery | Il provider ha bisogno di righe sintetiche forward-compat in `models list` e nei picker | -| 33 | `isBinaryThinking` | Toggle di reasoning on/off per provider a binary-thinking | Il provider espone solo thinking binario on/off | -| 34 | `supportsXHighThinking` | Supporto al reasoning `xhigh` per modelli selezionati | Il provider vuole `xhigh` solo su un sottoinsieme di modelli | -| 35 | `supportsAdaptiveThinking` | Supporto al thinking `adaptive` per modelli selezionati | Il provider vuole che `adaptive` venga mostrato solo per modelli con thinking adattivo gestito dal provider | -| 36 | `supportsMaxThinking` | Supporto al reasoning `max` per modelli selezionati | Il provider vuole che `max` venga mostrato solo per modelli con max thinking del provider | -| 37 | `resolveDefaultThinkingLevel` | Livello `/think` predefinito per una specifica famiglia di modelli | Il provider possiede la policy `/think` predefinita per una famiglia di modelli | -| 38 | `isModernModelRef` | Matcher di modelli moderni per i filtri dei profili live e la selezione smoke | Il provider possiede la corrispondenza dei modelli preferiti per live/smoke | -| 39 | `prepareRuntimeAuth` | Scambia una credenziale configurata con il token/chiave runtime effettivo subito prima dell'inferenza | Il provider ha bisogno di uno scambio di token o di una credenziale di richiesta a breve durata | -| 40 | `resolveUsageAuth` | Risolve le credenziali di usage/fatturazione per `/usage` e superfici di stato correlate | Il provider ha bisogno di parsing personalizzato del token di usage/quota o di una credenziale di usage diversa | -| 41 | `fetchUsageSnapshot` | Recupera e normalizza snapshot di usage/quota specifici del provider dopo che l'autenticazione è stata risolta | Il provider ha bisogno di un endpoint di usage o di un parser del payload specifico del provider | -| 42 | `createEmbeddingProvider` | Costruisce un adapter di embedding posseduto dal provider per memoria/ricerca | Il comportamento degli embedding di memoria appartiene al plugin provider | -| 43 | `buildReplayPolicy` | Restituisce una replay policy che controlla la gestione del transcript per il provider | Il provider ha bisogno di una policy transcript personalizzata (per esempio, rimozione dei blocchi di thinking) | -| 44 | `sanitizeReplayHistory` | Riscrive la cronologia di replay dopo la pulizia generica del transcript | Il provider ha bisogno di riscritture di replay specifiche del provider oltre agli helper condivisi di Compaction | -| 45 | `validateReplayTurns` | Validazione finale o rimodellamento dei turni di replay prima del runner incorporato | Il transport del provider ha bisogno di una validazione dei turni più rigorosa dopo la sanificazione generica | -| 46 | `onModelSelected` | Esegue effetti collaterali post-selezione posseduti dal provider | Il provider ha bisogno di telemetria o di stato posseduto dal provider quando un modello diventa attivo | +| 3 | `normalizeModelId` | Normalizza alias legacy o preview degli id modello prima della ricerca | Il provider possiede la pulizia degli alias prima della risoluzione del modello canonico | +| 4 | `normalizeTransport` | Normalizza `api` / `baseUrl` della famiglia del provider prima dell'assemblaggio generico del modello | Il provider possiede la pulizia del trasporto per id provider personalizzati nella stessa famiglia di trasporto | +| 5 | `normalizeConfig` | Normalizza `models.providers.` prima della risoluzione del runtime/provider | Il provider ha bisogno di una pulizia della configurazione che dovrebbe stare nel plugin; gli helper bundled della famiglia Google fungono anche da fallback per le voci di configurazione Google supportate | +| 6 | `applyNativeStreamingUsageCompat` | Applica riscritture di compatibilità dell'uso dello streaming nativo ai provider di configurazione | Il provider necessita di correzioni dei metadati di uso dello streaming nativo guidate dall'endpoint | +| 7 | `resolveConfigApiKey` | Risolve l'autenticazione con marker env per i provider di configurazione prima del caricamento dell'autenticazione a runtime | Il provider ha una risoluzione della chiave API con marker env posseduta dal provider; anche `amazon-bedrock` ha qui un resolver integrato per marker env AWS | +| 8 | `resolveSyntheticAuth` | Espone autenticazione locale/self-hosted o supportata dalla configurazione senza persistere testo in chiaro | Il provider può operare con un marker di credenziale sintetico/locale | +| 9 | `resolveExternalAuthProfiles` | Sovrappone profili di autenticazione esterni posseduti dal provider; il valore predefinito di `persistence` è `runtime-only` per credenziali possedute da CLI/app | Il provider riutilizza credenziali di autenticazione esterne senza persistere token di refresh copiati | +| 10 | `shouldDeferSyntheticProfileAuth` | Abbassa la priorità dei placeholder di profilo sintetico memorizzati rispetto all'autenticazione supportata da env/config | Il provider memorizza profili placeholder sintetici che non dovrebbero avere la precedenza | +| 11 | `resolveDynamicModel` | Fallback sincrono per id modello posseduti dal provider non ancora presenti nel registro locale | Il provider accetta id modello upstream arbitrari | +| 12 | `prepareDynamicModel` | Warm-up asincrono, poi `resolveDynamicModel` viene eseguito di nuovo | Il provider ha bisogno di metadati di rete prima di risolvere id sconosciuti | +| 13 | `normalizeResolvedModel` | Riscrittura finale prima che l'embedded runner usi il modello risolto | Il provider ha bisogno di riscritture del trasporto ma continua a usare un trasporto del core | +| 14 | `contributeResolvedModelCompat` | Contribuisce con flag di compatibilità per modelli del fornitore dietro un altro trasporto compatibile | Il provider riconosce i propri modelli su trasporti proxy senza assumere il controllo del provider | +| 15 | `capabilities` | Metadati di trascrizione/strumenti posseduti dal provider usati dalla logica condivisa del core | Il provider ha bisogno di peculiarità della trascrizione/famiglia del provider | +| 16 | `normalizeToolSchemas` | Normalizza gli schemi degli strumenti prima che l'embedded runner li veda | Il provider ha bisogno di pulizia dello schema della famiglia di trasporto | +| 17 | `inspectToolSchemas` | Espone diagnostiche dello schema possedute dal provider dopo la normalizzazione | Il provider vuole avvisi sulle parole chiave senza insegnare al core regole specifiche del provider | +| 18 | `resolveReasoningOutputMode` | Seleziona il contratto di output del ragionamento nativo rispetto a quello con tag | Il provider ha bisogno di output ragionamento/finale con tag invece dei campi nativi | +| 19 | `prepareExtraParams` | Normalizzazione dei parametri della richiesta prima dei wrapper generici delle opzioni di stream | Il provider ha bisogno di parametri di richiesta predefiniti o di pulizia dei parametri per provider | +| 20 | `createStreamFn` | Sostituisce completamente il normale percorso di stream con un trasporto personalizzato | Il provider ha bisogno di un protocollo wire personalizzato, non solo di un wrapper | +| 21 | `wrapStreamFn` | Wrapper di stream dopo l'applicazione dei wrapper generici | Il provider ha bisogno di wrapper di compatibilità per header/corpo/modello della richiesta senza un trasporto personalizzato | +| 22 | `resolveTransportTurnState` | Collega header o metadati nativi per turno di trasporto | Il provider vuole che i trasporti generici inviino un'identità di turno nativa del provider | +| 23 | `resolveWebSocketSessionPolicy` | Collega header WebSocket nativi o una policy di cool-down della sessione | Il provider vuole che i trasporti WS generici regolino header di sessione o policy di fallback | +| 24 | `formatApiKey` | Formatter del profilo di autenticazione: il profilo memorizzato diventa la stringa `apiKey` di runtime | Il provider memorizza metadati di autenticazione aggiuntivi e ha bisogno di una forma di token di runtime personalizzata | +| 25 | `refreshOAuth` | Override del refresh OAuth per endpoint di refresh personalizzati o policy di errore del refresh | Il provider non rientra nei refresher condivisi `pi-ai` | +| 26 | `buildAuthDoctorHint` | Hint di riparazione aggiunto quando il refresh OAuth fallisce | Il provider ha bisogno di indicazioni di riparazione dell'autenticazione possedute dal provider dopo un errore di refresh | +| 27 | `matchesContextOverflowError` | Matcher dell'overflow della finestra di contesto posseduto dal provider | Il provider ha errori raw di overflow che le euristiche generiche non rileverebbero | +| 28 | `classifyFailoverReason` | Classificazione del motivo di failover posseduta dal provider | Il provider può mappare errori raw di API/trasporto a rate-limit/sovraccarico/ecc. | +| 29 | `isCacheTtlEligible` | Policy della cache dei prompt per provider proxy/backhaul | Il provider ha bisogno di gating TTL della cache specifico del proxy | +| 30 | `buildMissingAuthMessage` | Sostituzione del messaggio generico di recupero per autenticazione mancante | Il provider ha bisogno di un hint di recupero specifico del provider per autenticazione mancante | +| 31 | `suppressBuiltInModel` | Soppressione di modelli upstream obsoleti più eventuale hint di errore rivolto all'utente | Il provider ha bisogno di nascondere righe upstream obsolete o sostituirle con un hint del fornitore | +| 32 | `augmentModelCatalog` | Righe di catalogo sintetiche/finali aggiunte dopo l'individuazione | Il provider ha bisogno di righe sintetiche forward-compat in `models list` e nei selettori | +| 33 | `resolveThinkingProfile` | Imposta il livello `/think`, le etichette visualizzate e il valore predefinito specifici del modello | Il provider espone una scala di thinking personalizzata o un'etichetta binaria per modelli selezionati | +| 34 | `isBinaryThinking` | Hook di compatibilità per il toggle di ragionamento on/off | Il provider espone solo il thinking binario acceso/spento | +| 35 | `supportsXHighThinking` | Hook di compatibilità per il supporto al ragionamento `xhigh` | Il provider vuole `xhigh` solo su un sottoinsieme di modelli | +| 36 | `resolveDefaultThinkingLevel` | Hook di compatibilità per il livello `/think` predefinito | Il provider possiede la policy predefinita di `/think` per una famiglia di modelli | +| 37 | `isModernModelRef` | Matcher di modello moderno per filtri di profili live e selezione smoke | Il provider possiede l'abbinamento del modello preferito live/smoke | +| 38 | `prepareRuntimeAuth` | Scambia una credenziale configurata con il token/la chiave effettivi di runtime subito prima dell'inferenza | Il provider ha bisogno di uno scambio di token o di una credenziale di richiesta a breve durata | +| 39 | `resolveUsageAuth` | Risolve le credenziali di utilizzo/fatturazione per `/usage` e superfici di stato correlate | Il provider ha bisogno di parsing personalizzato del token di utilizzo/quota o di una credenziale di utilizzo diversa | +| 40 | `fetchUsageSnapshot` | Recupera e normalizza snapshot di utilizzo/quota specifici del provider dopo che l'autenticazione è stata risolta | Il provider ha bisogno di un endpoint di utilizzo specifico del provider o di un parser del payload | +| 41 | `createEmbeddingProvider` | Costruisce un adapter di embedding posseduto dal provider per memoria/ricerca | Il comportamento degli embedding per la memoria appartiene al plugin del provider | +| 42 | `buildReplayPolicy` | Restituisce una policy di replay che controlla la gestione della trascrizione per il provider | Il provider ha bisogno di una policy di trascrizione personalizzata (per esempio, rimozione dei blocchi di thinking) | +| 43 | `sanitizeReplayHistory` | Riscrive la cronologia di replay dopo la pulizia generica della trascrizione | Il provider ha bisogno di riscritture del replay specifiche del provider oltre agli helper condivisi di Compaction | +| 44 | `validateReplayTurns` | Validazione finale o rimodellamento dei turni di replay prima dell'embedded runner | Il trasporto del provider ha bisogno di una validazione dei turni più rigorosa dopo la sanitizzazione generica | +| 45 | `onModelSelected` | Esegue effetti collaterali post-selezione posseduti dal provider | Il provider ha bisogno di telemetria o stato posseduto dal provider quando un modello diventa attivo | `normalizeModelId`, `normalizeTransport` e `normalizeConfig` controllano prima il -plugin provider corrispondente, poi passano agli altri plugin provider con hook compatibili -finché uno non modifica davvero l'ID modello o il transport/configurazione. Questo mantiene -funzionanti gli shim di alias/compat provider senza richiedere al chiamante di sapere quale -plugin incluso possieda la riscrittura. Se nessun hook provider riscrive una voce di -configurazione supportata della famiglia Google, il normalizzatore di configurazione Google incluso applica comunque +plugin provider corrispondente, poi passano agli altri plugin provider in grado di gestire hook +finché uno non modifica effettivamente l'id del modello o il trasporto/la configurazione. Questo mantiene +funzionanti gli shim di alias/compatibilità del provider senza richiedere al chiamante di sapere quale +plugin bundled possiede la riscrittura. Se nessun hook provider riscrive una voce di configurazione supportata +della famiglia Google, il normalizzatore di configurazione Google bundled applica comunque quella pulizia di compatibilità. Se il provider ha bisogno di un protocollo wire completamente personalizzato o di un esecutore di richieste personalizzato, -questa è una diversa classe di estensione. Questi hook servono per il comportamento del provider -che continua a essere eseguito sul normale ciclo di inferenza di OpenClaw. +si tratta di una classe diversa di estensione. Questi hook servono per il comportamento del provider +che continua a essere eseguito sul normale loop di inferenza di OpenClaw. ### Esempio di provider @@ -786,105 +802,112 @@ api.registerProvider({ - Anthropic usa `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, - `supportsAdaptiveThinking`, `supportsMaxThinking`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` + `resolveThinkingProfile`, `applyConfigDefaults`, `isModernModelRef` e `wrapStreamFn` perché possiede la forward-compat di Claude 4.6, - i suggerimenti della famiglia provider, le indicazioni di riparazione auth, l'integrazione - dell'endpoint di usage, l'idoneità della prompt-cache, i valori predefiniti di configurazione sensibili all'autenticazione, la policy thinking predefinita/adaptive di Claude e la modellazione dello stream specifica di Anthropic per + gli hint della famiglia provider, la guida alla riparazione dell'autenticazione, l'integrazione + dell'endpoint di utilizzo, l'idoneità della cache dei prompt, i valori predefiniti di configurazione consapevoli dell'autenticazione, la policy di thinking + predefinita/adattiva di Claude e lo shaping dello stream specifico di Anthropic per header beta, `/fast` / `serviceTier` e `context1m`. -- Gli helper di stream specifici di Claude per Anthropic restano per ora nella - seam pubblica `api.ts` / `contract-api.ts` del plugin incluso. Quella superficie di pacchetto +- Gli helper di stream specifici di Claude di Anthropic restano per ora nel seam + pubblico `api.ts` / `contract-api.ts` del plugin bundled. Quella superficie del pacchetto esporta `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, - `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` e i builder wrapper - Anthropic di livello più basso invece di allargare lo SDK generico intorno alle regole degli header beta di un solo + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` e i builder di wrapper Anthropic + di livello inferiore invece di ampliare l'SDK generico attorno alle regole degli header beta di un solo provider. - OpenAI usa `resolveDynamicModel`, `normalizeResolvedModel` e `capabilities` più `buildMissingAuthMessage`, `suppressBuiltInModel`, - `augmentModelCatalog`, `supportsXHighThinking` e `isModernModelRef` - perché possiede la forward-compat GPT-5.4, la normalizzazione diretta OpenAI - `openai-completions` -> `openai-responses`, i suggerimenti auth - consapevoli di Codex, la soppressione di Spark, le righe sintetiche dell'elenco OpenAI e la policy GPT-5 per thinking / - modelli live; la famiglia stream `openai-responses-defaults` possiede i - wrapper condivisi nativi OpenAI Responses per header di attribuzione, - `/fast`/`serviceTier`, verbosità del testo, ricerca web nativa di Codex, - modellazione del payload reasoning-compat e gestione del contesto di Responses. + `augmentModelCatalog`, `resolveThinkingProfile` e `isModernModelRef` + perché possiede la forward-compat di GPT-5.4, la normalizzazione diretta di OpenAI + `openai-completions` -> `openai-responses`, gli hint di autenticazione + consapevoli di Codex, la soppressione di Spark, le righe di elenco OpenAI sintetiche e la policy di thinking / + modello live di GPT-5; la famiglia di stream `openai-responses-defaults` possiede i + wrapper condivisi nativi di OpenAI Responses per header di attribuzione, + `/fast`/`serviceTier`, verbosità del testo, ricerca web Codex nativa, + shaping del payload compatibile con il ragionamento e gestione del contesto di Responses. - OpenRouter usa `catalog` più `resolveDynamicModel` e `prepareDynamicModel` perché il provider è pass-through e può esporre nuovi - ID modello prima che il catalogo statico di OpenClaw venga aggiornato; usa anche + id modello prima degli aggiornamenti del catalogo statico di OpenClaw; usa anche `capabilities`, `wrapStreamFn` e `isCacheTtlEligible` per mantenere - fuori dal core header di richiesta specifici del provider, metadati di routing, patch di reasoning e - policy della prompt-cache. La sua replay policy proviene dalla - famiglia `passthrough-gemini`, mentre la famiglia stream `openrouter-thinking` - possiede l'iniezione del reasoning via proxy e i salti dei modelli non supportati / `auto`. + fuori dal core gli header di richiesta specifici del provider, i metadati di routing, le patch di ragionamento e + la policy della cache dei prompt. La sua policy di replay proviene dalla famiglia + `passthrough-gemini`, mentre la famiglia di stream `openrouter-thinking` + possiede l'iniezione del ragionamento proxy e gli skip per modello non supportato / `auto`. - GitHub Copilot usa `catalog`, `auth`, `resolveDynamicModel` e - `capabilities` più `prepareRuntimeAuth` e `fetchUsageSnapshot` perché ha - bisogno di login del dispositivo posseduto dal provider, comportamento di fallback del modello, peculiarità dei transcript Claude, uno scambio di token GitHub -> token Copilot e un endpoint di usage posseduto dal provider. + `capabilities` più `prepareRuntimeAuth` e `fetchUsageSnapshot` perché + ha bisogno di login del dispositivo posseduto dal provider, comportamento di fallback del modello, peculiarità della trascrizione di Claude, + uno scambio token GitHub -> token Copilot e un endpoint di utilizzo posseduto dal provider. - OpenAI Codex usa `catalog`, `resolveDynamicModel`, `normalizeResolvedModel`, `refreshOAuth` e `augmentModelCatalog` più `prepareExtraParams`, `resolveUsageAuth` e `fetchUsageSnapshot` perché - continua a funzionare sui transport OpenAI del core ma possiede la propria - normalizzazione di transport/base URL, la policy di fallback del refresh OAuth, la scelta predefinita del transport, - righe sintetiche del catalogo Codex e l'integrazione dell'endpoint di usage di ChatGPT; condivide la stessa famiglia stream `openai-responses-defaults` di OpenAI diretto. + continua a essere eseguito sui trasporti OpenAI del core ma possiede la propria normalizzazione di trasporto/base URL, + la policy di fallback del refresh OAuth, la scelta del trasporto predefinito, + righe sintetiche del catalogo Codex e l'integrazione con l'endpoint di utilizzo ChatGPT; condivide + la stessa famiglia di stream `openai-responses-defaults` di OpenAI diretto. - Google AI Studio e Gemini CLI OAuth usano `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, `resolveReasoningOutputMode`, `wrapStreamFn` e `isModernModelRef` perché la - famiglia replay `google-gemini` possiede il fallback forward-compat di Gemini 3.1, - la validazione replay nativa Gemini, la sanificazione del bootstrap replay, la modalità di output del reasoning con tag e la corrispondenza dei modelli moderni, mentre la - famiglia stream `google-thinking` possiede la normalizzazione del payload thinking di Gemini; + famiglia di replay `google-gemini` possiede il fallback forward-compat di Gemini 3.1, + la validazione nativa del replay Gemini, la sanitizzazione del replay bootstrap, la modalità + di output del ragionamento con tag e l'abbinamento di modelli moderni, mentre la + famiglia di stream `google-thinking` possiede la normalizzazione del payload di thinking di Gemini; Gemini CLI OAuth usa anche `formatApiKey`, `resolveUsageAuth` e - `fetchUsageSnapshot` per formattazione dei token, parsing dei token e - wiring dell'endpoint quota. + `fetchUsageSnapshot` per la formattazione del token, il parsing del token e il collegamento + dell'endpoint quota. - Anthropic Vertex usa `buildReplayPolicy` attraverso la - famiglia replay `anthropic-by-model` così la pulizia replay specifica di Claude resta - limitata agli ID Claude invece che a ogni transport `anthropic-messages`. + famiglia di replay `anthropic-by-model` in modo che la pulizia del replay specifica di Claude resti + limitata agli id Claude invece che a ogni trasporto `anthropic-messages`. - Amazon Bedrock usa `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` e `resolveDefaultThinkingLevel` perché possiede - la classificazione degli errori throttle/not-ready/context-overflow specifica di Bedrock - per il traffico Anthropic-on-Bedrock; la sua replay policy condivide comunque lo stesso - guard solo-Claude `anthropic-by-model`. + `classifyFailoverReason` e `resolveThinkingProfile` perché possiede + la classificazione specifica di Bedrock degli errori di throttle/not-ready/context-overflow + per il traffico Anthropic-on-Bedrock; la sua policy di replay condivide comunque la stessa + protezione `anthropic-by-model` solo-Claude. - OpenRouter, Kilocode, Opencode e Opencode Go usano `buildReplayPolicy` - attraverso la famiglia replay `passthrough-gemini` perché fanno da proxy a modelli Gemini - tramite transport compatibili con OpenAI e hanno bisogno della - sanificazione della thought-signature Gemini senza validazione replay Gemini nativa né + attraverso la famiglia di replay `passthrough-gemini` perché fanno da proxy ai modelli Gemini + tramite trasporti compatibili con OpenAI e hanno bisogno della sanitizzazione della + thought-signature di Gemini senza validazione nativa del replay Gemini o riscritture bootstrap. - MiniMax usa `buildReplayPolicy` attraverso la - famiglia replay `hybrid-anthropic-openai` perché un solo provider possiede sia - semantiche Anthropic-message sia OpenAI-compatible; mantiene la rimozione dei - blocchi thinking solo-Claude sul lato Anthropic mentre riporta la modalità di output del reasoning a quella nativa, e la famiglia stream `minimax-fast-mode` possiede le riscritture dei modelli fast-mode sul percorso stream condiviso. -- Moonshot usa `catalog` più `wrapStreamFn` perché usa ancora il transport - OpenAI condiviso ma ha bisogno della normalizzazione del payload thinking posseduta dal provider; la - famiglia stream `moonshot-thinking` mappa configurazione più stato `/think` sul proprio - payload nativo binary thinking. + famiglia di replay `hybrid-anthropic-openai` perché un provider possiede sia + la semantica di messaggi Anthropic sia quella compatibile con OpenAI; mantiene l'eliminazione + dei blocchi di thinking solo-Claude sul lato Anthropic mentre sovrascrive la modalità di + output del ragionamento tornando a quella nativa, e la famiglia di stream `minimax-fast-mode` possiede + le riscritture del modello fast-mode sul percorso di stream condiviso. +- Moonshot usa `catalog`, `resolveThinkingProfile` e `wrapStreamFn` perché continua a usare il + trasporto OpenAI condiviso ma ha bisogno della normalizzazione del payload di thinking posseduta dal provider; la + famiglia di stream `moonshot-thinking` mappa configurazione più stato `/think` sul suo + payload nativo di thinking binario. - Kilocode usa `catalog`, `capabilities`, `wrapStreamFn` e `isCacheTtlEligible` perché ha bisogno di header di richiesta posseduti dal provider, - normalizzazione del payload reasoning, suggerimenti per transcript Gemini e gating Anthropic - cache-TTL; la famiglia stream `kilocode-thinking` mantiene l'iniezione del thinking Kilo - sul percorso stream proxy condiviso saltando `kilo/auto` e - altri ID modello proxy che non supportano payload reasoning espliciti. + normalizzazione del payload di ragionamento, hint di trascrizione Gemini e gating TTL della cache Anthropic; la famiglia di stream `kilocode-thinking` mantiene l'iniezione del thinking Kilo + sul percorso di stream proxy condiviso saltando `kilo/auto` e + altri id modello proxy che non supportano payload di ragionamento espliciti. - Z.AI usa `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, - `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` e `fetchUsageSnapshot` perché possiede fallback GLM-5, - valori predefiniti `tool_stream`, UX binary thinking, corrispondenza dei modelli moderni e sia - l'autenticazione usage sia il recupero quota; la famiglia stream `tool-stream-default-on` mantiene - il wrapper `tool_stream` predefinito attivo fuori dalla colla scritta a mano per singolo provider. + `isCacheTtlEligible`, `resolveThinkingProfile`, `isModernModelRef`, + `resolveUsageAuth` e `fetchUsageSnapshot` perché possiede il fallback GLM-5, + i valori predefiniti di `tool_stream`, l'UX del thinking binario, l'abbinamento di modelli moderni e sia + l'autenticazione di utilizzo sia il recupero della quota; la famiglia di stream `tool-stream-default-on` mantiene + il wrapper `tool_stream` con default attivo fuori dal glue scritto a mano per singolo provider. - xAI usa `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` e `isModernModelRef` - perché possiede la normalizzazione nativa del transport xAI Responses, le riscritture alias - Grok fast-mode, `tool_stream` predefinito, la pulizia strict-tool / reasoning-payload, - il riuso dell'autenticazione di fallback per strumenti posseduti dal plugin, la risoluzione forward-compat dei modelli Grok e le patch di compatibilità possedute dal provider come il profilo schema strumenti xAI, - keyword di schema non supportate, `web_search` nativo e la decodifica degli argomenti di chiamata tool in entità HTML. + perché possiede la normalizzazione del trasporto nativo xAI Responses, le riscritture + degli alias fast-mode di Grok, il valore predefinito `tool_stream`, la pulizia + di strict-tool / payload di ragionamento, il riutilizzo dell'autenticazione di fallback per strumenti posseduti dal plugin, la risoluzione forward-compat dei modelli Grok + e patch di compatibilità possedute dal provider come il profilo + dello schema strumenti xAI, parole chiave di schema non supportate, `web_search` nativo e la + decodifica degli argomenti delle chiamate strumento con entità HTML. - Mistral, OpenCode Zen e OpenCode Go usano solo `capabilities` per mantenere - le peculiarità transcript/tooling fuori dal core. -- I provider inclusi solo-catalogo come `byteplus`, `cloudflare-ai-gateway`, + fuori dal core le peculiarità di trascrizione/strumenti. +- I provider bundled solo catalogo come `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` e `volcengine` usano solo `catalog`. -- Qwen usa `catalog` per il proprio provider testuale più registrazioni condivise di comprensione media e +- Qwen usa `catalog` per il suo provider di testo più registrazioni condivise di comprensione dei contenuti multimediali e generazione video per le sue superfici multimodali. -- MiniMax e Xiaomi usano `catalog` più hook di usage perché il loro comportamento `/usage` - è posseduto dal plugin anche se l'inferenza continua a passare attraverso i transport condivisi. +- MiniMax e Xiaomi usano `catalog` più hook di utilizzo perché il loro comportamento `/usage` + è posseduto dal plugin anche se l'inferenza continua a passare attraverso i trasporti condivisi. -## Helper runtime +## Helper di runtime I plugin possono accedere a helper selezionati del core tramite `api.runtime`. Per il TTS: @@ -907,11 +930,11 @@ const voices = await api.runtime.tts.listVoices({ Note: -- `textToSpeech` restituisce il normale payload di output TTS del core per superfici file/nota vocale. +- `textToSpeech` restituisce il normale payload di output TTS del core per superfici file/messaggio vocale. - Usa la configurazione `messages.tts` del core e la selezione del provider. - Restituisce buffer audio PCM + sample rate. I plugin devono ricampionare/codificare per i provider. -- `listVoices` è facoltativo per provider. Usalo per picker voce o flussi di setup posseduti dal vendor. -- Gli elenchi delle voci possono includere metadati più ricchi come locale, genere e tag di personalità per picker consapevoli del provider. +- `listVoices` è opzionale per provider. Usalo per selettori di voce posseduti dal fornitore o flussi di setup. +- Gli elenchi di voci possono includere metadati più ricchi come locale, genere e tag di personalità per selettori consapevoli del provider. - OpenAI ed ElevenLabs supportano oggi la telefonia. Microsoft no. I plugin possono anche registrare provider voce tramite `api.registerSpeechProvider(...)`. @@ -934,15 +957,15 @@ api.registerSpeechProvider({ Note: -- Mantieni nel core la policy TTS, il fallback e la consegna delle risposte. -- Usa i provider voce per il comportamento di sintesi posseduto dal vendor. -- L'input legacy Microsoft `edge` viene normalizzato all'ID provider `microsoft`. -- Il modello di ownership preferito è orientato all'azienda: un singolo plugin vendor può possedere - provider testuali, voce, immagini e futuri media man mano che OpenClaw aggiunge quei - contratti di capability. +- Mantieni nel core la policy TTS, il fallback e la consegna della risposta. +- Usa i provider voce per il comportamento di sintesi posseduto dal fornitore. +- L'input legacy Microsoft `edge` viene normalizzato nell'id provider `microsoft`. +- Il modello di proprietà preferito è orientato all'azienda: un plugin di un solo fornitore può possedere + provider di testo, voce, immagini e futuri contenuti multimediali man mano che OpenClaw aggiunge questi + contratti di capacità. -Per la comprensione di immagini/audio/video, i plugin registrano un provider tipizzato di -comprensione media invece di un bag generico chiave/valore: +Per la comprensione di immagini/audio/video, i plugin registrano un unico provider tipizzato di +comprensione dei contenuti multimediali invece di un contenitore generico chiave/valore: ```ts api.registerMediaUnderstandingProvider({ @@ -956,15 +979,16 @@ api.registerMediaUnderstandingProvider({ Note: -- Mantieni orchestrazione, fallback, configurazione e wiring dei canali nel core. -- Mantieni il comportamento vendor nel plugin provider. -- L'espansione additiva dovrebbe restare tipizzata: nuovi metodi opzionali, nuovi campi di risultato opzionali, nuove capability opzionali. -- La generazione video segue già lo stesso pattern: - - il core possiede il contratto di capability e l'helper runtime - - i plugin vendor registrano `api.registerVideoGenerationProvider(...)` - - i plugin funzionalità/canale consumano `api.runtime.videoGeneration.*` +- Mantieni nel core orchestrazione, fallback, configurazione e collegamento dei canali. +- Mantieni il comportamento del fornitore nel plugin provider. +- L'espansione additiva dovrebbe restare tipizzata: nuovi metodi opzionali, nuovi + campi risultato opzionali, nuove capacità opzionali. +- La generazione di video segue già lo stesso schema: + - il core possiede il contratto di capacità e l'helper di runtime + - i plugin dei fornitori registrano `api.registerVideoGenerationProvider(...)` + - i plugin di funzionalità/canale consumano `api.runtime.videoGeneration.*` -Per gli helper runtime di comprensione media, i plugin possono chiamare: +Per gli helper di runtime di comprensione dei contenuti multimediali, i plugin possono chiamare: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -979,7 +1003,7 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Per la trascrizione audio, i plugin possono usare sia il runtime di comprensione media +Per la trascrizione audio, i plugin possono usare sia il runtime di comprensione dei contenuti multimediali sia il vecchio alias STT: ```ts @@ -993,13 +1017,13 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ Note: -- `api.runtime.mediaUnderstanding.*` è la superficie condivisa preferita per - la comprensione di immagini/audio/video. -- Usa la configurazione audio di comprensione media del core (`tools.media.audio`) e l'ordine di fallback del provider. +- `api.runtime.mediaUnderstanding.*` è la superficie condivisa preferita per la + comprensione di immagini/audio/video. +- Usa la configurazione audio di comprensione dei contenuti multimediali del core (`tools.media.audio`) e l'ordine di fallback del provider. - Restituisce `{ text: undefined }` quando non viene prodotto alcun output di trascrizione (per esempio input saltato/non supportato). - `api.runtime.stt.transcribeAudioFile(...)` resta come alias di compatibilità. -I plugin possono anche avviare esecuzioni in background di sottoagenti tramite `api.runtime.subagent`: +I plugin possono anche avviare esecuzioni di subagent in background tramite `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1013,13 +1037,13 @@ const result = await api.runtime.subagent.run({ Note: -- `provider` e `model` sono override opzionali per singola esecuzione, non modifiche persistenti della sessione. -- OpenClaw rispetta quei campi di override solo per chiamanti attendibili. -- Per le esecuzioni di fallback possedute dal plugin, gli operatori devono fare opt-in con `plugins.entries..subagent.allowModelOverride: true`. +- `provider` e `model` sono override opzionali per esecuzione, non modifiche persistenti della sessione. +- OpenClaw rispetta questi campi di override solo per chiamanti attendibili. +- Per esecuzioni di fallback possedute dal plugin, gli operatori devono aderire esplicitamente con `plugins.entries..subagent.allowModelOverride: true`. - Usa `plugins.entries..subagent.allowedModels` per limitare i plugin attendibili a specifici target canonici `provider/model`, oppure `"*"` per consentire esplicitamente qualsiasi target. -- Le esecuzioni di sottoagenti di plugin non attendibili continuano a funzionare, ma le richieste di override vengono rifiutate invece di ripiegare silenziosamente. +- Le esecuzioni di subagent di plugin non attendibili continuano a funzionare, ma le richieste di override vengono rifiutate invece di ricadere silenziosamente su un fallback. -Per la ricerca web, i plugin possono consumare l'helper runtime condiviso invece di +Per la ricerca web, i plugin possono consumare l'helper di runtime condiviso invece di entrare nel wiring dello strumento dell'agente: ```ts @@ -1042,8 +1066,8 @@ I plugin possono anche registrare provider di ricerca web tramite Note: - Mantieni nel core la selezione del provider, la risoluzione delle credenziali e la semantica condivisa delle richieste. -- Usa i provider di ricerca web per transport di ricerca specifici del vendor. -- `api.runtime.webSearch.*` è la superficie condivisa preferita per plugin funzionalità/canale che hanno bisogno del comportamento di ricerca senza dipendere dal wrapper dello strumento dell'agente. +- Usa provider di ricerca web per trasporti di ricerca specifici del fornitore. +- `api.runtime.webSearch.*` è la superficie condivisa preferita per plugin di funzionalità/canale che hanno bisogno del comportamento di ricerca senza dipendere dal wrapper dello strumento dell'agente. ### `api.runtime.imageGeneration` @@ -1058,8 +1082,8 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: genera un'immagine usando la catena configurata del provider di generazione immagini. -- `listProviders(...)`: elenca i provider di generazione immagini disponibili e le loro capability. +- `generate(...)`: genera un'immagine usando la catena di provider di generazione immagini configurata. +- `listProviders(...)`: elenca i provider di generazione immagini disponibili e le loro capacità. ## Route HTTP del Gateway @@ -1081,7 +1105,7 @@ api.registerHttpRoute({ Campi della route: - `path`: percorso della route sotto il server HTTP del Gateway. -- `auth`: obbligatorio. Usa `"gateway"` per richiedere la normale autenticazione del Gateway, oppure `"plugin"` per autenticazione/verifica webhook gestita dal plugin. +- `auth`: obbligatorio. Usa `"gateway"` per richiedere la normale autenticazione del Gateway, oppure `"plugin"` per autenticazione/verifica Webhook gestita dal plugin. - `match`: opzionale. `"exact"` (predefinito) oppure `"prefix"`. - `replaceExisting`: opzionale. Consente allo stesso plugin di sostituire la propria registrazione di route esistente. - `handler`: restituisce `true` quando la route ha gestito la richiesta. @@ -1090,23 +1114,23 @@ Note: - `api.registerHttpHandler(...)` è stato rimosso e causerà un errore di caricamento del plugin. Usa invece `api.registerHttpRoute(...)`. - Le route dei plugin devono dichiarare esplicitamente `auth`. -- I conflitti esatti `path + match` vengono rifiutati a meno che `replaceExisting: true`, e un plugin non può sostituire la route di un altro plugin. -- Le route sovrapposte con livelli `auth` diversi vengono rifiutate. Mantieni catene di fallthrough `exact`/`prefix` solo sullo stesso livello auth. -- Le route `auth: "plugin"` **non** ricevono automaticamente scope runtime dell'operatore. Servono per webhook/verifica firma gestiti dal plugin, non per chiamate helper privilegiate del Gateway. -- Le route `auth: "gateway"` vengono eseguite all'interno di uno scope runtime di richiesta Gateway, ma questo scope è intenzionalmente conservativo: - - l'autenticazione bearer con segreto condiviso (`gateway.auth.mode = "token"` / `"password"`) mantiene gli scope runtime delle route plugin bloccati su `operator.write`, anche se il chiamante invia `x-openclaw-scopes` - - le modalità HTTP attendibili con identità (per esempio `trusted-proxy` o `gateway.auth.mode = "none"` su un ingresso privato) rispettano `x-openclaw-scopes` solo quando l'header è esplicitamente presente - - se `x-openclaw-scopes` è assente in quelle richieste di route plugin con identità, lo scope runtime ricade su `operator.write` -- Regola pratica: non dare per scontato che una route plugin con autenticazione Gateway sia una superficie admin implicita. Se la tua route ha bisogno di comportamento solo-admin, richiedi una modalità auth con identità e documenta il contratto esplicito dell'header `x-openclaw-scopes`. +- I conflitti esatti `path + match` vengono rifiutati a meno che non sia impostato `replaceExisting: true`, e un plugin non può sostituire la route di un altro plugin. +- Le route sovrapposte con livelli `auth` diversi vengono rifiutate. Mantieni catene di fallthrough `exact`/`prefix` solo allo stesso livello di autenticazione. +- Le route `auth: "plugin"` **non** ricevono automaticamente scope di runtime dell'operatore. Sono pensate per Webhook/verifica della firma gestiti dal plugin, non per chiamate helper privilegiate del Gateway. +- Le route `auth: "gateway"` vengono eseguite all'interno di uno scope di runtime della richiesta Gateway, ma quello scope è intenzionalmente prudente: + - l'autenticazione bearer con secret condiviso (`gateway.auth.mode = "token"` / `"password"`) mantiene gli scope di runtime delle route del plugin bloccati su `operator.write`, anche se il chiamante invia `x-openclaw-scopes` + - le modalità HTTP attendibili che trasportano identità (per esempio `trusted-proxy` oppure `gateway.auth.mode = "none"` su un ingresso privato) rispettano `x-openclaw-scopes` solo quando l'header è esplicitamente presente + - se `x-openclaw-scopes` è assente in quelle richieste di route plugin che trasportano identità, lo scope di runtime ricade su `operator.write` +- Regola pratica: non presumere che una route plugin con autenticazione gateway sia implicitamente una superficie admin. Se la tua route ha bisogno di comportamento solo admin, richiedi una modalità di autenticazione che trasporta identità e documenta il contratto esplicito dell'header `x-openclaw-scopes`. -## Percorsi di import del Plugin SDK +## Percorsi di importazione dell'SDK del plugin -Usa i sottopercorsi SDK invece dell'import monolitico `openclaw/plugin-sdk` quando +Usa i sottopercorsi dell'SDK invece dell'importazione monolitica `openclaw/plugin-sdk` quando scrivi plugin: -- `openclaw/plugin-sdk/plugin-entry` per le primitive di registrazione dei plugin. -- `openclaw/plugin-sdk/core` per il contratto generico condiviso rivolto ai plugin. -- `openclaw/plugin-sdk/config-schema` per l'esportazione dello schema Zod root `openclaw.json` +- `openclaw/plugin-sdk/plugin-entry` per primitive di registrazione del plugin. +- `openclaw/plugin-sdk/core` per il contratto generico condiviso rivolto al plugin. +- `openclaw/plugin-sdk/config-schema` per l'esportazione dello schema Zod root di `openclaw.json` (`OpenClawSchema`). - Primitive stabili di canale come `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, @@ -1120,15 +1144,15 @@ scrivi plugin: `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` e - `openclaw/plugin-sdk/webhook-ingress` per wiring condiviso di setup/auth/reply/webhook. - `channel-inbound` è la sede condivisa per debounce, corrispondenza delle mention, - helper per policy di mention in ingresso, formattazione dell'envelope e helper di contesto - per l'envelope in ingresso. - `channel-setup` è la seam ristretta per setup facoltativo di installazione. - `setup-runtime` è la superficie di setup runtime-safe usata da `setupEntry` / - avvio differito, inclusi gli adapter di patch setup import-safe. - `setup-adapter-runtime` è la seam di adapter per setup account consapevole dell'env. - `setup-tools` è la piccola seam helper per CLI/archive/docs (`formatCliCommand`, + `openclaw/plugin-sdk/webhook-ingress` per il wiring condiviso di setup/autenticazione/risposta/Webhook. + `channel-inbound` è la home condivisa per debounce, matching delle menzioni, + helper di policy delle menzioni in ingresso, formattazione dell'envelope e helper di contesto + dell'envelope in ingresso. + `channel-setup` è il seam di setup ristretto per installazione opzionale. + `setup-runtime` è la superficie di setup sicura a runtime usata da `setupEntry` / + avvio differito, inclusi gli adapter patch di setup sicuri per l'importazione. + `setup-adapter-runtime` è il seam dell'adapter di setup account consapevole dell'env. + `setup-tools` è il piccolo seam helper CLI/archivio/documentazione (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). - Sottopercorsi di dominio come `openclaw/plugin-sdk/channel-config-helpers`, @@ -1150,120 +1174,129 @@ scrivi plugin: `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` e `openclaw/plugin-sdk/directory-runtime` per helper condivisi di runtime/configurazione. - `telegram-command-config` è la seam pubblica ristretta per normalizzazione/validazione dei - comandi personalizzati Telegram e resta disponibile anche se la superficie di contratto Telegram inclusa è temporaneamente non disponibile. - `text-runtime` è la seam condivisa per testo/markdown/logging, inclusi - stripping del testo visibile all'assistente, helper di rendering/chunking markdown, helper di redazione, - helper per directive-tag e utility di testo sicuro. -- Le seam di canale specifiche per l'approvazione dovrebbero preferire un unico contratto `approvalCapability` sul plugin. Il core legge poi auth, consegna, rendering, - routing nativo e comportamento del gestore nativo lazy dell'approvazione attraverso quella singola capability invece di mescolare il comportamento di approvazione in campi non correlati del plugin. -- `openclaw/plugin-sdk/channel-runtime` è deprecato e resta solo come - shim di compatibilità per plugin più vecchi. Il nuovo codice dovrebbe importare invece primitive generiche più ristrette, e il codice del repository non dovrebbe aggiungere nuovi import dello shim. -- Gli interni delle estensioni incluse restano privati. I plugin esterni dovrebbero usare solo sottopercorsi `openclaw/plugin-sdk/*`. Il codice core/test di OpenClaw può usare i - punti di ingresso pubblici del repository sotto una radice di pacchetto plugin come `index.js`, `api.js`, - `runtime-api.js`, `setup-entry.js` e file a scope ristretto come + `telegram-command-config` è il seam pubblico ristretto per normalizzazione/validazione dei + comandi personalizzati di Telegram e resta disponibile anche se la + superficie di contratto Telegram bundled è temporaneamente non disponibile. + `text-runtime` è il seam condiviso di testo/markdown/logging, incluso + lo stripping del testo visibile all'assistente, helper di rendering/chunking markdown, helper di redazione, + helper dei tag di direttiva e utility di testo sicuro. +- I seam di canale specifici per approvazione dovrebbero preferire un unico contratto + `approvalCapability` sul plugin. Il core legge quindi autenticazione, consegna, rendering, + native-routing e comportamento lazy del native-handler dell'approvazione attraverso quell'unica capacità + invece di mescolare il comportamento di approvazione in campi di plugin non correlati. +- `openclaw/plugin-sdk/channel-runtime` è deprecato e rimane solo come + shim di compatibilità per plugin più vecchi. Il nuovo codice dovrebbe importare invece le primitive generiche più ristrette, e il codice del repo non dovrebbe aggiungere nuovi import dello + shim. +- Gli interni delle estensioni bundled restano privati. I plugin esterni dovrebbero usare solo + i sottopercorsi `openclaw/plugin-sdk/*`. Il codice core/test di OpenClaw può usare i + punti di ingresso pubblici del repo sotto la root di un pacchetto plugin come `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js` e file con ambito ristretto come `login-qr-api.js`. Non importare mai `src/*` di un pacchetto plugin dal core o da un'altra estensione. -- Suddivisione del punto di ingresso del repository: - `/api.js` è il barrel helper/types, - `/runtime-api.js` è il barrel solo-runtime, - `/index.js` è il punto di ingresso del plugin incluso - e `/setup-entry.js` è il punto di ingresso del plugin di setup. -- Esempi attuali di provider inclusi: - - Anthropic usa `api.js` / `contract-api.js` per helper stream Claude come +- Divisione dei punti di ingresso del repo: + `/api.js` è il barrel di helper/tipi, + `/runtime-api.js` è il barrel solo runtime, + `/index.js` è l'entry del plugin bundled, + e `/setup-entry.js` è l'entry del plugin di setup. +- Esempi attuali di provider bundled: + - Anthropic usa `api.js` / `contract-api.js` per helper di stream Claude come `wrapAnthropicProviderStream`, helper per header beta e parsing di `service_tier`. - - OpenAI usa `api.js` per builder provider, helper del modello predefinito e - builder provider realtime. - - OpenRouter usa `api.js` per il proprio builder provider più helper di onboarding/configurazione, mentre `register.runtime.js` può ancora riesportare helper generici `plugin-sdk/provider-stream` per uso locale del repository. + - OpenAI usa `api.js` per builder di provider, helper di modelli predefiniti e + builder di provider realtime. + - OpenRouter usa `api.js` per il suo builder provider più helper di onboarding/configurazione, + mentre `register.runtime.js` può comunque riesportare helper generici + `plugin-sdk/provider-stream` per uso locale al repo. - I punti di ingresso pubblici caricati tramite facade preferiscono lo snapshot di configurazione runtime attivo - quando esiste, poi ripiegano sul file di configurazione risolto su disco quando - OpenClaw non sta ancora servendo uno snapshot runtime. -- Le primitive generiche condivise restano il contratto pubblico preferito dello SDK. Esiste ancora un piccolo insieme riservato di seam helper brandizzate per canali inclusi per compatibilità. Trattale come seam di manutenzione/compatibilità degli inclusi, non come nuovi target di import per terze parti; i nuovi contratti cross-channel dovrebbero comunque approdare su sottopercorsi generici `plugin-sdk/*` o sui barrel locali del plugin `api.js` / + quando ne esiste uno, poi ricadono sulla configurazione risolta su disco quando + OpenClaw non sta ancora servendo uno snapshot di runtime. +- Le primitive generiche condivise restano il contratto SDK pubblico preferito. Esiste ancora un piccolo + insieme di compatibilità riservato di seam helper brandizzati per canali bundled. Trattali come seam di manutenzione bundled/compatibilità, non come nuovi target di importazione per terze parti; i nuovi contratti cross-channel dovrebbero comunque essere introdotti su sottopercorsi generici `plugin-sdk/*` o nei barrel locali del plugin `api.js` / `runtime-api.js`. -Nota di compatibilità: +Nota sulla compatibilità: - Evita il barrel root `openclaw/plugin-sdk` nel nuovo codice. -- Preferisci prima le primitive stabili e ristrette. I sottopercorsi più recenti di setup/pairing/reply/ +- Preferisci prima le primitive stabili e ristrette. I più recenti sottopercorsi setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool sono il contratto previsto per il nuovo lavoro - su plugin inclusi ed esterni. - Il parsing/matching dei target appartiene a `openclaw/plugin-sdk/channel-targets`. - I gate delle azioni message e gli helper per l'ID del messaggio di reazione appartengono a + allowlist/status/message-tool sono il contratto previsto per il nuovo + lavoro su plugin bundled ed esterni. + Il parsing/matching del target appartiene a `openclaw/plugin-sdk/channel-targets`. + I gate delle azioni di messaggio e gli helper per message-id delle reazioni appartengono a `openclaw/plugin-sdk/channel-actions`. -- I barrel helper specifici delle estensioni incluse non sono stabili per impostazione predefinita. Se un - helper serve solo a un'estensione inclusa, tienilo dietro la seam locale `api.js` o `runtime-api.js` - dell'estensione invece di promuoverlo in +- I barrel helper specifici delle estensioni bundled non sono stabili per impostazione predefinita. Se un + helper serve solo a un'estensione bundled, tienilo dietro il seam locale + `api.js` o `runtime-api.js` dell'estensione invece di promuoverlo in `openclaw/plugin-sdk/`. -- Le nuove seam helper condivise dovrebbero essere generiche, non brandizzate per canale. Il parsing condiviso dei target appartiene a `openclaw/plugin-sdk/channel-targets`; gli interni specifici del canale restano dietro la seam locale `api.js` o `runtime-api.js` - del plugin che li possiede. -- I sottopercorsi specifici della capability come `image-generation`, - `media-understanding` e `speech` esistono perché i plugin inclusi/nativi li usano +- I nuovi seam helper condivisi dovrebbero essere generici, non brandizzati per canale. Il parsing condiviso + del target appartiene a `openclaw/plugin-sdk/channel-targets`; gli interni specifici del canale + restano dietro il seam locale `api.js` o `runtime-api.js` del plugin proprietario. +- I sottopercorsi specifici per capacità come `image-generation`, + `media-understanding` e `speech` esistono perché i plugin bundled/nativi li usano oggi. La loro presenza non significa di per sé che ogni helper esportato sia un contratto esterno congelato a lungo termine. ## Schemi dello strumento message -I plugin dovrebbero possedere i contributi allo schema specifici del canale in `describeMessageTool(...)`. -Mantieni nel plugin i campi specifici del provider, non nel core condiviso. +I plugin dovrebbero possedere i contributi di schema `describeMessageTool(...)` specifici del canale. +Mantieni i campi specifici del provider nel plugin, non nel core condiviso. -Per frammenti di schema portabili condivisi, riusa gli helper generici esportati tramite +Per frammenti di schema portabili condivisi, riutilizza gli helper generici esportati tramite `openclaw/plugin-sdk/channel-actions`: - `createMessageToolButtonsSchema()` per payload in stile griglia di pulsanti -- `createMessageToolCardSchema()` per payload strutturati a card +- `createMessageToolCardSchema()` per payload di card strutturate Se una forma di schema ha senso solo per un provider, definiscila nel sorgente -del plugin invece di promuoverla nello SDK condiviso. +di quel plugin invece di promuoverla nell'SDK condiviso. -## Risoluzione dei target di canale +## Risoluzione del target del canale -I plugin di canale dovrebbero possedere la semantica dei target specifica del canale. Mantieni generico l'host +I plugin di canale dovrebbero possedere la semantica del target specifica del canale. Mantieni generico l'host outbound condiviso e usa la superficie dell'adapter di messaggistica per le regole del provider: - `messaging.inferTargetChatType({ to })` decide se un target normalizzato - debba essere trattato come `direct`, `group` o `channel` prima del lookup nella directory. + deve essere trattato come `direct`, `group` o `channel` prima della ricerca nella directory. - `messaging.targetResolver.looksLikeId(raw, normalized)` dice al core se un - input deve saltare direttamente alla risoluzione tipo-ID invece che alla ricerca nella directory. -- `messaging.targetResolver.resolveTarget(...)` è il fallback del plugin quando il - core ha bisogno di una risoluzione finale posseduta dal provider dopo la normalizzazione o dopo un miss nella - directory. -- `messaging.resolveOutboundSessionRoute(...)` possiede la costruzione della route di sessione - specifica del provider una volta che il target è stato risolto. + input deve saltare direttamente alla risoluzione tipo-id invece che alla ricerca nella directory. +- `messaging.targetResolver.resolveTarget(...)` è il fallback del plugin quando + il core ha bisogno di una risoluzione finale posseduta dal provider dopo la normalizzazione o dopo un + mancato risultato nella directory. +- `messaging.resolveOutboundSessionRoute(...)` possiede la costruzione della route di sessione specifica del provider + una volta risolto un target. Suddivisione consigliata: - Usa `inferTargetChatType` per decisioni di categoria che dovrebbero avvenire prima della ricerca tra peer/gruppi. -- Usa `looksLikeId` per controlli del tipo “tratta questo come un ID target esplicito/nativo”. -- Usa `resolveTarget` per fallback di normalizzazione specifici del provider, non per +- Usa `looksLikeId` per controlli del tipo "tratta questo come un id target esplicito/nativo". +- Usa `resolveTarget` per fallback di normalizzazione specifico del provider, non per una ricerca ampia nella directory. -- Mantieni ID nativi del provider come chat id, thread id, JID, handle e room - id dentro valori `target` o parametri specifici del provider, non in campi SDK generici. +- Mantieni id nativi del provider come chat id, thread id, JID, handle e room + id all'interno dei valori `target` o nei parametri specifici del provider, non in campi SDK generici. ## Directory supportate dalla configurazione -I plugin che derivano voci di directory dalla configurazione dovrebbero mantenere quella logica nel -plugin e riutilizzare gli helper condivisi di +I plugin che derivano voci di directory dalla configurazione dovrebbero mantenere questa logica nel +plugin e riutilizzare gli helper condivisi da `openclaw/plugin-sdk/directory-runtime`. -Usa questo quando un canale ha bisogno di peer/gruppi supportati dalla configurazione come: +Usa questo approccio quando un canale ha peer/gruppi supportati dalla configurazione, come: - peer DM guidati da allowlist - mappe configurate di canali/gruppi -- fallback statici di directory con scope per account +- fallback statici di directory con ambito account Gli helper condivisi in `directory-runtime` gestiscono solo operazioni generiche: - filtro delle query -- applicazione del limite -- helper di deduplica/normalizzazione +- applicazione dei limiti +- helper di deduplicazione/normalizzazione - costruzione di `ChannelDirectoryEntry[]` -L'ispezione dell'account specifica del canale e la normalizzazione degli ID dovrebbero restare +L'ispezione dell'account e la normalizzazione degli id specifiche del canale dovrebbero restare nell'implementazione del plugin. -## Cataloghi provider +## Cataloghi dei provider I plugin provider possono definire cataloghi di modelli per l'inferenza con `registerProvider({ catalog: { run(...) { ... } } })`. @@ -1271,56 +1304,60 @@ I plugin provider possono definire cataloghi di modelli per l'inferenza con `catalog.run(...)` restituisce la stessa forma che OpenClaw scrive in `models.providers`: -- `{ provider }` per una voce di provider -- `{ providers }` per più voci di provider +- `{ provider }` per una voce provider +- `{ providers }` per più voci provider -Usa `catalog` quando il plugin possiede ID modello specifici del provider, valori predefiniti di URL di base o metadati di modelli protetti da autenticazione. +Usa `catalog` quando il plugin possiede id modello specifici del provider, valori predefiniti di base URL +o metadati del modello protetti da autenticazione. -`catalog.order` controlla quando il catalogo di un plugin viene unito rispetto ai provider impliciti integrati di OpenClaw: +`catalog.order` controlla quando il catalogo di un plugin viene unito rispetto ai +provider impliciti integrati di OpenClaw: -- `simple`: provider semplici guidati da chiave API o env -- `profile`: provider che compaiono quando esistono profili auth +- `simple`: provider semplici con chiave API o guidati da env +- `profile`: provider che compaiono quando esistono profili di autenticazione - `paired`: provider che sintetizzano più voci provider correlate - `late`: ultimo passaggio, dopo gli altri provider impliciti -I provider successivi vincono in caso di collisione della chiave, quindi i plugin possono intenzionalmente sovrascrivere una voce provider integrata con lo stesso ID provider. +I provider successivi vincono in caso di collisione di chiave, quindi i plugin possono intenzionalmente sovrascrivere una voce provider integrata con lo stesso id provider. Compatibilità: - `discovery` continua a funzionare come alias legacy - se sono registrati sia `catalog` sia `discovery`, OpenClaw usa `catalog` -## Ispezione in sola lettura del canale +## Ispezione del canale in sola lettura Se il tuo plugin registra un canale, preferisci implementare `plugin.config.inspectAccount(cfg, accountId)` insieme a `resolveAccount(...)`. Perché: -- `resolveAccount(...)` è il percorso runtime. Può assumere che le credenziali - siano completamente materializzate e può fallire rapidamente quando mancano i segreti richiesti. -- I percorsi di comando in sola lettura come `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` e i flussi doctor/riparazione della configurazione non dovrebbero aver bisogno di materializzare credenziali runtime solo per descrivere la configurazione. +- `resolveAccount(...)` è il percorso di runtime. Può presumere che le credenziali + siano completamente materializzate e può fallire rapidamente quando mancano segreti richiesti. +- I percorsi dei comandi in sola lettura come `openclaw status`, `openclaw status --all`, + `openclaw channels status`, `openclaw channels resolve` e i flussi di doctor/riparazione + della configurazione non dovrebbero aver bisogno di materializzare credenziali di runtime solo per + descrivere la configurazione. Comportamento consigliato per `inspectAccount(...)`: -- Restituisci solo stato descrittivo dell'account. -- Preserva `enabled` e `configured`. -- Includi i campi di origine/stato delle credenziali quando rilevanti, come: +- Restituisci solo uno stato descrittivo dell'account. +- Mantieni `enabled` e `configured`. +- Includi campi di origine/stato delle credenziali quando rilevanti, come: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Non è necessario restituire valori raw dei token solo per riportare la - disponibilità in sola lettura. Restituire `tokenStatus: "available"` (e il corrispondente campo di origine) è sufficiente per i comandi in stile stato. +- Non è necessario restituire valori di token raw solo per riportare la disponibilità in sola lettura. Restituire `tokenStatus: "available"` (e il corrispondente campo di origine) è sufficiente per comandi di tipo stato. - Usa `configured_unavailable` quando una credenziale è configurata tramite SecretRef ma - non disponibile nel percorso di comando corrente. + non disponibile nel percorso del comando corrente. -Questo consente ai comandi in sola lettura di riportare “configurato ma non disponibile in questo percorso di comando” invece di andare in crash o segnalare erroneamente che l'account non è configurato. +Questo consente ai comandi in sola lettura di riportare "configurato ma non disponibile in questo percorso di comando" +invece di andare in crash o riportare erroneamente l'account come non configurato. ## Package pack -Una directory plugin può includere un `package.json` con `openclaw.extensions`: +Una directory di plugin può includere un `package.json` con `openclaw.extensions`: ```json { @@ -1332,60 +1369,63 @@ Una directory plugin può includere un `package.json` con `openclaw.extensions`: } ``` -Ogni voce diventa un plugin. Se il pack elenca più estensioni, l'ID plugin +Ogni entry diventa un plugin. Se il pack elenca più estensioni, l'id del plugin diventa `name/`. -Se il tuo plugin importa dipendenze npm, installale in quella directory così +Se il tuo plugin importa dipendenze npm, installale in quella directory in modo che `node_modules` sia disponibile (`npm install` / `pnpm install`). -Guardrail di sicurezza: ogni voce `openclaw.extensions` deve restare dentro la directory del plugin -dopo la risoluzione dei symlink. Le voci che escono dalla directory del pacchetto vengono +Guardrail di sicurezza: ogni entry `openclaw.extensions` deve restare all'interno della directory del plugin +dopo la risoluzione dei symlink. Le entry che escono dalla directory del pacchetto vengono rifiutate. Nota di sicurezza: `openclaw plugins install` installa le dipendenze del plugin con -`npm install --omit=dev --ignore-scripts` (niente lifecycle script, niente dipendenze dev a runtime). Mantieni gli alberi delle dipendenze del plugin “pure JS/TS” ed evita pacchetti che richiedono build `postinstall`. +`npm install --omit=dev --ignore-scripts` (nessuno script lifecycle, nessuna dipendenza di sviluppo a runtime). Mantieni gli alberi delle dipendenze del plugin "pure JS/TS" ed evita pacchetti che richiedono build `postinstall`. -Facoltativo: `openclaw.setupEntry` può puntare a un modulo leggero solo-setup. -Quando OpenClaw ha bisogno di superfici di setup per un plugin di canale disabilitato, o +Facoltativo: `openclaw.setupEntry` può puntare a un modulo leggero solo setup. +Quando OpenClaw ha bisogno di superfici di setup per un plugin di canale disabilitato, oppure quando un plugin di canale è abilitato ma ancora non configurato, carica `setupEntry` -invece del punto di ingresso completo del plugin. Questo mantiene avvio e setup più leggeri -quando il punto di ingresso principale del plugin collega anche strumenti, hook o altro codice solo-runtime. +invece dell'entry completa del plugin. Questo rende avvio e setup più leggeri +quando l'entry principale del plugin collega anche strumenti, hook o altro codice solo runtime. Facoltativo: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -può far fare opt-in a un plugin di canale sullo stesso percorso `setupEntry` durante la fase -di avvio pre-listen del gateway, anche quando il canale è già configurato. +può fare opt-in di un plugin di canale allo stesso percorso `setupEntry` durante la fase di +avvio pre-listen del gateway, anche quando il canale è già configurato. -Usa questo solo quando `setupEntry` copre completamente la superficie di avvio che deve esistere -prima che il gateway inizi ad ascoltare. In pratica, significa che l'entry di setup -deve registrare ogni capability posseduta dal canale da cui l'avvio dipende, come: +Usalo solo quando `setupEntry` copre completamente la superficie di avvio che deve esistere +prima che il gateway inizi l'ascolto. In pratica, questo significa che l'entry di setup +deve registrare ogni capacità posseduta dal canale da cui dipende l'avvio, come: - la registrazione del canale stesso -- eventuali route HTTP che devono essere disponibili prima che il gateway inizi ad ascoltare -- eventuali metodi Gateway, strumenti o servizi che devono esistere durante quella stessa finestra +- eventuali route HTTP che devono essere disponibili prima che il gateway inizi l'ascolto +- eventuali metodi gateway, strumenti o servizi che devono esistere durante quella stessa finestra -Se la tua entry completa possiede ancora una capability di avvio richiesta, non abilitare -questo flag. Mantieni il comportamento predefinito del plugin e lascia che OpenClaw carichi l'entry completa durante l'avvio. +Se la tua entry completa possiede ancora qualche capacità di avvio richiesta, non abilitare +questo flag. Mantieni il comportamento predefinito del plugin e lascia che OpenClaw carichi la +entry completa durante l'avvio. -I canali inclusi possono anche pubblicare helper della superficie di contratto solo-setup che il core -può consultare prima che il runtime completo del canale venga caricato. L'attuale -superficie di promozione del setup è: +I canali bundled possono anche pubblicare helper di superficie contrattuale solo setup che il core +può consultare prima che il runtime completo del canale venga caricato. L'attuale superficie +di promozione del setup è: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Il core usa questa superficie quando deve promuovere una configurazione legacy di canale a singolo account +Il core usa questa superficie quando deve promuovere una configurazione di canale legacy a account singolo in `channels..accounts.*` senza caricare l'entry completa del plugin. -Matrix è l'esempio incluso attuale: sposta solo chiavi auth/bootstrap in un -account promosso con nome quando esistono già account con nome e può preservare una -chiave dell'account predefinito configurata ma non canonica invece di creare sempre +Matrix è l'esempio bundled attuale: sposta solo chiavi di autenticazione/bootstrap in un +account promosso con nome quando esistono già account con nome, e può preservare una +chiave di account predefinita configurata non canonica invece di creare sempre `accounts.default`. -Questi adapter di patch setup mantengono lazy la discovery della superficie di contratto inclusa. Il tempo di importazione resta leggero; la superficie di promozione viene caricata solo al primo uso invece di rientrare nell'avvio del canale incluso durante l'import del modulo. +Quegli adapter di patch del setup mantengono lazy l'individuazione della superficie contrattuale bundled. Il tempo +di importazione resta leggero; la superficie di promozione viene caricata solo al primo utilizzo invece di +rientrare nell'avvio del canale bundled all'import del modulo. Quando quelle superfici di avvio includono metodi RPC del Gateway, mantienili su un -prefisso specifico del plugin. Gli spazi dei nomi admin del core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) restano riservati e risolvono sempre +prefisso specifico del plugin. I namespace admin del core (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) restano riservati e vengono sempre risolti a `operator.admin`, anche se un plugin richiede uno scope più ristretto. Esempio: @@ -1403,10 +1443,10 @@ Esempio: } ``` -### Metadati del catalogo canali +### Metadati del catalogo dei canali -I plugin di canale possono pubblicizzare metadati di setup/discovery tramite `openclaw.channel` e -suggerimenti di installazione tramite `openclaw.install`. Questo mantiene il core privo di dati di catalogo. +I plugin di canale possono pubblicizzare metadati di setup/individuazione tramite `openclaw.channel` e +hint di installazione tramite `openclaw.install`. Questo mantiene il catalogo del core privo di dati. Esempio: @@ -1421,7 +1461,7 @@ Esempio: "selectionLabel": "Nextcloud Talk (self-hosted)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Chat self-hosted tramite bot webhook Nextcloud Talk.", + "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -1434,23 +1474,23 @@ Esempio: } ``` -Campi utili di `openclaw.channel` oltre all'esempio minimo: +Campi utili di `openclaw.channel` oltre l'esempio minimo: - `detailLabel`: etichetta secondaria per superfici più ricche di catalogo/stato -- `docsLabel`: sovrascrive il testo del link della documentazione -- `preferOver`: ID plugin/canale a priorità inferiore che questa voce di catalogo dovrebbe superare -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: controlli della copia sulla superficie di selezione -- `markdownCapable`: contrassegna il canale come capace di Markdown per decisioni di formattazione outbound +- `docsLabel`: sovrascrive il testo del link per il link alla documentazione +- `preferOver`: id di plugin/canale a priorità inferiore che questa voce di catalogo dovrebbe superare +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: controlli del testo della superficie di selezione +- `markdownCapable`: contrassegna il canale come compatibile con Markdown per le decisioni di formattazione outbound - `exposure.configured`: nasconde il canale dalle superfici di elenco dei canali configurati quando impostato su `false` - `exposure.setup`: nasconde il canale dai selettori interattivi di setup/configurazione quando impostato su `false` - `exposure.docs`: contrassegna il canale come interno/privato per le superfici di navigazione della documentazione -- `showConfigured` / `showInSetup`: alias legacy ancora accettati per compatibilità; preferisci `exposure` -- `quickstartAllowFrom`: fa fare opt-in al canale nel flusso standard quickstart `allowFrom` +- `showConfigured` / `showInSetup`: alias legacy ancora accettati per compatibilità; preferire `exposure` +- `quickstartAllowFrom`: fa opt-in del canale al flusso standard quickstart `allowFrom` - `forceAccountBinding`: richiede binding esplicito dell'account anche quando esiste un solo account -- `preferSessionLookupForAnnounceTarget`: preferisce la ricerca della sessione quando risolve target di announce +- `preferSessionLookupForAnnounceTarget`: preferisce la ricerca della sessione quando risolve target di annuncio -OpenClaw può anche unire **cataloghi di canali esterni** (per esempio, un export del -registro MPM). Inserisci un file JSON in uno di questi percorsi: +OpenClaw può anche unire **cataloghi di canali esterni** (per esempio, un'esportazione di registro +MPM). Inserisci un file JSON in uno di questi percorsi: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` @@ -1464,11 +1504,11 @@ contenere `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...} I plugin del motore di contesto possiedono l'orchestrazione del contesto di sessione per ingestione, assemblaggio e Compaction. Registrali dal tuo plugin con -`api.registerContextEngine(id, factory)`, poi seleziona il motore attivo con +`api.registerContextEngine(id, factory)`, quindi seleziona il motore attivo con `plugins.slots.contextEngine`. -Usa questo quando il tuo plugin ha bisogno di sostituire o estendere la pipeline di contesto -predefinita invece di aggiungere soltanto ricerca in memoria o hook. +Usa questo approccio quando il tuo plugin deve sostituire o estendere la pipeline di contesto predefinita +invece di limitarsi ad aggiungere ricerca nella memoria o hook. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1532,52 +1572,52 @@ export default function (api) { } ``` -## Aggiungere una nuova capability +## Aggiungere una nuova capacità Quando un plugin ha bisogno di un comportamento che non rientra nell'API attuale, non aggirare -il sistema dei plugin con un reach-in privato. Aggiungi la capability mancante. +il sistema dei plugin con un accesso privato interno. Aggiungi la capacità mancante. Sequenza consigliata: -1. definisci il contratto del core - Decidi quale comportamento condiviso il core dovrebbe possedere: policy, fallback, merge della configurazione, - ciclo di vita, semantica rivolta ai canali e forma dell'helper runtime. -2. aggiungi superfici tipizzate di registrazione/runtime del plugin - Estendi `OpenClawPluginApi` e/o `api.runtime` con la più piccola - superficie tipizzata di capability utile. -3. collega i consumer core + canale/funzionalità - I canali e i plugin funzionalità dovrebbero consumare la nuova capability tramite il core, - non importando direttamente un'implementazione vendor. -4. registra le implementazioni vendor - I plugin vendor registrano poi i propri backend rispetto alla capability. -5. aggiungi copertura di contratto - Aggiungi test così ownership e forma della registrazione restino esplicite nel tempo. +1. definire il contratto del core + Decidi quale comportamento condiviso deve possedere il core: policy, fallback, unione della configurazione, + ciclo di vita, semantica rivolta al canale e forma dell'helper di runtime. +2. aggiungere superfici tipizzate di registrazione/runtime del plugin + Estendi `OpenClawPluginApi` e/o `api.runtime` con la più piccola superficie di capacità + tipizzata utile. +3. collegare i consumer del core + canale/funzionalità + I plugin di canale e di funzionalità dovrebbero consumare la nuova capacità attraverso il core, + non importando direttamente un'implementazione del fornitore. +4. registrare le implementazioni dei fornitori + I plugin dei fornitori registrano quindi i propri backend rispetto alla capacità. +5. aggiungere copertura contrattuale + Aggiungi test in modo che la proprietà e la forma della registrazione restino esplicite nel tempo. -È così che OpenClaw resta opinabile senza diventare codificato rigidamente secondo -la visione del mondo di un solo provider. Consulta il [Capability Cookbook](/it/plugins/architecture) +È così che OpenClaw resta opinionato senza diventare codificato rigidamente secondo +la visione del mondo di un solo fornitore. Vedi il [Capability Cookbook](/it/plugins/architecture) per una checklist concreta dei file e un esempio completo. -### Checklist della capability +### Checklist per le capacità -Quando aggiungi una nuova capability, l'implementazione dovrebbe di solito toccare insieme -queste superfici: +Quando aggiungi una nuova capacità, l'implementazione di solito dovrebbe toccare insieme queste +superfici: - tipi di contratto del core in `src//types.ts` -- helper runner/runtime del core in `src//runtime.ts` +- runner/helper di runtime del core in `src//runtime.ts` - superficie di registrazione dell'API plugin in `src/plugins/types.ts` - wiring del registro dei plugin in `src/plugins/registry.ts` -- esposizione runtime del plugin in `src/plugins/runtime/*` quando i plugin funzionalità/canale +- esposizione del runtime del plugin in `src/plugins/runtime/*` quando i plugin di funzionalità/canale devono consumarla - helper di acquisizione/test in `src/test-utils/plugin-registration.ts` -- assert di ownership/contratto in `src/plugins/contracts/registry.ts` +- asserzioni di proprietà/contratto in `src/plugins/contracts/registry.ts` - documentazione per operatori/plugin in `docs/` -Se una di queste superfici manca, di solito è segno che la capability +Se manca una di queste superfici, di solito è segno che la capacità non è ancora completamente integrata. -### Template della capability +### Modello per le capacità -Pattern minimo: +Schema minimo: ```ts // core contract @@ -1603,7 +1643,7 @@ const clip = await api.runtime.videoGeneration.generate({ }); ``` -Pattern di test del contratto: +Schema di test del contratto: ```ts expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); @@ -1611,7 +1651,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Questo mantiene semplice la regola: -- il core possiede il contratto di capability + l'orchestrazione -- i plugin vendor possiedono le implementazioni vendor -- i plugin funzionalità/canale consumano helper runtime -- i test di contratto mantengono esplicita l'ownership +- il core possiede il contratto di capacità + l'orchestrazione +- i plugin dei fornitori possiedono le implementazioni del fornitore +- i plugin di funzionalità/canale consumano helper di runtime +- i test di contratto mantengono esplicita la proprietà diff --git a/docs/it/plugins/sdk-provider-plugins.md b/docs/it/plugins/sdk-provider-plugins.md index 8981458f9..20a245a9a 100644 --- a/docs/it/plugins/sdk-provider-plugins.md +++ b/docs/it/plugins/sdk-provider-plugins.md @@ -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. - 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. 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. -## Procedura dettagliata +## Procedura guidata @@ -96,11 +96,11 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli. ``` - 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 ` 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. - 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. - - La maggior parte dei provider richiede solo `catalog` + `resolveDynamicModel`. Aggiungi hook - in modo incrementale in base alle necessità del tuo provider. + + 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 - - Per provider che richiedono uno scambio token prima di ogni chiamata di inferenza: + + 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. ``` - 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. ``` - 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. ``` - 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.` | - | 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). - + - 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. @@ -698,11 +698,11 @@ autenticazione tramite chiave API e risoluzione dinamica dei modelli. ```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 ``` /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 diff --git a/docs/it/tools/agent-send.md b/docs/it/tools/agent-send.md index ba197d43c..df7490d7e 100644 --- a/docs/it/tools/agent-send.md +++ b/docs/it/tools/agent-send.md @@ -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 @@ -31,15 +31,15 @@ recapito programmatico. - + ```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. ```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 \` | Messaggio da inviare (obbligatorio) | -| `--to \` | Deriva la chiave di sessione da una destinazione (telefono, id chat) | -| `--agent \` | Sceglie come destinazione un agente configurato (usa la sua sessione `main`) | +| `--to \` | Ricava la chiave di sessione da una destinazione (telefono, id chat) | +| `--agent \` | Indirizza a un agente configurato (usa la sua sessione `main`) | | `--session-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 \` | Canale di recapito (whatsapp, telegram, discord, slack, ecc.) | -| `--reply-to \` | Override della destinazione di recapito | -| `--reply-channel \` | Override del canale di recapito | -| `--reply-account \` | Override dell'id account di recapito | -| `--thinking \` | Imposta il livello di thinking (off, minimal, low, medium, high, xhigh) | -| `--verbose \` | Imposta il livello di dettaglio | +| `--reply-to \` | Sostituzione della destinazione di recapito | +| `--reply-channel \` | Sostituzione del canale di recapito | +| `--reply-account \` | Sostituzione dell'id account di recapito | +| `--thinking \` | Imposta il livello di thinking per il profilo modello selezionato | +| `--verbose \` | Imposta il livello di verbosità | | `--timeout \` | 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 diff --git a/docs/it/tools/slash-commands.md b/docs/it/tools/slash-commands.md index 35f0e4c10..8356b6ebe 100644 --- a/docs/it/tools/slash-commands.md +++ b/docs/it/tools/slash-commands.md @@ -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 `! ` (con `/bash ` come alias). +Il comando bash della chat solo host usa `! ` (con `/bash ` 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 `! ` per eseguire comandi shell host (`/bash ` è 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 ` e `/session max-age ` gestiscono la scadenza del binding del thread. -- `/think ` 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 ` 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= security= ask= node=` mostra o imposta i valori predefiniti di exec. - `/model [name|#|status]` mostra o imposta il modello. - `/models [provider] [page] [limit=|size=|all]` elenca i provider o i modelli di un provider. - `/queue ` 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 [input]` esegue una skill per nome. -- `/allowlist [list|add|remove] ...` gestisce le voci dell’allowlist. Solo testo. -- `/approve ` risolve i prompt di approvazione exec. +- `/allowlist [list|add|remove] ...` gestisce le voci dell'allowlist. Solo testuale. +- `/approve ` risolve le richieste di approvazione exec. - `/btw ` 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 ` 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 ` interrompe uno o tutti i sottoagenti in esecuzione. -- `/steer ` 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 ` 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 ` interrompe uno o tutti i sub-agent in esecuzione. +- `/steer ` 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 ` esegue un comando shell host. Solo testo. Alias: `! `. Richiede `commands.bash: true` più le allowlist `tools.elevated`. +- `/bash ` esegue un comando shell host. Solo testuale. Alias: `! `. 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 [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 [duration]|disarm` arma temporaneamente i comandi ad alto rischio del nodo telefonico. - `/voice status|list [limit]|set ` 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 [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..commands.nativeSkills`. Note: -- I comandi accettano facoltativamente `:` tra il comando e gli argomenti (ad esempio `/think: high`, `/send: on`, `/help:`). -- `/new ` 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 ` 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 ` orientato alla configurazione e `/config set channels..accounts....` 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 ` orientato alla configurazione e `/config set channels..accounts....` 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 ` accetta le stesse specifiche plugin di `openclaw plugins install`: percorso/archivio locale, pacchetto npm oppure `clawhub:`. +- `/plugins install ` accetta le stesse specifiche di plugin di `openclaw plugins install`: percorso/archivio locale, pacchetto npm o `clawhub:`. - `/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 [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 [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::discord:slash:` - Slack: `agent::slack:slash:` (prefisso configurabile tramite `channels.slack.slashCommand.sessionPrefix`) - - Telegram: `telegram:slash:` (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:` (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. diff --git a/docs/it/tools/thinking.md b/docs/it/tools/thinking.md index a2bd6e6c8..9c957f6f1 100644 --- a/docs/it/tools/thinking.md +++ b/docs/it/tools/thinking.md @@ -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 `, `/think:` oppure `/thinking `. -- Livelli, alias: `off | minimal | low | medium | high | xhigh | adaptive | max` +- Direttiva inline in qualsiasi corpo in ingresso: `/t `, `/think:` o `/thinking `. +- 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["/"].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["/"].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 ` : ` 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 ` : ` 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 ()`, 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:` 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 ()`, 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:` 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.