openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh it translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-19 01:13:27 +00:00
parent 4cbaec79df
commit f4bd86da35
10 changed files with 1190 additions and 1204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
docs/it/channels/index.md
View File

@ -1,57 +1,57 @@
---
read_when:
- Vuoi scegliere un canale di chat per OpenClaw
- Hai bisogno di una rapida panoramica delle piattaforme di messaggistica supportate
- Ti serve una rapida panoramica delle piattaforme di messaggistica supportate
summary: Piattaforme di messaggistica a cui OpenClaw può connettersi
title: Canali di chat
x-i18n:
generated_at: "2026-04-05T13:42:51Z"
generated_at: "2026-04-19T01:11:07Z"
model: gpt-5.4
provider: openai
source_hash: 246ee6f16aebe751241f00102bb435978ed21f6158385aff5d8e222e30567416
source_hash: d41c3a37d91c07f15afd8e199a289297772331c70e38697346a373595eb2d993
source_path: channels/index.md
workflow: 15
---
# Canali di chat
OpenClaw può parlare con te su qualsiasi app di chat che usi già. Ogni canale si connette tramite il Gateway.
Il testo è supportato ovunque; contenuti multimediali e reazioni variano a seconda del canale.
OpenClaw può parlarti su qualsiasi app di chat che già usi. Ogni canale si connette tramite il Gateway.
Il testo è supportato ovunque; contenuti multimediali e reazioni variano in base al canale.
## Canali supportati
- [BlueBubbles](/channels/bluebubbles) — **Consigliato per iMessage**; usa l'API REST del server macOS BlueBubbles con supporto completo delle funzionalità (plugin incluso; modifica, annullamento invio, effetti, reazioni, gestione dei gruppi — la modifica è attualmente non funzionante su macOS 26 Tahoe).
- [Discord](/channels/discord) — API Bot e Gateway di Discord; supporta server, canali e DM.
- [Feishu](/channels/feishu) — bot Feishu/Lark tramite WebSocket (plugin incluso).
- [Google Chat](/channels/googlechat) — app Google Chat API tramite webhook HTTP.
- [iMessage (legacy)](/channels/imessage) — integrazione macOS legacy tramite CLI imsg (deprecata, usa BlueBubbles per le nuove configurazioni).
- [IRC](/channels/irc) — server IRC classici; canali e DM con controlli di pairing/allowlist.
- [LINE](/channels/line) — bot LINE Messaging API (plugin incluso).
- [Matrix](/channels/matrix) — protocollo Matrix (plugin incluso).
- [Mattermost](/channels/mattermost) — API Bot e WebSocket; canali, gruppi, DM (plugin incluso).
- [Microsoft Teams](/channels/msteams) — Bot Framework; supporto enterprise (plugin incluso).
- [Nextcloud Talk](/channels/nextcloud-talk) — chat self-hosted tramite Nextcloud Talk (plugin incluso).
- [Nostr](/channels/nostr) — DM decentralizzati tramite NIP-04 (plugin incluso).
- [QQ Bot](/channels/qqbot) — API QQ Bot; chat private, chat di gruppo e contenuti multimediali avanzati (plugin incluso).
- [Signal](/channels/signal) — signal-cli; orientato alla privacy.
- [Slack](/channels/slack) — SDK Bolt; app per workspace.
- [Synology Chat](/channels/synology-chat) — Chat Synology NAS tramite webhook in uscita e in entrata (plugin incluso).
- [Telegram](/channels/telegram) — API Bot tramite grammY; supporta i gruppi.
- [Tlon](/channels/tlon) — messenger basato su Urbit (plugin incluso).
- [Twitch](/channels/twitch) — chat Twitch tramite connessione IRC (plugin incluso).
- [Voice Call](/plugins/voice-call) — telefonia tramite Plivo o Twilio (plugin, installato separatamente).
- [WebChat](/web/webchat) — interfaccia Gateway WebChat tramite WebSocket.
- [WeChat](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin) — plugin Tencent iLink Bot tramite login QR; solo chat private.
- [WhatsApp](/channels/whatsapp) — il più popolare; usa Baileys e richiede l'abbinamento tramite QR.
- [Zalo](/channels/zalo) — API Zalo Bot; popolare messenger del Vietnam (plugin incluso).
- [Zalo Personal](/channels/zalouser) — account personale Zalo tramite login QR (plugin incluso).
- [BlueBubbles](/it/channels/bluebubbles) — **Consigliato per iMessage**; usa la REST API del server macOS BlueBubbles con supporto completo delle funzionalità (Plugin incluso; modifica, annulla invio, effetti, reazioni, gestione dei gruppi — la modifica è attualmente non funzionante su macOS 26 Tahoe).
- [Discord](/it/channels/discord) — API Bot + Gateway di Discord; supporta server, canali e messaggi diretti.
- [Feishu](/it/channels/feishu) — bot Feishu/Lark tramite WebSocket (Plugin incluso).
- [Google Chat](/it/channels/googlechat) — app Google Chat API tramite Webhook HTTP.
- [iMessage (legacy)](/it/channels/imessage) — integrazione macOS legacy tramite CLI imsg (deprecata, usa BlueBubbles per le nuove configurazioni).
- [IRC](/it/channels/irc) — server IRC classici; canali + messaggi diretti con controlli di pairing/allowlist.
- [LINE](/it/channels/line) — bot LINE Messaging API (Plugin incluso).
- [Matrix](/it/channels/matrix) — protocollo Matrix (Plugin incluso).
- [Mattermost](/it/channels/mattermost) — API Bot + WebSocket; canali, gruppi, messaggi diretti (Plugin incluso).
- [Microsoft Teams](/it/channels/msteams) — Bot Framework; supporto enterprise (Plugin incluso).
- [Nextcloud Talk](/it/channels/nextcloud-talk) — chat self-hosted tramite Nextcloud Talk (Plugin incluso).
- [Nostr](/it/channels/nostr) — messaggi diretti decentralizzati tramite NIP-04 (Plugin incluso).
- [QQ Bot](/it/channels/qqbot) — API QQ Bot; chat private, chat di gruppo e contenuti multimediali avanzati (Plugin incluso).
- [Signal](/it/channels/signal) — signal-cli; orientato alla privacy.
- [Slack](/it/channels/slack) — SDK Bolt; app per workspace.
- [Synology Chat](/it/channels/synology-chat) — chat Synology NAS tramite Webhook in uscita + in entrata (Plugin incluso).
- [Telegram](/it/channels/telegram) — Bot API tramite grammY; supporta i gruppi.
- [Tlon](/it/channels/tlon) — messenger basato su Urbit (Plugin incluso).
- [Twitch](/it/channels/twitch) — chat Twitch tramite connessione IRC (Plugin incluso).
- [Voice Call](/it/plugins/voice-call) — telefonia tramite Plivo o Twilio (plugin, installato separatamente).
- [WebChat](/web/webchat) — interfaccia WebChat del Gateway tramite WebSocket.
- [WeChat](/it/channels/wechat) — plugin Tencent iLink Bot tramite accesso con QR; solo chat private (plugin esterno).
- [WhatsApp](/it/channels/whatsapp) — il più popolare; usa Baileys e richiede l'associazione tramite QR.
- [Zalo](/it/channels/zalo) — API Zalo Bot; il popolare messenger del Vietnam (Plugin incluso).
- [Zalo Personal](/it/channels/zalouser) — account personale Zalo tramite accesso con QR (Plugin incluso).
## Note
- I canali possono essere eseguiti simultaneamente; configurane più di uno e OpenClaw instraderà in base alla chat.
- La configurazione più rapida è di solito **Telegram** (semplice token bot). WhatsApp richiede l'abbinamento tramite QR e
- I canali possono essere eseguiti contemporaneamente; configurane più di uno e OpenClaw instraderà per chat.
- La configurazione più rapida di solito è **Telegram** (semplice token del bot). WhatsApp richiede l'associazione tramite QR e
memorizza più stato su disco.
- Il comportamento dei gruppi varia a seconda del canale; vedi [Gruppi](/channels/groups).
- Il pairing dei DM e le allowlist sono applicati per sicurezza; vedi [Sicurezza](/gateway/security).
- Risoluzione dei problemi: [Risoluzione dei problemi dei canali](/channels/troubleshooting).
- I provider di modelli sono documentati separatamente; vedi [Provider di modelli](/providers/models).
- Il comportamento dei gruppi varia in base al canale; vedi [Groups](/it/channels/groups).
- Il pairing dei messaggi diretti e le allowlist vengono applicati per sicurezza; vedi [Security](/it/gateway/security).
- Risoluzione dei problemi: [Risoluzione dei problemi dei canali](/it/channels/troubleshooting).
- I provider di modelli sono documentati separatamente; vedi [Provider di modelli](/it/providers/models).

175
docs/it/channels/wechat.md Normal file
View File

@ -0,0 +1,175 @@
---
read_when:
- Vuoi connettere OpenClaw a WeChat o Weixin
- Stai installando o risolvendo i problemi del Plugin del canale openclaw-weixin
- Devi capire come i Plugin di canale esterni vengono eseguiti accanto al Gateway
summary: Configurazione del canale WeChat tramite il Plugin esterno openclaw-weixin
title: WeChat
x-i18n:
generated_at: "2026-04-19T01:11:13Z"
model: gpt-5.4
provider: openai
source_hash: ae669f2b6300e0c2b1d1dc57743a0a2ab0c05b9e277ec2ac640a03e6e7ab3b84
source_path: channels/wechat.md
workflow: 15
---
# WeChat
OpenClaw si connette a WeChat tramite il Plugin di canale esterno di Tencent
`@tencent-weixin/openclaw-weixin`.
Stato: Plugin esterno. Le chat dirette e i contenuti multimediali sono supportati. Le chat di gruppo non sono
dichiarate dai metadati di capacità del Plugin attuale.
## Denominazione
- **WeChat** è il nome rivolto all'utente in questa documentazione.
- **Weixin** è il nome usato dal pacchetto di Tencent e dall'id del Plugin.
- `openclaw-weixin` è l'id del canale OpenClaw.
- `@tencent-weixin/openclaw-weixin` è il pacchetto npm.
Usa `openclaw-weixin` nei comandi CLI e nei percorsi di configurazione.
## Come funziona
Il codice di WeChat non si trova nel repository core di OpenClaw. OpenClaw fornisce il
contratto generico del Plugin di canale, e il Plugin esterno fornisce il runtime
specifico per WeChat:
1. `openclaw plugins install` installa `@tencent-weixin/openclaw-weixin`.
2. Il Gateway rileva il manifest del Plugin e carica l'entrypoint del Plugin.
3. Il Plugin registra l'id del canale `openclaw-weixin`.
4. `openclaw channels login --channel openclaw-weixin` avvia il login tramite QR.
5. Il Plugin archivia le credenziali dell'account nella directory di stato di OpenClaw.
6. Quando il Gateway si avvia, il Plugin avvia il monitor Weixin per ogni
account configurato.
7. I messaggi WeChat in ingresso vengono normalizzati tramite il contratto del canale, instradati
all'agente OpenClaw selezionato e inviati di nuovo tramite il percorso in uscita del Plugin.
Questa separazione è importante: il core di OpenClaw deve restare indipendente dal canale. Il login a WeChat,
le chiamate API Tencent iLink, il caricamento/scaricamento dei media, i token di contesto e il
monitoraggio degli account sono di competenza del Plugin esterno.
## Installazione
Installazione rapida:
```bash
npx -y @tencent-weixin/openclaw-weixin-cli install
```
Installazione manuale:
```bash
openclaw plugins install "@tencent-weixin/openclaw-weixin"
openclaw config set plugins.entries.openclaw-weixin.enabled true
```
Riavvia il Gateway dopo l'installazione:
```bash
openclaw gateway restart
```
## Login
Esegui il login tramite QR sulla stessa macchina che esegue il Gateway:
```bash
openclaw channels login --channel openclaw-weixin
```
Scansiona il codice QR con WeChat sul telefono e conferma il login. Il Plugin salva
localmente il token dell'account dopo una scansione riuscita.
Per aggiungere un altro account WeChat, esegui di nuovo lo stesso comando di login. Per più
account, isola le sessioni dei messaggi diretti per account, canale e mittente:
```bash
openclaw config set session.dmScope per-account-channel-peer
```
## Controllo degli accessi
I messaggi diretti usano il normale modello OpenClaw di abbinamento e allowlist per i Plugin
di canale.
Approva nuovi mittenti:
```bash
openclaw pairing list openclaw-weixin
openclaw pairing approve openclaw-weixin <CODE>
```
Per il modello completo di controllo degli accessi, vedi [Pairing](/it/channels/pairing).
## Compatibilità
Il Plugin controlla la versione host di OpenClaw all'avvio.
| Linea del Plugin | Versione OpenClaw | Tag npm |
| ---------------- | ---------------------- | -------- |
| `2.x` | `>=2026.3.22` | `latest` |
| `1.x` | `>=2026.1.0 <2026.3.22` | `legacy` |
Se il Plugin segnala che la tua versione di OpenClaw è troppo vecchia, aggiorna
OpenClaw oppure installa la linea legacy del Plugin:
```bash
openclaw plugins install @tencent-weixin/openclaw-weixin@legacy
```
## Processo sidecar
Il Plugin WeChat può eseguire lavoro di supporto accanto al Gateway mentre monitora l'API
Tencent iLink. Nel problema #68451, questo percorso di supporto ha esposto un bug nella
pulizia generica dei Gateway obsoleti di OpenClaw: un processo figlio poteva tentare di ripulire il
processo Gateway padre, causando cicli di riavvio in gestori di processo come systemd.
L'attuale pulizia all'avvio di OpenClaw esclude il processo corrente e i suoi antenati,
quindi un helper di canale non deve terminare il Gateway che lo ha avviato. Questa correzione è
generica; non è un percorso specifico di WeChat nel core.
## Risoluzione dei problemi
Controlla installazione e stato:
```bash
openclaw plugins list
openclaw channels status --probe
openclaw --version
```
Se il canale risulta installato ma non si connette, conferma che il Plugin sia
abilitato e riavvia:
```bash
openclaw config set plugins.entries.openclaw-weixin.enabled true
openclaw gateway restart
```
Se il Gateway si riavvia ripetutamente dopo aver abilitato WeChat, aggiorna sia OpenClaw sia
il Plugin:
```bash
npm view @tencent-weixin/openclaw-weixin version
openclaw plugins install "@tencent-weixin/openclaw-weixin" --force
openclaw gateway restart
```
Disabilitazione temporanea:
```bash
openclaw config set plugins.entries.openclaw-weixin.enabled false
openclaw gateway restart
```
## Documentazione correlata
- Panoramica dei canali: [Chat Channels](/it/channels)
- Pairing: [Pairing](/it/channels/pairing)
- Instradamento dei canali: [Channel Routing](/it/channels/channel-routing)
- Architettura dei Plugin: [Plugin Architecture](/it/plugins/architecture)
- SDK del Plugin di canale: [Channel Plugin SDK](/it/plugins/sdk-channel-plugins)
- Pacchetto esterno: [@tencent-weixin/openclaw-weixin](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin)

369
docs/it/concepts/active-memory.md
View File

@ -2,35 +2,29 @@
read_when:
- Vuoi capire a cosa serve Active Memory
- Vuoi attivare Active Memory per un agente conversazionale
- Vuoi regolare il comportamento di Active Memory senza abilitarla ovunque
summary: Un sottoagente di memoria bloccante di proprietà del Plugin che inietta la memoria pertinente nelle sessioni di chat interattive
- Vuoi regolare il comportamento di Active Memory senza abilitarlo ovunque
summary: Un sotto-agente di memoria di blocco gestito dal Plugin che inietta memoria pertinente nelle sessioni di chat interattive
title: Active Memory
x-i18n:
generated_at: "2026-04-16T08:18:36Z"
generated_at: "2026-04-19T01:11:10Z"
model: gpt-5.4
provider: openai
source_hash: ab36c5fea1578348cc2258ea3b344cc7bdc814f337d659cdb790512b3ea45473
source_hash: 30fb5d12f1f2e3845d95b90925814faa5c84240684ebd4325c01598169088432
source_path: concepts/active-memory.md
workflow: 15
---
# Active Memory
Active Memory è un sottoagente di memoria bloccante opzionale di proprietà del Plugin che viene eseguito
prima della risposta principale per le sessioni conversazionali idonee.
Active Memory è un sotto-agente di memoria di blocco opzionale gestito dal Plugin che viene eseguito prima della risposta principale per le sessioni conversazionali idonee.
Esiste perché la maggior parte dei sistemi di memoria è capace ma reattiva. Si affida
all'agente principale per decidere quando cercare nella memoria, oppure all'utente per dire cose
come "ricorda questo" o "cerca nella memoria". A quel punto, il momento in cui la memoria avrebbe
reso la risposta naturale è già passato.
Esiste perché la maggior parte dei sistemi di memoria è capace ma reattiva. Si affida all'agente principale per decidere quando cercare nella memoria, oppure all'utente per dire cose come "ricorda questo" o "cerca nella memoria". A quel punto, il momento in cui la memoria avrebbe reso naturale la risposta è già passato.
Active Memory offre al sistema un'unica opportunità limitata di far emergere la memoria pertinente
prima che venga generata la risposta principale.
Active Memory offre al sistema un'occasione limitata per far emergere memoria pertinente prima che venga generata la risposta principale.
## Incolla questo nel tuo agente
Incolla questo nel tuo agente se vuoi che abiliti Active Memory con una configurazione
autosufficiente e sicura per impostazione predefinita:
Incolla questo nel tuo agente se vuoi abilitare Active Memory con una configurazione autonoma e con impostazioni predefinite sicure:
```json5
{
@ -56,9 +50,7 @@ autosufficiente e sicura per impostazione predefinita:
}
```
Questo attiva il Plugin per l'agente `main`, lo mantiene limitato per impostazione predefinita alle
sessioni in stile messaggio diretto, gli consente prima di ereditare il modello della sessione corrente
e usa il modello di fallback configurato solo se non è disponibile alcun modello esplicito o ereditato.
Questo attiva il plugin per l'agente `main`, lo mantiene limitato per impostazione predefinita alle sessioni in stile messaggio diretto, gli consente prima di ereditare il modello della sessione corrente e usa il modello di fallback configurato solo se non è disponibile alcun modello esplicito o ereditato.
Dopo, riavvia il Gateway:
@ -77,8 +69,8 @@ Per ispezionarlo in tempo reale in una conversazione:
La configurazione più sicura è:
1. abilitare il Plugin
2. scegliere come target un agente conversazionale
1. abilitare il plugin
2. scegliere come destinazione un agente conversazionale
3. mantenere il logging attivo solo durante la regolazione
Inizia con questo in `openclaw.json`:
@ -114,22 +106,19 @@ openclaw gateway
Cosa significa:
- `plugins.entries.active-memory.enabled: true` attiva il Plugin
- `plugins.entries.active-memory.enabled: true` attiva il plugin
- `config.agents: ["main"]` abilita Active Memory solo per l'agente `main`
- `config.allowedChatTypes: ["direct"]` mantiene Active Memory attivo per impostazione predefinita solo per le sessioni in stile messaggio diretto
- se `config.model` non è impostato, Active Memory eredita prima il modello della sessione corrente
- `config.modelFallback` fornisce facoltativamente il tuo provider/modello di fallback per il recupero
- `config.promptStyle: "balanced"` usa lo stile di prompt predefinito per uso generale per la modalità `recent`
- Active Memory viene comunque eseguito solo nelle sessioni di chat persistenti interattive idonee
- Active Memory viene comunque eseguito solo su sessioni di chat interattive persistenti idonee
## Consigli sulla velocità
La configurazione più semplice è lasciare `config.model` non impostato e lasciare che Active Memory usi
lo stesso modello che già usi per le risposte normali. Questa è l'impostazione predefinita più sicura
perché segue le tue preferenze esistenti di provider, autenticazione e modello.
La configurazione più semplice è lasciare `config.model` non impostato e consentire ad Active Memory di usare lo stesso modello che già usi per le risposte normali. Questa è l'impostazione predefinita più sicura perché segue le tue preferenze esistenti per provider, autenticazione e modello.
Se vuoi che Active Memory sembri più veloce, usa un modello di inferenza dedicato
invece di riutilizzare il modello principale della chat.
Se vuoi che Active Memory sembri più veloce, usa un modello di inferenza dedicato invece di prendere in prestito il modello della chat principale.
Esempio di configurazione con provider veloce:
@ -156,20 +145,19 @@ plugins: {
}
```
Opzioni di modello veloce da prendere in considerazione:
Opzioni di modello veloce da considerare:
- `cerebras/gpt-oss-120b` per un modello di recupero dedicato e veloce con una superficie degli strumenti ridotta
- `cerebras/gpt-oss-120b` per un modello di recupero dedicato veloce con una superficie di strumenti ristretta
- il tuo normale modello di sessione, lasciando `config.model` non impostato
- un modello di fallback a bassa latenza come `google/gemini-3-flash` quando vuoi un modello di recupero separato senza cambiare il tuo modello principale della chat
- un modello di fallback a bassa latenza come `google/gemini-3-flash` quando vuoi un modello di recupero separato senza cambiare il tuo modello principale di chat
Perché Cerebras è una valida opzione orientata alla velocità per Active Memory:
- la superficie degli strumenti di Active Memory è ridotta: chiama solo `memory_search` e `memory_get`
- la superficie di strumenti di Active Memory è ristretta: chiama solo `memory_search` e `memory_get`
- la qualità del recupero conta, ma la latenza conta più che nel percorso della risposta principale
- un provider veloce dedicato evita di legare la latenza del recupero della memoria al tuo provider principale della chat
- un provider veloce dedicato evita di vincolare la latenza del recupero della memoria al tuo provider principale di chat
Se non vuoi un modello separato ottimizzato per la velocità, lascia `config.model` non impostato
e lascia che Active Memory erediti il modello della sessione corrente.
Se non vuoi un modello separato ottimizzato per la velocità, lascia `config.model` non impostato e consenti ad Active Memory di ereditare il modello della sessione corrente.
### Configurazione di Cerebras
@ -188,7 +176,7 @@ models: {
}
```
Poi fai puntare Active Memory a quel modello:
Poi indirizza Active Memory verso di essa:
```json5
plugins: {
@ -205,18 +193,15 @@ plugins: {
Avvertenza:
- assicurati che la chiave API di Cerebras abbia effettivamente accesso al modello che scegli, perché la sola visibilità di `/v1/models` non garantisce l'accesso a `chat/completions`
- assicurati che la chiave API di Cerebras abbia davvero accesso al modello che scegli, perché la sola visibilità di `/v1/models` non garantisce l'accesso a `chat/completions`
## Come vederlo
Active Memory inietta un prefisso di prompt nascosto non attendibile per il modello. Non
espone i tag grezzi `<active_memory_plugin>...</active_memory_plugin>` nella normale
risposta visibile al client.
Active Memory inietta un prefisso di prompt nascosto e non attendibile per il modello. Non espone tag grezzi `<active_memory_plugin>...</active_memory_plugin>` nella normale risposta visibile al client.
## Attivazione/disattivazione della sessione
Usa il comando del Plugin quando vuoi sospendere o riprendere Active Memory per la
sessione di chat corrente senza modificare la configurazione:
Usa il comando del plugin quando vuoi mettere in pausa o riprendere Active Memory per la sessione di chat corrente senza modificare la configurazione:
```text
/active-memory status
@ -224,12 +209,11 @@ sessione di chat corrente senza modificare la configurazione:
/active-memory on
```
Questo vale per la sessione corrente. Non modifica
`plugins.entries.active-memory.enabled`, il targeting dell'agente o altre
Questo è limitato alla sessione. Non modifica
`plugins.entries.active-memory.enabled`, la selezione dell'agente o altre
configurazioni globali.
Se vuoi che il comando scriva la configurazione e sospenda o riprenda Active Memory per
tutte le sessioni, usa la forma globale esplicita:
Se vuoi che il comando scriva la configurazione e metta in pausa o riprenda Active Memory per tutte le sessioni, usa la forma globale esplicita:
```text
/active-memory status --global
@ -238,30 +222,23 @@ tutte le sessioni, usa la forma globale esplicita:
```
La forma globale scrive `plugins.entries.active-memory.config.enabled`. Lascia
`plugins.entries.active-memory.enabled` attivo così il comando rimane disponibile per
riattivare Active Memory in seguito.
`plugins.entries.active-memory.enabled` attivo così che il comando rimanga disponibile per riattivare Active Memory in seguito.
Se vuoi vedere cosa sta facendo Active Memory in una sessione attiva, attiva le
opzioni della sessione che corrispondono all'output che vuoi:
Se vuoi vedere cosa sta facendo Active Memory in una sessione in tempo reale, attiva le opzioni della sessione che corrispondono all'output che vuoi:
```text
/verbose on
/trace on
```
Con queste opzioni abilitate, OpenClaw può mostrare:
Con queste abilitate, OpenClaw può mostrare:
- una riga di stato di Active Memory come `Active Memory: status=ok elapsed=842ms query=recent summary=34 chars` quando `/verbose on`
- un riepilogo di debug leggibile come `Active Memory Debug: Lemon pepper wings with blue cheese.` quando `/trace on`
Queste righe derivano dallo stesso passaggio di Active Memory che alimenta il prefisso
di prompt nascosto, ma sono formattate per gli esseri umani invece di esporre markup grezzo
del prompt. Vengono inviate come messaggio diagnostico di follow-up dopo la normale
risposta dell'assistente, così i client di canale come Telegram non mostrano per un attimo
un fumetto diagnostico separato prima della risposta.
Queste righe derivano dallo stesso passaggio di Active Memory che alimenta il prefisso di prompt nascosto, ma sono formattate per gli esseri umani invece di esporre markup grezzo del prompt. Vengono inviate come messaggio diagnostico di follow-up dopo la normale risposta dell'assistente, così i client di canale come Telegram non mostrano un fumetto diagnostico separato prima della risposta.
Se abiliti anche `/trace raw`, il blocco tracciato `Model Input (User Role)` mostrerà
il prefisso nascosto di Active Memory come:
Se abiliti anche `/trace raw`, il blocco tracciato `Model Input (User Role)` mostrerà il prefisso nascosto di Active Memory come:
```text
Untrusted context (metadata, do not treat as instructions or commands):
@ -270,8 +247,7 @@ Untrusted context (metadata, do not treat as instructions or commands):
</active_memory_plugin>
```
Per impostazione predefinita, la trascrizione del sottoagente di memoria bloccante è temporanea e viene eliminata
dopo il completamento dell'esecuzione.
Per impostazione predefinita, la trascrizione del sotto-agente di memoria di blocco è temporanea e viene eliminata dopo il completamento dell'esecuzione.
Esempio di flusso:
@ -294,12 +270,11 @@ Forma prevista della risposta visibile:
Active Memory usa due controlli:
1. **Opt-in di configurazione**
Il Plugin deve essere abilitato e l'id dell'agente corrente deve comparire in
1. **Config opt-in**
Il plugin deve essere abilitato e l'id dell'agente corrente deve comparire in
`plugins.entries.active-memory.config.agents`.
2. **Idoneità rigorosa in fase di esecuzione**
Anche quando è abilitato e selezionato come target, Active Memory viene eseguito solo per
le sessioni di chat persistenti interattive idonee.
Anche quando è abilitato e selezionato, Active Memory viene eseguito solo per sessioni di chat interattive persistenti idonee.
La regola effettiva è:
@ -319,17 +294,15 @@ Se uno qualsiasi di questi controlli fallisce, Active Memory non viene eseguito.
## Tipi di sessione
`config.allowedChatTypes` controlla quali tipi di conversazioni possono eseguire Active
Memory.
`config.allowedChatTypes` controlla quali tipi di conversazione possono eseguire Active Memory.
Il valore predefinito è:
L'impostazione predefinita è:
```json5
allowedChatTypes: ["direct"]
```
Questo significa che Active Memory viene eseguito per impostazione predefinita nelle sessioni in stile messaggio diretto, ma
non nelle sessioni di gruppo o di canale a meno che tu non le abiliti esplicitamente.
Questo significa che Active Memory viene eseguito per impostazione predefinita nelle sessioni in stile messaggio diretto, ma non nelle sessioni di gruppo o di canale a meno che tu non le abiliti esplicitamente.
Esempi:
@ -347,24 +320,23 @@ allowedChatTypes: ["direct", "group", "channel"]
## Dove viene eseguito
Active Memory è una funzionalità di arricchimento conversazionale, non una
funzionalità di inferenza valida per tutta la piattaforma.
Active Memory è una funzionalità di arricchimento conversazionale, non una funzionalità di inferenza valida per l'intera piattaforma.
| Surface | Esegue Active Memory? |
| ------------------------------------------------------------------- | ------------------------------------------------------ |
| Control UI / sessioni persistenti della chat web | Sì, se il Plugin è abilitato e l'agente è selezionato come target |
| Altre sessioni di canale interattive sullo stesso percorso di chat persistente | Sì, se il Plugin è abilitato e l'agente è selezionato come target |
| Esecuzioni headless one-shot | No |
| Esecuzioni Heartbeat/in background | No |
| Percorsi interni generici `agent-command` | No |
| Esecuzione interna del sottoagente/helper | No |
| Surface | Active Memory viene eseguito? |
| ------------------------------------------------------------------- | ------------------------------------------------------- |
| Sessioni persistenti di Control UI / chat web | Sì, se il plugin è abilitato e l'agente è selezionato |
| Altre sessioni di canale interattive sullo stesso percorso di chat persistente | Sì, se il plugin è abilitato e l'agente è selezionato |
| Esecuzioni headless una tantum | No |
| Esecuzioni Heartbeat/in background | No |
| Percorsi interni `agent-command` generici | No |
| Esecuzione di sotto-agenti/helper interni | No |
## Perché usarlo
Usa Active Memory quando:
- la sessione è persistente e visibile all'utente
- l'agente ha una memoria a lungo termine significativa in cui cercare
- la sessione è persistente e rivolta all'utente
- l'agente ha una memoria a lungo termine significativa da cercare
- continuità e personalizzazione contano più del puro determinismo del prompt
Funziona particolarmente bene per:
@ -377,12 +349,12 @@ Funziona particolarmente bene per:
- automazione
- worker interni
- attività API one-shot
- attività API una tantum
- contesti in cui una personalizzazione nascosta sarebbe sorprendente
## Come funziona
La struttura in esecuzione è:
La struttura di esecuzione è:
```mermaid
flowchart LR
@ -393,7 +365,7 @@ flowchart LR
I --> M["Main Reply"]
```
Il sottoagente di memoria bloccante può usare solo:
Il sotto-agente di memoria di blocco può usare solo:
- `memory_search`
- `memory_get`
@ -402,19 +374,19 @@ Se la connessione è debole, dovrebbe restituire `NONE`.
## Modalità di query
`config.queryMode` controlla quanta parte della conversazione vede il sottoagente di memoria bloccante.
`config.queryMode` controlla quanta parte della conversazione vede il sotto-agente di memoria di blocco.
## Stili di prompt
`config.promptStyle` controlla quanto il sottoagente di memoria bloccante sia
propenso o rigoroso nel decidere se restituire memoria.
`config.promptStyle` controlla quanto il sotto-agente di memoria di blocco sia incline o rigoroso
nel decidere se restituire memoria.
Stili disponibili:
- `balanced`: impostazione predefinita per uso generale per la modalità `recent`
- `strict`: il meno propenso; ideale quando vuoi pochissima influenza dal contesto vicino
- `strict`: il meno incline; ideale quando vuoi pochissima influenza dal contesto vicino
- `contextual`: il più favorevole alla continuità; ideale quando la cronologia della conversazione dovrebbe contare di più
- `recall-heavy`: più incline a far emergere memoria su corrispondenze più deboli ma comunque plausibili
- `recall-heavy`: più disposto a far emergere memoria anche su corrispondenze meno forti ma comunque plausibili
- `precision-heavy`: preferisce in modo aggressivo `NONE` a meno che la corrispondenza non sia evidente
- `preference-only`: ottimizzato per preferiti, abitudini, routine, gusti e fatti personali ricorrenti
@ -426,7 +398,7 @@ recent -> balanced
full -> contextual
```
Se imposti `config.promptStyle` esplicitamente, quell'override ha la precedenza.
Se imposti `config.promptStyle` esplicitamente, quella sostituzione ha la priorità.
Esempio:
@ -445,7 +417,7 @@ explicit plugin model
-> optional configured fallback model
```
`config.modelFallback` controlla il passaggio del fallback configurato.
`config.modelFallback` controlla il passaggio di fallback configurato.
Fallback personalizzato facoltativo:
@ -453,48 +425,41 @@ Fallback personalizzato facoltativo:
modelFallback: "google/gemini-3-flash"
```
Se non viene risolto alcun modello esplicito, ereditato o di fallback configurato, Active Memory
salta il recupero per quel turno.
Se non viene risolto alcun modello esplicito, ereditato o di fallback configurato, Active Memory salta il recupero per quel turno.
`config.modelFallbackPolicy` viene mantenuto solo come campo di compatibilità deprecato
per le configurazioni meno recenti. Non modifica più il comportamento in fase di esecuzione.
`config.modelFallbackPolicy` viene mantenuto solo come campo di compatibilità deprecato per configurazioni meno recenti. Non modifica più il comportamento in fase di esecuzione.
## Meccanismi avanzati di emergenza
Queste opzioni intenzionalmente non fanno parte della configurazione consigliata.
Queste opzioni non fanno intenzionalmente parte della configurazione consigliata.
`config.thinking` può sovrascrivere il livello di ragionamento del sottoagente di memoria bloccante:
`config.thinking` può sovrascrivere il livello di thinking del sotto-agente di memoria di blocco:
```json5
thinking: "medium"
```
Valore predefinito:
Impostazione predefinita:
```json5
thinking: "off"
```
Non abilitarlo per impostazione predefinita. Active Memory viene eseguito nel percorso della risposta, quindi il tempo di
ragionamento aggiuntivo aumenta direttamente la latenza visibile all'utente.
Non abilitarlo per impostazione predefinita. Active Memory viene eseguito nel percorso della risposta, quindi tempo di thinking aggiuntivo aumenta direttamente la latenza visibile all'utente.
`config.promptAppend` aggiunge istruzioni extra dell'operatore dopo il prompt predefinito di Active
Memory e prima del contesto della conversazione:
`config.promptAppend` aggiunge istruzioni operative extra dopo il prompt predefinito di Active Memory e prima del contesto della conversazione:
```json5
promptAppend: "Prefer stable long-term preferences over one-off events."
```
`config.promptOverride` sostituisce il prompt predefinito di Active Memory. OpenClaw
aggiunge comunque il contesto della conversazione in seguito:
`config.promptOverride` sostituisce il prompt predefinito di Active Memory. OpenClaw aggiunge comunque il contesto della conversazione in seguito:
```json5
promptOverride: "You are a memory search agent. Return NONE or one compact user fact."
```
La personalizzazione del prompt non è consigliata a meno che tu non stia testando deliberatamente un
contratto di recupero diverso. Il prompt predefinito è ottimizzato per restituire `NONE`
oppure un contesto compatto di fatti dell'utente per il modello principale.
La personalizzazione del prompt non è consigliata a meno che tu non stia deliberatamente testando un contratto di recupero diverso. Il prompt predefinito è ottimizzato per restituire `NONE` oppure un contesto compatto di fatti utente per il modello principale.
### `message`
@ -504,11 +469,11 @@ Viene inviato solo l'ultimo messaggio dell'utente.
Latest user message only
```
Usa questa modalità quando:
Usalo quando:
- vuoi il comportamento più veloce
- vuoi il bias più forte verso il recupero di preferenze stabili
- i turni successivi non richiedono contesto conversazionale
- i turni successivi non hanno bisogno del contesto conversazionale
Timeout consigliato:
@ -528,10 +493,10 @@ Latest user message:
...
```
Usa questa modalità quando:
Usalo quando:
- vuoi un miglior equilibrio tra velocità e ancoraggio conversazionale
- le domande di follow-up dipendono spesso dagli ultimi pochi turni
- vuoi un miglior equilibrio tra velocità e radicamento conversazionale
- le domande di follow-up dipendono spesso dagli ultimi turni
Timeout consigliato:
@ -539,7 +504,7 @@ Timeout consigliato:
### `full`
L'intera conversazione viene inviata al sottoagente di memoria bloccante.
L'intera conversazione viene inviata al sotto-agente di memoria di blocco.
```text
Full conversation context:
@ -549,15 +514,15 @@ user: ...
...
```
Usa questa modalità quando:
Usalo quando:
- la massima qualità di recupero conta più della latenza
- la conversazione contiene una configurazione importante molto indietro nel thread
- la migliore qualità di recupero possibile conta più della latenza
- la conversazione contiene impostazioni importanti molto indietro nel thread
Timeout consigliato:
- aumentalo in modo sostanziale rispetto a `message` o `recent`
- inizia intorno a `15000` ms o più, a seconda della dimensione del thread
- inizia intorno a `15000` ms o più in alto, a seconda della dimensione del thread
In generale, il timeout dovrebbe aumentare con la dimensione del contesto:
@ -565,19 +530,17 @@ In generale, il timeout dovrebbe aumentare con la dimensione del contesto:
message < recent < full
```
## Persistenza della trascrizione
## Persistenza delle trascrizioni
Le esecuzioni del sottoagente di memoria bloccante di Active Memory creano una vera trascrizione `session.jsonl`
durante la chiamata del sottoagente di memoria bloccante.
Le esecuzioni del sotto-agente di memoria di blocco di Active Memory creano una vera trascrizione `session.jsonl` durante la chiamata del sotto-agente di memoria di blocco.
Per impostazione predefinita, quella trascrizione è temporanea:
Per impostazione predefinita, questa trascrizione è temporanea:
- viene scritta in una directory temporanea
- viene usata solo per l'esecuzione del sottoagente di memoria bloccante
- viene eliminata subito dopo la fine dell'esecuzione
- viene usata solo per l'esecuzione del sotto-agente di memoria di blocco
- viene eliminata immediatamente dopo la fine dell'esecuzione
Se vuoi mantenere su disco queste trascrizioni del sottoagente di memoria bloccante per il debug o
l'ispezione, attiva esplicitamente la persistenza:
Se vuoi mantenere su disco queste trascrizioni del sotto-agente di memoria di blocco per debugging o ispezione, attiva esplicitamente la persistenza:
```json5
{
@ -596,11 +559,9 @@ l'ispezione, attiva esplicitamente la persistenza:
}
```
Quando è abilitato, Active Memory archivia le trascrizioni in una directory separata nella
cartella delle sessioni dell'agente di destinazione, non nel percorso principale della trascrizione
della conversazione dell'utente.
Quando abilitato, Active Memory archivia le trascrizioni in una directory separata sotto la cartella delle sessioni dell'agente di destinazione, non nel percorso principale della trascrizione della conversazione utente.
La disposizione predefinita è concettualmente:
La struttura predefinita è concettualmente:
```text
agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl
@ -608,15 +569,15 @@ agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jso
Puoi cambiare la sottodirectory relativa con `config.transcriptDir`.
Usa questa opzione con cautela:
Usalo con cautela:
- le trascrizioni del sottoagente di memoria bloccante possono accumularsi rapidamente nelle sessioni molto attive
- la modalità di query `full` può duplicare molto contesto conversazionale
- le trascrizioni del sotto-agente di memoria di blocco possono accumularsi rapidamente nelle sessioni molto attive
- la modalità di query `full` può duplicare molto contesto della conversazione
- queste trascrizioni contengono contesto di prompt nascosto e memorie recuperate
## Configurazione
Tutta la configurazione di Active Memory si trova in:
Tutta la configurazione di Active Memory si trova sotto:
```text
plugins.entries.active-memory
@ -624,32 +585,32 @@ plugins.entries.active-memory
I campi più importanti sono:
| Key | Type | Meaning |
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `enabled` | `boolean` | Abilita il Plugin stesso |
| `config.agents` | `string[]` | Id agente che possono usare Active Memory |
| `config.model` | `string` | Riferimento facoltativo al modello del sottoagente di memoria bloccante; se non impostato, Active Memory usa il modello della sessione corrente |
| `config.queryMode` | `"message" \| "recent" \| "full"` | Controlla quanta parte della conversazione vede il sottoagente di memoria bloccante |
| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controlla quanto il sottoagente di memoria bloccante sia propenso o rigoroso nel decidere se restituire memoria |
| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Sovrascrittura avanzata del ragionamento per il sottoagente di memoria bloccante; valore predefinito `off` per la velocità |
| `config.promptOverride` | `string` | Sostituzione avanzata completa del prompt; non consigliata per l'uso normale |
| `config.promptAppend` | `string` | Istruzioni extra avanzate aggiunte al prompt predefinito o sovrascritto |
| `config.timeoutMs` | `number` | Timeout rigido per il sottoagente di memoria bloccante |
| `config.maxSummaryChars` | `number` | Numero massimo totale di caratteri consentiti nel riepilogo active-memory |
| `config.logging` | `boolean` | Emette log di Active Memory durante la regolazione |
| `config.persistTranscripts` | `boolean` | Mantiene su disco le trascrizioni del sottoagente di memoria bloccante invece di eliminare i file temporanei |
| `config.transcriptDir` | `string` | Directory relativa delle trascrizioni del sottoagente di memoria bloccante nella cartella delle sessioni dell'agente |
| Key | Type | Significato |
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `enabled` | `boolean` | Abilita il plugin stesso |
| `config.agents` | `string[]` | ID degli agenti che possono usare Active Memory |
| `config.model` | `string` | Riferimento facoltativo al modello del sotto-agente di memoria di blocco; se non impostato, Active Memory usa il modello della sessione corrente |
| `config.queryMode` | `"message" \| "recent" \| "full"` | Controlla quanta parte della conversazione vede il sotto-agente di memoria di blocco |
| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controlla quanto il sotto-agente di memoria di blocco sia incline o rigoroso nel decidere se restituire memoria |
| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Sovrascrittura avanzata del thinking per il sotto-agente di memoria di blocco; predefinito `off` per la velocità |
| `config.promptOverride` | `string` | Sostituzione avanzata completa del prompt; non consigliata per l'uso normale |
| `config.promptAppend` | `string` | Istruzioni extra avanzate aggiunte al prompt predefinito o sovrascritto |
| `config.timeoutMs` | `number` | Timeout rigido per il sotto-agente di memoria di blocco, limitato a 120000 ms |
| `config.maxSummaryChars` | `number` | Numero massimo totale di caratteri consentiti nel riepilogo di active-memory |
| `config.logging` | `boolean` | Emette log di Active Memory durante la regolazione |
| `config.persistTranscripts` | `boolean` | Mantiene su disco le trascrizioni del sotto-agente di memoria di blocco invece di eliminare i file temporanei |
| `config.transcriptDir` | `string` | Directory relativa delle trascrizioni del sotto-agente di memoria di blocco sotto la cartella delle sessioni dell'agente |
Campi utili per la regolazione:
| Key | Type | Meaning |
| ----------------------------- | -------- | ------------------------------------------------------------- |
| `config.maxSummaryChars` | `number` | Numero massimo totale di caratteri consentiti nel riepilogo active-memory |
| Key | Type | Significato |
| ----------------------------- | -------- | --------------------------------------------------------------- |
| `config.maxSummaryChars` | `number` | Numero massimo totale di caratteri consentiti nel riepilogo di active-memory |
| `config.recentUserTurns` | `number` | Turni utente precedenti da includere quando `queryMode` è `recent` |
| `config.recentAssistantTurns` | `number` | Turni assistente precedenti da includere quando `queryMode` è `recent` |
| `config.recentUserChars` | `number` | Numero massimo di caratteri per ciascun turno utente recente |
| `config.recentAssistantChars` | `number` | Numero massimo di caratteri per ciascun turno assistente recente |
| `config.cacheTtlMs` | `number` | Riutilizzo della cache per query identiche ripetute |
| `config.recentUserChars` | `number` | Numero massimo di caratteri per turno utente recente |
| `config.recentAssistantChars` | `number` | Numero massimo di caratteri per turno assistente recente |
| `config.cacheTtlMs` | `number` | Riutilizzo della cache per query identiche ripetute |
## Configurazione consigliata
@ -675,25 +636,22 @@ Inizia con `recent`.
}
```
Se vuoi ispezionare il comportamento in tempo reale durante la regolazione, usa `/verbose on` per la
normale riga di stato e `/trace on` per il riepilogo di debug di active-memory invece
di cercare un comando di debug separato per active-memory. Nei canali di chat, quelle
righe diagnostiche vengono inviate dopo la risposta principale dell'assistente invece che prima.
Se vuoi ispezionare il comportamento in tempo reale durante la regolazione, usa `/verbose on` per la normale riga di stato e `/trace on` per il riepilogo di debug di active-memory invece di cercare un comando di debug separato per active-memory. Nei canali chat, quelle righe diagnostiche vengono inviate dopo la risposta principale dell'assistente invece che prima.
Poi passa a:
- `message` se vuoi una latenza inferiore
- `full` se decidi che il contesto aggiuntivo vale la lentezza del sottoagente di memoria bloccante
- `full` se decidi che un contesto aggiuntivo vale la lentezza del sotto-agente di memoria di blocco
## Debugging
Se Active Memory non appare dove te lo aspetti:
1. Conferma che il Plugin sia abilitato in `plugins.entries.active-memory.enabled`.
1. Conferma che il plugin sia abilitato in `plugins.entries.active-memory.enabled`.
2. Conferma che l'id dell'agente corrente sia elencato in `config.agents`.
3. Conferma che il test avvenga tramite una sessione di chat persistente interattiva.
3. Conferma di stare testando attraverso una sessione di chat interattiva persistente.
4. Attiva `config.logging: true` e osserva i log del Gateway.
5. Verifica che la ricerca in memoria funzioni con `openclaw memory status --deep`.
5. Verifica che la ricerca nella memoria stessa funzioni con `openclaw memory status --deep`.
Se i risultati della memoria sono rumorosi, restringi:
@ -708,59 +666,40 @@ Se Active Memory è troppo lento:
## Problemi comuni
### Il provider di embedding è cambiato in modo imprevisto
### Il provider di embedding è cambiato inaspettatamente
Active Memory usa la normale pipeline `memory_search` in
`agents.defaults.memorySearch`. Questo significa che la configurazione del provider di embedding è un
requisito solo quando la tua configurazione `memorySearch` richiede embedding per il comportamento
che desideri.
Active Memory usa la normale pipeline `memory_search` sotto
`agents.defaults.memorySearch`. Questo significa che la configurazione del provider di embedding è un requisito solo quando la tua configurazione `memorySearch` richiede embedding per il comportamento che vuoi.
In pratica:
- la configurazione esplicita del provider è **obbligatoria** se vuoi un provider che non venga
rilevato automaticamente, come `ollama`
- la configurazione esplicita del provider è **obbligatoria** se il rilevamento automatico non risolve
alcun provider di embedding utilizzabile per il tuo ambiente
- la configurazione esplicita del provider è **fortemente consigliata** se vuoi una selezione
deterministica del provider invece di "vince il primo disponibile"
- la configurazione esplicita del provider di solito **non è obbligatoria** se il rilevamento automatico già
risolve il provider che desideri e quel provider è stabile nel tuo deployment
- la configurazione esplicita del provider è **obbligatoria** se vuoi un provider che non viene rilevato automaticamente, come `ollama`
- la configurazione esplicita del provider è **obbligatoria** se il rilevamento automatico non risolve alcun provider di embedding utilizzabile per il tuo ambiente
- la configurazione esplicita del provider è **fortemente consigliata** se vuoi una selezione deterministica del provider invece di "vince il primo disponibile"
- la configurazione esplicita del provider di solito **non è obbligatoria** se il rilevamento automatico risolve già il provider che vuoi e quel provider è stabile nella tua distribuzione
Se `memorySearch.provider` non è impostato, OpenClaw rileva automaticamente il primo
provider di embedding disponibile.
Se `memorySearch.provider` non è impostato, OpenClaw rileva automaticamente il primo provider di embedding disponibile.
Questo può creare confusione nei deployment reali:
Questo può creare confusione nelle distribuzioni reali:
- una nuova chiave API disponibile può cambiare quale provider usa la ricerca in memoria
- un comando o una superficie diagnostica possono far sembrare il provider selezionato
diverso dal percorso che stai effettivamente raggiungendo durante la sincronizzazione della memoria in tempo reale o il
bootstrap della ricerca
- i provider ospitati possono fallire con errori di quota o rate limit che compaiono solo
quando Active Memory inizia a eseguire ricerche di recupero prima di ogni risposta
- una chiave API appena disponibile può cambiare quale provider usa la ricerca nella memoria
- un comando o una superficie diagnostica può far sembrare diverso il provider selezionato rispetto al percorso che stai effettivamente raggiungendo durante la sincronizzazione della memoria in tempo reale o il bootstrap della ricerca
- i provider ospitati possono fallire con errori di quota o limitazione della frequenza che emergono solo quando Active Memory inizia a eseguire ricerche di recupero prima di ogni risposta
Active Memory può comunque funzionare senza embedding quando `memory_search` può operare
in modalità degradata solo lessicale, cosa che di solito avviene quando non è possibile risolvere
alcun provider di embedding.
Active Memory può comunque essere eseguito senza embedding quando `memory_search` può operare in modalità degradata solo lessicale, cosa che tipicamente avviene quando non è possibile risolvere alcun provider di embedding.
Non dare per scontato lo stesso fallback in caso di errori in fase di esecuzione del provider, come esaurimento
della quota, rate limit, errori di rete/provider o modelli locali/remoti mancanti dopo che un provider è già stato selezionato.
Non dare per scontato lo stesso fallback in caso di errori del provider in fase di esecuzione, come esaurimento quota, limitazioni della frequenza, errori di rete/provider o modelli locali/remoti mancanti dopo che un provider è già stato selezionato.
In pratica:
- se non è possibile risolvere alcun provider di embedding, `memory_search` può degradare a
un recupero solo lessicale
- se un provider di embedding viene risolto e poi fallisce in fase di esecuzione, OpenClaw
attualmente non garantisce un fallback lessicale per quella richiesta
- se hai bisogno di una selezione deterministica del provider, fissa
`agents.defaults.memorySearch.provider`
- se hai bisogno di failover del provider in caso di errori in fase di esecuzione, configura
`agents.defaults.memorySearch.fallback` esplicitamente
- se non è possibile risolvere alcun provider di embedding, `memory_search` può degradare al recupero solo lessicale
- se un provider di embedding viene risolto e poi fallisce in fase di esecuzione, OpenClaw al momento non garantisce un fallback lessicale per quella richiesta
- se hai bisogno di una selezione deterministica del provider, imposta in modo esplicito `agents.defaults.memorySearch.provider`
- se hai bisogno di failover del provider in caso di errori in fase di esecuzione, configura esplicitamente `agents.defaults.memorySearch.fallback`
Se dipendi da un recupero supportato da embedding, indicizzazione multimodale o da uno specifico
provider locale/remoto, fissa esplicitamente il provider invece di affidarti al
rilevamento automatico.
Se dipendi dal recupero supportato da embedding, dall'indicizzazione multimodale o da un provider locale/remoto specifico, imposta esplicitamente il provider invece di fare affidamento sul rilevamento automatico.
Esempi comuni di configurazione fissa:
Esempi comuni di impostazione esplicita:
OpenAI:
@ -807,8 +746,7 @@ Ollama:
}
```
Se ti aspetti il failover del provider in caso di errori in fase di esecuzione come esaurimento della quota,
fissare solo un provider non basta. Configura anche un fallback esplicito:
Se ti aspetti il failover del provider in caso di errori in fase di esecuzione come esaurimento della quota, impostare esplicitamente un provider da solo non basta. Configura anche un fallback esplicito:
```json5
{
@ -823,24 +761,18 @@ fissare solo un provider non basta. Configura anche un fallback esplicito:
}
```
### Debug dei problemi del provider
### Debugging dei problemi del provider
Se Active Memory è lento, vuoto o sembra cambiare provider in modo imprevisto:
- osserva i log del Gateway mentre riproduci il problema; cerca righe come
`active-memory: ... start|done`, `memory sync failed (search-bootstrap)` o
errori di embedding specifici del provider
- attiva `/trace on` per mostrare nella sessione il riepilogo di debug di Active Memory di proprietà del Plugin
- attiva `/verbose on` se vuoi anche la normale riga di stato `🧩 Active Memory: ...`
dopo ogni risposta
- esegui `openclaw memory status --deep` per ispezionare l'attuale backend di
ricerca in memoria e lo stato dell'indice
- controlla `agents.defaults.memorySearch.provider` e la relativa autenticazione/configurazione per
assicurarti che il provider che ti aspetti sia davvero quello che può essere risolto in fase di esecuzione
- se usi `ollama`, verifica che il modello di embedding configurato sia installato, per
esempio con `ollama list`
- osserva i log del Gateway mentre riproduci il problema; cerca righe come `active-memory: ... start|done`, `memory sync failed (search-bootstrap)` o errori di embedding specifici del provider
- attiva `/trace on` per mostrare nella sessione il riepilogo di debug di Active Memory gestito dal Plugin
- attiva `/verbose on` se vuoi anche la normale riga di stato `🧩 Active Memory: ...` dopo ogni risposta
- esegui `openclaw memory status --deep` per ispezionare il backend corrente di ricerca della memoria e lo stato dell'indice
- controlla `agents.defaults.memorySearch.provider` e l'autenticazione/configurazione correlata per assicurarti che il provider che ti aspetti sia davvero quello che può essere risolto in fase di esecuzione
- se usi `ollama`, verifica che il modello di embedding configurato sia installato, per esempio con `ollama list`
Esempio di ciclo di debug:
Esempio di ciclo di debugging:
```text
1. Start the gateway and watch its logs
@ -879,11 +811,10 @@ Oppure, se vuoi embedding Gemini:
}
```
Dopo aver cambiato il provider, riavvia il Gateway ed esegui un nuovo test con
`/trace on` così la riga di debug di Active Memory rifletta il nuovo percorso di embedding.
Dopo aver cambiato il provider, riavvia il Gateway ed esegui un nuovo test con `/trace on` in modo che la riga di debug di Active Memory rifletta il nuovo percorso di embedding.
## Pagine correlate
- [Memory Search](/it/concepts/memory-search)
- [Ricerca nella memoria](/it/concepts/memory-search)
- [Riferimento della configurazione della memoria](/it/reference/memory-config)
- [Configurazione del Plugin SDK](/it/plugins/sdk-setup)
- [Configurazione di Plugin SDK](/it/plugins/sdk-setup)

40
docs/it/debug/node-issue.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Debug di script di sviluppo solo Node o di errori della modalità watch
- Indagine sugli arresti anomali del loader tsx/esbuild in OpenClaw
summary: Note sugli arresti anomali di Node + tsx "__name is not a function" e soluzioni alternative
- Analisi degli arresti anomali del loader tsx/esbuild in OpenClaw
summary: Note sull'arresto anomalo di Node + tsx "__name is not a function" e soluzioni alternative
title: Arresto anomalo di Node + tsx
x-i18n:
generated_at: "2026-04-05T13:50:55Z"
generated_at: "2026-04-19T01:11:10Z"
model: gpt-5.4
provider: openai
source_hash: f5beab7cdfe7679680f65176234a617293ce495886cfffb151518adfa61dc8dc
source_hash: ca45c795c356ada8f81e75b394ec82743d3d1bf1bbe83a24ec6699946b920f01
source_path: debug/node-issue.md
workflow: 15
---
@ -17,9 +17,9 @@ x-i18n:
## Riepilogo
L'esecuzione di OpenClaw tramite Node con `tsx` fallisce all'avvio con:
L'esecuzione di OpenClaw tramite Node con `tsx` non riesce all'avvio con:
```
```bash
[openclaw] Failed to start CLI: TypeError: __name is not a function
at createSubsystemLogger (.../src/logging/subsystem.ts:203:25)
at .../src/agents/auth-profiles/constants.ts:25:20
@ -36,7 +36,7 @@ Questo è iniziato dopo il passaggio degli script di sviluppo da Bun a `tsx` (co
## Riproduzione (solo Node)
```bash
# nella radice del repo
# nella root del repo
node --version
pnpm install
node --import tsx src/entry.ts status
@ -57,27 +57,27 @@ node --import tsx scripts/repro/tsx-name-repro.ts
## Note / ipotesi
- `tsx` usa esbuild per trasformare TS/ESM. `keepNames` di esbuild emette un helper `__name` e avvolge le definizioni di funzione con `__name(...)`.
- L'arresto anomalo indica che `__name` esiste ma non è una funzione a runtime, il che implica che l'helper manca oppure è stato sovrascritto per questo modulo nel percorso del loader Node 25.
- L'arresto anomalo indica che `__name` esiste ma non è una funzione in fase di runtime, il che implica che l'helper manca o viene sovrascritto per questo modulo nel percorso del loader di Node 25.
- Problemi simili con l'helper `__name` sono stati segnalati in altri consumer di esbuild quando l'helper manca o viene riscritto.
## Cronologia della regressione
- `2871657e` (2026-01-06): gli script sono passati da Bun a tsx per rendere Bun facoltativo.
- `2871657e` (2026-01-06): gli script sono passati da Bun a tsx per rendere Bun opzionale.
- Prima di allora (percorso Bun), `openclaw status` e `gateway:watch` funzionavano.
## Soluzioni alternative
- Usa Bun per gli script di sviluppo (attuale revert temporaneo).
- Usa Node + tsc watch, quindi esegui l'output compilato:
- Usare Bun per gli script di sviluppo (attuale revert temporaneo).
- Usare `tsgo` per il type checking del repo, quindi eseguire l'output compilato:
```bash
pnpm exec tsc --watch --preserveWatchOutput
node --watch openclaw.mjs status
pnpm tsgo
node openclaw.mjs status
```
- Confermato localmente: `pnpm exec tsc -p tsconfig.json` + `node openclaw.mjs status` funziona su Node 25.
- Disabilita `keepNames` di esbuild nel loader TS, se possibile (questo evita l'inserimento dell'helper `__name`); al momento tsx non espone questa opzione.
- Prova Node LTS (22/24) con `tsx` per vedere se il problema è specifico di Node 25.
- Nota storica: qui è stato usato `tsc` durante il debug di questo problema Node/tsx, ma ora i lane di type checking del repo usano `tsgo`.
- Disabilitare `keepNames` di esbuild nel loader TS, se possibile (impedisce l'inserimento dell'helper `__name`); tsx al momento non espone questa opzione.
- Testare Node LTS (22/24) con `tsx` per capire se il problema è specifico di Node 25.
## Riferimenti
@ -85,8 +85,8 @@ node --import tsx scripts/repro/tsx-name-repro.ts
- [https://esbuild.github.io/api/#keep-names](https://esbuild.github.io/api/#keep-names)
- [https://github.com/evanw/esbuild/issues/1031](https://github.com/evanw/esbuild/issues/1031)
## Passi successivi
## Prossimi passi
- Riprodurre su Node 22/24 per confermare la regressione di Node 25.
- Testare `tsx` nightly o bloccare a una versione precedente se esiste una regressione nota.
- Se si riproduce su Node LTS, inviare upstream una riproduzione minima con lo stack trace `__name`.
- Riprodurre su Node 22/24 per confermare una regressione di Node 25.
- Testare `tsx` nightly o fissare una versione precedente se esiste una regressione nota.
- Se si riproduce su Node LTS, aprire un repro minimo upstream con lo stack trace di `__name`.

150
docs/it/install/gcp.md
View File

@ -1,15 +1,15 @@
---
read_when:
- Vuoi OpenClaw in esecuzione 24/7 su GCP
- Vuoi un Gateway sempre attivo di livello production sulla tua VM
- Vuoi pieno controllo su persistenza, binari e comportamento al riavvio
summary: Esegui OpenClaw Gateway 24/7 su una VM GCP Compute Engine (Docker) con stato persistente
- Vuoi che OpenClaw sia in esecuzione 24 ore su 24, 7 giorni su 7 su GCP
- Vuoi un Gateway sempre attivo, di livello production, sulla tua VM
- Vuoi il pieno controllo su persistenza, binari e comportamento di riavvio
summary: Esegui OpenClaw Gateway 24/7 su una VM di GCP Compute Engine (Docker) con stato persistente
title: GCP
x-i18n:
generated_at: "2026-04-05T13:55:50Z"
generated_at: "2026-04-19T01:11:12Z"
model: gpt-5.4
provider: openai
source_hash: 73daaee3de71dad5175f42abf3e11355f2603b2f9e2b2523eac4d4c7015e3ebc
source_hash: 6b4cf7924cbcfae74f268c88caedb79ed87a6ad37f4910ad65d92a5d99fe49c1
source_path: install/gcp.md
workflow: 15
---
@ -18,70 +18,70 @@ x-i18n:
## Obiettivo
Eseguire un Gateway OpenClaw persistente su una VM GCP Compute Engine usando Docker, con stato persistente, binari incorporati e comportamento di riavvio sicuro.
Eseguire un Gateway OpenClaw persistente su una VM GCP Compute Engine usando Docker, con stato persistente, binari integrati nell’immagine e comportamento di riavvio sicuro.
Se vuoi "OpenClaw 24/7 per ~$5-12/mese", questa è una configurazione affidabile su Google Cloud.
Il prezzo varia in base al tipo di macchina e alla regione; scegli la VM più piccola adatta al tuo carico di lavoro e aumenta le risorse se incontri OOM.
Il prezzo varia in base al tipo di macchina e alla regione; scegli la VM più piccola adatta al tuo carico di lavoro e scala verso l’alto se incontri OOM.
## Cosa stiamo facendo (in termini semplici)?
## Cosa stiamo facendo (in parole semplici)?
- Creare un progetto GCP e abilitare la fatturazione
- Creare una VM Compute Engine
- Installare Docker (runtime applicativo isolato)
- Avviare OpenClaw Gateway in Docker
- Rendere persistenti `~/.openclaw` + `~/.openclaw/workspace` sull'host (sopravvive a riavvii/ricostruzioni)
- Accedere alla Control UI dal laptop tramite un tunnel SSH
- Installare Docker (runtime isolato per l’app)
- Avviare il Gateway OpenClaw in Docker
- Rendere persistenti `~/.openclaw` + `~/.openclaw/workspace` sull’host (sopravvivono a riavvii/ricostruzioni)
- Accedere alla Control UI dal tuo laptop tramite un tunnel SSH
Quello stato montato in `~/.openclaw` include `openclaw.json`, per agente
Lo stato montato di `~/.openclaw` include `openclaw.json`, i file per agente
`agents/<agentId>/agent/auth-profiles.json` e `.env`.
È possibile accedere al Gateway tramite:
- inoltro porta SSH dal laptop
- inoltro porta SSH dal tuo laptop
- esposizione diretta della porta se gestisci personalmente firewall e token
Questa guida usa Debian su GCP Compute Engine.
Anche Ubuntu funziona; adatta i pacchetti di conseguenza.
Per il flusso Docker generico, vedi [Docker](/install/docker).
Per il flusso Docker generico, vedi [Docker](/it/install/docker).
---
## Percorso rapido (operatori esperti)
1. Crea un progetto GCP + abilita l'API Compute Engine
1. Crea un progetto GCP + abilita l’API Compute Engine
2. Crea una VM Compute Engine (e2-small, Debian 12, 20GB)
3. Accedi alla VM via SSH
3. Entra nella VM via SSH
4. Installa Docker
5. Clona il repository OpenClaw
6. Crea directory host persistenti
7. Configura `.env` e `docker-compose.yml`
8. Incorpora i binari richiesti, compila e avvia
8. Integra i binari richiesti nell’immagine, compila e avvia
---
## Cosa ti serve
- Account GCP (eleggibile al free tier per e2-micro)
- CLI gcloud installata (oppure usa Cloud Console)
- Accesso SSH dal laptop
- Account GCP (free tier disponibile per e2-micro)
- CLI `gcloud` installata (oppure usa Cloud Console)
- Accesso SSH dal tuo laptop
- Familiarità di base con SSH + copia/incolla
- ~20-30 minuti
- Docker e Docker Compose
- Credenziali di autenticazione del modello
- Credenziali provider facoltative
- Credenziali provider opzionali
- QR WhatsApp
- token bot Telegram
- Gmail OAuth
- OAuth Gmail
---
<Steps>
<Step title="Installa la CLI gcloud (oppure usa Console)">
**Opzione A: CLI gcloud** (consigliata per l'automazione)
**Opzione A: CLI gcloud** (consigliata per l’automazione)
Installa da [https://cloud.google.com/sdk/docs/install](https://cloud.google.com/sdk/docs/install)
Inizializza e autenticati:
Inizializza e autentica:
```bash
gcloud init
@ -90,7 +90,7 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
**Opzione B: Cloud Console**
Tutti i passaggi possono essere eseguiti tramite l'interfaccia web su [https://console.cloud.google.com](https://console.cloud.google.com)
Tutti i passaggi possono essere eseguiti tramite l’interfaccia web su [https://console.cloud.google.com](https://console.cloud.google.com)
</Step>
@ -102,9 +102,9 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
gcloud config set project my-openclaw-project
```
Abilita la fatturazione su [https://console.cloud.google.com/billing](https://console.cloud.google.com/billing) (obbligatoria per Compute Engine).
Abilita la fatturazione su [https://console.cloud.google.com/billing](https://console.cloud.google.com/billing) (necessaria per Compute Engine).
Abilita l'API Compute Engine:
Abilita l’API Compute Engine:
```bash
gcloud services enable compute.googleapis.com
@ -112,10 +112,10 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
**Console:**
1. Vai a IAM e amministrazione > Crea progetto
2. Dagli un nome e crealo
1. Vai su IAM e amministrazione > Crea progetto
2. Assegna un nome e crealo
3. Abilita la fatturazione per il progetto
4. Vai a API e servizi > Abilita API > cerca "Compute Engine API" > Abilita
4. Vai su API e servizi > Abilita API > cerca "Compute Engine API" > Abilita
</Step>
@ -126,7 +126,7 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
| --------- | ------------------------ | ------------------ | -------------------------------------------- |
| e2-medium | 2 vCPU, 4GB RAM | ~$25/mese | Più affidabile per build Docker locali |
| e2-small | 2 vCPU, 2GB RAM | ~$12/mese | Minimo consigliato per build Docker |
| e2-micro | 2 vCPU (condivise), 1GB RAM | Eleggibile al free tier | Spesso fallisce per OOM durante la build Docker (exit 137) |
| e2-micro | 2 vCPU (condivise), 1GB RAM | Free tier disponibile | Spesso fallisce con OOM nelle build Docker (exit 137) |
**CLI:**
@ -141,9 +141,9 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
**Console:**
1. Vai a Compute Engine > Istanze VM > Crea istanza
1. Vai su Compute Engine > Istanze VM > Crea istanza
2. Nome: `openclaw-gateway`
3. Regione: `us-central1`, Zona: `us-central1-a`
3. Regione: `us-central1`, zona: `us-central1-a`
4. Tipo di macchina: `e2-small`
5. Disco di avvio: Debian 12, 20GB
6. Crea
@ -159,7 +159,7 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
**Console:**
Fai clic sul pulsante "SSH" accanto alla tua VM nel pannello di controllo di Compute Engine.
Fai clic sul pulsante "SSH" accanto alla tua VM nella dashboard di Compute Engine.
Nota: la propagazione della chiave SSH può richiedere 1-2 minuti dopo la creazione della VM. Se la connessione viene rifiutata, attendi e riprova.
@ -173,13 +173,13 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
sudo usermod -aG docker $USER
```
Esci e rientra affinché la modifica del gruppo abbia effetto:
Esci e rientra perché la modifica del gruppo abbia effetto:
```bash
exit
```
Poi accedi di nuovo via SSH:
Poi rientra via SSH:
```bash
gcloud compute ssh openclaw-gateway --zone=us-central1-a
@ -200,13 +200,13 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
cd openclaw
```
Questa guida presuppone che compilerai un'immagine personalizzata per garantire la persistenza dei binari.
Questa guida presuppone che tu compili un’immagine personalizzata per garantire la persistenza dei binari.
</Step>
<Step title="Crea directory host persistenti">
I container Docker sono effimeri.
Tutto lo stato a lunga durata deve vivere sull'host.
Tutto lo stato a lunga durata deve risiedere sull’host.
```bash
mkdir -p ~/.openclaw
@ -215,33 +215,36 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
</Step>
<Step title="Configura le variabili d'ambiente">
Crea `.env` nella radice del repository.
<Step title="Configura le variabili d’ambiente">
Crea `.env` nella root del repository.
```bash
OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=change-me-now
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_CONFIG_DIR=/home/$USER/.openclaw
OPENCLAW_WORKSPACE_DIR=/home/$USER/.openclaw/workspace
GOG_KEYRING_PASSWORD=change-me-now
GOG_KEYRING_PASSWORD=
XDG_CONFIG_HOME=/home/node/.openclaw
```
Genera segreti robusti:
Lascia `OPENCLAW_GATEWAY_TOKEN` vuoto a meno che tu non voglia esplicitamente
gestirlo tramite `.env`; OpenClaw scrive un token gateway casuale nella
configurazione al primo avvio. Genera una password per il keyring e incollala in
`GOG_KEYRING_PASSWORD`:
```bash
openssl rand -hex 32
```
**Non salvare questo file nel commit.**
**Non eseguire il commit di questo file.**
Questo file `.env` è per variabili d'ambiente del container/runtime come `OPENCLAW_GATEWAY_TOKEN`.
L'autenticazione memorizzata del provider OAuth/chiave API vive nel mount
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`.
Questo file `.env` è destinato all’ambiente del container/runtime, come `OPENCLAW_GATEWAY_TOKEN`.
L’autenticazione OAuth/API-key dei provider memorizzata si trova in
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json` montato.
</Step>
@ -270,7 +273,7 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
- ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
- ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
ports:
# Consigliato: mantieni il Gateway solo loopback sulla VM; accedi tramite tunnel SSH.
# Consigliato: mantieni il Gateway accessibile solo su loopback nella VM; accedi tramite tunnel SSH.
# Per esporlo pubblicamente, rimuovi il prefisso `127.0.0.1:` e configura il firewall di conseguenza.
- "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
command:
@ -286,24 +289,24 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
]
```
`--allow-unconfigured` serve solo per comodità durante il bootstrap, non sostituisce una corretta configurazione del gateway. Imposta comunque l'autenticazione (`gateway.auth.token` o password) e usa impostazioni di bind sicure per il tuo deployment.
`--allow-unconfigured` serve solo per comodità in fase di bootstrap, non sostituisce una configurazione gateway corretta. Imposta comunque l’autenticazione (`gateway.auth.token` o password) e usa impostazioni di bind sicure per il tuo deployment.
</Step>
<Step title="Passaggi runtime condivisi per Docker su VM">
Usa la guida runtime condivisa per il flusso host Docker comune:
Usa la guida runtime condivisa per il flusso comune dell’host Docker:
- [Incorpora i binari richiesti nell'immagine](/install/docker-vm-runtime#bake-required-binaries-into-the-image)
- [Compila e avvia](/install/docker-vm-runtime#build-and-launch)
- [Cosa persiste e dove](/install/docker-vm-runtime#what-persists-where)
- [Aggiornamenti](/install/docker-vm-runtime#updates)
- [Integra i binari richiesti nell’immagine](/it/install/docker-vm-runtime#bake-required-binaries-into-the-image)
- [Compila e avvia](/it/install/docker-vm-runtime#build-and-launch)
- [Cosa persiste e dove](/it/install/docker-vm-runtime#what-persists-where)
- [Aggiornamenti](/it/install/docker-vm-runtime#updates)
</Step>
<Step title="Note di avvio specifiche per GCP">
Su GCP, se la build fallisce con `Killed` o `exit code 137` durante `pnpm install --frozen-lockfile`, la VM è rimasta senza memoria. Usa almeno `e2-small`, oppure `e2-medium` per build iniziali più affidabili.
Su GCP, se la build fallisce con `Killed` o `exit code 137` durante `pnpm install --frozen-lockfile`, la VM ha esaurito la memoria. Usa almeno `e2-small`, oppure `e2-medium` per build iniziali più affidabili.
Quando fai il bind su LAN (`OPENCLAW_GATEWAY_BIND=lan`), configura un'origine browser fidata prima di continuare:
Quando esegui il bind su LAN (`OPENCLAW_GATEWAY_BIND=lan`), configura un’origine browser attendibile prima di continuare:
```bash
docker compose run --rm openclaw-cli config set gateway.controlUi.allowedOrigins '["http://127.0.0.1:18789"]' --strict-json
@ -324,16 +327,15 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
`http://127.0.0.1:18789/`
Ristampa un link dashboard pulito:
Ristampa un link pulito della dashboard:
```bash
docker compose run --rm openclaw-cli dashboard --no-open
```
Se la UI richiede l'autenticazione con segreto condiviso, incolla il token o la
Se l’interfaccia richiede l’autenticazione con segreto condiviso, incolla il token o la
password configurati nelle impostazioni della Control UI. Questo flusso Docker scrive un token per
impostazione predefinita; se cambi la configurazione del container in autenticazione con password, usa invece quella
password.
impostazione predefinita; se cambi la configurazione del container usando l’autenticazione con password, usa invece quella password.
Se la Control UI mostra `unauthorized` o `disconnected (1008): pairing required`, approva il dispositivo browser:
@ -342,15 +344,15 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
docker compose run --rm openclaw-cli devices approve <requestId>
```
Ti serve di nuovo il riferimento su persistenza condivisa e aggiornamenti?
Vedi [Docker VM Runtime](/install/docker-vm-runtime#what-persists-where) e [Aggiornamenti Docker VM Runtime](/install/docker-vm-runtime#updates).
Hai di nuovo bisogno del riferimento su persistenza condivisa e aggiornamenti?
Vedi [Docker VM Runtime](/it/install/docker-vm-runtime#what-persists-where) e [aggiornamenti Docker VM Runtime](/it/install/docker-vm-runtime#updates).
</Step>
</Steps>
---
## Troubleshooting
## Risoluzione dei problemi
**Connessione SSH rifiutata**
@ -364,17 +366,17 @@ Controlla il tuo profilo OS Login:
gcloud compute os-login describe-profile
```
Assicurati che il tuo account abbia i permessi IAM richiesti (Compute OS Login o Compute OS Admin Login).
Assicurati che il tuo account abbia le autorizzazioni IAM richieste (Compute OS Login o Compute OS Admin Login).
**Memoria esaurita (OOM)**
Se la build Docker fallisce con `Killed` e `exit code 137`, la VM è stata terminata per OOM. Passa a e2-small (minimo) o e2-medium (consigliato per build locali affidabili):
```bash
# Ferma prima la VM
# Prima arresta la VM
gcloud compute instances stop openclaw-gateway --zone=us-central1-a
# Cambia tipo di macchina
# Cambia il tipo di macchina
gcloud compute instances set-machine-type openclaw-gateway \
--zone=us-central1-a \
--machine-type=e2-small
@ -395,10 +397,10 @@ Per automazione o pipeline CI/CD, crea un service account dedicato con permessi
```bash
gcloud iam service-accounts create openclaw-deploy \
--display-name="OpenClaw Deployment"
--display-name="Deployment OpenClaw"
```
2. Concedi il ruolo Compute Instance Admin (oppure un ruolo personalizzato più ristretto):
2. Concedi il ruolo Compute Instance Admin (o un ruolo personalizzato più restrittivo):
```bash
gcloud projects add-iam-policy-binding my-openclaw-project \
@ -406,7 +408,7 @@ Per automazione o pipeline CI/CD, crea un service account dedicato con permessi
--role="roles/compute.instanceAdmin.v1"
```
Evita di usare il ruolo Owner per l'automazione. Usa il principio del privilegio minimo.
Evita di usare il ruolo Owner per l’automazione. Applica il principio del privilegio minimo.
Vedi [https://cloud.google.com/iam/docs/understanding-roles](https://cloud.google.com/iam/docs/understanding-roles) per i dettagli sui ruoli IAM.
@ -414,6 +416,6 @@ Vedi [https://cloud.google.com/iam/docs/understanding-roles](https://cloud.googl
## Passaggi successivi
- Configura i canali di messaggistica: [Channels](/it/channels)
- Associa dispositivi locali come nodi: [Nodes](/nodes)
- Configura il Gateway: [Gateway configuration](/gateway/configuration)
- Configura i canali di messaggistica: [Canali](/it/channels)
- Associa i dispositivi locali come Node: [Node](/it/nodes)
- Configura il Gateway: [Configurazione del Gateway](/it/gateway/configuration)

129
docs/it/install/hetzner.md
View File

@ -1,69 +1,69 @@
---
read_when:
- Vuoi OpenClaw in esecuzione 24/7 su un VPS cloud (non sul tuo laptop)
- Vuoi un Gateway always-on di livello production sul tuo VPS
- Vuoi il pieno controllo su persistenza, binari e comportamento ai riavvii
- Vuoi che OpenClaw sia in esecuzione 24/7 su un VPS cloud (non sul tuo laptop)
- Vuoi un Gateway di livello production, sempre attivo, sul tuo VPS
- Vuoi il controllo completo su persistenza, binari e comportamento di riavvio
- Stai eseguendo OpenClaw in Docker su Hetzner o un provider simile
summary: Esegui OpenClaw Gateway 24/7 su un VPS Hetzner economico (Docker) con stato persistente e binari inclusi nell'immagine
summary: Esegui OpenClaw Gateway 24/7 su un VPS Hetzner economico (Docker) con stato persistente e binari inclusi
title: Hetzner
x-i18n:
generated_at: "2026-04-05T13:55:39Z"
generated_at: "2026-04-19T01:11:13Z"
model: gpt-5.4
provider: openai
source_hash: d859e4c0943040b022835f320708f879a11eadef70f2816cf0f2824eaaf165ef
source_hash: 32f5e552ea87970b89c762059bc27f22e0aa3abf001307cae8829b9f1c713a42
source_path: install/hetzner.md
workflow: 15
---
# OpenClaw su Hetzner (Docker, guida VPS di produzione)
# OpenClaw su Hetzner (Docker, guida per VPS production)
## Obiettivo
Eseguire un Gateway OpenClaw persistente su un VPS Hetzner usando Docker, con stato durevole, binari inclusi nell'immagine e comportamento sicuro ai riavvii.
Eseguire un Gateway OpenClaw persistente su un VPS Hetzner usando Docker, con stato durevole, binari inclusi nell'immagine e comportamento di riavvio sicuro.
Se vuoi “OpenClaw 24/7 per ~$5”, questa è la configurazione affidabile più semplice.
I prezzi di Hetzner cambiano; scegli il VPS Debian/Ubuntu più piccolo e passa a una dimensione superiore se incontri OOM.
Se vuoi “OpenClaw 24/7 per circa $5”, questa è la configurazione affidabile più semplice.
I prezzi di Hetzner cambiano; scegli il VPS Debian/Ubuntu più piccolo e aumenta le risorse se incontri OOM.
Promemoria sul modello di sicurezza:
- Gli agenti condivisi in azienda vanno bene quando tutti sono nello stesso perimetro di fiducia e il runtime è solo per uso aziendale.
- Mantieni una separazione rigorosa: VPS/runtime dedicato + account dedicati; nessun profilo personale Apple/Google/browser/password manager su quell'host.
- Se gli utenti sono avversariali tra loro, separa per gateway/host/utente OS.
- Gli agenti condivisi in azienda vanno bene quando tutti rientrano nello stesso confine di fiducia e il runtime è solo per uso aziendale.
- Mantieni una separazione rigorosa: VPS/runtime dedicato + account dedicati; niente profili personali Apple/Google/browser/password manager su quell'host.
- Se gli utenti sono avversari tra loro, separa per gateway/host/utente OS.
Vedi [Sicurezza](/gateway/security) e [Hosting VPS](/vps).
Vedi [Security](/it/gateway/security) e [VPS hosting](/it/vps).
## Cosa stiamo facendo (in termini semplici)?
## Cosa stiamo facendo (in parole semplici)?
- Affittare un piccolo server Linux (VPS Hetzner)
- Noleggiare un piccolo server Linux (VPS Hetzner)
- Installare Docker (runtime applicativo isolato)
- Avviare OpenClaw Gateway in Docker
- Rendere persistenti `~/.openclaw` + `~/.openclaw/workspace` sull'host (sopravvivono a riavvii/rebuild)
- Avviare il Gateway OpenClaw in Docker
- Rendere persistenti `~/.openclaw` + `~/.openclaw/workspace` sull'host (sopravvive a riavvii/ricostruzioni)
- Accedere alla Control UI dal tuo laptop tramite un tunnel SSH
Quello stato montato in `~/.openclaw` include `openclaw.json`, il file per agente
Lo stato montato in `~/.openclaw` include `openclaw.json`, il file per agente
`agents/<agentId>/agent/auth-profiles.json` e `.env`.
È possibile accedere al Gateway tramite:
- port forwarding SSH dal tuo laptop
- esposizione diretta della porta se gestisci tu firewall e token
- Inoltro di porta SSH dal tuo laptop
- Esposizione diretta della porta se gestisci tu stesso firewall e token
Questa guida presuppone Ubuntu o Debian su Hetzner.
Se usi un altro VPS Linux, adatta i pacchetti di conseguenza.
Per il flusso Docker generico, vedi [Docker](/install/docker).
Per il flusso Docker generico, vedi [Docker](/it/install/docker).
---
## Percorso rapido (operatori esperti)
1. Effettua il provisioning del VPS Hetzner
2. Installa Docker
3. Clona il repository OpenClaw
4. Crea directory host persistenti
5. Configura `.env` e `docker-compose.yml`
6. Inserisci i binari richiesti nell'immagine
1. Provisioning del VPS Hetzner
2. Installazione di Docker
3. Clonazione del repository OpenClaw
4. Creazione delle directory host persistenti
5. Configurazione di `.env` e `docker-compose.yml`
6. Inclusione dei binari richiesti nell'immagine
7. `docker compose up -d`
8. Verifica persistenza e accesso al Gateway
8. Verifica della persistenza e dell'accesso al Gateway
---
@ -71,19 +71,19 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
- VPS Hetzner con accesso root
- Accesso SSH dal tuo laptop
- Una familiarità di base con SSH + copia/incolla
- Familiarità di base con SSH + copia/incolla
- ~20 minuti
- Docker e Docker Compose
- Credenziali auth del modello
- Credenziali provider opzionali
- Credenziali di autenticazione del modello
- Credenziali opzionali dei provider
- QR WhatsApp
- token bot Telegram
- Token bot Telegram
- OAuth Gmail
---
<Steps>
<Step title="Effettua il provisioning del VPS">
<Step title="Esegui il provisioning del VPS">
Crea un VPS Ubuntu o Debian in Hetzner.
Connettiti come root:
@ -92,7 +92,7 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
ssh root@YOUR_VPS_IP
```
Questa guida presuppone che il VPS sia stateful.
Questa guida presuppone che il VPS sia con stato persistente.
Non trattarlo come infrastruttura usa e getta.
</Step>
@ -119,40 +119,43 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
cd openclaw
```
Questa guida presuppone che tu costruisca un'immagine personalizzata per garantire la persistenza dei binari.
Questa guida presuppone che tu voglia creare un'immagine personalizzata per garantire la persistenza dei binari.
</Step>
<Step title="Crea directory host persistenti">
I container Docker sono effimeri.
Tutto lo stato a lunga durata deve vivere sull'host.
Tutto lo stato a lunga durata deve trovarsi sull'host.
```bash
mkdir -p /root/.openclaw/workspace
# Imposta il proprietario sull'utente del container (uid 1000):
# Imposta la proprietà all'utente del container (uid 1000):
chown -R 1000:1000 /root/.openclaw
```
</Step>
<Step title="Configura le variabili d'ambiente">
Crea `.env` nella root del repository.
Crea `.env` nella radice del repository.
```bash
OPENCLAW_IMAGE=openclaw:latest
OPENCLAW_GATEWAY_TOKEN=change-me-now
OPENCLAW_GATEWAY_TOKEN=
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789
OPENCLAW_CONFIG_DIR=/root/.openclaw
OPENCLAW_WORKSPACE_DIR=/root/.openclaw/workspace
GOG_KEYRING_PASSWORD=change-me-now
GOG_KEYRING_PASSWORD=
XDG_CONFIG_HOME=/home/node/.openclaw
```
Genera secret robusti:
Lascia `OPENCLAW_GATEWAY_TOKEN` vuoto a meno che tu non voglia esplicitamente
gestirlo tramite `.env`; OpenClaw scrive un token gateway casuale nella
configurazione al primo avvio. Genera una password per il keyring e incollala in
`GOG_KEYRING_PASSWORD`:
```bash
openssl rand -hex 32
@ -160,8 +163,8 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
**Non fare commit di questo file.**
Questo file `.env` serve per l'env del container/runtime come `OPENCLAW_GATEWAY_TOKEN`.
L'autenticazione provider OAuth/chiave API memorizzata vive nel file montato
Questo file `.env` è per l'ambiente del container/runtime, ad esempio `OPENCLAW_GATEWAY_TOKEN`.
L'autenticazione OAuth/API key dei provider memorizzata si trova nel mount di
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`.
</Step>
@ -191,7 +194,7 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
- ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
- ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
ports:
# Consigliato: mantieni il Gateway accessibile solo via loopback sul VPS; accedi tramite tunnel SSH.
# Consigliato: mantieni il Gateway accessibile solo in loopback sul VPS; accedi tramite tunnel SSH.
# Per esporlo pubblicamente, rimuovi il prefisso `127.0.0.1:` e configura il firewall di conseguenza.
- "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789"
command:
@ -207,22 +210,22 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
]
```
`--allow-unconfigured` serve solo per comodità di bootstrap, non sostituisce una configurazione gateway corretta. Imposta comunque auth (`gateway.auth.token` o password) e usa impostazioni di bind sicure per il tuo deployment.
`--allow-unconfigured` serve solo per comodità durante il bootstrap, non sostituisce una configurazione corretta del gateway. Imposta comunque l'autenticazione (`gateway.auth.token` o password) e usa impostazioni di bind sicure per il tuo deployment.
</Step>
<Step title="Passaggi condivisi del runtime Docker VM">
Usa la guida runtime condivisa per il flusso comune degli host Docker:
<Step title="Passaggi runtime condivisi per Docker VM">
Usa la guida runtime condivisa per il flusso host Docker comune:
- [Inserisci i binari richiesti nell'immagine](/install/docker-vm-runtime#bake-required-binaries-into-the-image)
- [Build e avvio](/install/docker-vm-runtime#build-and-launch)
- [Cosa persiste e dove](/install/docker-vm-runtime#what-persists-where)
- [Aggiornamenti](/install/docker-vm-runtime#updates)
- [Includi i binari richiesti nell'immagine](/it/install/docker-vm-runtime#bake-required-binaries-into-the-image)
- [Build e avvio](/it/install/docker-vm-runtime#build-and-launch)
- [Cosa persiste e dove](/it/install/docker-vm-runtime#what-persists-where)
- [Aggiornamenti](/it/install/docker-vm-runtime#updates)
</Step>
<Step title="Accesso specifico per Hetzner">
Dopo i passaggi condivisi di build e avvio, apri un tunnel dal tuo laptop:
Dopo i passaggi condivisi di build e avvio, crea un tunnel dal tuo laptop:
```bash
ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
@ -232,22 +235,22 @@ Per il flusso Docker generico, vedi [Docker](/install/docker).
`http://127.0.0.1:18789/`
Incolla il secret condiviso configurato. Questa guida usa il token del gateway per
impostazione predefinita; se hai cambiato a password auth, usa invece quella password.
Incolla il segreto condiviso configurato. Questa guida usa il token gateway per
impostazione predefinita; se sei passato all'autenticazione con password, usa invece quella password.
</Step>
</Steps>
La mappa condivisa della persistenza si trova in [Runtime Docker VM](/install/docker-vm-runtime#what-persists-where).
La mappa condivisa della persistenza si trova in [Docker VM Runtime](/it/install/docker-vm-runtime#what-persists-where).
## Infrastructure as Code (Terraform)
Per i team che preferiscono flussi infrastructure-as-code, una configurazione Terraform mantenuta dalla community offre:
Per i team che preferiscono flussi Infrastructure as Code, una configurazione Terraform gestita dalla community offre:
- Configurazione Terraform modulare con gestione dello stato remoto
- Provisioning automatizzato tramite cloud-init
- Script di deployment (bootstrap, deploy, backup/restore)
- Rafforzamento della sicurezza (firewall, UFW, accesso solo SSH)
- Hardening della sicurezza (firewall, UFW, accesso solo SSH)
- Configurazione del tunnel SSH per l'accesso al gateway
**Repository:**
@ -255,12 +258,12 @@ Per i team che preferiscono flussi infrastructure-as-code, una configurazione Te
- Infrastruttura: [openclaw-terraform-hetzner](https://github.com/andreesg/openclaw-terraform-hetzner)
- Configurazione Docker: [openclaw-docker-config](https://github.com/andreesg/openclaw-docker-config)
Questo approccio completa la configurazione Docker sopra con deployment riproducibili, infrastruttura sotto controllo di versione e disaster recovery automatizzato.
Questo approccio integra la configurazione Docker sopra con deployment riproducibili, infrastruttura sotto controllo di versione e disaster recovery automatizzato.
> **Nota:** mantenuto dalla community. Per problemi o contributi, vedi i link ai repository sopra.
> **Nota:** Gestito dalla community. Per problemi o contributi, vedi i link ai repository sopra.
## Passaggi successivi
- Configura i canali di messaggistica: [Canali](/it/channels)
- Configura il Gateway: [Configurazione del Gateway](/gateway/configuration)
- Mantieni OpenClaw aggiornato: [Aggiornamento](/install/updating)
- Configura i canali di messaggistica: [Channels](/it/channels)
- Configura il Gateway: [Gateway configuration](/it/gateway/configuration)
- Mantieni OpenClaw aggiornato: [Updating](/it/install/updating)

493
docs/it/plugins/manifest.md
View File

@ -1,81 +1,65 @@
---
read_when:
- Stai creando un Plugin OpenClaw
- Devi distribuire uno schema di configurazione del Plugin o eseguire il debug degli errori di validazione del Plugin
summary: Manifest del Plugin + requisiti dello schema JSON (validazione rigorosa della configurazione)
- Stai creando un plugin OpenClaw
- Devi distribuire uno schema di configurazione del plugin o eseguire il debug degli errori di convalida del plugin
summary: Requisiti del manifest del Plugin + schema JSON (convalida rigorosa della configurazione)
title: Manifest del Plugin
x-i18n:
generated_at: "2026-04-15T08:18:06Z"
generated_at: "2026-04-19T01:11:09Z"
model: gpt-5.4
provider: openai
source_hash: ba2183bfa8802871e4ef33a0ebea290606e8351e9e83e25ee72456addb768730
source_hash: 2dfc00759108ddee7bfcda8c42acf7f2d47451676447ba3caf8b5950f8a1c181
source_path: plugins/manifest.md
workflow: 15
---
# Manifest del Plugin (`openclaw.plugin.json`)
Questa pagina riguarda solo il **manifest nativo del Plugin OpenClaw**.
Questa pagina riguarda solo il **manifest nativo del plugin OpenClaw**.
Per i layout di bundle compatibili, vedi [Bundle di Plugin](/it/plugins/bundles).
Per i layout di bundle compatibili, vedi [Bundle di plugin](/it/plugins/bundles).
I formati di bundle compatibili usano file manifest diversi:
- Bundle Codex: `.codex-plugin/plugin.json`
- Bundle Claude: `.claude-plugin/plugin.json` o il layout predefinito del componente Claude
senza un manifest
- Bundle Claude: `.claude-plugin/plugin.json` o il layout predefinito del componente Claude senza manifest
- Bundle Cursor: `.cursor-plugin/plugin.json`
OpenClaw rileva automaticamente anche questi layout di bundle, ma non vengono validati
rispetto allo schema `openclaw.plugin.json` descritto qui.
OpenClaw rileva automaticamente anche quei layout di bundle, ma non vengono convalidati rispetto allo schema `openclaw.plugin.json` descritto qui.
Per i bundle compatibili, OpenClaw al momento legge i metadati del bundle più le root
delle Skills dichiarate, le root dei comandi Claude, i valori predefiniti di `settings.json` del bundle Claude,
i valori predefiniti LSP del bundle Claude e i pacchetti hook supportati quando il layout corrisponde
alle aspettative di runtime di OpenClaw.
Per i bundle compatibili, OpenClaw al momento legge i metadati del bundle più le radici delle skill dichiarate, le radici dei comandi Claude, i valori predefiniti di `settings.json` del bundle Claude, i valori predefiniti LSP del bundle Claude e i pacchetti hook supportati quando il layout corrisponde alle aspettative del runtime di OpenClaw.
Ogni Plugin OpenClaw nativo **deve** distribuire un file `openclaw.plugin.json` nella
**root del Plugin**. OpenClaw usa questo manifest per validare la configurazione
**senza eseguire il codice del Plugin**. I manifest mancanti o non validi sono trattati come
errori del Plugin e bloccano la validazione della configurazione.
Ogni plugin nativo OpenClaw **deve** includere un file `openclaw.plugin.json` nella **radice del plugin**. OpenClaw usa questo manifest per convalidare la configurazione **senza eseguire il codice del plugin**. I manifest mancanti o non validi sono trattati come errori del plugin e bloccano la convalida della configurazione.
Vedi la guida completa al sistema dei Plugin: [Plugin](/it/tools/plugin).
Per il modello di capability nativo e le attuali indicazioni sulla compatibilità esterna:
[Modello di capability](/it/plugins/architecture#public-capability-model).
Vedi la guida completa al sistema di plugin: [Plugin](/it/tools/plugin).
Per il modello di capacità nativo e le indicazioni attuali sulla compatibilità esterna:
[Modello di capacità](/it/plugins/architecture#public-capability-model).
## Cosa fa questo file
## A cosa serve questo file
`openclaw.plugin.json` è il metadato che OpenClaw legge prima di caricare il codice
del tuo Plugin.
`openclaw.plugin.json` è il metadato che OpenClaw legge prima di caricare il codice del tuo plugin.
Usalo per:
- identità del Plugin
- validazione della configurazione
- metadati di autenticazione e onboarding che devono essere disponibili senza avviare il
runtime del Plugin
- hint di attivazione economici che le superfici del control plane possono ispezionare prima che il runtime
venga caricato
- descrittori di setup economici che le superfici di setup/onboarding possono ispezionare prima che il
runtime venga caricato
- metadati di alias e auto-abilitazione che devono essere risolti prima che il runtime del Plugin venga caricato
- metadati abbreviati di proprietà della famiglia di modelli che devono auto-attivare il
Plugin prima che il runtime venga caricato
- istantanee statiche di proprietà delle capability usate per il wiring di compatibilità dei bundle e la
copertura dei contratti
- metadati economici del runner QA che l'host condiviso `openclaw qa` può ispezionare
prima che il runtime del Plugin venga caricato
- metadati di configurazione specifici del canale che devono essere uniti nelle superfici di catalogo e validazione
senza caricare il runtime
- identità del plugin
- convalida della configurazione
- metadati di autenticazione e onboarding che devono essere disponibili senza avviare il runtime del plugin
- suggerimenti di attivazione leggeri che le superfici del control plane possono ispezionare prima che il runtime venga caricato
- descrittori di configurazione leggeri che le superfici di configurazione/onboarding possono ispezionare prima che il runtime venga caricato
- metadati di alias e auto-attivazione che devono essere risolti prima che il runtime del plugin venga caricato
- metadati abbreviati di proprietà della famiglia di modelli che devono attivare automaticamente il plugin prima che il runtime venga caricato
- snapshot statiche di proprietà delle capacità usate per il wiring di compatibilità dei bundle e la copertura dei contratti
- metadati leggeri del runner QA che l'host condiviso `openclaw qa` può ispezionare prima che il runtime del plugin venga caricato
- metadati di configurazione specifici del canale che devono essere uniti alle superfici di catalogo e convalida senza caricare il runtime
- suggerimenti UI per la configurazione
Non usarlo per:
- registrare il comportamento di runtime
- registrare comportamenti di runtime
- dichiarare entrypoint del codice
- metadati di installazione npm
Questi appartengono al codice del tuo Plugin e a `package.json`.
Questi appartengono al codice del tuo plugin e a `package.json`.
## Esempio minimo
@ -102,7 +86,14 @@ Questi appartengono al codice del tuo Plugin e a `package.json`.
"modelSupport": {
"modelPrefixes": ["router-"]
},
"providerEndpoints": [
{
"endpointClass": "xai-native",
"hosts": ["api.x.ai"]
}
],
"cliBackends": ["openrouter-cli"],
"syntheticAuthRefs": ["openrouter-cli"],
"providerAuthEnvVars": {
"openrouter": ["OPENROUTER_API_KEY"]
},
@ -148,63 +139,64 @@ Questi appartengono al codice del tuo Plugin e a `package.json`.
## Riferimento dei campi di primo livello
| Campo | Obbligatorio | Tipo | Significato |
| ----------------------------------- | ------------ | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | Sì | `string` | ID canonico del Plugin. È l'ID usato in `plugins.entries.<id>`. |
| `configSchema` | Sì | `object` | Schema JSON inline per la configurazione di questo Plugin. |
| `enabledByDefault` | No | `true` | Contrassegna un Plugin bundle come abilitato per impostazione predefinita. Omettilo, oppure imposta qualsiasi valore diverso da `true`, per lasciare il Plugin disabilitato per impostazione predefinita. |
| `legacyPluginIds` | No | `string[]` | ID legacy che vengono normalizzati a questo ID canonico del Plugin. |
| `autoEnableWhenConfiguredProviders` | No | `string[]` | ID provider che devono abilitare automaticamente questo Plugin quando auth, config o riferimenti a modelli li menzionano. |
| `kind` | No | `"memory"` \| `"context-engine"` | Dichiara un tipo esclusivo di Plugin usato da `plugins.slots.*`. |
| `channels` | No | `string[]` | ID dei canali posseduti da questo Plugin. Usati per discovery e validazione della configurazione. |
| `providers` | No | `string[]` | ID provider posseduti da questo Plugin. |
| `modelSupport` | No | `object` | Metadati abbreviati della famiglia di modelli posseduti dal manifest usati per auto-caricare il Plugin prima del runtime. |
| `cliBackends` | No | `string[]` | ID dei backend di inferenza CLI posseduti da questo Plugin. Usati per l'auto-attivazione all'avvio da riferimenti espliciti nella configurazione. |
| `commandAliases` | No | `object[]` | Nomi di comandi posseduti da questo Plugin che devono produrre diagnostica di configurazione e CLI consapevole del Plugin prima che il runtime venga caricato. |
| `providerAuthEnvVars` | No | `Record<string, string[]>` | Metadati economici delle variabili env di auth provider che OpenClaw può ispezionare senza caricare il codice del Plugin. |
| `providerAuthAliases` | No | `Record<string, string>` | ID provider che devono riutilizzare un altro ID provider per la ricerca auth, ad esempio un provider di coding che condivide la chiave API del provider di base e i profili auth. |
| `channelEnvVars` | No | `Record<string, string[]>` | Metadati economici delle variabili env del canale che OpenClaw può ispezionare senza caricare il codice del Plugin. Usali per superfici di setup o auth del canale guidate da env che gli helper generici di avvio/configurazione devono vedere. |
| `providerAuthChoices` | No | `object[]` | Metadati economici delle scelte di autenticazione per selettori di onboarding, risoluzione del provider preferito e semplice wiring dei flag CLI. |
| `activation` | No | `object` | Hint di attivazione economici per il caricamento attivato da provider, comando, canale, route e capability. Solo metadati; il runtime del Plugin continua a possedere il comportamento reale. |
| `setup` | No | `object` | Descrittori economici di setup/onboarding che le superfici di discovery e setup possono ispezionare senza caricare il runtime del Plugin. |
| `qaRunners` | No | `object[]` | Descrittori economici dei runner QA usati dall'host condiviso `openclaw qa` prima che il runtime del Plugin venga caricato. |
| `contracts` | No | `object` | Istantanea statica delle capability bundle per speech, trascrizione realtime, voce realtime, media-understanding, generazione di immagini, generazione musicale, generazione video, web-fetch, ricerca web e proprietà dei tool. |
| `channelConfigs` | No | `Record<string, object>` | Metadati di configurazione del canale posseduti dal manifest uniti nelle superfici di discovery e validazione prima che il runtime venga caricato. |
| `skills` | No | `string[]` | Directory di Skills da caricare, relative alla root del Plugin. |
| `name` | No | `string` | Nome leggibile del Plugin. |
| `description` | No | `string` | Breve riepilogo mostrato nelle superfici del Plugin. |
| `version` | No | `string` | Versione informativa del Plugin. |
| `uiHints` | No | `Record<string, object>` | Etichette UI, segnaposto e suggerimenti di sensibilità per i campi di configurazione. |
| Campo | Obbligatorio | Tipo | Significato |
| ----------------------------------- | ------------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | Sì | `string` | ID canonico del plugin. È l'ID usato in `plugins.entries.<id>`. |
| `configSchema` | Sì | `object` | Schema JSON inline per la configurazione di questo plugin. |
| `enabledByDefault` | No | `true` | Indica che un plugin bundle è abilitato per impostazione predefinita. Omettilo, oppure imposta qualsiasi valore diverso da `true`, per lasciare il plugin disabilitato per impostazione predefinita. |
| `legacyPluginIds` | No | `string[]` | ID legacy che vengono normalizzati a questo ID canonico del plugin. |
| `autoEnableWhenConfiguredProviders` | No | `string[]` | ID provider che devono abilitare automaticamente questo plugin quando auth, configurazione o riferimenti a modelli li menzionano. |
| `kind` | No | `"memory"` \| `"context-engine"` | Dichiara un tipo esclusivo di plugin usato da `plugins.slots.*`. |
| `channels` | No | `string[]` | ID dei canali posseduti da questo plugin. Usati per discovery e convalida della configurazione. |
| `providers` | No | `string[]` | ID dei provider posseduti da questo plugin. |
| `modelSupport` | No | `object` | Metadati abbreviati delle famiglie di modelli posseduti dal manifest, usati per caricare automaticamente il plugin prima del runtime. |
| `providerEndpoints` | No | `object[]` | Metadati di host/baseUrl degli endpoint posseduti dal manifest per le route del provider che il core deve classificare prima che il runtime del provider venga caricato. |
| `cliBackends` | No | `string[]` | ID dei backend di inferenza CLI posseduti da questo plugin. Usati per l'auto-attivazione all'avvio a partire da riferimenti espliciti nella configurazione. |
| `syntheticAuthRefs` | No | `string[]` | Riferimenti a provider o backend CLI i cui hook di auth sintetica posseduti dal plugin devono essere verificati durante la discovery a freddo dei modelli prima che il runtime venga caricato. |
| `nonSecretAuthMarkers` | No | `string[]` | Valori segnaposto della chiave API posseduti dal plugin bundle che rappresentano uno stato di credenziali non segrete locale, OAuth o ambientale. |
| `commandAliases` | No | `object[]` | Nomi di comandi posseduti da questo plugin che devono produrre diagnostica di configurazione e CLI consapevole del plugin prima che il runtime venga caricato. |
| `providerAuthEnvVars` | No | `Record<string, string[]>` | Metadati leggeri delle variabili d'ambiente di auth del provider che OpenClaw può ispezionare senza caricare il codice del plugin. |
| `providerAuthAliases` | No | `Record<string, string>` | ID provider che devono riutilizzare un altro ID provider per la ricerca dell'auth, per esempio un provider di coding che condivide la chiave API del provider di base e i profili di autenticazione. |
| `channelEnvVars` | No | `Record<string, string[]>` | Metadati leggeri delle variabili d'ambiente del canale che OpenClaw può ispezionare senza caricare il codice del plugin. Usalo per superfici di configurazione o auth del canale guidate da env che gli helper generici di avvio/configurazione devono vedere. |
| `providerAuthChoices` | No | `object[]` | Metadati leggeri delle scelte di autenticazione per selettori di onboarding, risoluzione del provider preferito e semplice wiring dei flag CLI. |
| `activation` | No | `object` | Suggerimenti di attivazione leggeri per caricamento attivato da provider, comando, canale, route e capacità. Solo metadati; il runtime del plugin continua a possedere il comportamento effettivo. |
| `setup` | No | `object` | Descrittori leggeri di configurazione/onboarding che le superfici di discovery e configurazione possono ispezionare senza caricare il runtime del plugin. |
| `qaRunners` | No | `object[]` | Descrittori leggeri dei runner QA usati dall'host condiviso `openclaw qa` prima che il runtime del plugin venga caricato. |
| `contracts` | No | `object` | Snapshot statica delle capacità bundle per speech, trascrizione realtime, voce realtime, media-understanding, generazione di immagini, generazione musicale, generazione video, web-fetch, ricerca web e proprietà degli strumenti. |
| `channelConfigs` | No | `Record<string, object>` | Metadati di configurazione del canale posseduti dal manifest uniti alle superfici di discovery e convalida prima che il runtime venga caricato. |
| `skills` | No | `string[]` | Directory Skills da caricare, relative alla radice del plugin. |
| `name` | No | `string` | Nome leggibile del plugin. |
| `description` | No | `string` | Breve riepilogo mostrato nelle superfici del plugin. |
| `version` | No | `string` | Versione informativa del plugin. |
| `uiHints` | No | `Record<string, object>` | Etichette UI, placeholder e suggerimenti di sensibilità per i campi di configurazione. |
## Riferimento `providerAuthChoices`
Ogni voce `providerAuthChoices` descrive una scelta di onboarding o autenticazione.
Ogni voce di `providerAuthChoices` descrive una scelta di onboarding o autenticazione.
OpenClaw la legge prima che il runtime del provider venga caricato.
| Campo | Obbligatorio | Tipo | Significato |
| --------------------- | ------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `provider` | Sì | `string` | ID del provider a cui appartiene questa scelta. |
| `method` | Sì | `string` | ID del metodo di autenticazione a cui inoltrare. |
| `choiceId` | Sì | `string` | ID stabile della scelta di autenticazione usato dai flussi di onboarding e CLI. |
| `choiceLabel` | No | `string` | Etichetta visibile all'utente. Se omessa, OpenClaw usa `choiceId` come fallback. |
| `choiceHint` | No | `string` | Breve testo di supporto per il selettore. |
| `assistantPriority` | No | `number` | I valori più bassi vengono ordinati prima nei selettori interattivi guidati dall'assistente. |
| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Nasconde la scelta dai selettori dell'assistente pur consentendo comunque la selezione manuale via CLI. |
| `deprecatedChoiceIds` | No | `string[]` | ID legacy delle scelte che devono reindirizzare gli utenti a questa scelta sostitutiva. |
| `groupId` | No | `string` | ID opzionale del gruppo per raggruppare scelte correlate. |
| `groupLabel` | No | `string` | Etichetta visibile all'utente per quel gruppo. |
| `groupHint` | No | `string` | Breve testo di supporto per il gruppo. |
| `optionKey` | No | `string` | Chiave interna dell'opzione per semplici flussi di autenticazione con un solo flag. |
| `cliFlag` | No | `string` | Nome del flag CLI, ad esempio `--openrouter-api-key`. |
| `cliOption` | No | `string` | Forma completa dell'opzione CLI, ad esempio `--openrouter-api-key <key>`. |
| `cliDescription` | No | `string` | Descrizione usata nella guida CLI. |
| `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | In quali superfici di onboarding deve comparire questa scelta. Se omesso, il valore predefinito è `["text-inference"]`. |
| Campo | Obbligatorio | Tipo | Significato |
| --------------------- | ------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `provider` | Sì | `string` | ID del provider a cui appartiene questa scelta. |
| `method` | Sì | `string` | ID del metodo di autenticazione a cui inoltrare. |
| `choiceId` | Sì | `string` | ID stabile della scelta di autenticazione usato dai flussi di onboarding e CLI. |
| `choiceLabel` | No | `string` | Etichetta visibile all'utente. Se omessa, OpenClaw usa `choiceId` come fallback. |
| `choiceHint` | No | `string` | Breve testo di aiuto per il selettore. |
| `assistantPriority` | No | `number` | I valori più bassi vengono ordinati prima nei selettori interattivi guidati dall'assistente. |
| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Nasconde la scelta dai selettori dell'assistente pur consentendo comunque la selezione manuale via CLI. |
| `deprecatedChoiceIds` | No | `string[]` | ID legacy della scelta che devono reindirizzare gli utenti a questa scelta sostitutiva. |
| `groupId` | No | `string` | ID di gruppo facoltativo per raggruppare scelte correlate. |
| `groupLabel` | No | `string` | Etichetta visibile all'utente per quel gruppo. |
| `groupHint` | No | `string` | Breve testo di aiuto per il gruppo. |
| `optionKey` | No | `string` | Chiave di opzione interna per semplici flussi di autenticazione a flag singolo. |
| `cliFlag` | No | `string` | Nome del flag CLI, ad esempio `--openrouter-api-key`. |
| `cliOption` | No | `string` | Forma completa dell'opzione CLI, ad esempio `--openrouter-api-key <key>`. |
| `cliDescription` | No | `string` | Descrizione usata nell'help della CLI. |
| `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | In quali superfici di onboarding deve apparire questa scelta. Se omesso, il valore predefinito è `["text-inference"]`. |
## Riferimento `commandAliases`
Usa `commandAliases` quando un Plugin possiede un nome di comando di runtime che gli utenti possono
inserire per errore in `plugins.allow` o provare a eseguire come comando CLI di root. OpenClaw
usa questi metadati per la diagnostica senza importare il codice di runtime del Plugin.
Usa `commandAliases` quando un plugin possiede un nome di comando di runtime che gli utenti possono erroneamente inserire in `plugins.allow` o provare a eseguire come comando CLI di root. OpenClaw usa questi metadati per la diagnostica senza importare il codice di runtime del plugin.
```json
{
@ -218,45 +210,38 @@ usa questi metadati per la diagnostica senza importare il codice di runtime del
}
```
| Campo | Obbligatorio | Tipo | Significato |
| ------------ | ------------ | ----------------- | ----------------------------------------------------------------------- |
| `name` | Sì | `string` | Nome del comando che appartiene a questo Plugin. |
| `kind` | No | `"runtime-slash"` | Contrassegna l'alias come comando slash della chat anziché comando CLI di root. |
| `cliCommand` | No | `string` | Comando CLI di root correlato da suggerire per le operazioni CLI, se esiste. |
| Campo | Obbligatorio | Tipo | Significato |
| ------------ | ------------ | ----------------- | ------------------------------------------------------------------------------- |
| `name` | Sì | `string` | Nome del comando che appartiene a questo plugin. |
| `kind` | No | `"runtime-slash"` | Indica che l'alias è un comando slash della chat anziché un comando CLI di root. |
| `cliCommand` | No | `string` | Comando CLI di root correlato da suggerire per le operazioni CLI, se esiste. |
## Riferimento `activation`
Usa `activation` quando il Plugin può dichiarare in modo economico quali eventi del control plane
dovrebbero attivarlo in seguito.
Usa `activation` quando il plugin può dichiarare in modo economico quali eventi del control plane dovrebbero attivarlo in seguito.
## Riferimento `qaRunners`
Usa `qaRunners` quando un Plugin contribuisce con uno o più runner di trasporto sotto
la root condivisa `openclaw qa`. Mantieni questi metadati economici e statici; il runtime del Plugin
continua a possedere l'effettiva registrazione CLI tramite una superficie leggera
`runtime-api.ts` che esporta `qaRunnerCliRegistrations`.
Usa `qaRunners` quando un plugin contribuisce uno o più runner di trasporto sotto la root condivisa `openclaw qa`. Mantieni questi metadati leggeri e statici; il runtime del plugin continua a possedere la registrazione CLI effettiva tramite una superficie leggera `runtime-api.ts` che esporta `qaRunnerCliRegistrations`.
```json
{
"qaRunners": [
{
"commandName": "matrix",
"description": "Esegui la corsia QA live Matrix supportata da Docker su un homeserver usa e getta"
"description": "Esegue la corsia QA Matrix live basata su Docker contro un homeserver usa e getta"
}
]
}
```
| Campo | Obbligatorio | Tipo | Significato |
| ------------- | ------------ | -------- | --------------------------------------------------------------------- |
| `commandName` | Sì | `string` | Sottocomando montato sotto `openclaw qa`, ad esempio `matrix`. |
| `description` | No | `string` | Testo guida di fallback usato quando l'host condiviso ha bisogno di un comando stub. |
| Campo | Obbligatorio | Tipo | Significato |
| ------------- | ------------ | -------- | ------------------------------------------------------------------- |
| `commandName` | Sì | `string` | Sottocomando montato sotto `openclaw qa`, ad esempio `matrix`. |
| `description` | No | `string` | Testo di help di fallback usato quando l'host condiviso necessita di un comando stub. |
Questo blocco contiene solo metadati. Non registra il comportamento di runtime e non
sostituisce `register(...)`, `setupEntry` o altri entrypoint di runtime/Plugin.
I consumer attuali lo usano come suggerimento di restringimento prima di un caricamento più ampio del Plugin, quindi
l'assenza di metadati di attivazione di solito comporta solo un costo in termini di prestazioni; non dovrebbe
modificare la correttezza finché esistono ancora i fallback legacy di proprietà del manifest.
Questo blocco contiene solo metadati. Non registra comportamenti di runtime e non sostituisce `register(...)`, `setupEntry` o altri entrypoint di runtime/plugin.
I consumer attuali lo usano come suggerimento di restringimento prima di un caricamento più ampio del plugin, quindi l'assenza di metadati di attivazione di solito comporta solo un costo in termini di prestazioni; non dovrebbe modificare la correttezza finché esistono ancora fallback legacy di proprietà del manifest.
```json
{
@ -270,28 +255,23 @@ modificare la correttezza finché esistono ancora i fallback legacy di propriet
}
```
| Campo | Obbligatorio | Tipo | Significato |
| ---------------- | ------------ | ---------------------------------------------------- | --------------------------------------------------------------------- |
| `onProviders` | No | `string[]` | ID dei provider che devono attivare questo Plugin quando richiesti. |
| `onCommands` | No | `string[]` | ID dei comandi che devono attivare questo Plugin. |
| `onChannels` | No | `string[]` | ID dei canali che devono attivare questo Plugin. |
| `onRoutes` | No | `string[]` | Tipi di route che devono attivare questo Plugin. |
| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Suggerimenti generali di capability usati dalla pianificazione di attivazione del control plane. |
| Campo | Obbligatorio | Tipo | Significato |
| ---------------- | ------------ | ---------------------------------------------------- | ------------------------------------------------------------------- |
| `onProviders` | No | `string[]` | ID dei provider che devono attivare questo plugin quando richiesti. |
| `onCommands` | No | `string[]` | ID dei comandi che devono attivare questo plugin. |
| `onChannels` | No | `string[]` | ID dei canali che devono attivare questo plugin. |
| `onRoutes` | No | `string[]` | Tipi di route che devono attivare questo plugin. |
| `onCapabilities` | No | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Suggerimenti ampi di capacità usati dalla pianificazione di attivazione del control plane. |
Consumer live attuali:
- la pianificazione CLI attivata da comandi usa come fallback
`commandAliases[].cliCommand` o `commandAliases[].name` legacy
- la pianificazione setup/canale attivata da canali usa come fallback la proprietà
legacy `channels[]` quando mancano metadati espliciti di attivazione del canale
- la pianificazione setup/runtime attivata da provider usa come fallback la proprietà
legacy `providers[]` e `cliBackends[]` di primo livello quando mancano metadati espliciti
di attivazione del provider
- la pianificazione CLI attivata da comando usa come fallback `commandAliases[].cliCommand` o `commandAliases[].name` legacy
- la pianificazione di configurazione/canale attivata da canale usa come fallback la proprietà legacy `channels[]` quando mancano metadati espliciti di attivazione del canale
- la pianificazione di configurazione/runtime attivata da provider usa come fallback la proprietà legacy `providers[]` e la proprietà di primo livello `cliBackends[]` quando mancano metadati espliciti di attivazione del provider
## Riferimento `setup`
Usa `setup` quando le superfici di setup e onboarding hanno bisogno di metadati economici posseduti dal Plugin
prima che il runtime venga caricato.
Usa `setup` quando le superfici di configurazione e onboarding hanno bisogno di metadati economici posseduti dal plugin prima che il runtime venga caricato.
```json
{
@ -310,37 +290,28 @@ prima che il runtime venga caricato.
}
```
`cliBackends` di primo livello rimane valido e continua a descrivere i
backend di inferenza CLI. `setup.cliBackends` è la superficie descrittiva specifica del setup per
i flussi di control plane/setup che devono restare solo metadati.
Il campo `cliBackends` di primo livello resta valido e continua a descrivere i backend di inferenza CLI. `setup.cliBackends` è la superficie descrittiva specifica della configurazione per i flussi del control plane/configurazione che devono rimanere solo metadati.
Quando presenti, `setup.providers` e `setup.cliBackends` sono la superficie di ricerca preferita,
basata prima sui descrittori, per la discovery del setup. Se il descrittore restringe solo il Plugin candidato e il setup
ha comunque bisogno di hook di runtime più ricchi in fase di setup,
imposta `requiresRuntime: true` e mantieni `setup-api` come
percorso di esecuzione di fallback.
Quando presenti, `setup.providers` e `setup.cliBackends` sono la superficie di ricerca preferita, orientata prima ai descrittori, per la discovery della configurazione. Se il descrittore restringe solo il plugin candidato e la configurazione necessita comunque di hook di runtime più ricchi in fase di setup, imposta `requiresRuntime: true` e mantieni `setup-api` come percorso di esecuzione di fallback.
Poiché la ricerca del setup può eseguire codice `setup-api` posseduto dal Plugin,
i valori normalizzati di `setup.providers[].id` e `setup.cliBackends[]` devono restare univoci tra tutti i
Plugin rilevati. La proprietà ambigua fallisce in modo chiuso invece di scegliere un vincitore
in base all'ordine di discovery.
Poiché la ricerca della configurazione può eseguire codice `setup-api` posseduto dal plugin, i valori normalizzati di `setup.providers[].id` e `setup.cliBackends[]` devono rimanere univoci tra i plugin rilevati. Una proprietà ambigua fallisce in modalità chiusa invece di scegliere un vincitore in base all'ordine di discovery.
### Riferimento `setup.providers`
| Campo | Obbligatorio | Tipo | Significato |
| ------------- | ------------ | ---------- | ------------------------------------------------------------------------------------------- |
| `id` | Sì | `string` | ID del provider esposto durante setup o onboarding. Mantieni gli ID normalizzati univoci globalmente. |
| `authMethods` | No | `string[]` | ID dei metodi di setup/auth supportati da questo provider senza caricare il runtime completo. |
| `envVars` | No | `string[]` | Variabili env che le superfici generiche di setup/stato possono controllare prima che il runtime del Plugin venga caricato. |
| Campo | Obbligatorio | Tipo | Significato |
| ------------- | ------------ | ---------- | ---------------------------------------------------------------------------------------- |
| `id` | Sì | `string` | ID provider esposto durante la configurazione o l'onboarding. Mantieni gli ID normalizzati univoci globalmente. |
| `authMethods` | No | `string[]` | ID dei metodi di configurazione/autenticazione supportati da questo provider senza caricare il runtime completo. |
| `envVars` | No | `string[]` | Variabili d'ambiente che le superfici generiche di configurazione/stato possono controllare prima che il runtime del plugin venga caricato. |
### Campi `setup`
| Campo | Obbligatorio | Tipo | Significato |
| ------------------ | ------------ | ---------- | ------------------------------------------------------------------------------------------------ |
| `providers` | No | `object[]` | Descrittori di setup del provider esposti durante setup e onboarding. |
| `cliBackends` | No | `string[]` | ID dei backend usati in fase di setup per la ricerca basata prima sui descrittori. Mantieni gli ID normalizzati univoci globalmente. |
| `configMigrations` | No | `string[]` | ID delle migrazioni di configurazione possedute dalla superficie di setup di questo Plugin. |
| `requiresRuntime` | No | `boolean` | Se il setup richiede ancora l'esecuzione di `setup-api` dopo la ricerca del descrittore. |
| Campo | Obbligatorio | Tipo | Significato |
| ------------------ | ------------ | ---------- | --------------------------------------------------------------------------------------------------- |
| `providers` | No | `object[]` | Descrittori di configurazione del provider esposti durante la configurazione e l'onboarding. |
| `cliBackends` | No | `string[]` | ID dei backend usati in fase di setup per la ricerca orientata prima ai descrittori. Mantieni gli ID normalizzati univoci globalmente. |
| `configMigrations` | No | `string[]` | ID delle migrazioni di configurazione possedute dalla superficie di setup di questo plugin. |
| `requiresRuntime` | No | `boolean` | Indica se la configurazione necessita ancora dell'esecuzione di `setup-api` dopo la ricerca per descrittori. |
## Riferimento `uiHints`
@ -361,19 +332,18 @@ in base all'ordine di discovery.
Ogni suggerimento di campo può includere:
| Campo | Tipo | Significato |
| ------------- | ---------- | ---------------------------------------- |
| `label` | `string` | Etichetta del campo visibile all'utente. |
| `help` | `string` | Breve testo di supporto. |
| `tags` | `string[]` | Tag UI opzionali. |
| `advanced` | `boolean` | Contrassegna il campo come avanzato. |
| `sensitive` | `boolean` | Contrassegna il campo come segreto o sensibile. |
| `placeholder` | `string` | Testo segnaposto per i campi del modulo. |
| Campo | Tipo | Significato |
| ------------- | ---------- | ----------------------------------------- |
| `label` | `string` | Etichetta del campo visibile all'utente. |
| `help` | `string` | Breve testo di aiuto. |
| `tags` | `string[]` | Tag UI facoltativi. |
| `advanced` | `boolean` | Indica il campo come avanzato. |
| `sensitive` | `boolean` | Indica il campo come segreto o sensibile. |
| `placeholder` | `string` | Testo segnaposto per gli input del modulo. |
## Riferimento `contracts`
Usa `contracts` solo per metadati statici di proprietà delle capability che OpenClaw può
leggere senza importare il runtime del Plugin.
Usa `contracts` solo per metadati statici di proprietà delle capacità che OpenClaw può leggere senza importare il runtime del plugin.
```json
{
@ -393,22 +363,21 @@ leggere senza importare il runtime del Plugin.
Ogni elenco è facoltativo:
| Campo | Tipo | Significato |
| -------------------------------- | ---------- | ----------------------------------------------------------------- |
| `speechProviders` | `string[]` | ID dei provider speech posseduti da questo Plugin. |
| `realtimeTranscriptionProviders` | `string[]` | ID dei provider di trascrizione realtime posseduti da questo Plugin. |
| `realtimeVoiceProviders` | `string[]` | ID dei provider di voce realtime posseduti da questo Plugin. |
| `mediaUnderstandingProviders` | `string[]` | ID dei provider media-understanding posseduti da questo Plugin. |
| `imageGenerationProviders` | `string[]` | ID dei provider di generazione immagini posseduti da questo Plugin. |
| `videoGenerationProviders` | `string[]` | ID dei provider di generazione video posseduti da questo Plugin. |
| `webFetchProviders` | `string[]` | ID dei provider web-fetch posseduti da questo Plugin. |
| `webSearchProviders` | `string[]` | ID dei provider di ricerca web posseduti da questo Plugin. |
| `tools` | `string[]` | Nomi dei tool dell'agente posseduti da questo Plugin per i controlli dei contratti bundle. |
| Campo | Tipo | Significato |
| -------------------------------- | ---------- | ------------------------------------------------------------------ |
| `speechProviders` | `string[]` | ID dei provider speech posseduti da questo plugin. |
| `realtimeTranscriptionProviders` | `string[]` | ID dei provider di trascrizione realtime posseduti da questo plugin. |
| `realtimeVoiceProviders` | `string[]` | ID dei provider di voce realtime posseduti da questo plugin. |
| `mediaUnderstandingProviders` | `string[]` | ID dei provider media-understanding posseduti da questo plugin. |
| `imageGenerationProviders` | `string[]` | ID dei provider di generazione immagini posseduti da questo plugin. |
| `videoGenerationProviders` | `string[]` | ID dei provider di generazione video posseduti da questo plugin. |
| `webFetchProviders` | `string[]` | ID dei provider web-fetch posseduti da questo plugin. |
| `webSearchProviders` | `string[]` | ID dei provider di ricerca web posseduti da questo plugin. |
| `tools` | `string[]` | Nomi degli strumenti dell'agente posseduti da questo plugin per i controlli dei contratti bundle. |
## Riferimento `channelConfigs`
Usa `channelConfigs` quando un Plugin di canale ha bisogno di metadati di configurazione economici prima
che il runtime venga caricato.
Usa `channelConfigs` quando un plugin di canale ha bisogno di metadati di configurazione leggeri prima che il runtime venga caricato.
```json
{
@ -435,21 +404,19 @@ che il runtime venga caricato.
}
```
Ogni voce del canale può includere:
Ogni voce di canale può includere:
| Campo | Tipo | Significato |
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------- |
| Campo | Tipo | Significato |
| ------------- | ------------------------ | -------------------------------------------------------------------------------------------- |
| `schema` | `object` | Schema JSON per `channels.<id>`. Obbligatorio per ogni voce dichiarata di configurazione del canale. |
| `uiHints` | `Record<string, object>` | Etichette UI/segnaposto/suggerimenti di sensibilità opzionali per quella sezione di configurazione del canale. |
| `label` | `string` | Etichetta del canale unita nelle superfici di selezione e ispezione quando i metadati di runtime non sono pronti. |
| `description` | `string` | Breve descrizione del canale per le superfici di ispezione e catalogo. |
| `preferOver` | `string[]` | ID di Plugin legacy o a priorità inferiore che questo canale deve superare nelle superfici di selezione. |
| `uiHints` | `Record<string, object>` | Etichette UI / placeholder / suggerimenti di sensibilità facoltativi per quella sezione di configurazione del canale. |
| `label` | `string` | Etichetta del canale unita alle superfici di selezione e ispezione quando i metadati di runtime non sono pronti. |
| `description` | `string` | Breve descrizione del canale per le superfici di ispezione e catalogo. |
| `preferOver` | `string[]` | ID di plugin legacy o a priorità inferiore che questo canale deve superare nelle superfici di selezione. |
## Riferimento `modelSupport`
Usa `modelSupport` quando OpenClaw deve dedurre il tuo Plugin provider da
ID abbreviati di modello come `gpt-5.4` o `claude-sonnet-4.6` prima che il runtime del Plugin
venga caricato.
Usa `modelSupport` quando OpenClaw deve inferire il tuo plugin provider da ID abbreviati di modello come `gpt-5.4` o `claude-sonnet-4.6` prima che il runtime del plugin venga caricato.
```json
{
@ -462,74 +429,58 @@ venga caricato.
OpenClaw applica questa precedenza:
- i riferimenti espliciti `provider/model` usano i metadati del manifest `providers` proprietario
- `modelPatterns` ha precedenza su `modelPrefixes`
- se corrispondono sia un Plugin non bundle sia un Plugin bundle, vince il Plugin
non bundle
- l'ambiguità rimanente viene ignorata finché l'utente o la configurazione non specificano un provider
- i riferimenti espliciti `provider/model` usano i metadati `providers` del manifest proprietario
- `modelPatterns` hanno precedenza su `modelPrefixes`
- se corrispondono sia un plugin non bundle sia un plugin bundle, vince il plugin non bundle
- l'ambiguità residua viene ignorata finché l'utente o la configurazione non specificano un provider
Campi:
| Campo | Tipo | Significato |
| --------------- | ---------- | --------------------------------------------------------------------------- |
| Campo | Tipo | Significato |
| --------------- | ---------- | ------------------------------------------------------------------------------ |
| `modelPrefixes` | `string[]` | Prefissi confrontati con `startsWith` rispetto agli ID abbreviati dei modelli. |
| `modelPatterns` | `string[]` | Sorgenti regex confrontate con gli ID abbreviati dei modelli dopo la rimozione del suffisso del profilo. |
Le chiavi legacy di capability di primo livello sono deprecate. Usa `openclaw doctor --fix` per
spostare `speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`,
`webFetchProviders` e `webSearchProviders` sotto `contracts`; il normale
caricamento del manifest non tratta più quei campi di primo livello come
proprietà di capability.
Le chiavi legacy di capacità di primo livello sono deprecate. Usa `openclaw doctor --fix` per spostare `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` e `webSearchProviders` sotto `contracts`; il caricamento normale del manifest non tratta più quei campi di primo livello come proprietà di capacità.
## Manifest rispetto a package.json
I due file svolgono compiti diversi:
| File | Usalo per |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | Discovery, validazione della configurazione, metadati delle scelte di autenticazione e suggerimenti UI che devono esistere prima dell'esecuzione del codice del Plugin |
| `package.json` | Metadati npm, installazione delle dipendenze e il blocco `openclaw` usato per entrypoint, controllo dell'installazione, setup o metadati di catalogo |
| File | Usalo per |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | Discovery, convalida della configurazione, metadati delle scelte di autenticazione e suggerimenti UI che devono esistere prima dell'esecuzione del codice del plugin |
| `package.json` | Metadati npm, installazione delle dipendenze e blocco `openclaw` usato per entrypoint, gating dell'installazione, setup o metadati di catalogo |
Se non sei sicuro di dove appartenga un metadato, usa questa regola:
- se OpenClaw deve conoscerlo prima di caricare il codice del Plugin, inseriscilo in `openclaw.plugin.json`
- se riguarda packaging, file di entry o comportamento dell'installazione npm, inseriscilo in `package.json`
- se OpenClaw deve conoscerlo prima di caricare il codice del plugin, inseriscilo in `openclaw.plugin.json`
- se riguarda packaging, file di entry o comportamento di installazione npm, inseriscilo in `package.json`
### Campi `package.json` che influiscono sulla discovery
### Campi `package.json` che influenzano la discovery
Alcuni metadati del Plugin pre-runtime vivono intenzionalmente in `package.json` sotto il blocco
`openclaw` invece che in `openclaw.plugin.json`.
Alcuni metadati del plugin precedenti al runtime vivono intenzionalmente in `package.json` sotto il blocco `openclaw` invece che in `openclaw.plugin.json`.
Esempi importanti:
| Campo | Significato |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `openclaw.extensions` | Dichiara gli entrypoint dei Plugin nativi. |
| `openclaw.setupEntry` | Entry point leggero solo per il setup usato durante onboarding e avvio differito del canale. |
| `openclaw.channel` | Metadati economici del catalogo dei canali come etichette, percorsi della documentazione, alias e testo di selezione. |
| `openclaw.channel.configuredState` | Metadati leggeri del controllore dello stato configurato che possono rispondere a "esiste già una configurazione solo env?" senza caricare il runtime completo del canale. |
| `openclaw.channel.persistedAuthState` | Metadati leggeri del controllore dello stato auth persistito che possono rispondere a "esiste già qualcosa con accesso effettuato?" senza caricare il runtime completo del canale. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Suggerimenti di installazione/aggiornamento per Plugin bundle e pubblicati esternamente. |
| `openclaw.install.defaultChoice` | Percorso di installazione preferito quando sono disponibili più origini di installazione. |
| `openclaw.install.minHostVersion` | Versione minima supportata dell'host OpenClaw, usando un floor semver come `>=2026.3.22`. |
| `openclaw.install.allowInvalidConfigRecovery` | Consente un percorso ristretto di recupero della reinstallazione di Plugin bundle quando la configurazione non è valida. |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Consente il caricamento delle superfici del canale solo setup prima del Plugin di canale completo durante l'avvio. |
| Campo | Significato |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions` | Dichiara gli entrypoint nativi del plugin. |
| `openclaw.setupEntry` | Entry point leggero solo setup usato durante l'onboarding e l'avvio differito del canale. |
| `openclaw.channel` | Metadati leggeri del catalogo dei canali come etichette, percorsi della documentazione, alias e testo di selezione. |
| `openclaw.channel.configuredState` | Metadati leggeri del controllo dello stato configurato che possono rispondere a "esiste già una configurazione solo env?" senza caricare il runtime completo del canale. |
| `openclaw.channel.persistedAuthState` | Metadati leggeri del controllo dello stato di autenticazione persistito che possono rispondere a "c'è già qualcosa connesso?" senza caricare il runtime completo del canale. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Suggerimenti di installazione/aggiornamento per plugin bundle e plugin pubblicati esternamente. |
| `openclaw.install.defaultChoice` | Percorso di installazione preferito quando sono disponibili più origini di installazione. |
| `openclaw.install.minHostVersion` | Versione minima supportata dell'host OpenClaw, usando un vincolo semver minimo come `>=2026.3.22`. |
| `openclaw.install.allowInvalidConfigRecovery` | Consente un percorso limitato di recupero tramite reinstallazione del plugin bundle quando la configurazione non è valida. |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Consente il caricamento delle superfici del canale solo setup prima del plugin di canale completo durante l'avvio. |
`openclaw.install.minHostVersion` viene applicato durante l'installazione e il
caricamento del registro dei manifest. I valori non validi vengono rifiutati; i valori
più recenti ma validi saltano il Plugin sugli host più vecchi.
`openclaw.install.minHostVersion` viene applicato durante l'installazione e il caricamento del registro dei manifest. I valori non validi vengono rifiutati; i valori validi ma più recenti saltano il plugin sugli host più vecchi.
`openclaw.install.allowInvalidConfigRecovery` è intenzionalmente ristretto. Non
rende installabili configurazioni arbitrarie non funzionanti. Oggi consente solo ai flussi di installazione
di recuperare da specifici errori di upgrade obsoleti di Plugin bundle, come un
percorso mancante del Plugin bundle o una voce `channels.<id>` obsoleta per quello stesso
Plugin bundle. Errori di configurazione non correlati continuano a bloccare l'installazione e indirizzano gli operatori
a `openclaw doctor --fix`.
`openclaw.install.allowInvalidConfigRecovery` è intenzionalmente limitato. Non rende installabili configurazioni arbitrarie non funzionanti. Oggi consente solo ai flussi di installazione di recuperare da specifici errori di aggiornamento obsoleti di plugin bundle, come un percorso mancante del plugin bundle o una voce obsoleta `channels.<id>` per quello stesso plugin bundle. Errori di configurazione non correlati continuano a bloccare l'installazione e indirizzano gli operatori a `openclaw doctor --fix`.
`openclaw.channel.persistedAuthState` è un metadato di package per un piccolo
modulo di controllo:
`openclaw.channel.persistedAuthState` è un metadato di package per un piccolo modulo di controllo:
```json
{
@ -545,13 +496,9 @@ modulo di controllo:
}
```
Usalo quando i flussi di setup, doctor o stato configurato hanno bisogno di una
verifica auth economica sì/no prima che il Plugin di canale completo venga caricato. L'export di destinazione deve essere una piccola
funzione che legge solo lo stato persistito; non instradarla attraverso il barrel di runtime
completo del canale.
Usalo quando i flussi di setup, doctor o stato configurato hanno bisogno di una verifica economica sì/no dell'autenticazione prima che il plugin completo del canale venga caricato. L'export di destinazione deve essere una piccola funzione che legge solo lo stato persistito; non instradarla attraverso il barrel completo del runtime del canale.
`openclaw.channel.configuredState` segue la stessa forma per controlli economici
dello stato configurato solo env:
`openclaw.channel.configuredState` segue la stessa forma per controlli economici dello stato configurato solo env:
```json
{
@ -567,65 +514,45 @@ dello stato configurato solo env:
}
```
Usalo quando un canale può rispondere sullo stato configurato da env o da altri
piccoli input non di runtime. Se il controllo richiede la risoluzione completa della configurazione o il vero
runtime del canale, mantieni invece quella logica nell'hook `config.hasConfiguredState`
del Plugin.
Usalo quando un canale può determinare lo stato configurato da env o da altri input minimi non di runtime. Se il controllo richiede la risoluzione completa della configurazione o il vero runtime del canale, mantieni invece quella logica nell'hook del plugin `config.hasConfiguredState`.
## Requisiti dello schema JSON
- **Ogni Plugin deve distribuire uno schema JSON**, anche se non accetta alcuna configurazione.
- **Ogni plugin deve includere uno schema JSON**, anche se non accetta alcuna configurazione.
- È accettabile uno schema vuoto, ad esempio `{ "type": "object", "additionalProperties": false }`.
- Gli schemi vengono validati in fase di lettura/scrittura della configurazione, non in fase di runtime.
- Gli schemi vengono convalidati al momento della lettura/scrittura della configurazione, non a runtime.
## Comportamento della validazione
## Comportamento della convalida
- Le chiavi `channels.*` sconosciute sono **errori**, a meno che l'ID del canale non sia dichiarato da
un manifest del Plugin.
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` e `plugins.slots.*`
devono fare riferimento a ID di Plugin **rilevabili**. Gli ID sconosciuti sono **errori**.
- Se un Plugin è installato ma ha un manifest o uno schema mancante o non valido,
la validazione fallisce e Doctor segnala l'errore del Plugin.
- Se la configurazione del Plugin esiste ma il Plugin è **disabilitato**, la configurazione viene mantenuta e
viene mostrato un **avviso** in Doctor + nei log.
- Le chiavi sconosciute `channels.*` sono **errori**, a meno che l'ID del canale non sia dichiarato da un manifest di plugin.
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` e `plugins.slots.*` devono fare riferimento a ID di plugin **rilevabili**. Gli ID sconosciuti sono **errori**.
- Se un plugin è installato ma ha un manifest o uno schema mancante o non valido, la convalida fallisce e Doctor segnala l'errore del plugin.
- Se la configurazione del plugin esiste ma il plugin è **disabilitato**, la configurazione viene mantenuta e viene mostrato un **avviso** in Doctor + nei log.
Vedi [Riferimento della configurazione](/it/gateway/configuration) per lo schema completo `plugins.*`.
## Note
- Il manifest è **obbligatorio per i Plugin OpenClaw nativi**, inclusi i caricamenti locali dal filesystem.
- Il runtime carica comunque separatamente il modulo del Plugin; il manifest serve solo per
discovery + validazione.
- I manifest nativi vengono analizzati con JSON5, quindi commenti, virgole finali e
chiavi non tra virgolette sono accettati purché il valore finale sia comunque un oggetto.
- Solo i campi del manifest documentati vengono letti dal loader del manifest. Evita di aggiungere
qui chiavi personalizzate di primo livello.
- `providerAuthEnvVars` è il percorso di metadati economico per probe auth, validazione
dei marker env e superfici simili di autenticazione del provider che non devono avviare il runtime del Plugin
solo per ispezionare i nomi env.
- `providerAuthAliases` consente alle varianti del provider di riutilizzare le variabili env di auth,
i profili auth, l'autenticazione supportata dalla configurazione e la scelta di onboarding della chiave API
di un altro provider senza codificare rigidamente questa relazione nel core.
- `channelEnvVars` è il percorso di metadati economico per fallback shell-env, prompt
di setup e superfici simili del canale che non devono avviare il runtime del Plugin
solo per ispezionare i nomi env.
- `providerAuthChoices` è il percorso di metadati economico per selettori di scelta auth,
risoluzione di `--auth-choice`, mappatura del provider preferito e semplice registrazione
dei flag CLI di onboarding prima che il runtime del provider venga caricato. Per i metadati della procedura guidata di runtime
che richiedono codice del provider, vedi
[Hook di runtime del provider](/it/plugins/architecture#provider-runtime-hooks).
- I tipi esclusivi di Plugin vengono selezionati tramite `plugins.slots.*`.
- Il manifest è **obbligatorio per i plugin nativi OpenClaw**, inclusi i caricamenti dal filesystem locale.
- Il runtime continua a caricare separatamente il modulo del plugin; il manifest serve solo per discovery + convalida.
- I manifest nativi vengono analizzati con JSON5, quindi commenti, virgole finali e chiavi senza virgolette sono accettati purché il valore finale resti un oggetto.
- Solo i campi del manifest documentati vengono letti dal loader del manifest. Evita di aggiungere qui chiavi personalizzate di primo livello.
- `providerAuthEnvVars` è il percorso di metadati leggero per probe di autenticazione, convalida di marcatori env e superfici simili di auth del provider che non devono avviare il runtime del plugin solo per ispezionare i nomi env.
- `providerAuthAliases` consente alle varianti del provider di riutilizzare le variabili d'ambiente di auth di un altro provider, i profili di autenticazione, l'auth basata sulla configurazione e la scelta di onboarding della chiave API senza hardcodare questa relazione nel core.
- `providerEndpoints` consente ai plugin provider di possedere semplici metadati di corrispondenza host/baseUrl degli endpoint. Usalo solo per classi di endpoint già supportate dal core; il plugin continua a possedere il comportamento di runtime.
- `syntheticAuthRefs` è il percorso di metadati leggero per hook di auth sintetica posseduti dal provider che devono essere visibili alla discovery a freddo dei modelli prima che esista il registro di runtime. Elenca solo i riferimenti il cui provider di runtime o backend CLI implementa davvero `resolveSyntheticAuth`.
- `nonSecretAuthMarkers` è il percorso di metadati leggero per chiavi API segnaposto possedute dal plugin bundle, come marcatori di credenziali locali, OAuth o ambientali. Il core le tratta come non segrete per la visualizzazione dell'auth e gli audit dei segreti senza hardcodare il provider proprietario.
- `channelEnvVars` è il percorso di metadati leggero per fallback dell'ambiente shell, prompt di setup e superfici simili del canale che non devono avviare il runtime del plugin solo per ispezionare i nomi env.
- `providerAuthChoices` è il percorso di metadati leggero per selettori di scelta dell'autenticazione, risoluzione di `--auth-choice`, mapping del provider preferito e semplice registrazione dei flag CLI di onboarding prima che il runtime del provider venga caricato. Per i metadati del wizard di runtime che richiedono codice del provider, vedi [Hook di runtime del provider](/it/plugins/architecture#provider-runtime-hooks).
- I tipi esclusivi di plugin vengono selezionati tramite `plugins.slots.*`.
- `kind: "memory"` viene selezionato da `plugins.slots.memory`.
- `kind: "context-engine"` viene selezionato da `plugins.slots.contextEngine`
(predefinito: `legacy` integrato).
- `channels`, `providers`, `cliBackends` e `skills` possono essere omessi quando un
Plugin non ne ha bisogno.
- Se il tuo Plugin dipende da moduli nativi, documenta i passaggi di build e qualsiasi
requisito di allowlist del package manager (ad esempio, pnpm `allow-build-scripts`
- `kind: "context-engine"` viene selezionato da `plugins.slots.contextEngine` (predefinito: `legacy` integrato).
- `channels`, `providers`, `cliBackends` e `skills` possono essere omessi quando un plugin non ne ha bisogno.
- Se il tuo plugin dipende da moduli nativi, documenta i passaggi di build e gli eventuali requisiti di allowlist del gestore di pacchetti (ad esempio, pnpm `allow-build-scripts`
- `pnpm rebuild <package>`).
## Correlati
- [Creazione di Plugin](/it/plugins/building-plugins) — introduzione ai Plugin
- [Creazione di Plugin](/it/plugins/building-plugins) — introduzione ai plugin
- [Architettura dei Plugin](/it/plugins/architecture) — architettura interna
- [Panoramica dell'SDK](/it/plugins/sdk-overview) — riferimento dell'SDK del Plugin
- [Panoramica dell'SDK](/it/plugins/sdk-overview) — riferimento del Plugin SDK

412
docs/it/plugins/sdk-migration.md
View File

@ -5,44 +5,33 @@ read_when:
- Stai aggiornando un Plugin alla moderna architettura dei plugin
- Gestisci un Plugin OpenClaw esterno
sidebarTitle: Migrate to SDK
summary: Migra dal livello legacy di retrocompatibilità al moderno Plugin SDK
summary: Migra dal livello legacy di retrocompatibilità al moderno SDK dei plugin
title: Migrazione al Plugin SDK
x-i18n:
generated_at: "2026-04-17T08:17:30Z"
generated_at: "2026-04-19T01:11:10Z"
model: gpt-5.4
provider: openai
source_hash: f0283f949eec358a12a0709db846cde2a1509f28e5c60db6e563cb8a540b979d
source_hash: e0df202ed35b3e72bfec1d23201d0e83294fe09cec2caf6e276835098491a899
source_path: plugins/sdk-migration.md
workflow: 15
---
# Migrazione al Plugin SDK
OpenClaw è passato da un ampio livello di retrocompatibilità a una moderna
architettura dei plugin con import mirati e documentati. Se il tuo plugin è
stato creato prima della nuova architettura, questa guida ti aiuta a eseguire
la migrazione.
OpenClaw è passato da un ampio livello di retrocompatibilità a una moderna architettura dei plugin con import focalizzati e documentati. Se il tuo plugin è stato creato prima della nuova architettura, questa guida ti aiuta a effettuare la migrazione.
## Cosa sta cambiando
Il vecchio sistema dei plugin forniva due superfici molto ampie che
consentivano ai plugin di importare tutto ciò di cui avevano bisogno da un
unico punto di ingresso:
Il vecchio sistema dei plugin forniva due superfici molto ampie che permettevano ai plugin di importare tutto ciò di cui avevano bisogno da un unico punto di ingresso:
- **`openclaw/plugin-sdk/compat`** — un singolo import che riesportava decine di
helper. È stato introdotto per mantenere funzionanti i plugin più vecchi
basati su hook mentre veniva sviluppata la nuova architettura dei plugin.
- **`openclaw/extension-api`** — un bridge che dava ai plugin accesso diretto a
helper lato host come l'embedded agent runner.
- **`openclaw/plugin-sdk/compat`** — un singolo import che riesportava decine di helper. È stato introdotto per mantenere funzionanti i vecchi plugin basati su hook mentre veniva sviluppata la nuova architettura dei plugin.
- **`openclaw/extension-api`** — un bridge che forniva ai plugin accesso diretto agli helper lato host, come l'embedded agent runner.
Entrambe le superfici sono ora **deprecate**. Continuano a funzionare a
runtime, ma i nuovi plugin non devono usarle e i plugin esistenti dovrebbero
migrare prima che la prossima major release le rimuova.
Entrambe le superfici sono ora **deprecate**. Continuano a funzionare in fase di runtime, ma i nuovi plugin non devono usarle e i plugin esistenti dovrebbero migrare prima che la prossima major release le rimuova.
<Warning>
Il livello di retrocompatibilità verrà rimosso in una futura major release.
I plugin che continuano a importare da queste superfici smetteranno di
funzionare quando ciò accadrà.
I plugin che importano ancora da queste superfici smetteranno di funzionare quando ciò accadrà.
</Warning>
## Perché è cambiato
@ -50,84 +39,56 @@ migrare prima che la prossima major release le rimuova.
Il vecchio approccio causava problemi:
- **Avvio lento** — importare un helper caricava decine di moduli non correlati
- **Dipendenze circolari** — riesportazioni ampie rendevano facile creare cicli di importazione
- **Dipendenze circolari** — le riesportazioni ampie rendevano facile creare cicli di import
- **Superficie API poco chiara** — non c'era modo di capire quali export fossero stabili e quali interni
Il moderno Plugin SDK risolve questo problema: ogni percorso di import
(`openclaw/plugin-sdk/\<subpath\>`) è un modulo piccolo e autosufficiente con
uno scopo chiaro e un contratto documentato.
Il moderno Plugin SDK risolve questo problema: ogni percorso di import (`openclaw/plugin-sdk/\<subpath\>`) è un modulo piccolo e autonomo con uno scopo chiaro e un contratto documentato.
Sono stati rimossi anche i legacy convenience seam dei provider per i canali
inclusi. Import come `openclaw/plugin-sdk/slack`,
`openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`,
`openclaw/plugin-sdk/whatsapp`, i channel-branded helper seam e
`openclaw/plugin-sdk/telegram-core` erano scorciatoie private del mono-repo,
non contratti plugin stabili. Usa invece subpath SDK generici e mirati.
All'interno del workspace dei plugin inclusi, mantieni gli helper di proprietà
del provider nel file `api.ts` o `runtime-api.ts` del plugin stesso.
Anche i legacy provider convenience seams per i canali bundled non esistono più. Import come `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, i channel-branded helper seams e `openclaw/plugin-sdk/telegram-core` erano scorciatoie private del mono-repo, non contratti stabili per i plugin. Usa invece subpath generici e mirati del SDK. All'interno del workspace dei plugin bundled, mantieni gli helper del provider nel file `api.ts` o `runtime-api.ts` di quel plugin.
Esempi attuali di provider inclusi:
Esempi attuali di provider bundled:
- Anthropic mantiene gli helper di stream specifici per Claude nel proprio seam
`api.ts` / `contract-api.ts`
- OpenAI mantiene i provider builder, gli helper per i modelli predefiniti e i
realtime provider builder nel proprio `api.ts`
- OpenRouter mantiene il provider builder e gli helper di onboarding/config nel
proprio `api.ts`
- Anthropic mantiene gli helper di stream specifici per Claude nel proprio seam `api.ts` / `contract-api.ts`
- OpenAI mantiene i builder del provider, gli helper per il modello predefinito e i builder del provider realtime nel proprio `api.ts`
- OpenRouter mantiene il builder del provider e gli helper di onboarding/config nel proprio `api.ts`
## Come eseguire la migrazione
## Come effettuare la migrazione
<Steps>
<Step title="Migra gli handler approval-native ai capability fact">
I plugin di canale con capacità di approvazione ora espongono il
comportamento di approvazione nativo tramite
`approvalCapability.nativeRuntime` più il registro condiviso del contesto di runtime.
<Step title="Migra gli handler approval-native ai capability facts">
I plugin di canale con capacità di approvazione ora espongono il comportamento di approvazione nativo tramite `approvalCapability.nativeRuntime` insieme al registro condiviso del contesto runtime.
Modifiche principali:
- Sostituisci `approvalCapability.handler.loadRuntime(...)` con
`approvalCapability.nativeRuntime`
- Sposta l'autenticazione/consegna specifica per l'approvazione dal legacy
wiring `plugin.auth` / `plugin.approvals` a `approvalCapability`
- `ChannelPlugin.approvals` è stato rimosso dal contratto pubblico del
channel plugin; sposta i campi delivery/native/render in `approvalCapability`
- `plugin.auth` resta solo per i flussi di login/logout del canale; gli hook
di autenticazione per l'approvazione non vengono più letti dal core
- Registra gli oggetti di runtime di proprietà del canale come client,
token o app Bolt tramite
`openclaw/plugin-sdk/channel-runtime-context`
- Non inviare avvisi di reroute di proprietà del plugin dagli handler di
approvazione nativi; il core ora gestisce gli avvisi di instradamento
altrove dai risultati effettivi di consegna
- Quando passi `channelRuntime` a `createChannelManager(...)`, fornisci una
vera superficie `createPluginRuntime().channel`. Gli stub parziali
vengono rifiutati.
- Sostituisci `approvalCapability.handler.loadRuntime(...)` con `approvalCapability.nativeRuntime`
- Sposta auth/delivery specifici per l'approvazione dal legacy wiring `plugin.auth` / `plugin.approvals` a `approvalCapability`
- `ChannelPlugin.approvals` è stato rimosso dal contratto pubblico del channel-plugin; sposta i campi delivery/native/render su `approvalCapability`
- `plugin.auth` rimane solo per i flussi di login/logout del canale; gli hook di auth per l'approvazione presenti lì non vengono più letti dal core
- Registra gli oggetti runtime posseduti dal canale, come client, token o app Bolt, tramite `openclaw/plugin-sdk/channel-runtime-context`
- Non inviare avvisi di reindirizzamento posseduti dal plugin dagli handler di approvazione nativi; il core ora gestisce gli avvisi instradati altrove a partire dai risultati di delivery reali
- Quando passi `channelRuntime` a `createChannelManager(...)`, fornisci una vera superficie `createPluginRuntime().channel`. Gli stub parziali vengono rifiutati.
Vedi `/plugins/sdk-channel-plugins` per l'attuale layout della capability
di approvazione.
Vedi `/plugins/sdk-channel-plugins` per il layout corrente della capability di approvazione.
</Step>
<Step title="Controlla il comportamento di fallback del wrapper Windows">
Se il tuo plugin usa `openclaw/plugin-sdk/windows-spawn`, i wrapper Windows
`.cmd`/`.bat` non risolti ora falliscono in modo chiuso a meno che tu non
passi esplicitamente `allowShellFallback: true`.
<Step title="Verifica il comportamento di fallback del wrapper Windows">
Se il tuo plugin usa `openclaw/plugin-sdk/windows-spawn`, i wrapper Windows `.cmd`/`.bat` non risolti ora falliscono in modo chiuso a meno che tu non passi esplicitamente `allowShellFallback: true`.
```typescript
// Prima
// Before
const program = applyWindowsSpawnProgramPolicy({ candidate });
// Dopo
// After
const program = applyWindowsSpawnProgramPolicy({
candidate,
// Imposta questo solo per chiamanti di compatibilità attendibili che
// accettano intenzionalmente il fallback mediato dalla shell.
// Only set this for trusted compatibility callers that intentionally
// accept shell-mediated fallback.
allowShellFallback: true,
});
```
Se il tuo chiamante non dipende intenzionalmente dal fallback della shell,
non impostare `allowShellFallback` e gestisci invece l'errore generato.
Se il tuo chiamante non dipende intenzionalmente dal fallback della shell, non impostare `allowShellFallback` e gestisci invece l'errore generato.
</Step>
@ -141,37 +102,35 @@ Esempi attuali di provider inclusi:
</Step>
<Step title="Sostituisci con import mirati">
Ogni export della vecchia superficie corrisponde a uno specifico percorso
di import moderno:
<Step title="Sostituisci con import focalizzati">
Ogni export della vecchia superficie corrisponde a uno specifico percorso di import moderno:
```typescript
// Prima (livello di retrocompatibilità deprecato)
// Before (deprecated backwards-compatibility layer)
import {
createChannelReplyPipeline,
createPluginRuntimeStore,
resolveControlCommandGate,
} from "openclaw/plugin-sdk/compat";
// Dopo (import moderni e mirati)
// After (modern focused imports)
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
```
Per gli helper lato host, usa il runtime del plugin iniettato invece di
importare direttamente:
Per gli helper lato host, usa invece il runtime del plugin iniettato invece di importare direttamente:
```typescript
// Prima (bridge extension-api deprecato)
// Before (deprecated extension-api bridge)
import { runEmbeddedPiAgent } from "openclaw/extension-api";
const result = await runEmbeddedPiAgent({ sessionId, prompt });
// Dopo (runtime iniettato)
// After (injected runtime)
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
```
Lo stesso schema si applica ad altri helper legacy del bridge:
Lo stesso schema si applica agli altri helper legacy del bridge:
| Vecchio import | Equivalente moderno |
| --- | --- |
@ -185,7 +144,7 @@ Esempi attuali di provider inclusi:
</Step>
<Step title="Build e test">
<Step title="Compila ed esegui i test">
```bash
pnpm build
pnpm test -- my-plugin/
@ -198,207 +157,190 @@ Esempi attuali di provider inclusi:
<Accordion title="Tabella comune dei percorsi di import">
| Percorso di import | Scopo | Export principali |
| --- | --- | --- |
| `plugin-sdk/plugin-entry` | Helper canonico per il punto di ingresso del plugin | `definePluginEntry` |
| `plugin-sdk/plugin-entry` | Helper canonico per l'entry del plugin | `definePluginEntry` |
| `plugin-sdk/core` | Riesportazione legacy ombrello per definizioni/builder di entry dei canali | `defineChannelPluginEntry`, `createChatChannelPlugin` |
| `plugin-sdk/config-schema` | Export dello schema di configurazione radice | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | Helper per entry a provider singolo | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | Definizioni e builder mirati per l'entry del canale | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | Helper condivisi per la procedura guidata di configurazione | Prompt di allowlist, builder dello stato di configurazione |
| `plugin-sdk/setup-runtime` | Helper di runtime per il setup | Adapter di patch setup import-safe, helper per note di lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proxy di setup delegati |
| `plugin-sdk/config-schema` | Export dello schema di configurazione root | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | Helper per entry con provider singolo | `defineSingleProviderPluginEntry` |
| `plugin-sdk/channel-core` | Definizioni e builder focalizzati per le entry dei canali | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/setup` | Helper condivisi per la procedura guidata di setup | Prompt di allowlist, builder dello stato di setup |
| `plugin-sdk/setup-runtime` | Helper runtime per il setup | Adapter di patch setup import-safe, helper per note di lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proxy di setup delegati |
| `plugin-sdk/setup-adapter-runtime` | Helper per adapter di setup | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | Helper di tooling per il setup | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Helper multi-account | Helper per elenco account/config/action-gate |
| `plugin-sdk/setup-tools` | Helper per gli strumenti di setup | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Helper multi-account | Helper per elenco/configurazione/gate delle azioni degli account |
| `plugin-sdk/account-id` | Helper per account-id | `DEFAULT_ACCOUNT_ID`, normalizzazione di account-id |
| `plugin-sdk/account-resolution` | Helper per la risoluzione degli account | Helper per lookup account + fallback predefinito |
| `plugin-sdk/account-helpers` | Helper mirati per account | Helper per elenco account/account-action |
| `plugin-sdk/channel-setup` | Adapter della procedura guidata di configurazione | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, più `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/channel-pairing` | Primitive per l'associazione DM | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | Wiring per prefisso risposta + digitazione | `createChannelReplyPipeline` |
| `plugin-sdk/account-resolution` | Helper per la ricerca degli account | Helper per la ricerca degli account + fallback predefinito |
| `plugin-sdk/account-helpers` | Helper mirati per account | Helper per elenco account/azioni sugli account |
| `plugin-sdk/channel-setup` | Adapter per la procedura guidata di setup | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, più `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/channel-pairing` | Primitive di pairing DM | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | Wiring per prefisso della risposta + digitazione | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | Factory per adapter di configurazione | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Builder per schema di configurazione | Tipi di schema di configurazione del canale |
| `plugin-sdk/telegram-command-config` | Helper di configurazione dei comandi Telegram | Normalizzazione del nome comando, trimming della descrizione, validazione di duplicati/conflitti |
| `plugin-sdk/channel-policy` | Risoluzione delle policy gruppo/DM | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | Tracciamento dello stato account | `createAccountStatusSink` |
| `plugin-sdk/channel-config-schema` | Builder dello schema di configurazione | Tipi dello schema di configurazione del canale |
| `plugin-sdk/telegram-command-config` | Helper per la configurazione dei comandi Telegram | Normalizzazione del nome del comando, trimming della descrizione, validazione di duplicati/conflitti |
| `plugin-sdk/channel-policy` | Risoluzione delle policy per gruppi/DM | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | Tracciamento dello stato dell'account | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | Helper per inbound envelope | Helper condivisi per route + builder di envelope |
| `plugin-sdk/inbound-reply-dispatch` | Helper per risposte in ingresso | Helper condivisi per registrazione e dispatch |
| `plugin-sdk/inbound-reply-dispatch` | Helper per le risposte in ingresso | Helper condivisi per registrazione e dispatch |
| `plugin-sdk/messaging-targets` | Parsing dei target di messaggistica | Helper per parsing/matching dei target |
| `plugin-sdk/outbound-media` | Helper per media in uscita | Caricamento condiviso dei media in uscita |
| `plugin-sdk/outbound-runtime` | Helper di runtime per l'uscita | Helper per identità in uscita/delegati di invio |
| `plugin-sdk/outbound-runtime` | Helper runtime per l'uscita | Helper per identità in uscita/delegati di invio |
| `plugin-sdk/thread-bindings-runtime` | Helper per thread-binding | Helper per ciclo di vita dei thread-binding e adapter |
| `plugin-sdk/agent-media-payload` | Helper legacy per media payload | Builder di media payload dell'agente per layout legacy dei campi |
| `plugin-sdk/channel-runtime` | Shim di compatibilità deprecato | Solo utility legacy per channel runtime |
| `plugin-sdk/agent-media-payload` | Helper legacy per payload media | Builder del payload media dell'agente per layout legacy dei campi |
| `plugin-sdk/channel-runtime` | Shim di compatibilità deprecato | Solo utility legacy per il runtime del canale |
| `plugin-sdk/channel-send-result` | Tipi del risultato di invio | Tipi del risultato di risposta |
| `plugin-sdk/runtime-store` | Archiviazione persistente del plugin | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | Helper di runtime ad ampio spettro | Helper per runtime/logging/backup/installazione plugin |
| `plugin-sdk/runtime-env` | Helper mirati per l'ambiente di runtime | Helper per logger/runtime env, timeout, retry e backoff |
| `plugin-sdk/plugin-runtime` | Helper condivisi per plugin runtime | Helper per comandi/hook/http/interattività del plugin |
| `plugin-sdk/hook-runtime` | Helper per la pipeline degli hook | Helper condivisi per la pipeline di webhook/hook interni |
| `plugin-sdk/lazy-runtime` | Helper per lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helper per i processi | Helper condivisi per `exec` |
| `plugin-sdk/cli-runtime` | Helper di runtime per CLI | Formattazione comandi, attese, helper per versione |
| `plugin-sdk/gateway-runtime` | Helper per Gateway | Client Gateway e helper di patch dello stato del canale |
| `plugin-sdk/runtime-store` | Storage persistente del plugin | `createPluginRuntimeStore` |
| `plugin-sdk/runtime` | Helper runtime ampi | Helper per runtime/logging/backup/installazione plugin |
| `plugin-sdk/runtime-env` | Helper mirati per runtime env | Logger/runtime env, helper per timeout, retry e backoff |
| `plugin-sdk/plugin-runtime` | Helper runtime condivisi del plugin | Helper per comandi/hook/http/interattivi del plugin |
| `plugin-sdk/hook-runtime` | Helper per la pipeline degli hook | Helper condivisi per pipeline di webhook/hook interni |
| `plugin-sdk/lazy-runtime` | Helper per runtime lazy | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helper di processo | Helper condivisi per exec |
| `plugin-sdk/cli-runtime` | Helper runtime per CLI | Formattazione dei comandi, attese, helper per versione |
| `plugin-sdk/gateway-runtime` | Helper per Gateway | Client Gateway e helper per patch dello stato dei canali |
| `plugin-sdk/config-runtime` | Helper di configurazione | Helper per caricamento/scrittura della configurazione |
| `plugin-sdk/telegram-command-config` | Helper per comandi Telegram | Helper di validazione dei comandi Telegram con fallback stabile quando la superficie del contratto Telegram inclusa non è disponibile |
| `plugin-sdk/approval-runtime` | Helper per prompt di approvazione | Payload di approvazione exec/plugin, helper per capability/profili di approvazione, helper di routing/runtime per approvazioni native |
| `plugin-sdk/approval-auth-runtime` | Helper di autenticazione per approvazione | Risoluzione degli approvatori, autenticazione delle azioni nella stessa chat |
| `plugin-sdk/approval-client-runtime` | Helper client per approvazione | Helper per profili/filtri di approvazione exec native |
| `plugin-sdk/approval-delivery-runtime` | Helper di consegna per approvazione | Adapter per capability/consegna di approvazioni native |
| `plugin-sdk/approval-gateway-runtime` | Helper Gateway per approvazione | Helper condiviso per la risoluzione del gateway di approvazione |
| `plugin-sdk/approval-handler-adapter-runtime` | Helper adapter per approvazione | Helper leggeri per il caricamento di adapter di approvazione nativi per hot channel entrypoint |
| `plugin-sdk/approval-handler-runtime` | Helper handler per approvazione | Helper di runtime più ampi per handler di approvazione; preferisci i seam adapter/gateway più mirati quando bastano |
| `plugin-sdk/approval-native-runtime` | Helper per target di approvazione | Helper di binding target/account per approvazioni native |
| `plugin-sdk/approval-reply-runtime` | Helper per risposta di approvazione | Helper per payload di risposta di approvazione exec/plugin |
| `plugin-sdk/channel-runtime-context` | Helper per channel runtime-context | Helper generici per register/get/watch del channel runtime-context |
| `plugin-sdk/security-runtime` | Helper di sicurezza | Helper condivisi per trust, gating DM, contenuti esterni e raccolta di segreti |
| `plugin-sdk/ssrf-policy` | Helper per policy SSRF | Helper per allowlist host e policy di rete privata |
| `plugin-sdk/ssrf-runtime` | Helper di runtime SSRF | Dispatcher pinning, fetch protetta, helper per policy SSRF |
| `plugin-sdk/telegram-command-config` | Helper per comandi Telegram | Helper di validazione dei comandi Telegram stabili con fallback quando la superficie contrattuale del Telegram bundled non è disponibile |
| `plugin-sdk/approval-runtime` | Helper per prompt di approvazione | Payload di approvazione exec/plugin, helper per capability/profilo di approvazione, helper runtime/routing di approvazione nativa |
| `plugin-sdk/approval-auth-runtime` | Helper di auth per l'approvazione | Risoluzione degli approvatori, auth delle azioni nella stessa chat |
| `plugin-sdk/approval-client-runtime` | Helper client per l'approvazione | Helper per profili/filtri di approvazione exec nativa |
| `plugin-sdk/approval-delivery-runtime` | Helper di delivery per l'approvazione | Adapter per capability/delivery di approvazione nativa |
| `plugin-sdk/approval-gateway-runtime` | Helper Gateway per l'approvazione | Helper condiviso per la risoluzione del Gateway di approvazione |
| `plugin-sdk/approval-handler-adapter-runtime` | Helper per adapter di approvazione | Helper leggeri per il caricamento di adapter di approvazione nativa per entrypoint hot dei canali |
| `plugin-sdk/approval-handler-runtime` | Helper per handler di approvazione | Helper runtime più ampi per handler di approvazione; preferisci i seam adapter/gateway più mirati quando sono sufficienti |
| `plugin-sdk/approval-native-runtime` | Helper per target di approvazione | Helper per binding tra target/account di approvazione nativa |
| `plugin-sdk/approval-reply-runtime` | Helper per risposte di approvazione | Helper per payload di risposta di approvazione exec/plugin |
| `plugin-sdk/channel-runtime-context` | Helper per il contesto runtime del canale | Helper generici per register/get/watch del contesto runtime del canale |
| `plugin-sdk/security-runtime` | Helper di sicurezza | Helper condivisi per trust, gating DM, contenuti esterni e raccolta di secret |
| `plugin-sdk/ssrf-policy` | Helper per policy SSRF | Helper per allowlist degli host e policy di rete privata |
| `plugin-sdk/ssrf-runtime` | Helper runtime SSRF | Helper per pinned-dispatcher, fetch protetto e policy SSRF |
| `plugin-sdk/collection-runtime` | Helper per cache limitata | `pruneMapToMaxSize` |
| `plugin-sdk/diagnostic-runtime` | Helper per gating diagnostico | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | Helper per formattazione errori | `formatUncaughtError`, `isApprovalNotFoundError`, helper per grafi di errori |
| `plugin-sdk/fetch-runtime` | Helper per fetch/proxy con wrapper | `resolveFetch`, helper per proxy |
| `plugin-sdk/host-runtime` | Helper per normalizzazione host | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | Helper per retry | `RetryConfig`, `retryAsync`, runner di policy |
| `plugin-sdk/allow-from` | Formattazione della allowlist | `formatAllowFromLowercase` |
| `plugin-sdk/allowlist-resolution` | Mappatura degli input di allowlist | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | Helper per command gating e superfici dei comandi | `resolveControlCommandGate`, helper per autorizzazione del mittente, helper per registro dei comandi |
| `plugin-sdk/diagnostic-runtime` | Helper per il gating diagnostico | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
| `plugin-sdk/error-runtime` | Helper per la formattazione degli errori | `formatUncaughtError`, `isApprovalNotFoundError`, helper del grafo degli errori |
| `plugin-sdk/fetch-runtime` | Helper per fetch/proxy wrapperizzati | `resolveFetch`, helper per proxy |
| `plugin-sdk/host-runtime` | Helper per la normalizzazione dell'host | `normalizeHostname`, `normalizeScpRemoteHost` |
| `plugin-sdk/retry-runtime` | Helper per retry | `RetryConfig`, `retryAsync`, esecutori di policy |
| `plugin-sdk/allow-from` | Formattazione dell'allowlist | `formatAllowFromLowercase` |
| `plugin-sdk/allowlist-resolution` | Mappatura degli input dell'allowlist | `mapAllowlistResolutionInputs` |
| `plugin-sdk/command-auth` | Gating dei comandi e helper per la superficie dei comandi | `resolveControlCommandGate`, helper per l'autorizzazione del mittente, helper per il registro dei comandi |
| `plugin-sdk/command-status` | Renderer di stato/help dei comandi | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
| `plugin-sdk/secret-input` | Parsing dell'input segreto | Helper per input segreto |
| `plugin-sdk/secret-input` | Parsing degli input secret | Helper per input secret |
| `plugin-sdk/webhook-ingress` | Helper per richieste Webhook | Utility per target Webhook |
| `plugin-sdk/webhook-request-guards` | Helper di guardia per body Webhook | Helper per lettura/limite del corpo della richiesta |
| `plugin-sdk/webhook-request-guards` | Helper di guardia per i body Webhook | Helper per lettura/limite del body della richiesta |
| `plugin-sdk/reply-runtime` | Runtime condiviso per le risposte | Dispatch in ingresso, Heartbeat, pianificatore delle risposte, chunking |
| `plugin-sdk/reply-dispatch-runtime` | Helper mirati per il dispatch delle risposte | Helper per finalizzazione + dispatch del provider |
| `plugin-sdk/reply-dispatch-runtime` | Helper mirati per il dispatch delle risposte | Helper per finalize + dispatch del provider |
| `plugin-sdk/reply-history` | Helper per reply-history | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | Pianificazione dei riferimenti di risposta | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Helper per chunk di risposta | Helper per chunking di testo/markdown |
| `plugin-sdk/session-store-runtime` | Helper per session store | Helper per percorso dello store + updated-at |
| `plugin-sdk/state-paths` | Helper per percorsi di stato | Helper per directory di stato e OAuth |
| `plugin-sdk/routing` | Helper per routing/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helper di normalizzazione per session-key |
| `plugin-sdk/status-helpers` | Helper per stato del canale | Builder di riepilogo dello stato canale/account, valori predefiniti dello stato runtime, helper per metadati dei problemi |
| `plugin-sdk/target-resolver-runtime` | Helper per target resolver | Helper condivisi per target resolver |
| `plugin-sdk/string-normalization-runtime` | Helper per normalizzazione stringhe | Helper per normalizzazione di slug/stringhe |
| `plugin-sdk/request-url` | Helper per URL della richiesta | Estrai URL stringa da input simili a request |
| `plugin-sdk/run-command` | Helper per comandi temporizzati | Runner di comandi temporizzati con stdout/stderr normalizzati |
| `plugin-sdk/state-paths` | Helper per i percorsi di stato | Helper per directory di stato e OAuth |
| `plugin-sdk/routing` | Helper per instradamento/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helper per la normalizzazione della session-key |
| `plugin-sdk/status-helpers` | Helper di stato del canale | Builder di riepilogo dello stato di canale/account, valori predefiniti dello stato runtime, helper per metadati dei problemi |
| `plugin-sdk/target-resolver-runtime` | Helper per il risolutore dei target | Helper condivisi per il risolutore dei target |
| `plugin-sdk/string-normalization-runtime` | Helper per la normalizzazione delle stringhe | Helper per la normalizzazione di slug/stringhe |
| `plugin-sdk/request-url` | Helper per URL di richiesta | Estrae URL stringa da input simili a request |
| `plugin-sdk/run-command` | Helper per comandi temporizzati | Esecutore di comandi temporizzati con `stdout`/`stderr` normalizzati |
| `plugin-sdk/param-readers` | Lettori di parametri | Lettori comuni di parametri per tool/CLI |
| `plugin-sdk/tool-payload` | Estrazione del payload dei tool | Estrai payload normalizzati dagli oggetti risultato dei tool |
| `plugin-sdk/tool-send` | Estrazione di invio dei tool | Estrai i campi canonici del target di invio dagli argomenti del tool |
| `plugin-sdk/tool-payload` | Estrazione del payload dei tool | Estrae payload normalizzati da oggetti risultato dei tool |
| `plugin-sdk/tool-send` | Estrazione di invio dei tool | Estrae campi target di invio canonici dagli argomenti del tool |
| `plugin-sdk/temp-path` | Helper per percorsi temporanei | Helper condivisi per percorsi temporanei di download |
| `plugin-sdk/logging-core` | Helper di logging | Logger di sottosistema e helper di redazione |
| `plugin-sdk/markdown-table-runtime` | Helper per tabelle Markdown | Helper per modalità delle tabelle Markdown |
| `plugin-sdk/reply-payload` | Tipi di risposta dei messaggi | Tipi di reply payload |
| `plugin-sdk/provider-setup` | Helper curati per il setup di provider locali/self-hosted | Helper per discovery/config di provider self-hosted |
| `plugin-sdk/self-hosted-provider-setup` | Helper mirati per il setup di provider self-hosted compatibili OpenAI | Gli stessi helper per discovery/config di provider self-hosted |
| `plugin-sdk/provider-auth-runtime` | Helper di autenticazione runtime del provider | Helper per la risoluzione runtime delle API key |
| `plugin-sdk/provider-auth-api-key` | Helper per setup API key del provider | Helper per onboarding API key/scrittura del profilo |
| `plugin-sdk/provider-auth-result` | Helper per risultato di autenticazione del provider | Builder standard del risultato di autenticazione OAuth |
| `plugin-sdk/provider-auth-login` | Helper per login interattivo del provider | Helper condivisi per login interattivo |
| `plugin-sdk/provider-env-vars` | Helper per env var del provider | Helper per lookup delle env var di autenticazione del provider |
| `plugin-sdk/provider-model-shared` | Helper condivisi per modelli/replay del provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder condivisi per replay-policy, helper per endpoint del provider e helper per normalizzazione degli id dei modelli |
| `plugin-sdk/provider-catalog-shared` | Helper condivisi per il catalogo provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/markdown-table-runtime` | Helper per tabelle Markdown | Helper per la modalità tabella Markdown |
| `plugin-sdk/reply-payload` | Tipi di risposta del messaggio | Tipi del payload di risposta |
| `plugin-sdk/provider-setup` | Helper curati per setup di provider locali/self-hosted | Helper per discovery/configurazione di provider self-hosted |
| `plugin-sdk/self-hosted-provider-setup` | Helper focalizzati per setup di provider self-hosted compatibili con OpenAI | Gli stessi helper per discovery/configurazione di provider self-hosted |
| `plugin-sdk/provider-auth-runtime` | Helper di auth runtime del provider | Helper runtime per la risoluzione delle API key |
| `plugin-sdk/provider-auth-api-key` | Helper di setup delle API key del provider | Helper per onboarding/scrittura profilo delle API key |
| `plugin-sdk/provider-auth-result` | Helper per auth-result del provider | Builder standard del risultato di auth OAuth |
| `plugin-sdk/provider-auth-login` | Helper di login interattivo del provider | Helper condivisi per login interattivo |
| `plugin-sdk/provider-env-vars` | Helper per env var del provider | Helper per lookup delle env var di auth del provider |
| `plugin-sdk/provider-model-shared` | Helper condivisi per modello/replay del provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder condivisi di replay-policy, helper per endpoint del provider e helper per la normalizzazione di model-id |
| `plugin-sdk/provider-catalog-shared` | Helper condivisi per il catalogo dei provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-onboard` | Patch di onboarding del provider | Helper di configurazione per l'onboarding |
| `plugin-sdk/provider-http` | Helper HTTP del provider | Helper generici per HTTP/capacità endpoint del provider |
| `plugin-sdk/provider-web-fetch` | Helper web-fetch del provider | Helper per registrazione/cache del provider web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Helper di configurazione web-search del provider | Helper mirati per configurazione/credenziali web-search per provider che non richiedono wiring di abilitazione del plugin |
| `plugin-sdk/provider-web-search-contract` | Helper del contratto web-search del provider | Helper mirati per il contratto di configurazione/credenziali web-search come `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setter/getter di credenziali con ambito |
| `plugin-sdk/provider-web-search-contract` | Helper contrattuali web-search del provider | Helper contrattuali mirati per configurazione/credenziali web-search come `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setter/getter di credenziali con scope |
| `plugin-sdk/provider-web-search` | Helper web-search del provider | Helper per registrazione/cache/runtime del provider web-search |
| `plugin-sdk/provider-tools` | Helper di compatibilità tool/schema del provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, cleanup + diagnostica dello schema Gemini e helper di compatibilità xAI come `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | Helper di utilizzo del provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` e altri helper di utilizzo del provider |
| `plugin-sdk/provider-stream` | Helper wrapper di stream del provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipi dei wrapper di stream e helper wrapper condivisi per Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/keyed-async-queue` | Coda asincrona ordinata | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | Helper media condivisi | Helper per fetch/transform/store dei media più builder di media payload |
| `plugin-sdk/media-generation-runtime` | Helper condivisi per la generazione media | Helper condivisi per failover, selezione dei candidati e messaggi di modello mancante per la generazione di immagini/video/musica |
| `plugin-sdk/media-understanding` | Helper per media-understanding | Tipi del provider di media understanding più export di helper per immagini/audio rivolti ai provider |
| `plugin-sdk/text-runtime` | Helper testuali condivisi | Rimozione del testo visibile all'assistente, helper per render/chunking/tabelle Markdown, helper di redazione, helper per tag di direttiva, utility di testo sicuro e relativi helper di testo/logging |
| `plugin-sdk/provider-transport-runtime` | Helper di trasporto del provider | Helper di trasporto nativi del provider come fetch protetto, trasformazioni dei messaggi di trasporto e stream di eventi di trasporto scrivibili |
| `plugin-sdk/keyed-async-queue` | Coda async ordinata | `KeyedAsyncQueue` |
| `plugin-sdk/media-runtime` | Helper media condivisi | Helper per fetch/trasformazione/store dei media più builder del payload media |
| `plugin-sdk/media-generation-runtime` | Helper condivisi per la generazione di media | Helper condivisi per failover, selezione dei candidati e messaggi di modello mancante per la generazione di immagini/video/musica |
| `plugin-sdk/media-understanding` | Helper per media-understanding | Tipi del provider per media understanding più export di helper lato provider per immagini/audio |
| `plugin-sdk/text-runtime` | Helper di testo condivisi | Rimozione del testo visibile all'assistente, helper per rendering/chunking/tabelle Markdown, helper di redazione, helper per directive-tag, utility di testo sicuro e relativi helper per testo/logging |
| `plugin-sdk/text-chunking` | Helper per chunking del testo | Helper per chunking del testo in uscita |
| `plugin-sdk/speech` | Helper Speech | Tipi dei provider Speech più helper rivolti ai provider per direttive, registry e validazione |
| `plugin-sdk/speech-core` | Core Speech condiviso | Tipi dei provider Speech, registry, direttive, normalizzazione |
| `plugin-sdk/realtime-transcription` | Helper per trascrizione realtime | Tipi dei provider e helper per registry |
| `plugin-sdk/realtime-voice` | Helper per voce realtime | Tipi dei provider e helper per registry |
| `plugin-sdk/image-generation-core` | Core condiviso per la generazione di immagini | Tipi per la generazione di immagini, helper per failover, autenticazione e registry |
| `plugin-sdk/music-generation` | Helper per la generazione musicale | Tipi di provider/richiesta/risultato per la generazione musicale |
| `plugin-sdk/music-generation-core` | Core condiviso per la generazione musicale | Tipi per la generazione musicale, helper per failover, lookup dei provider e parsing di model-ref |
| `plugin-sdk/video-generation` | Helper per la generazione video | Tipi di provider/richiesta/risultato per la generazione video |
| `plugin-sdk/video-generation-core` | Core condiviso per la generazione video | Tipi per la generazione video, helper per failover, lookup dei provider e parsing di model-ref |
| `plugin-sdk/speech` | Helper Speech | Tipi del provider Speech più export di helper lato provider per directive, registro e validazione |
| `plugin-sdk/speech-core` | Core Speech condiviso | Tipi del provider Speech, registro, directive, normalizzazione |
| `plugin-sdk/realtime-transcription` | Helper per trascrizione realtime | Tipi del provider e helper del registro |
| `plugin-sdk/realtime-voice` | Helper per voce realtime | Tipi del provider e helper del registro |
| `plugin-sdk/image-generation-core` | Core condiviso per la generazione di immagini | Tipi, failover, auth e helper del registro per la generazione di immagini |
| `plugin-sdk/music-generation` | Helper per generazione musicale | Tipi di provider/richiesta/risultato per la generazione musicale |
| `plugin-sdk/music-generation-core` | Core condiviso per la generazione musicale | Tipi per la generazione musicale, helper di failover, ricerca provider e parsing di model-ref |
| `plugin-sdk/video-generation` | Helper per generazione video | Tipi di provider/richiesta/risultato per la generazione video |
| `plugin-sdk/video-generation-core` | Core condiviso per la generazione video | Tipi per la generazione video, helper di failover, ricerca provider e parsing di model-ref |
| `plugin-sdk/interactive-runtime` | Helper per risposte interattive | Normalizzazione/riduzione del payload delle risposte interattive |
| `plugin-sdk/channel-config-primitives` | Primitive di configurazione del canale | Primitive mirate per lo schema di configurazione del canale |
| `plugin-sdk/channel-config-primitives` | Primitive di configurazione del canale | Primitive mirate dello schema di configurazione del canale |
| `plugin-sdk/channel-config-writes` | Helper per scrittura della configurazione del canale | Helper di autorizzazione per la scrittura della configurazione del canale |
| `plugin-sdk/channel-plugin-common` | Prelude condiviso del canale | Export condivisi del prelude del channel plugin |
| `plugin-sdk/channel-status` | Helper di stato del canale | Helper condivisi per snapshot/riepilogo dello stato del canale |
| `plugin-sdk/allowlist-config-edit` | Helper di configurazione della allowlist | Helper per modifica/lettura della configurazione della allowlist |
| `plugin-sdk/group-access` | Helper di accesso ai gruppi | Helper condivisi per le decisioni di accesso ai gruppi |
| `plugin-sdk/direct-dm` | Helper Direct-DM | Helper condivisi di autenticazione/guard per Direct-DM |
| `plugin-sdk/extension-shared` | Helper condivisi per extension | Primitive helper per canale passivo/stato e proxy ambient |
| `plugin-sdk/webhook-targets` | Helper per target Webhook | Registry dei target Webhook e helper per installazione delle route |
| `plugin-sdk/webhook-path` | Helper per percorsi Webhook | Helper per la normalizzazione dei percorsi Webhook |
| `plugin-sdk/web-media` | Helper web media condivisi | Helper per caricamento di media remoti/locali |
| `plugin-sdk/allowlist-config-edit` | Helper di configurazione dell'allowlist | Helper per modifica/lettura della configurazione dell'allowlist |
| `plugin-sdk/group-access` | Helper per accesso ai gruppi | Helper condivisi per le decisioni di accesso ai gruppi |
| `plugin-sdk/direct-dm` | Helper per direct-DM | Helper condivisi di auth/guard per direct-DM |
| `plugin-sdk/extension-shared` | Helper condivisi dell'estensione | Primitive helper per canale/stato passivi e proxy ambient |
| `plugin-sdk/webhook-targets` | Helper per target Webhook | Registro dei target Webhook e helper per installazione delle route |
| `plugin-sdk/webhook-path` | Helper per percorsi Webhook | Helper per normalizzazione dei percorsi Webhook |
| `plugin-sdk/web-media` | Helper media web condivisi | Helper per caricamento di media remoti/locali |
| `plugin-sdk/zod` | Riesportazione di zod | `zod` riesportato per i consumer del Plugin SDK |
| `plugin-sdk/memory-core` | Helper inclusi di memory-core | Superficie helper per gestore memoria/configurazione/file/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Facade runtime del motore di memoria | Facade runtime per indice/ricerca della memoria |
| `plugin-sdk/memory-core-host-engine-foundation` | Motore foundation dell'host di memoria | Export del motore foundation dell'host di memoria |
| `plugin-sdk/memory-core-host-engine-embeddings` | Motore embedding dell'host di memoria | Contratti embedding della memoria, accesso al registry, provider locale e helper generici batch/remoti; i provider remoti concreti si trovano nei plugin proprietari corrispondenti |
| `plugin-sdk/memory-core-host-engine-qmd` | Motore QMD dell'host di memoria | Export del motore QMD dell'host di memoria |
| `plugin-sdk/memory-core-host-engine-storage` | Motore storage dell'host di memoria | Export del motore storage dell'host di memoria |
| `plugin-sdk/memory-core-host-multimodal` | Helper multimodali dell'host di memoria | Helper multimodali dell'host di memoria |
| `plugin-sdk/memory-core-host-query` | Helper query dell'host di memoria | Helper query dell'host di memoria |
| `plugin-sdk/memory-core-host-secret` | Helper secret dell'host di memoria | Helper secret dell'host di memoria |
| `plugin-sdk/memory-core-host-events` | Helper del journal eventi dell'host di memoria | Helper del journal eventi dell'host di memoria |
| `plugin-sdk/memory-core-host-status` | Helper di stato dell'host di memoria | Helper di stato dell'host di memoria |
| `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI dell'host di memoria | Helper runtime CLI dell'host di memoria |
| `plugin-sdk/memory-core-host-runtime-core` | Runtime core dell'host di memoria | Helper runtime core dell'host di memoria |
| `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime dell'host di memoria | Helper file/runtime dell'host di memoria |
| `plugin-sdk/memory-host-core` | Alias runtime core dell'host di memoria | Alias neutrale rispetto al vendor per gli helper runtime core dell'host di memoria |
| `plugin-sdk/memory-host-events` | Alias journal eventi dell'host di memoria | Alias neutrale rispetto al vendor per gli helper del journal eventi dell'host di memoria |
| `plugin-sdk/memory-host-files` | Alias file/runtime dell'host di memoria | Alias neutrale rispetto al vendor per gli helper file/runtime dell'host di memoria |
| `plugin-sdk/memory-host-markdown` | Helper markdown gestiti | Helper condivisi per managed-markdown per plugin adiacenti alla memoria |
| `plugin-sdk/memory-host-search` | Facade di ricerca Active Memory | Facade runtime lazy del gestore di ricerca Active Memory |
| `plugin-sdk/memory-host-status` | Alias stato dell'host di memoria | Alias neutrale rispetto al vendor per gli helper di stato dell'host di memoria |
| `plugin-sdk/memory-lancedb` | Helper inclusi di memory-lancedb | Superficie helper di memory-lancedb |
| `plugin-sdk/memory-core` | Helper bundled memory-core | Superficie helper per memory manager/config/file/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Facciata runtime del motore di memoria | Facciata runtime per indice/ricerca della memoria |
| `plugin-sdk/memory-core-host-engine-foundation` | Motore foundation host della memoria | Export del motore foundation host della memoria |
| `plugin-sdk/memory-core-host-engine-embeddings` | Motore embeddings host della memoria | Contratti degli embedding di memoria, accesso al registro, provider locale e helper generici batch/remoti; i provider remoti concreti si trovano nei plugin che li possiedono |
| `plugin-sdk/memory-core-host-engine-qmd` | Motore QMD host della memoria | Export del motore QMD host della memoria |
| `plugin-sdk/memory-core-host-engine-storage` | Motore storage host della memoria | Export del motore storage host della memoria |
| `plugin-sdk/memory-core-host-multimodal` | Helper multimodali host della memoria | Helper multimodali host della memoria |
| `plugin-sdk/memory-core-host-query` | Helper query host della memoria | Helper query host della memoria |
| `plugin-sdk/memory-core-host-secret` | Helper secret host della memoria | Helper secret host della memoria |
| `plugin-sdk/memory-core-host-events` | Helper per event journal host della memoria | Helper per event journal host della memoria |
| `plugin-sdk/memory-core-host-status` | Helper di stato host della memoria | Helper di stato host della memoria |
| `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI host della memoria | Helper runtime CLI host della memoria |
| `plugin-sdk/memory-core-host-runtime-core` | Runtime core host della memoria | Helper runtime core host della memoria |
| `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host della memoria | Helper file/runtime host della memoria |
| `plugin-sdk/memory-host-core` | Alias runtime core host della memoria | Alias neutrale rispetto al vendor per gli helper runtime core host della memoria |
| `plugin-sdk/memory-host-events` | Alias event journal host della memoria | Alias neutrale rispetto al vendor per gli helper event journal host della memoria |
| `plugin-sdk/memory-host-files` | Alias file/runtime host della memoria | Alias neutrale rispetto al vendor per gli helper file/runtime host della memoria |
| `plugin-sdk/memory-host-markdown` | Helper per markdown gestito | Helper condivisi per managed-markdown per plugin adiacenti alla memoria |
| `plugin-sdk/memory-host-search` | Facciata di ricerca Active Memory | Facciata runtime lazy del search-manager di Active Memory |
| `plugin-sdk/memory-host-status` | Alias stato host della memoria | Alias neutrale rispetto al vendor per gli helper di stato host della memoria |
| `plugin-sdk/memory-lancedb` | Helper bundled memory-lancedb | Superficie helper memory-lancedb |
| `plugin-sdk/testing` | Utility di test | Helper di test e mock |
</Accordion>
Questa tabella è intenzionalmente il sottoinsieme comune per la migrazione, non
l'intera superficie del SDK. L'elenco completo di oltre 200 entrypoint si trova
in `scripts/lib/plugin-sdk-entrypoints.json`.
Questa tabella è intenzionalmente il sottoinsieme comune per la migrazione, non l'intera superficie del SDK. L'elenco completo di oltre 200 entrypoint si trova in `scripts/lib/plugin-sdk-entrypoints.json`.
Quell'elenco include ancora alcuni helper seam per plugin inclusi come
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
`plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Questi continuano a essere
esportati per la manutenzione e la compatibilità dei plugin inclusi, ma sono
intenzionalmente omessi dalla tabella comune di migrazione e non sono il target
consigliato per nuovo codice plugin.
Quell'elenco include ancora alcuni helper seam dei plugin bundled come `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Questi continuano a essere esportati per la manutenzione e la compatibilità dei plugin bundled, ma sono intenzionalmente omessi dalla tabella comune di migrazione e non sono il target consigliato per il nuovo codice dei plugin.
La stessa regola si applica ad altre famiglie di helper inclusi come:
La stessa regola si applica ad altre famiglie di helper bundled come:
- helper di supporto browser: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support`
- Matrix: `plugin-sdk/matrix*`
- LINE: `plugin-sdk/line*`
- IRC: `plugin-sdk/irc*`
- superfici di helper/plugin inclusi come `plugin-sdk/googlechat`,
`plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`,
`plugin-sdk/mattermost*`, `plugin-sdk/msteams`,
`plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`,
`plugin-sdk/twitch`,
`plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`,
`plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`,
`plugin-sdk/thread-ownership` e `plugin-sdk/voice-call`
- superfici di helper/plugin bundled come `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership` e `plugin-sdk/voice-call`
`plugin-sdk/github-copilot-token` espone attualmente la superficie mirata di
helper per token `DEFAULT_COPILOT_API_BASE_URL`,
`deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken`.
`plugin-sdk/github-copilot-token` espone attualmente la superficie mirata degli helper per token `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken`.
Usa l'import più mirato che corrisponde al compito. Se non riesci a trovare un
export, controlla il sorgente in `src/plugin-sdk/` oppure chiedi su Discord.
Usa l'import più mirato che corrisponde al lavoro da svolgere. Se non riesci a trovare un export, controlla il sorgente in `src/plugin-sdk/` o chiedi su Discord.
## Tempistica di rimozione
## Tempistiche di rimozione
| Quando | Cosa succede |
| ---------------------- | ----------------------------------------------------------------------- |
| **Ora** | Le superfici deprecate emettono avvisi a runtime |
| **Prossima major release** | Le superfici deprecate verranno rimosse; i plugin che le usano ancora non funzioneranno |
| **Prossima major release** | Le superfici deprecate verranno rimosse; i plugin che le usano ancora smetteranno di funzionare |
Tutti i plugin core sono già stati migrati. I plugin esterni dovrebbero
migrare prima della prossima major release.
Tutti i plugin core sono già stati migrati. I plugin esterni dovrebbero effettuare la migrazione prima della prossima major release.
## Sopprimere temporaneamente gli avvisi
## Soppressione temporanea degli avvisi
Imposta queste variabili d'ambiente mentre lavori alla migrazione:
@ -407,13 +349,13 @@ OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
```
Si tratta di una soluzione temporanea, non di una soluzione permanente.
Questa è una via di fuga temporanea, non una soluzione permanente.
## Correlati
- [Guida introduttiva](/it/plugins/building-plugins) — crea il tuo primo plugin
- [Panoramica del SDK](/it/plugins/sdk-overview) — riferimento completo per gli import dei subpath
- [Per iniziare](/it/plugins/building-plugins) — crea il tuo primo plugin
- [Panoramica dell'SDK](/it/plugins/sdk-overview) — riferimento completo agli import per subpath
- [Plugin di canale](/it/plugins/sdk-channel-plugins) — creare plugin di canale
- [Plugin provider](/it/plugins/sdk-provider-plugins) — creare plugin provider
- [Interni dei plugin](/it/plugins/architecture) — approfondimento sull'architettura
- [Manifest del plugin](/it/plugins/manifest) — riferimento dello schema del manifest
- [Manifest del plugin](/it/plugins/manifest) — riferimento allo schema del manifest

445
docs/it/plugins/sdk-overview.md
View File

@ -4,27 +4,27 @@ read_when:
- Vuoi un riferimento per tutti i metodi di registrazione su OpenClawPluginApi
- Stai cercando una specifica esportazione dell'SDK
sidebarTitle: SDK Overview
summary: Mappa di importazione, riferimento dell'API di registrazione e architettura dell'SDK
title: Panoramica dell'SDK del Plugin
summary: Mappa di importazione, riferimento API di registrazione e architettura dell'SDK
title: Panoramica dell'SDK per Plugin
x-i18n:
generated_at: "2026-04-18T08:05:09Z"
generated_at: "2026-04-19T01:11:24Z"
model: gpt-5.4
provider: openai
source_hash: 05d3d0022cca32d29c76f6cea01cdf4f88ac69ef0ef3d7fb8a60fbf9a6b9b331
source_hash: 522c2c542bc0ea4793541fda18931b963ad71f07e9c83e4f22f05184eb1ba91a
source_path: plugins/sdk-overview.md
workflow: 15
---
# Panoramica dell'SDK del Plugin
# Panoramica dell'SDK per Plugin
L'SDK del plugin è il contratto tipizzato tra i plugin e il core. Questa pagina è il
riferimento per **cosa importare** e **cosa è possibile registrare**.
L'SDK per plugin è il contratto tipizzato tra i plugin e il core. Questa pagina è il
riferimento per **cosa importare** e **cosa puoi registrare**.
<Tip>
**Cerchi una guida pratica?**
- Primo plugin? Inizia con [Guida introduttiva](/it/plugins/building-plugins)
- Plugin di canale? Vedi [Plugin di canale](/it/plugins/sdk-channel-plugins)
- Plugin provider? Vedi [Plugin provider](/it/plugins/sdk-provider-plugins)
- Primo plugin? Inizia con [Getting Started](/it/plugins/building-plugins)
- Plugin di canale? Vedi [Channel Plugins](/it/plugins/sdk-channel-plugins)
- Plugin provider? Vedi [Provider Plugins](/it/plugins/sdk-provider-plugins)
</Tip>
## Convenzione di importazione
@ -37,123 +37,124 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
Ogni sottopercorso è un modulo piccolo e autosufficiente. Questo mantiene l'avvio rapido e
previene i problemi di dipendenze circolari. Per gli helper di entry/build specifici per canale,
previene problemi di dipendenze circolari. Per gli helper di entry/build specifici del canale,
preferisci `openclaw/plugin-sdk/channel-core`; mantieni `openclaw/plugin-sdk/core` per
la superficie ombrello più ampia e gli helper condivisi come
la superficie ombrello più ampia e per gli helper condivisi come
`buildChannelConfigSchema`.
Non aggiungere né dipendere da seam di convenienza con nomi di provider come
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, o
seam di helper con branding del canale. I plugin inclusi dovrebbero comporre sottopercorsi
generici dell'SDK all'interno dei propri barrel `api.ts` o `runtime-api.ts`, e il core
dovrebbe usare quei barrel locali al plugin oppure aggiungere un contratto SDK generico e ristretto
quando la necessità è davvero trasversale ai canali.
seam di helper con branding di canale. I plugin inclusi dovrebbero comporre sottopercorsi
SDK generici all'interno dei propri barrel `api.ts` o `runtime-api.ts`, e il core
dovrebbe usare quei barrel locali del plugin oppure aggiungere un contratto SDK generico e ristretto
quando l'esigenza è davvero trasversale ai canali.
La mappa di esportazione generata contiene ancora un piccolo insieme di seam helper per plugin inclusi
La mappa delle esportazioni generata contiene ancora un piccolo insieme di seam helper di plugin inclusi
come `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Quei
sottopercorsi esistono solo per la manutenzione e la compatibilità dei plugin inclusi; sono
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Questi
sottopercorsi esistono solo per manutenzione e compatibilità dei plugin inclusi; sono
intenzionalmente omessi dalla tabella comune qui sotto e non sono il percorso di importazione
consigliato per i nuovi plugin di terze parti.
consigliato per nuovi plugin di terze parti.
## Riferimento dei sottopercorsi
I sottopercorsi usati più comunemente, raggruppati per scopo. L'elenco completo generato di
I sottopercorsi più usati, raggruppati per scopo. L'elenco completo generato di
oltre 200 sottopercorsi si trova in `scripts/lib/plugin-sdk-entrypoints.json`.
I sottopercorsi helper riservati ai plugin inclusi compaiono ancora in quell'elenco generato.
Considerali come superfici di dettaglio implementativo/compatibilità, a meno che una pagina della documentazione
Trattali come superfici di dettaglio implementativo/compatibilità, a meno che una pagina della documentazione
non ne promuova esplicitamente uno come pubblico.
### Entry del plugin
| Sottopercorso | Esportazioni chiave |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| Sottopercorso | Esportazioni chiave |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
| `plugin-sdk/config-schema` | `OpenClawSchema` |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
<AccordionGroup>
<Accordion title="Sottopercorsi del canale">
<Accordion title="Sottopercorsi dei canali">
| Sottopercorso | Esportazioni chiave |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | Esportazione dello schema Zod radice `openclaw.json` (`OpenClawSchema`) |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, più `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | Helper condivisi per la procedura guidata di configurazione, prompt della allowlist, builder dello stato di configurazione |
| `plugin-sdk/setup` | Helper condivisi per il wizard di configurazione, prompt allowlist, builder dello stato di configurazione |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Helper per configurazione multi-account/action-gate, helper di fallback dell'account predefinito |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helper di normalizzazione dell'ID account |
| `plugin-sdk/account-resolution` | Helper per ricerca account + fallback predefinito |
| `plugin-sdk/account-helpers` | Helper mirati per elenco account/azioni account |
| `plugin-sdk/account-core` | Helper per config/gate di azione multi-account e helper di fallback dell'account predefinito |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helper di normalizzazione dell'account ID |
| `plugin-sdk/account-resolution` | Helper di ricerca account + fallback predefinito |
| `plugin-sdk/account-helpers` | Helper ristretti per elenco account/azioni account |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Tipi dello schema di configurazione del canale |
| `plugin-sdk/channel-config-schema` | Tipi di schema di configurazione del canale |
| `plugin-sdk/telegram-command-config` | Helper di normalizzazione/validazione dei comandi personalizzati di Telegram con fallback al contratto incluso |
| `plugin-sdk/command-gating` | Helper mirati per i gate di autorizzazione dei comandi |
| `plugin-sdk/command-gating` | Helper ristretti per gate di autorizzazione dei comandi |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
| `plugin-sdk/inbound-envelope` | Helper condivisi per instradamento inbound + builder di envelope |
| `plugin-sdk/inbound-envelope` | Helper condivisi per route inbound + builder di envelope |
| `plugin-sdk/inbound-reply-dispatch` | Helper condivisi per registrazione e dispatch inbound |
| `plugin-sdk/messaging-targets` | Helper per parsing/matching dei target |
| `plugin-sdk/outbound-media` | Helper condivisi per il caricamento dei media outbound |
| `plugin-sdk/outbound-runtime` | Helper per identità outbound/delega di invio |
| `plugin-sdk/poll-runtime` | Helper mirati per la normalizzazione dei sondaggi |
| `plugin-sdk/thread-bindings-runtime` | Helper per ciclo di vita dei binding dei thread e adattatori |
| `plugin-sdk/agent-media-payload` | Builder legacy del payload media dell'agente |
| `plugin-sdk/conversation-runtime` | Helper per binding di conversazioni/thread, pairing e binding configurati |
| `plugin-sdk/runtime-config-snapshot` | Helper per snapshot della configurazione runtime |
| `plugin-sdk/runtime-group-policy` | Helper per la risoluzione delle policy di gruppo runtime |
| `plugin-sdk/outbound-media` | Helper condivisi per il caricamento dei contenuti multimediali outbound |
| `plugin-sdk/outbound-runtime` | Helper outbound per identità/delega di invio |
| `plugin-sdk/poll-runtime` | Helper ristretti per la normalizzazione dei sondaggi |
| `plugin-sdk/thread-bindings-runtime` | Helper per lifecycle e adapter dei binding dei thread |
| `plugin-sdk/agent-media-payload` | Builder legacy del payload multimediale dell'agente |
| `plugin-sdk/conversation-runtime` | Helper per binding conversazione/thread, pairing e binding configurati |
| `plugin-sdk/runtime-config-snapshot` | Helper per snapshot di configurazione runtime |
| `plugin-sdk/runtime-group-policy` | Helper runtime per la risoluzione delle policy di gruppo |
| `plugin-sdk/channel-status` | Helper condivisi per snapshot/riepilogo dello stato del canale |
| `plugin-sdk/channel-config-primitives` | Primitive mirate dello schema di configurazione del canale |
| `plugin-sdk/channel-config-primitives` | Primitive ristrette dello schema di configurazione del canale |
| `plugin-sdk/channel-config-writes` | Helper di autorizzazione per scritture della configurazione del canale |
| `plugin-sdk/channel-plugin-common` | Esportazioni prelude condivise del plugin di canale |
| `plugin-sdk/allowlist-config-edit` | Helper di lettura/modifica della configurazione della allowlist |
| `plugin-sdk/group-access` | Helper condivisi per le decisioni di accesso ai gruppi |
| `plugin-sdk/direct-dm` | Helper condivisi per autenticazione/guard delle DM dirette |
| `plugin-sdk/channel-plugin-common` | Esportazioni di prelude condivise per plugin di canale |
| `plugin-sdk/allowlist-config-edit` | Helper di modifica/lettura della configurazione allowlist |
| `plugin-sdk/group-access` | Helper condivisi per decisioni di accesso ai gruppi |
| `plugin-sdk/direct-dm` | Helper condivisi per auth/guard dei messaggi diretti |
| `plugin-sdk/interactive-runtime` | Helper per normalizzazione/riduzione del payload di risposta interattiva |
| `plugin-sdk/channel-inbound` | Barrel di compatibilità per debounce inbound, matching delle menzioni, helper per policy delle menzioni e helper envelope |
| `plugin-sdk/channel-mention-gating` | Helper mirati per la policy delle menzioni senza la superficie runtime inbound più ampia |
| `plugin-sdk/channel-inbound` | Barrel di compatibilità per inbound debounce, matching delle menzioni, helper per le policy di menzione e helper di envelope |
| `plugin-sdk/channel-mention-gating` | Helper ristretti per le policy di menzione senza la più ampia superficie runtime inbound |
| `plugin-sdk/channel-location` | Helper per contesto e formattazione della posizione del canale |
| `plugin-sdk/channel-logging` | Helper di logging del canale per scarti inbound e errori di typing/ack |
| `plugin-sdk/channel-send-result` | Tipi del risultato della risposta |
| `plugin-sdk/channel-logging` | Helper di logging del canale per scarti inbound e errori di digitazione/ack |
| `plugin-sdk/channel-send-result` | Tipi di risultato della risposta |
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
| `plugin-sdk/channel-targets` | Helper per parsing/matching dei target |
| `plugin-sdk/channel-contract` | Tipi del contratto del canale |
| `plugin-sdk/channel-contract` | Tipi di contratto del canale |
| `plugin-sdk/channel-feedback` | Wiring di feedback/reazioni |
| `plugin-sdk/channel-secret-runtime` | Helper mirati del contratto dei secret come `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` e tipi target dei secret |
| `plugin-sdk/channel-secret-runtime` | Helper ristretti per il contratto dei secret come `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` e tipi di target dei secret |
</Accordion>
<Accordion title="Sottopercorsi del provider">
<Accordion title="Sottopercorsi dei provider">
| Sottopercorso | Esportazioni chiave |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | Helper curati per la configurazione di provider locali/self-hosted |
| `plugin-sdk/self-hosted-provider-setup` | Helper mirati per la configurazione di provider self-hosted compatibili con OpenAI |
| `plugin-sdk/cli-backend` | Valori predefiniti del backend CLI + costanti watchdog |
| `plugin-sdk/provider-auth-runtime` | Helper runtime per la risoluzione delle API key per i plugin provider |
| `plugin-sdk/provider-auth-api-key` | Helper per onboarding/scrittura del profilo API key come `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | Builder standard del risultato di autenticazione OAuth |
| `plugin-sdk/provider-auth-login` | Helper condivisi per login interattivo dei plugin provider |
| `plugin-sdk/provider-env-vars` | Helper di ricerca delle variabili d'ambiente di autenticazione del provider |
| `plugin-sdk/provider-auth-runtime` | Helper runtime per la risoluzione delle API key dei plugin provider |
| `plugin-sdk/provider-auth-api-key` | Helper per onboarding/scrittura del profilo delle API key come `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | Builder standard del risultato auth OAuth |
| `plugin-sdk/provider-auth-login` | Helper condivisi di login interattivo per plugin provider |
| `plugin-sdk/provider-env-vars` | Helper per la ricerca delle variabili d'ambiente auth del provider |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder condivisi delle policy di replay, helper per endpoint del provider e helper di normalizzazione dell'ID modello come `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder condivisi di replay-policy, helper per endpoint del provider e helper di normalizzazione del model ID come `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | Helper generici per capacità HTTP/endpoint del provider |
| `plugin-sdk/provider-web-fetch-contract` | Helper mirati del contratto di configurazione/selezione web-fetch come `enablePluginInConfig` e `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Helper di registrazione/cache del provider web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Helper mirati di configurazione/credenziali web-search per provider che non richiedono wiring di abilitazione del plugin |
| `plugin-sdk/provider-web-search-contract` | Helper mirati del contratto di configurazione/credenziali web-search come `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setter/getter di credenziali con ambito |
| `plugin-sdk/provider-web-search` | Helper di registrazione/cache/runtime del provider web-search |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, cleanup + diagnostica dello schema Gemini e helper di compatibilità xAI come `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-web-fetch-contract` | Helper ristretti per contratto di configurazione/selezione web-fetch come `enablePluginInConfig` e `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Helper per registrazione/cache dei provider web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Helper ristretti per configurazione/credenziali web-search per provider che non necessitano del wiring di abilitazione plugin |
| `plugin-sdk/provider-web-search-contract` | Helper ristretti per contratto di configurazione/credenziali web-search come `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` e setter/getter di credenziali con ambito |
| `plugin-sdk/provider-web-search` | Helper per registrazione/cache/runtime dei provider web-search |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pulizia + diagnostica dello schema Gemini e helper compat xAI come `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` e simili |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipi di stream wrapper e helper wrapper condivisi per Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-onboard` | Helper per patch della configurazione di onboarding |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipi di wrapper di stream e helper wrapper condivisi per Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-transport-runtime` | Helper di trasporto nativo del provider come fetch protetto, trasformazioni dei messaggi di trasporto e stream di eventi di trasporto scrivibili |
| `plugin-sdk/provider-onboard` | Helper per patch di configurazione dell'onboarding |
| `plugin-sdk/global-singleton` | Helper per singleton/map/cache locali al processo |
</Accordion>
@ -163,143 +164,143 @@ non ne promuova esplicitamente uno come pubblico.
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper del registro dei comandi, helper di autorizzazione del mittente |
| `plugin-sdk/command-status` | Builder di messaggi di comando/aiuto come `buildCommandsMessagePaginated` e `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | Risoluzione degli approvatori e helper di autenticazione delle azioni nella stessa chat |
| `plugin-sdk/approval-client-runtime` | Helper di profilo/filtro di approvazione `exec` nativa |
| `plugin-sdk/approval-delivery-runtime` | Adattatori nativi di capacità/consegna delle approvazioni |
| `plugin-sdk/approval-gateway-runtime` | Helper condiviso di risoluzione del Gateway di approvazione |
| `plugin-sdk/approval-handler-adapter-runtime` | Helper leggeri di caricamento degli adattatori di approvazione nativa per entrypoint di canale ad alta frequenza |
| `plugin-sdk/approval-handler-runtime` | Helper runtime più ampi per il gestore delle approvazioni; preferisci i seam più ristretti adapter/gateway quando sono sufficienti |
| `plugin-sdk/approval-native-runtime` | Helper per target di approvazione nativa + binding dell'account |
| `plugin-sdk/approval-reply-runtime` | Helper del payload di risposta per approvazioni `exec`/plugin |
| `plugin-sdk/command-auth-native` | Autenticazione dei comandi nativi + helper nativi per target di sessione |
| `plugin-sdk/approval-client-runtime` | Helper di profilo/filtro di approvazione per exec nativo |
| `plugin-sdk/approval-delivery-runtime` | Adapter condivisi per capacità/consegna delle approvazioni native |
| `plugin-sdk/approval-gateway-runtime` | Helper condiviso per la risoluzione del Gateway delle approvazioni |
| `plugin-sdk/approval-handler-adapter-runtime` | Helper leggeri di caricamento degli adapter di approvazione nativi per entrypoint hot dei canali |
| `plugin-sdk/approval-handler-runtime` | Helper runtime più ampi per il gestore delle approvazioni; preferisci i seam adapter/gateway più ristretti quando sono sufficienti |
| `plugin-sdk/approval-native-runtime` | Helper nativi per target di approvazione + binding dell'account |
| `plugin-sdk/approval-reply-runtime` | Helper del payload di risposta per approvazioni exec/plugin |
| `plugin-sdk/command-auth-native` | Helper nativi per auth dei comandi + target di sessione nativa |
| `plugin-sdk/command-detection` | Helper condivisi per il rilevamento dei comandi |
| `plugin-sdk/command-surface` | Normalizzazione del corpo del comando e helper della superficie di comando |
| `plugin-sdk/command-surface` | Helper per normalizzazione del corpo del comando e command-surface |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | Helper mirati di raccolta del contratto dei secret per superfici secret di canale/plugin |
| `plugin-sdk/secret-ref-runtime` | Helper mirati `coerceSecretRef` e di tipizzazione di SecretRef per il parsing di configurazione/contratto dei secret |
| `plugin-sdk/security-runtime` | Helper condivisi per trust, gating delle DM, contenuti esterni e raccolta dei secret |
| `plugin-sdk/ssrf-policy` | Helper della policy SSRF per allowlist degli host e reti private |
| `plugin-sdk/ssrf-dispatcher` | Helper mirati del dispatcher pinned senza l'ampia superficie runtime dell'infrastruttura |
| `plugin-sdk/ssrf-runtime` | Helper per dispatcher pinned, fetch protetto da SSRF e policy SSRF |
| `plugin-sdk/secret-input` | Helper di parsing degli input secret |
| `plugin-sdk/webhook-ingress` | Helper per richieste/target Webhook |
| `plugin-sdk/channel-secret-runtime` | Helper ristretti di raccolta del contratto dei secret per superfici secret di canali/plugin |
| `plugin-sdk/secret-ref-runtime` | Helper ristretti `coerceSecretRef` e di tipizzazione SecretRef per il parsing del contratto dei secret/della configurazione |
| `plugin-sdk/security-runtime` | Helper condivisi per trust, gate DM, contenuti esterni e raccolta dei secret |
| `plugin-sdk/ssrf-policy` | Helper per policy SSRF di allowlist host e rete privata |
| `plugin-sdk/ssrf-dispatcher` | Helper ristretti per pinned-dispatcher senza l'ampia superficie runtime infra |
| `plugin-sdk/ssrf-runtime` | Helper per pinned-dispatcher, fetch protetto da SSRF e policy SSRF |
| `plugin-sdk/secret-input` | Helper di parsing dell'input dei secret |
| `plugin-sdk/webhook-ingress` | Helper per richiesta/target Webhook |
| `plugin-sdk/webhook-request-guards` | Helper per dimensione del body della richiesta/timeout |
</Accordion>
<Accordion title="Sottopercorsi di runtime e archiviazione">
<Accordion title="Sottopercorsi di runtime e storage">
| Sottopercorso | Esportazioni chiave |
| --- | --- |
| `plugin-sdk/runtime` | Ampi helper per runtime/logging/backup/installazione plugin |
| `plugin-sdk/runtime-env` | Helper mirati per env runtime, logger, timeout, retry e backoff |
| `plugin-sdk/runtime-env` | Helper ristretti per env runtime, logger, timeout, retry e backoff |
| `plugin-sdk/channel-runtime-context` | Helper generici per registrazione e lookup del contesto runtime del canale |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | Helper condivisi per comandi/hook/http/interattivi del plugin |
| `plugin-sdk/hook-runtime` | Helper condivisi per la pipeline di hook Webhook/interna |
| `plugin-sdk/lazy-runtime` | Helper per import/binding runtime lazy come `createLazyRuntimeModule`, `createLazyRuntimeMethod` e `createLazyRuntimeSurface` |
| `plugin-sdk/plugin-runtime` | Helper condivisi per comandi/hook/http/interattività dei plugin |
| `plugin-sdk/hook-runtime` | Helper condivisi per pipeline di hook webhook/interni |
| `plugin-sdk/lazy-runtime` | Helper per import/binding lazy del runtime come `createLazyRuntimeModule`, `createLazyRuntimeMethod` e `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Helper per esecuzione di processi |
| `plugin-sdk/cli-runtime` | Helper per formattazione CLI, attesa e versione |
| `plugin-sdk/gateway-runtime` | Helper per client Gateway e patch dello stato del canale |
| `plugin-sdk/config-runtime` | Helper per caricamento/scrittura della configurazione |
| `plugin-sdk/telegram-command-config` | Normalizzazione di nome/descrizione dei comandi Telegram e controlli di duplicati/conflitti, anche quando la superficie del contratto Telegram incluso non è disponibile |
| `plugin-sdk/text-autolink-runtime` | Rilevamento di autolink di riferimenti a file senza l'ampio barrel `text-runtime` |
| `plugin-sdk/approval-runtime` | Helper per approvazioni `exec`/plugin, builder di capacità di approvazione, helper auth/profilo, helper nativi di routing/runtime |
| `plugin-sdk/reply-runtime` | Helper condivisi per runtime inbound/risposta, chunking, dispatch, Heartbeat, pianificatore delle risposte |
| `plugin-sdk/reply-dispatch-runtime` | Helper mirati di dispatch/finalizzazione delle risposte |
| `plugin-sdk/reply-history` | Helper condivisi per la cronologia delle risposte a breve finestra come `buildHistoryContext`, `recordPendingHistoryEntry` e `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/telegram-command-config` | Normalizzazione di nomi/descrizioni dei comandi Telegram e controlli di duplicati/conflitti, anche quando la superficie del contratto Telegram incluso non è disponibile |
| `plugin-sdk/text-autolink-runtime` | Rilevamento di autolink per riferimenti a file senza l'ampio barrel `text-runtime` |
| `plugin-sdk/approval-runtime` | Helper per approvazioni exec/plugin, builder di capacità di approvazione, helper auth/profili, helper nativi di routing/runtime |
| `plugin-sdk/reply-runtime` | Helper condivisi per runtime inbound/risposta, chunking, dispatch, Heartbeat, pianificatore di risposta |
| `plugin-sdk/reply-dispatch-runtime` | Helper ristretti per dispatch/finalizzazione della risposta |
| `plugin-sdk/reply-history` | Helper condivisi per la reply-history a breve finestra come `buildHistoryContext`, `recordPendingHistoryEntry` e `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Helper mirati per chunking di testo/Markdown |
| `plugin-sdk/session-store-runtime` | Helper per percorso del session store + updated-at |
| `plugin-sdk/state-paths` | Helper per i percorsi delle directory state/OAuth |
| `plugin-sdk/reply-chunking` | Helper ristretti per il chunking di testo/markdown |
| `plugin-sdk/session-store-runtime` | Helper per percorso dello store di sessione + `updated-at` |
| `plugin-sdk/state-paths` | Helper per percorsi di directory state/OAuth |
| `plugin-sdk/routing` | Helper per route/session-key/binding dell'account come `resolveAgentRoute`, `buildAgentSessionKey` e `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Helper condivisi per riepiloghi di stato di canale/account, valori predefiniti dello stato runtime e helper per metadati dei problemi |
| `plugin-sdk/target-resolver-runtime` | Helper condivisi per il resolver dei target |
| `plugin-sdk/status-helpers` | Helper condivisi per riepilogo dello stato di canali/account, valori predefiniti dello stato runtime e helper per metadati dei problemi |
| `plugin-sdk/target-resolver-runtime` | Helper condivisi per la risoluzione dei target |
| `plugin-sdk/string-normalization-runtime` | Helper per normalizzazione di slug/stringhe |
| `plugin-sdk/request-url` | Estrai URL stringa da input simili a fetch/richiesta |
| `plugin-sdk/run-command` | Esecutore di comandi temporizzato con risultati stdout/stderr normalizzati |
| `plugin-sdk/param-readers` | Lettori comuni di parametri per tool/CLI |
| `plugin-sdk/tool-payload` | Estrai payload normalizzati dagli oggetti risultato dei tool |
| `plugin-sdk/tool-send` | Estrai campi canonici del target di invio dagli argomenti del tool |
| `plugin-sdk/temp-path` | Helper condivisi per percorsi di download temporanei |
| `plugin-sdk/tool-payload` | Estrai payload normalizzati da oggetti risultato dei tool |
| `plugin-sdk/tool-send` | Estrai campi target di invio canonici dagli argomenti dei tool |
| `plugin-sdk/temp-path` | Helper condivisi per percorsi temporanei di download |
| `plugin-sdk/logging-core` | Helper per logger di sottosistema e redazione |
| `plugin-sdk/markdown-table-runtime` | Helper per modalità tabella Markdown |
| `plugin-sdk/json-store` | Piccoli helper per lettura/scrittura dello stato JSON |
| `plugin-sdk/file-lock` | Helper re-entrant per file lock |
| `plugin-sdk/persistent-dedupe` | Helper per cache di deduplicazione persistente su disco |
| `plugin-sdk/acp-runtime` | Helper ACP per runtime/sessione e reply-dispatch |
| `plugin-sdk/acp-binding-resolve-runtime` | Risoluzione di binding ACP in sola lettura senza import di startup del ciclo di vita |
| `plugin-sdk/agent-config-primitives` | Primitive mirate dello schema di configurazione runtime dell'agente |
| `plugin-sdk/markdown-table-runtime` | Helper per modalità tabelle Markdown |
| `plugin-sdk/json-store` | Piccoli helper per lettura/scrittura di stato JSON |
| `plugin-sdk/file-lock` | Helper per file-lock rientrante |
| `plugin-sdk/persistent-dedupe` | Helper per cache di deduplica persistente su disco |
| `plugin-sdk/acp-runtime` | Helper per runtime/sessione ACP e reply-dispatch |
| `plugin-sdk/acp-binding-resolve-runtime` | Risoluzione in sola lettura dei binding ACP senza import di avvio del lifecycle |
| `plugin-sdk/agent-config-primitives` | Primitive ristrette dello schema di configurazione runtime dell'agente |
| `plugin-sdk/boolean-param` | Lettore permissivo di parametri booleani |
| `plugin-sdk/dangerous-name-runtime` | Helper di risoluzione per matching di nomi pericolosi |
| `plugin-sdk/dangerous-name-runtime` | Helper di risoluzione per il matching di nomi pericolosi |
| `plugin-sdk/device-bootstrap` | Helper per bootstrap del dispositivo e token di pairing |
| `plugin-sdk/extension-shared` | Primitive helper condivise per canali passivi, stato e proxy ambientale |
| `plugin-sdk/models-provider-runtime` | Helper per il comando `/models` e risposte dei provider |
| `plugin-sdk/extension-shared` | Primitive helper condivise per canali passivi, stato e proxy ambient |
| `plugin-sdk/models-provider-runtime` | Helper per il comando `/models` e per le risposte dei provider |
| `plugin-sdk/skill-commands-runtime` | Helper per l'elenco dei comandi Skills |
| `plugin-sdk/native-command-registry` | Helper per registro/build/serializzazione dei comandi nativi |
| `plugin-sdk/agent-harness` | Superficie sperimentale per plugin trusted per harness di agente a basso livello: tipi di harness, helper di steer/abort dell'esecuzione attiva, helper di bridge degli strumenti OpenClaw e utility per i risultati dei tentativi |
| `plugin-sdk/agent-harness` | Superficie sperimentale trusted-plugin per harness di agente a basso livello: tipi di harness, helper per steer/abort di esecuzioni attive, helper per il bridge degli strumenti OpenClaw e utility per i risultati dei tentativi |
| `plugin-sdk/provider-zai-endpoint` | Helper per il rilevamento degli endpoint Z.A.I |
| `plugin-sdk/infra-runtime` | Helper per eventi di sistema/Heartbeat |
| `plugin-sdk/collection-runtime` | Piccoli helper per cache limitate |
| `plugin-sdk/diagnostic-runtime` | Helper per flag ed eventi diagnostici |
| `plugin-sdk/error-runtime` | Grafo degli errori, formattazione, helper condivisi di classificazione degli errori, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Helper per fetch wrapperizzato, proxy e lookup pinned |
| `plugin-sdk/runtime-fetch` | Fetch runtime consapevole del dispatcher senza import di proxy/guarded-fetch |
| `plugin-sdk/response-limit-runtime` | Lettore limitato del body della risposta senza l'ampia superficie media runtime |
| `plugin-sdk/error-runtime` | Grafo degli errori, formattazione, helper condivisi per classificazione degli errori, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Helper per fetch con wrapper, proxy e lookup pinned |
| `plugin-sdk/runtime-fetch` | Fetch runtime consapevole del dispatcher senza import di proxy/fetch protetto |
| `plugin-sdk/response-limit-runtime` | Lettore limitato del body della risposta senza l'ampia superficie runtime dei media |
| `plugin-sdk/session-binding-runtime` | Stato corrente del binding della conversazione senza routing dei binding configurati o store di pairing |
| `plugin-sdk/session-store-runtime` | Helper di lettura del session store senza ampi import di scritture/manutenzione della configurazione |
| `plugin-sdk/session-store-runtime` | Helper di lettura dello store di sessione senza ampi import di scrittura/manutenzione della configurazione |
| `plugin-sdk/context-visibility-runtime` | Risoluzione della visibilità del contesto e filtro del contesto supplementare senza ampi import di configurazione/sicurezza |
| `plugin-sdk/string-coerce-runtime` | Helper mirati per coercizione e normalizzazione di record/stringhe primitive senza import di Markdown/logging |
| `plugin-sdk/string-coerce-runtime` | Helper ristretti per coercizione e normalizzazione di record/stringhe primitive senza import di markdown/logging |
| `plugin-sdk/host-runtime` | Helper per normalizzazione di hostname e host SCP |
| `plugin-sdk/retry-runtime` | Helper per configurazione del retry ed esecutore del retry |
| `plugin-sdk/retry-runtime` | Helper per configurazione ed esecuzione dei retry |
| `plugin-sdk/agent-runtime` | Helper per directory/identità/workspace dell'agente |
| `plugin-sdk/directory-runtime` | Query/deduplicazione delle directory basata sulla configurazione |
| `plugin-sdk/directory-runtime` | Query/deduplica di directory supportate dalla configurazione |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="Sottopercorsi di capacità e test">
| Sottopercorso | Esportazioni chiave |
| --- | --- |
| `plugin-sdk/media-runtime` | Helper condivisi per fetch/trasformazione/archiviazione dei media più builder di payload media |
| `plugin-sdk/media-generation-runtime` | Helper condivisi per failover della generazione media, selezione dei candidati e messaggistica per modello mancante |
| `plugin-sdk/media-understanding` | Tipi di provider per comprensione dei media più esportazioni helper rivolte ai provider per immagini/audio |
| `plugin-sdk/text-runtime` | Helper condivisi per testo/Markdown/logging come rimozione del testo visibile all'assistente, helper per render/chunking/tabelle Markdown, helper di redazione, helper per tag di direttiva e utility per testo sicuro |
| `plugin-sdk/text-chunking` | Helper per chunking del testo outbound |
| `plugin-sdk/speech` | Tipi di provider speech più helper rivolti ai provider per direttive, registro e validazione |
| `plugin-sdk/media-runtime` | Helper condivisi per fetch/trasformazione/store dei media più builder di payload media |
| `plugin-sdk/media-generation-runtime` | Helper condivisi per failover della generazione media, selezione dei candidati e messaggistica per modelli mancanti |
| `plugin-sdk/media-understanding` | Tipi di provider per comprensione dei media più esportazioni helper lato provider per immagini/audio |
| `plugin-sdk/text-runtime` | Helper condivisi per testo/markdown/logging come rimozione del testo visibile all'assistente, helper per rendering/chunking/tabelle Markdown, helper di redazione, helper per tag di direttiva e utility per testo sicuro |
| `plugin-sdk/text-chunking` | Helper per chunking del testo in uscita |
| `plugin-sdk/speech` | Tipi di provider speech più helper lato provider per direttive, registro e validazione |
| `plugin-sdk/speech-core` | Tipi condivisi di provider speech, helper per registro, direttive e normalizzazione |
| `plugin-sdk/realtime-transcription` | Tipi di provider per trascrizione in tempo reale e helper di registro |
| `plugin-sdk/realtime-voice` | Tipi di provider per voce in tempo reale e helper di registro |
| `plugin-sdk/image-generation` | Tipi di provider per generazione di immagini |
| `plugin-sdk/image-generation-core` | Tipi condivisi per generazione di immagini, helper per failover, autenticazione e registro |
| `plugin-sdk/image-generation-core` | Tipi condivisi per generazione di immagini, failover, auth e helper di registro |
| `plugin-sdk/music-generation` | Tipi di provider/richiesta/risultato per generazione musicale |
| `plugin-sdk/music-generation-core` | Tipi condivisi per generazione musicale, helper per failover, lookup del provider e parsing di model-ref |
| `plugin-sdk/music-generation-core` | Tipi condivisi per generazione musicale, helper di failover, lookup del provider e parsing di model-ref |
| `plugin-sdk/video-generation` | Tipi di provider/richiesta/risultato per generazione video |
| `plugin-sdk/video-generation-core` | Tipi condivisi per generazione video, helper per failover, lookup del provider e parsing di model-ref |
| `plugin-sdk/webhook-targets` | Registro dei target Webhook e helper per installazione delle route |
| `plugin-sdk/webhook-path` | Helper per normalizzazione del percorso Webhook |
| `plugin-sdk/web-media` | Helper condivisi per il caricamento di media remoti/locali |
| `plugin-sdk/zod` | `zod` riesportato per i consumatori dell'SDK del plugin |
| `plugin-sdk/video-generation-core` | Tipi condivisi per generazione video, helper di failover, lookup del provider e parsing di model-ref |
| `plugin-sdk/webhook-targets` | Registro dei target Webhook e helper di installazione delle route |
| `plugin-sdk/webhook-path` | Helper per normalizzazione dei percorsi Webhook |
| `plugin-sdk/web-media` | Helper condivisi per caricamento di media remoti/locali |
| `plugin-sdk/zod` | `zod` riesportato per i consumer dell'SDK per plugin |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
<Accordion title="Sottopercorsi della memoria">
| Sottopercorso | Esportazioni chiave |
| --- | --- |
| `plugin-sdk/memory-core` | Superficie helper `memory-core` inclusa per helper di manager/configurazione/file/CLI |
| `plugin-sdk/memory-core` | Superficie helper `memory-core` inclusa per helper di manager/config/file/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Facciata runtime per indice/ricerca della memoria |
| `plugin-sdk/memory-core-host-engine-foundation` | Esportazioni del motore foundation dell'host della memoria |
| `plugin-sdk/memory-core-host-engine-embeddings` | Contratti di embedding dell'host della memoria, accesso al registro, provider locale e helper generici batch/remoti |
| `plugin-sdk/memory-core-host-engine-embeddings` | Contratti embedding dell'host della memoria, accesso al registro, provider locale e helper generici batch/remoti |
| `plugin-sdk/memory-core-host-engine-qmd` | Esportazioni del motore QMD dell'host della memoria |
| `plugin-sdk/memory-core-host-engine-storage` | Esportazioni del motore di archiviazione dell'host della memoria |
| `plugin-sdk/memory-core-host-engine-storage` | Esportazioni del motore di storage dell'host della memoria |
| `plugin-sdk/memory-core-host-multimodal` | Helper multimodali dell'host della memoria |
| `plugin-sdk/memory-core-host-query` | Helper di query dell'host della memoria |
| `plugin-sdk/memory-core-host-secret` | Helper secret dell'host della memoria |
| `plugin-sdk/memory-core-host-events` | Helper del journal degli eventi dell'host della memoria |
| `plugin-sdk/memory-core-host-events` | Helper del journal eventi dell'host della memoria |
| `plugin-sdk/memory-core-host-status` | Helper di stato dell'host della memoria |
| `plugin-sdk/memory-core-host-runtime-cli` | Helper runtime CLI dell'host della memoria |
| `plugin-sdk/memory-core-host-runtime-core` | Helper runtime core dell'host della memoria |
| `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime dell'host della memoria |
| `plugin-sdk/memory-host-core` | Alias neutrale rispetto al vendor per gli helper runtime core dell'host della memoria |
| `plugin-sdk/memory-host-events` | Alias neutrale rispetto al vendor per gli helper del journal degli eventi dell'host della memoria |
| `plugin-sdk/memory-host-events` | Alias neutrale rispetto al vendor per gli helper del journal eventi dell'host della memoria |
| `plugin-sdk/memory-host-files` | Alias neutrale rispetto al vendor per gli helper file/runtime dell'host della memoria |
| `plugin-sdk/memory-host-markdown` | Helper condivisi per Markdown gestito per plugin adiacenti alla memoria |
| `plugin-sdk/memory-host-markdown` | Helper condivisi per markdown gestito per plugin adiacenti alla memoria |
| `plugin-sdk/memory-host-search` | Facciata runtime di Active Memory per l'accesso al gestore di ricerca |
| `plugin-sdk/memory-host-status` | Alias neutrale rispetto al vendor per gli helper di stato dell'host della memoria |
| `plugin-sdk/memory-lancedb` | Superficie helper `memory-lancedb` inclusa |
@ -308,11 +309,11 @@ non ne promuova esplicitamente uno come pubblico.
<Accordion title="Sottopercorsi helper inclusi riservati">
| Famiglia | Sottopercorsi attuali | Uso previsto |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helper di supporto del plugin browser incluso (`browser-support` rimane il barrel di compatibilità) |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helper di supporto per il plugin browser incluso (`browser-support` resta il barrel di compatibilità) |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Superficie helper/runtime Matrix inclusa |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superficie helper/runtime LINE inclusa |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superficie helper IRC inclusa |
| Helper specifici del canale | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seam di compatibilità/helper di canale inclusi |
| Helper specifici del canale | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Seam helper/di compatibilità dei canali inclusi |
| Helper specifici di auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Seam helper di funzionalità/plugin inclusi; `plugin-sdk/github-copilot-token` attualmente esporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
@ -326,9 +327,9 @@ metodi:
| Metodo | Cosa registra |
| ------------------------------------------------ | ------------------------------------- |
| `api.registerProvider(...)` | Inferenza di testo (LLM) |
| `api.registerAgentHarness(...)` | Esecutore sperimentale di agenti a basso livello |
| `api.registerCliBackend(...)` | Backend CLI locale per l'inferenza |
| `api.registerProvider(...)` | Inferenza testuale (LLM) |
| `api.registerAgentHarness(...)` | Esecutore sperimentale di agente a basso livello |
| `api.registerCliBackend(...)` | Backend CLI locale per inferenza |
| `api.registerChannel(...)` | Canale di messaggistica |
| `api.registerSpeechProvider(...)` | Sintesi text-to-speech / STT |
| `api.registerRealtimeTranscriptionProvider(...)` | Trascrizione realtime in streaming |
@ -337,44 +338,44 @@ metodi:
| `api.registerImageGenerationProvider(...)` | Generazione di immagini |
| `api.registerMusicGenerationProvider(...)` | Generazione musicale |
| `api.registerVideoGenerationProvider(...)` | Generazione video |
| `api.registerWebFetchProvider(...)` | Provider di fetch / scraping web |
| `api.registerWebFetchProvider(...)` | Provider di web fetch / scraping |
| `api.registerWebSearchProvider(...)` | Ricerca web |
### Tool e comandi
### Strumenti e comandi
| Metodo | Cosa registra |
| ------------------------------- | -------------------------------------------- |
| `api.registerTool(tool, opts?)` | Tool dell'agente (obbligatorio o `{ optional: true }`) |
| `api.registerTool(tool, opts?)` | Strumento agente (obbligatorio o `{ optional: true }`) |
| `api.registerCommand(def)` | Comando personalizzato (bypassa l'LLM) |
### Infrastruttura
| Metodo | Cosa registra |
| ---------------------------------------------- | --------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Hook di evento |
| `api.registerHook(events, handler, opts?)` | Hook evento |
| `api.registerHttpRoute(params)` | Endpoint HTTP del Gateway |
| `api.registerGatewayMethod(name, handler)` | Metodo RPC del Gateway |
| `api.registerCli(registrar, opts?)` | Sottocomando CLI |
| `api.registerService(service)` | Servizio in background |
| `api.registerInteractiveHandler(registration)` | Gestore interattivo |
| `api.registerMemoryPromptSupplement(builder)` | Sezione aggiuntiva del prompt adiacente alla memoria |
| `api.registerMemoryCorpusSupplement(adapter)` | Corpus aggiuntivo di ricerca/lettura della memoria |
| `api.registerMemoryPromptSupplement(builder)` | Sezione di prompt additiva adiacente alla memoria |
| `api.registerMemoryCorpusSupplement(adapter)` | Corpus additivo per ricerca/lettura della memoria |
Gli spazi dei nomi amministrativi core riservati (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) restano sempre `operator.admin`, anche se un plugin prova ad assegnare
un ambito di metodo Gateway più ristretto. Preferisci prefissi specifici del plugin per
i metodi posseduti dal plugin.
Gli spazi dei nomi di amministrazione core riservati (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) restano sempre `operator.admin`, anche se un plugin prova ad assegnare uno
scope del metodo Gateway più ristretto. Preferisci prefissi specifici del plugin per
i metodi di proprietà del plugin.
### Metadati di registrazione CLI
`api.registerCli(registrar, opts?)` accetta due tipi di metadati di primo livello:
`api.registerCli(registrar, opts?)` accetta due tipi di metadati di livello superiore:
- `commands`: radici di comando esplicite possedute dal registrar
- `descriptors`: descrittori di comando al momento del parsing usati per l'help della CLI root,
- `commands`: radici di comando esplicite di proprietà del registrar
- `descriptors`: descrittori di comando a tempo di parsing usati per l'help della CLI root,
il routing e la registrazione lazy della CLI del plugin
Se vuoi che un comando del plugin resti caricato lazy nel normale percorso della CLI root,
fornisci `descriptors` che coprano ogni radice di comando di primo livello esposta da quel
Se vuoi che un comando del plugin rimanga caricato lazy nel normale percorso della CLI root,
fornisci `descriptors` che coprano ogni radice di comando di livello superiore esposta da quel
registrar.
```typescript
@ -397,19 +398,19 @@ api.registerCli(
Usa `commands` da solo solo quando non hai bisogno della registrazione lazy della CLI root.
Quel percorso di compatibilità eager resta supportato, ma non installa
placeholder supportati da descriptor per il caricamento lazy al momento del parsing.
placeholder supportati da descrittori per il caricamento lazy a tempo di parsing.
### Registrazione del backend CLI
`api.registerCliBackend(...)` consente a un plugin di gestire la configurazione predefinita di un
`api.registerCliBackend(...)` consente a un plugin di possedere la configurazione predefinita per un
backend CLI AI locale come `codex-cli`.
- Il `id` del backend diventa il prefisso del provider nei model ref come `codex-cli/gpt-5`.
- L'`id` del backend diventa il prefisso del provider nei model ref come `codex-cli/gpt-5`.
- La `config` del backend usa la stessa forma di `agents.defaults.cliBackends.<id>`.
- La configurazione utente ha comunque la precedenza. OpenClaw unisce `agents.defaults.cliBackends.<id>` sopra il
valore predefinito del plugin prima di eseguire la CLI.
- Usa `normalizeConfig` quando un backend ha bisogno di riscritture di compatibilità dopo il merge
(per esempio normalizzando vecchie forme di flag).
- La configurazione utente continua ad avere precedenza. OpenClaw unisce `agents.defaults.cliBackends.<id>` sulla
configurazione predefinita del plugin prima di eseguire la CLI.
- Usa `normalizeConfig` quando un backend necessita di riscritture di compatibilità dopo il merge
(per esempio per normalizzare vecchie forme di flag).
### Slot esclusivi
@ -417,45 +418,45 @@ backend CLI AI locale come `codex-cli`.
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Motore di contesto (uno attivo alla volta). La callback `assemble()` riceve `availableTools` e `citationsMode` così il motore può adattare le aggiunte al prompt. |
| `api.registerMemoryCapability(capability)` | Capacità di memoria unificata |
| `api.registerMemoryPromptSection(builder)` | Builder della sezione prompt della memoria |
| `api.registerMemoryPromptSection(builder)` | Builder della sezione di prompt della memoria |
| `api.registerMemoryFlushPlan(resolver)` | Resolver del piano di flush della memoria |
| `api.registerMemoryRuntime(runtime)` | Adattatore runtime della memoria |
| `api.registerMemoryRuntime(runtime)` | Adapter runtime della memoria |
### Adattatori di embedding della memoria
### Adapter embedding della memoria
| Metodo | Cosa registra |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adattatore di embedding della memoria per il plugin attivo |
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding della memoria per il plugin attivo |
- `registerMemoryCapability` è l'API preferita del plugin di memoria esclusivo.
- `registerMemoryCapability` è l'API esclusiva preferita del plugin di memoria.
- `registerMemoryCapability` può anche esporre `publicArtifacts.listArtifacts(...)`
così i plugin companion possono consumare artefatti di memoria esportati tramite
`openclaw/plugin-sdk/memory-host-core` invece di entrare nel layout privato
di uno specifico plugin di memoria.
`openclaw/plugin-sdk/memory-host-core` invece di accedere al layout privato di uno specifico
plugin di memoria.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` e
`registerMemoryRuntime` sono API legacy-compatibili del plugin di memoria esclusivo.
`registerMemoryRuntime` sono API esclusive legacy-compatibili del plugin di memoria.
- `registerMemoryEmbeddingProvider` consente al plugin di memoria attivo di registrare uno
o più ID di adattatore di embedding (per esempio `openai`, `gemini` o un ID personalizzato definito dal plugin).
o più ID di adapter embedding (per esempio `openai`, `gemini` o un ID personalizzato definito dal plugin).
- La configurazione utente come `agents.defaults.memorySearch.provider` e
`agents.defaults.memorySearch.fallback` viene risolta rispetto a quegli ID di adattatore
`agents.defaults.memorySearch.fallback` viene risolta rispetto a quegli ID di adapter
registrati.
### Eventi e ciclo di vita
| Metodo | Cosa fa |
| -------------------------------------------- | --------------------------- |
| `api.on(hookName, handler, opts?)` | Hook del ciclo di vita tipizzato |
| Metodo | Cosa fa |
| -------------------------------------------- | -------------------------- |
| `api.on(hookName, handler, opts?)` | Hook di ciclo di vita tipizzato |
| `api.onConversationBindingResolved(handler)` | Callback di binding della conversazione |
### Semantica delle decisioni degli hook
### Semantica di decisione degli hook
- `before_tool_call`: restituire `{ block: true }` è terminale. Non appena un gestore lo imposta, i gestori con priorità inferiore vengono saltati.
- `before_tool_call`: restituire `{ block: false }` viene trattato come nessuna decisione (uguale a omettere `block`), non come un override.
- `before_install`: restituire `{ block: true }` è terminale. Non appena un gestore lo imposta, i gestori con priorità inferiore vengono saltati.
- `before_install`: restituire `{ block: false }` viene trattato come nessuna decisione (uguale a omettere `block`), non come un override.
- `reply_dispatch`: restituire `{ handled: true, ... }` è terminale. Non appena un gestore rivendica il dispatch, i gestori con priorità inferiore e il percorso di dispatch predefinito del modello vengono saltati.
- `message_sending`: restituire `{ cancel: true }` è terminale. Non appena un gestore lo imposta, i gestori con priorità inferiore vengono saltati.
- `message_sending`: restituire `{ cancel: false }` viene trattato come nessuna decisione (uguale a omettere `cancel`), non come un override.
- `before_tool_call`: restituire `{ block: true }` è terminale. Una volta che un gestore lo imposta, i gestori con priorità inferiore vengono saltati.
- `before_tool_call`: restituire `{ block: false }` viene trattato come nessuna decisione (come omettere `block`), non come override.
- `before_install`: restituire `{ block: true }` è terminale. Una volta che un gestore lo imposta, i gestori con priorità inferiore vengono saltati.
- `before_install`: restituire `{ block: false }` viene trattato come nessuna decisione (come omettere `block`), non come override.
- `reply_dispatch`: restituire `{ handled: true, ... }` è terminale. Una volta che un gestore rivendica il dispatch, i gestori con priorità inferiore e il percorso predefinito di dispatch del modello vengono saltati.
- `message_sending`: restituire `{ cancel: true }` è terminale. Una volta che un gestore lo imposta, i gestori con priorità inferiore vengono saltati.
- `message_sending`: restituire `{ cancel: false }` viene trattato come nessuna decisione (come omettere `cancel`), non come override.
### Campi dell'oggetto API
@ -463,16 +464,16 @@ backend CLI AI locale come `codex-cli`.
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | ID del plugin |
| `api.name` | `string` | Nome visualizzato |
| `api.version` | `string?` | Versione del plugin (opzionale) |
| `api.description` | `string?` | Descrizione del plugin (opzionale) |
| `api.version` | `string?` | Versione del plugin (facoltativa) |
| `api.description` | `string?` | Descrizione del plugin (facoltativa) |
| `api.source` | `string` | Percorso sorgente del plugin |
| `api.rootDir` | `string?` | Directory root del plugin (opzionale) |
| `api.config` | `OpenClawConfig` | Snapshot corrente della configurazione (snapshot runtime in-memory attivo quando disponibile) |
| `api.rootDir` | `string?` | Directory radice del plugin (facoltativa) |
| `api.config` | `OpenClawConfig` | Snapshot della configurazione corrente (snapshot runtime attivo in memoria quando disponibile) |
| `api.pluginConfig` | `Record<string, unknown>` | Configurazione specifica del plugin da `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Helper runtime](/it/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger con scope (`debug`, `info`, `warn`, `error`) |
| `api.logger` | `PluginLogger` | Logger con ambito (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Modalità di caricamento corrente; `"setup-runtime"` è la finestra leggera di avvio/configurazione prima dell'entry completa |
| `api.resolvePath(input)` | `(string) => string` | Risolve il percorso relativo alla root del plugin |
| `api.resolvePath(input)` | `(string) => string` | Risolve un percorso relativo alla radice del plugin |
## Convenzione dei moduli interni
@ -480,49 +481,49 @@ All'interno del tuo plugin, usa file barrel locali per le importazioni interne:
```
my-plugin/
api.ts # Esportazioni pubbliche per consumatori esterni
api.ts # Esportazioni pubbliche per consumer esterni
runtime-api.ts # Esportazioni runtime solo interne
index.ts # Entry point del plugin
setup-entry.ts # Entry leggera solo per la configurazione (opzionale)
index.ts # Punto di ingresso del plugin
setup-entry.ts # Entry leggera solo per la configurazione (facoltativa)
```
<Warning>
Non importare mai il tuo plugin tramite `openclaw/plugin-sdk/<your-plugin>`
dal codice di produzione. Indirizza le importazioni interne tramite `./api.ts` o
Non importare mai il tuo stesso plugin tramite `openclaw/plugin-sdk/<your-plugin>`
dal codice di produzione. Instrada le importazioni interne tramite `./api.ts` o
`./runtime-api.ts`. Il percorso SDK è solo il contratto esterno.
</Warning>
Le superfici pubbliche dei plugin inclusi caricate tramite facade (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts` e file entry pubblici simili) ora preferiscono lo
snapshot attivo della configurazione runtime quando OpenClaw è già in esecuzione. Se non esiste ancora
`index.ts`, `setup-entry.ts` e file di entry pubblici simili) ora preferiscono lo
snapshot della configurazione runtime attiva quando OpenClaw è già in esecuzione. Se non esiste ancora
uno snapshot runtime, usano come fallback il file di configurazione risolto su disco.
I plugin provider possono anche esporre un barrel di contratto locale al plugin e ristretto quando un
helper è intenzionalmente specifico del provider e non appartiene ancora a un sottopercorso
SDK generico. Esempio incluso attuale: il provider Anthropic mantiene i suoi helper
di stream Claude nel proprio seam pubblico `api.ts` / `contract-api.ts` invece di
promuovere la logica dell'header beta Anthropic e `service_tier` in un contratto
I plugin provider possono anche esporre un barrel di contratto locale al plugin quando un
helper è intenzionalmente specifico del provider e non appartiene ancora a un sottopercorso SDK
generico. Esempio attuale incluso: il provider Anthropic mantiene i suoi helper di stream Claude
nel proprio seam pubblico `api.ts` / `contract-api.ts` invece di
promuovere la logica di header beta Anthropic e `service_tier` in un contratto
generico `plugin-sdk/*`.
Altri esempi inclusi attuali:
Altri esempi attuali inclusi:
- `@openclaw/openai-provider`: `api.ts` esporta builder di provider,
helper per modelli predefiniti e builder di provider realtime
- `@openclaw/openai-provider`: `api.ts` esporta builder del provider,
helper per modelli predefiniti e builder del provider realtime
- `@openclaw/openrouter-provider`: `api.ts` esporta il builder del provider più
helper di onboarding/configurazione
<Warning>
Il codice di produzione delle estensioni dovrebbe anche evitare importazioni `openclaw/plugin-sdk/<other-plugin>`.
Se un helper è davvero condiviso, promuovilo a un sottopercorso SDK neutrale
Il codice di produzione delle estensioni dovrebbe anche evitare importazioni
`openclaw/plugin-sdk/<other-plugin>`. Se un helper è davvero condiviso, promuovilo a un sottopercorso SDK neutrale
come `openclaw/plugin-sdk/speech`, `.../provider-model-shared` o un'altra
superficie orientata alle capacità invece di accoppiare due plugin tra loro.
</Warning>
## Correlati
- [Punti di ingresso](/it/plugins/sdk-entrypoints) — opzioni di `definePluginEntry` e `defineChannelPluginEntry`
- [Helper runtime](/it/plugins/sdk-runtime) — riferimento completo dello spazio dei nomi `api.runtime`
- [Configurazione e setup](/it/plugins/sdk-setup) — packaging, manifest, schemi di configurazione
- [Testing](/it/plugins/sdk-testing) — utility di test e regole di lint
- [Migrazione dell'SDK](/it/plugins/sdk-migration) — migrazione da superfici deprecate
- [Elementi interni del plugin](/it/plugins/architecture) — architettura approfondita e modello di capacità
- [Entry Points](/it/plugins/sdk-entrypoints) — opzioni di `definePluginEntry` e `defineChannelPluginEntry`
- [Runtime Helpers](/it/plugins/sdk-runtime) — riferimento completo dello spazio dei nomi `api.runtime`
- [Setup and Config](/it/plugins/sdk-setup) — packaging, manifest, schemi di configurazione
- [Testing](/it/plugins/sdk-testing) — utility di test e regole lint
- [SDK Migration](/it/plugins/sdk-migration) — migrazione dalle superfici deprecate
- [Plugin Internals](/it/plugins/architecture) — architettura approfondita e modello di capacità

109
docs/it/providers/google.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Vuoi usare i modelli Google Gemini con OpenClaw
- Hai bisogno della chiave API o del flusso di autenticazione OAuth
- Hai bisogno del flusso di autenticazione con chiave API o OAuth
summary: Configurazione di Google Gemini (chiave API + OAuth, generazione di immagini, comprensione dei media, TTS, ricerca web)
title: Google (Gemini)
x-i18n:
generated_at: "2026-04-16T08:18:32Z"
generated_at: "2026-04-19T01:11:24Z"
model: gpt-5.4
provider: openai
source_hash: ec2d62855f5e80efda758aad71bcaa95c38b1e41761fa1100d47a06c62881419
source_hash: e5e055b02cc51899e11836a882f1f981fedfa5c4dbe42261ac2f2eba5e4d707c
source_path: providers/google.md
workflow: 15
---
@ -16,7 +16,7 @@ x-i18n:
# Google (Gemini)
Il Plugin Google fornisce accesso ai modelli Gemini tramite Google AI Studio, oltre a
generazione di immagini, comprensione dei media (immagini/audio/video), sintesi vocale e ricerca web tramite
generazione di immagini, comprensione dei media (immagine/audio/video), sintesi vocale e ricerca web tramite
Gemini Grounding.
- Provider: `google`
@ -30,7 +30,7 @@ Scegli il metodo di autenticazione che preferisci e segui i passaggi di configur
<Tabs>
<Tab title="Chiave API">
**Ideale per:** accesso standard all'API Gemini tramite Google AI Studio.
**Ideale per:** accesso standard alle API Gemini tramite Google AI Studio.
<Steps>
<Step title="Esegui l'onboarding">
@ -76,11 +76,11 @@ Scegli il metodo di autenticazione che preferisci e segui i passaggi di configur
<Warning>
Il provider `google-gemini-cli` è un'integrazione non ufficiale. Alcuni utenti
segnalano limitazioni dell'account quando si usa OAuth in questo modo. Usalo a tuo rischio.
segnalano restrizioni dell'account quando si usa OAuth in questo modo. Usalo a tuo rischio.
</Warning>
<Steps>
<Step title="Installa Gemini CLI">
<Step title="Installa la Gemini CLI">
Il comando locale `gemini` deve essere disponibile nel `PATH`.
```bash
@ -91,7 +91,7 @@ Scegli il metodo di autenticazione che preferisci e segui i passaggi di configur
npm install -g @google/gemini-cli
```
OpenClaw supporta sia le installazioni Homebrew sia quelle npm globali, inclusi
OpenClaw supporta sia le installazioni Homebrew sia le installazioni npm globali, inclusi
i layout comuni di Windows/npm.
</Step>
<Step title="Accedi tramite OAuth">
@ -117,53 +117,58 @@ Scegli il metodo di autenticazione che preferisci e segui i passaggi di configur
(Oppure le varianti `GEMINI_CLI_*`.)
<Note>
Se le richieste OAuth di Gemini CLI falliscono dopo l'accesso, imposta `GOOGLE_CLOUD_PROJECT` oppure
`GOOGLE_CLOUD_PROJECT_ID` sull'host del Gateway e riprova.
Se le richieste OAuth di Gemini CLI falliscono dopo l'accesso, imposta `GOOGLE_CLOUD_PROJECT` o
`GOOGLE_CLOUD_PROJECT_ID` sull'host Gateway e riprova.
</Note>
<Note>
Se l'accesso fallisce prima che inizi il flusso nel browser, assicurati che il comando locale `gemini`
sia installato e presente nel `PATH`.
sia installato e disponibile nel `PATH`.
</Note>
Il provider solo OAuth `google-gemini-cli` è una superficie separata di
inferenza testuale. La generazione di immagini, la comprensione dei media e Gemini Grounding restano sul
provider con id `google`.
provider id `google`.
</Tab>
</Tabs>
## Capacità
| Capacità | Supportato |
| ---------------------- | ----------------- |
| Completamenti chat | Sì |
| Generazione di immagini| Sì |
| Generazione musicale | Sì |
| Sintesi vocale | Sì |
| Comprensione immagini | Sì |
| Trascrizione audio | Sì |
| Comprensione video | Sì |
| Ricerca web (Grounding)| Sì |
| Thinking/ragionamento | Sì (Gemini 3.1+) |
| Modelli Gemma 4 | Sì |
| Capacità | Supportato |
| ----------------------- | ----------------------------- |
| Completamenti chat | Sì |
| Generazione di immagini | Sì |
| Generazione musicale | Sì |
| Sintesi vocale | Sì |
| Comprensione immagini | Sì |
| Trascrizione audio | Sì |
| Comprensione video | Sì |
| Ricerca web (Grounding) | Sì |
| Thinking/reasoning | Sì (Gemini 2.5+ / Gemini 3+) |
| Modelli Gemma 4 | Sì |
<Tip>
I modelli Gemma 4 (ad esempio `gemma-4-26b-a4b-it`) supportano la modalità thinking. OpenClaw
I modelli Gemini 3 usano `thinkingLevel` invece di `thinkingBudget`. OpenClaw mappa
i controlli di reasoning di Gemini 3, Gemini 3.1 e dell'alias `gemini-*-latest` a
`thinkingLevel` in modo che le esecuzioni predefinite/a bassa latenza non inviino
valori `thinkingBudget` disabilitati.
I modelli Gemma 4 (per esempio `gemma-4-26b-a4b-it`) supportano la modalità thinking. OpenClaw
riscrive `thinkingBudget` in un `thinkingLevel` Google supportato per Gemma 4.
Impostare thinking su `off` mantiene thinking disabilitato invece di mapparlo a
Impostare il thinking su `off` mantiene il thinking disabilitato invece di mapparlo a
`MINIMAL`.
</Tip>
## Generazione di immagini
Il provider di generazione immagini `google` incluso usa come predefinito
Il provider in bundle `google` per la generazione di immagini usa come predefinito
`google/gemini-3.1-flash-image-preview`.
- Supporta anche `google/gemini-3-pro-image-preview`
- Generazione: fino a 4 immagini per richiesta
- Modalità modifica: abilitata, fino a 5 immagini di input
- Controlli geometrici: `size`, `aspectRatio` e `resolution`
- Controlli di geometria: `size`, `aspectRatio` e `resolution`
Per usare Google come provider di immagini predefinito:
@ -180,16 +185,16 @@ Per usare Google come provider di immagini predefinito:
```
<Note>
Consulta [Generazione di immagini](/it/tools/image-generation) per i parametri condivisi dello strumento, la selezione del provider e il comportamento di failover.
Vedi [Image Generation](/it/tools/image-generation) per i parametri condivisi dello strumento, la selezione del provider e il comportamento di failover.
</Note>
## Generazione video
Il Plugin `google` incluso registra anche la generazione video tramite lo strumento condiviso
Il Plugin in bundle `google` registra anche la generazione video tramite lo strumento condiviso
`video_generate`.
- Modello video predefinito: `google/veo-3.1-fast-generate-preview`
- Modalità: testo in video, immagine in video e flussi con riferimento a singolo video
- Modalità: testo in video, immagine in video e flussi con riferimento a video singolo
- Supporta `aspectRatio`, `resolution` e `audio`
- Limite attuale della durata: **da 4 a 8 secondi**
@ -208,12 +213,12 @@ Per usare Google come provider video predefinito:
```
<Note>
Consulta [Generazione video](/it/tools/video-generation) per i parametri condivisi dello strumento, la selezione del provider e il comportamento di failover.
Vedi [Video Generation](/it/tools/video-generation) per i parametri condivisi dello strumento, la selezione del provider e il comportamento di failover.
</Note>
## Generazione musicale
Il Plugin `google` incluso registra anche la generazione musicale tramite lo strumento condiviso
Il Plugin in bundle `google` registra anche la generazione musicale tramite lo strumento condiviso
`music_generate`.
- Modello musicale predefinito: `google/lyria-3-clip-preview`
@ -238,18 +243,18 @@ Per usare Google come provider musicale predefinito:
```
<Note>
Consulta [Generazione musicale](/it/tools/music-generation) per i parametri condivisi dello strumento, la selezione del provider e il comportamento di failover.
Vedi [Music Generation](/it/tools/music-generation) per i parametri condivisi dello strumento, la selezione del provider e il comportamento di failover.
</Note>
## Sintesi vocale
Il provider vocale `google` incluso usa il percorso TTS della Gemini API con
Il provider vocale in bundle `google` usa il percorso TTS della Gemini API con
`gemini-3.1-flash-tts-preview`.
- Voce predefinita: `Kore`
- Autenticazione: `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY` o `GOOGLE_API_KEY`
- Output: WAV per i normali allegati TTS, PCM per Talk/telefonia
- Output nativo di note vocali: non supportato su questo percorso Gemini API perché l'API restituisce PCM invece di Opus
- Output: WAV per allegati TTS normali, PCM per Talk/telefonia
- Output nativo come nota vocale: non supportato su questo percorso Gemini API perché l'API restituisce PCM invece di Opus
Per usare Google come provider TTS predefinito:
@ -271,18 +276,18 @@ Per usare Google come provider TTS predefinito:
```
Il TTS della Gemini API accetta tag audio espressivi tra parentesi quadre nel testo, come
`[whispers]` o `[laughs]`. Per tenere i tag fuori dalla risposta visibile in chat mentre
li invii al TTS, inseriscili in un blocco `[[tts:text]]...[[/tts:text]]`:
`[whispers]` o `[laughs]`. Per tenere i tag fuori dalla risposta chat visibile ma
inviarli al TTS, inseriscili dentro un blocco `[[tts:text]]...[[/tts:text]]`:
```text
Ecco il testo pulito della risposta.
Qui c'è il testo pulito della risposta.
[[tts:text]][whispers] Ecco la versione parlata.[[/tts:text]]
[[tts:text]][whispers] Qui c'è la versione parlata.[[/tts:text]]
```
<Note>
Una chiave API di Google Cloud Console limitata alla Gemini API è valida per questo
provider. Questo non è il percorso separato dell'API Cloud Text-to-Speech.
provider. Questo non è il percorso separato della Cloud Text-to-Speech API.
</Note>
## Configurazione avanzata
@ -292,11 +297,11 @@ provider. Questo non è il percorso separato dell'API Cloud Text-to-Speech.
Per le esecuzioni dirette della Gemini API (`api: "google-generative-ai"`), OpenClaw
passa un handle `cachedContent` configurato direttamente alle richieste Gemini.
- Configura i parametri per modello o globali con
- Configura parametri per modello o globali usando
`cachedContent` oppure il legacy `cached_content`
- Se sono presenti entrambi, `cachedContent` ha la precedenza
- Se sono presenti entrambi, ha priorità `cachedContent`
- Valore di esempio: `cachedContents/prebuilt-context`
- L'uso di Gemini con cache hit è normalizzato in OpenClaw `cacheRead` a partire da
- L'uso cache-hit di Gemini viene normalizzato in OpenClaw `cacheRead` da
`cachedContentTokenCount` upstream
```json5
@ -318,11 +323,11 @@ provider. Questo non è il percorso separato dell'API Cloud Text-to-Speech.
</Accordion>
<Accordion title="Note sull'uso del JSON di Gemini CLI">
Quando usi il provider OAuth `google-gemini-cli`, OpenClaw normalizza
Quando si usa il provider OAuth `google-gemini-cli`, OpenClaw normalizza
l'output JSON della CLI come segue:
- Il testo della risposta proviene dal campo JSON `response` della CLI.
- L'utilizzo ricade su `stats` quando la CLI lascia vuoto `usage`.
- L'uso ricade su `stats` quando la CLI lascia vuoto `usage`.
- `stats.cached` viene normalizzato in OpenClaw `cacheRead`.
- Se `stats.input` manca, OpenClaw ricava i token di input da
`stats.input_tokens - stats.cached`.
@ -331,7 +336,7 @@ provider. Questo non è il percorso separato dell'API Cloud Text-to-Speech.
<Accordion title="Configurazione di ambiente e daemon">
Se il Gateway viene eseguito come daemon (launchd/systemd), assicurati che `GEMINI_API_KEY`
sia disponibile per quel processo (ad esempio in `~/.openclaw/.env` o tramite
sia disponibile per quel processo (per esempio in `~/.openclaw/.env` o tramite
`env.shellEnv`).
</Accordion>
</AccordionGroup>
@ -340,15 +345,15 @@ provider. Questo non è il percorso separato dell'API Cloud Text-to-Speech.
<CardGroup cols={2}>
<Card title="Selezione del modello" href="/it/concepts/model-providers" icon="layers">
Scegliere provider, riferimenti ai modelli e comportamento di failover.
Scelta dei provider, dei riferimenti ai modelli e del comportamento di failover.
</Card>
<Card title="Generazione di immagini" href="/it/tools/image-generation" icon="image">
Parametri condivisi dello strumento per le immagini e selezione del provider.
Parametri condivisi dello strumento immagini e selezione del provider.
</Card>
<Card title="Generazione video" href="/it/tools/video-generation" icon="video">
Parametri condivisi dello strumento per i video e selezione del provider.
Parametri condivisi dello strumento video e selezione del provider.
</Card>
<Card title="Generazione musicale" href="/it/tools/music-generation" icon="music">
Parametri condivisi dello strumento per la musica e selezione del provider.
Parametri condivisi dello strumento musicale e selezione del provider.
</Card>
</CardGroup>