chore(i18n): refresh it translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
4655c84490
commit
cc2fdc1d5e
File diff suppressed because it is too large
Load Diff
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- Configurazione di Slack o debug della modalità socket/HTTP di Slack
|
||||
summary: Configurazione di Slack e comportamento di runtime (Socket Mode + HTTP Events API)
|
||||
summary: Configurazione di Slack e comportamento di runtime (Socket Mode + URL di richiesta HTTP)
|
||||
title: Slack
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:07:03Z"
|
||||
generated_at: "2026-04-06T08:16:06Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 7e4ff2ce7d92276d62f4f3d3693ddb56ca163d5fdc2f1082ff7ba3421fada69c
|
||||
source_hash: 897001c13d400cc8387a27000b82dd4c0512b2b88e2fe47785634aed8b7ab7af
|
||||
source_path: channels/slack.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Slack
|
||||
|
||||
Stato: pronto per la produzione per DM + canali tramite integrazioni dell'app Slack. La modalità predefinita è Socket Mode; è supportata anche la modalità HTTP Events API.
|
||||
Stato: pronto per la produzione per DM + canali tramite integrazioni dell'app Slack. La modalità predefinita è Socket Mode; sono supportati anche gli URL di richiesta HTTP.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Abbinamento" icon="link" href="/it/channels/pairing">
|
||||
I DM di Slack usano per impostazione predefinita la modalità di abbinamento.
|
||||
</Card>
|
||||
<Card title="Comandi slash" icon="terminal" href="/it/tools/slash-commands">
|
||||
Comportamento dei comandi nativo e catalogo dei comandi.
|
||||
Comportamento nativo dei comandi e catalogo dei comandi.
|
||||
</Card>
|
||||
<Card title="Risoluzione dei problemi del canale" icon="wrench" href="/it/channels/troubleshooting">
|
||||
Diagnostica cross-channel e playbook di ripristino.
|
||||
Diagnostica tra canali e procedure di riparazione.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -33,7 +33,7 @@ Stato: pronto per la produzione per DM + canali tramite integrazioni dell'app Sl
|
||||
<Tabs>
|
||||
<Tab title="Socket Mode (predefinita)">
|
||||
<Steps>
|
||||
<Step title="Crea l'app Slack e i token">
|
||||
<Step title="Crea app Slack e token">
|
||||
Nelle impostazioni dell'app Slack:
|
||||
|
||||
- abilita **Socket Mode**
|
||||
@ -75,7 +75,7 @@ SLACK_BOT_TOKEN=xoxb-...
|
||||
- `channel_rename`
|
||||
- `pin_added`, `pin_removed`
|
||||
|
||||
Abilita anche App Home **Messages Tab** per i DM.
|
||||
Abilita anche la **Messages Tab** di App Home per i DM.
|
||||
</Step>
|
||||
|
||||
<Step title="Avvia il gateway">
|
||||
@ -89,13 +89,13 @@ openclaw gateway
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Modalità HTTP Events API">
|
||||
<Tab title="URL di richiesta HTTP">
|
||||
<Steps>
|
||||
<Step title="Configura l'app Slack per HTTP">
|
||||
|
||||
- imposta la modalità su HTTP (`channels.slack.mode="http"`)
|
||||
- copia il **Signing Secret** di Slack
|
||||
- imposta Event Subscriptions + Interactivity + l'URL di richiesta del comando Slash sullo stesso percorso webhook (predefinito `/slack/events`)
|
||||
- imposta l'URL di richiesta di Event Subscriptions + Interactivity + Slash command sullo stesso percorso webhook (predefinito `/slack/events`)
|
||||
|
||||
</Step>
|
||||
|
||||
@ -120,7 +120,7 @@ openclaw gateway
|
||||
<Step title="Usa percorsi webhook univoci per HTTP multi-account">
|
||||
La modalità HTTP per account è supportata.
|
||||
|
||||
Assegna a ogni account un `webhookPath` distinto in modo che le registrazioni non vadano in conflitto.
|
||||
Assegna a ogni account un `webhookPath` distinto in modo che le registrazioni non entrino in conflitto.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@ -129,8 +129,8 @@ openclaw gateway
|
||||
|
||||
## Checklist di manifest e scope
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Esempio di manifest dell'app Slack" defaultOpen>
|
||||
<Tabs>
|
||||
<Tab title="Socket Mode (predefinita)">
|
||||
|
||||
```json
|
||||
{
|
||||
@ -205,8 +205,98 @@ openclaw gateway
|
||||
}
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
</Tab>
|
||||
|
||||
<Tab title="URL di richiesta HTTP">
|
||||
|
||||
```json
|
||||
{
|
||||
"display_information": {
|
||||
"name": "OpenClaw",
|
||||
"description": "Slack connector for OpenClaw"
|
||||
},
|
||||
"features": {
|
||||
"bot_user": {
|
||||
"display_name": "OpenClaw",
|
||||
"always_online": true
|
||||
},
|
||||
"app_home": {
|
||||
"messages_tab_enabled": true,
|
||||
"messages_tab_read_only_enabled": false
|
||||
},
|
||||
"slash_commands": [
|
||||
{
|
||||
"command": "/openclaw",
|
||||
"description": "Send a message to OpenClaw",
|
||||
"should_escape": false,
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
}
|
||||
]
|
||||
},
|
||||
"oauth_config": {
|
||||
"scopes": {
|
||||
"bot": [
|
||||
"app_mentions:read",
|
||||
"assistant:write",
|
||||
"channels:history",
|
||||
"channels:read",
|
||||
"chat:write",
|
||||
"commands",
|
||||
"emoji:read",
|
||||
"files:read",
|
||||
"files:write",
|
||||
"groups:history",
|
||||
"groups:read",
|
||||
"im:history",
|
||||
"im:read",
|
||||
"im:write",
|
||||
"mpim:history",
|
||||
"mpim:read",
|
||||
"mpim:write",
|
||||
"pins:read",
|
||||
"pins:write",
|
||||
"reactions:read",
|
||||
"reactions:write",
|
||||
"users:read"
|
||||
]
|
||||
}
|
||||
},
|
||||
"settings": {
|
||||
"event_subscriptions": {
|
||||
"request_url": "https://gateway-host.example.com/slack/events",
|
||||
"bot_events": [
|
||||
"app_mention",
|
||||
"channel_rename",
|
||||
"member_joined_channel",
|
||||
"member_left_channel",
|
||||
"message.channels",
|
||||
"message.groups",
|
||||
"message.im",
|
||||
"message.mpim",
|
||||
"pin_added",
|
||||
"pin_removed",
|
||||
"reaction_added",
|
||||
"reaction_removed"
|
||||
]
|
||||
},
|
||||
"interactivity": {
|
||||
"is_enabled": true,
|
||||
"request_url": "https://gateway-host.example.com/slack/events",
|
||||
"message_menu_options_url": "https://gateway-host.example.com/slack/events"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Scope di paternità opzionali (operazioni di scrittura)">
|
||||
Aggiungi lo scope bot `chat:write.customize` se vuoi che i messaggi in uscita usino l'identità dell'agente attivo (nome utente e icona personalizzati) invece dell'identità predefinita dell'app Slack.
|
||||
|
||||
Se usi un'icona emoji, Slack si aspetta la sintassi `:emoji_name:`.
|
||||
</Accordion>
|
||||
<Accordion title="Scope opzionali del token utente (operazioni di lettura)">
|
||||
Se configuri `channels.slack.userToken`, gli scope di lettura tipici sono:
|
||||
|
||||
@ -216,7 +306,7 @@ openclaw gateway
|
||||
- `reactions:read`
|
||||
- `pins:read`
|
||||
- `emoji:read`
|
||||
- `search:read` (se dipendi dalle letture della ricerca di Slack)
|
||||
- `search:read` (se dipendi dalle letture di ricerca di Slack)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -227,27 +317,26 @@ openclaw gateway
|
||||
- La modalità HTTP richiede `botToken` + `signingSecret`.
|
||||
- `botToken`, `appToken`, `signingSecret` e `userToken` accettano stringhe in chiaro
|
||||
o oggetti SecretRef.
|
||||
- I token nella configurazione sovrascrivono il fallback env.
|
||||
- I token di configurazione hanno la precedenza sul fallback env.
|
||||
- Il fallback env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` si applica solo all'account predefinito.
|
||||
- `userToken` (`xoxp-...`) è solo di configurazione (nessun fallback env) e usa per impostazione predefinita un comportamento di sola lettura (`userTokenReadOnly: true`).
|
||||
- Facoltativo: aggiungi `chat:write.customize` se vuoi che i messaggi in uscita usino l'identità dell'agente attivo (con `username` e icona personalizzati). `icon_emoji` usa la sintassi `:emoji_name:`.
|
||||
- `userToken` (`xoxp-...`) è solo di configurazione (nessun fallback env) e per impostazione predefinita usa un comportamento di sola lettura (`userTokenReadOnly: true`).
|
||||
|
||||
Comportamento della panoramica di stato:
|
||||
Comportamento dell'istantanea di stato:
|
||||
|
||||
- L'ispezione dell'account Slack traccia i campi `*Source` e `*Status`
|
||||
per credenziale (`botToken`, `appToken`, `signingSecret`, `userToken`).
|
||||
- L'ispezione dell'account Slack tiene traccia dei campi `*Source` e `*Status`
|
||||
per ogni credenziale (`botToken`, `appToken`, `signingSecret`, `userToken`).
|
||||
- Lo stato è `available`, `configured_unavailable` o `missing`.
|
||||
- `configured_unavailable` significa che l'account è configurato tramite SecretRef
|
||||
o un'altra sorgente di segreti non inline, ma il percorso comando/runtime
|
||||
corrente non è riuscito a risolvere il valore effettivo.
|
||||
o un'altra sorgente segreta non inline, ma il percorso comando/runtime corrente
|
||||
non è riuscito a risolvere il valore effettivo.
|
||||
- In modalità HTTP, è incluso `signingSecretStatus`; in Socket Mode, la
|
||||
coppia richiesta è `botTokenStatus` + `appTokenStatus`.
|
||||
|
||||
<Tip>
|
||||
Per le azioni/letture della directory, quando configurato può essere preferito il token utente. Per le scritture, il token bot resta preferito; le scritture con token utente sono consentite solo quando `userTokenReadOnly: false` e il token bot non è disponibile.
|
||||
Per azioni/letture di directory, il token utente può essere preferito quando configurato. Per le scritture, il token bot resta preferito; le scritture con token utente sono consentite solo quando `userTokenReadOnly: false` e il token bot non è disponibile.
|
||||
</Tip>
|
||||
|
||||
## Azioni e gate
|
||||
## Azioni e controlli
|
||||
|
||||
Le azioni Slack sono controllate da `channels.slack.actions.*`.
|
||||
|
||||
@ -255,18 +344,18 @@ Gruppi di azioni disponibili negli strumenti Slack attuali:
|
||||
|
||||
| Gruppo | Predefinito |
|
||||
| ---------- | ----------- |
|
||||
| messages | abilitato |
|
||||
| reactions | abilitato |
|
||||
| pins | abilitato |
|
||||
| memberInfo | abilitato |
|
||||
| emojiList | abilitato |
|
||||
| messages | enabled |
|
||||
| reactions | enabled |
|
||||
| pins | enabled |
|
||||
| memberInfo | enabled |
|
||||
| emojiList | enabled |
|
||||
|
||||
Le azioni correnti dei messaggi Slack includono `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` ed `emoji-list`.
|
||||
Le azioni correnti per i messaggi Slack includono `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` ed `emoji-list`.
|
||||
|
||||
## Controllo degli accessi e instradamento
|
||||
## Controllo accessi e instradamento
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Criteri DM">
|
||||
<Tab title="Criterio DM">
|
||||
`channels.slack.dmPolicy` controlla l'accesso ai DM (legacy: `channels.slack.dm.policy`):
|
||||
|
||||
- `pairing` (predefinito)
|
||||
@ -279,21 +368,21 @@ Le azioni correnti dei messaggi Slack includono `send`, `upload-file`, `download
|
||||
- `dm.enabled` (predefinito true)
|
||||
- `channels.slack.allowFrom` (preferito)
|
||||
- `dm.allowFrom` (legacy)
|
||||
- `dm.groupEnabled` (i DM di gruppo sono false per impostazione predefinita)
|
||||
- `dm.groupChannels` (allowlist MPIM facoltativa)
|
||||
- `dm.groupEnabled` (DM di gruppo predefiniti su false)
|
||||
- `dm.groupChannels` (allowlist MPIM opzionale)
|
||||
|
||||
Precedenza multi-account:
|
||||
|
||||
- `channels.slack.accounts.default.allowFrom` si applica solo all'account `default`.
|
||||
- Gli account nominati ereditano `channels.slack.allowFrom` quando il loro `allowFrom` non è impostato.
|
||||
- Gli account nominati non ereditano `channels.slack.accounts.default.allowFrom`.
|
||||
- Gli account con nome ereditano `channels.slack.allowFrom` quando il proprio `allowFrom` non è impostato.
|
||||
- Gli account con nome non ereditano `channels.slack.accounts.default.allowFrom`.
|
||||
|
||||
L'abbinamento nei DM usa `openclaw pairing approve slack <code>`.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Criteri canale">
|
||||
`channels.slack.groupPolicy` controlla la gestione dei canali:
|
||||
<Tab title="Criterio del canale">
|
||||
`channels.slack.groupPolicy` controlla la gestione del canale:
|
||||
|
||||
- `open`
|
||||
- `allowlist`
|
||||
@ -306,21 +395,21 @@ Le azioni correnti dei messaggi Slack includono `send`, `upload-file`, `download
|
||||
Risoluzione nome/ID:
|
||||
|
||||
- le voci dell'allowlist dei canali e dell'allowlist DM vengono risolte all'avvio quando l'accesso del token lo consente
|
||||
- le voci irrisolte con nome canale vengono mantenute come configurate ma ignorate per l'instradamento per impostazione predefinita
|
||||
- l'autorizzazione in ingresso e l'instradamento del canale usano per impostazione predefinita prima l'ID; la corrispondenza diretta di username/slug richiede `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
- le voci irrisolte del nome canale vengono mantenute come configurate ma ignorate per impostazione predefinita dall'instradamento
|
||||
- l'autorizzazione in ingresso e l'instradamento dei canali sono incentrati sugli ID per impostazione predefinita; la corrispondenza diretta di username/slug richiede `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Menzioni e utenti del canale">
|
||||
I messaggi del canale sono soggetti a gate per menzione per impostazione predefinita.
|
||||
I messaggi del canale sono vincolati alle menzioni per impostazione predefinita.
|
||||
|
||||
Sorgenti di menzione:
|
||||
Fonti di menzione:
|
||||
|
||||
- menzione esplicita dell'app (`<@botId>`)
|
||||
- pattern regex di menzione (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
|
||||
- comportamento implicito del thread di risposta al bot
|
||||
- comportamento implicito di risposta nel thread al bot
|
||||
|
||||
Controlli per canale (`channels.slack.channels.<id>`; i nomi solo tramite risoluzione all'avvio o `dangerouslyAllowNameMatching`):
|
||||
Controlli per canale (`channels.slack.channels.<id>`; nomi solo tramite risoluzione all'avvio o `dangerouslyAllowNameMatching`):
|
||||
|
||||
- `requireMention`
|
||||
- `users` (allowlist)
|
||||
@ -328,26 +417,26 @@ Le azioni correnti dei messaggi Slack includono `send`, `upload-file`, `download
|
||||
- `skills`
|
||||
- `systemPrompt`
|
||||
- `tools`, `toolsBySender`
|
||||
- formato della chiave `toolsBySender`: `id:`, `e164:`, `username:`, `name:` o wildcard `"*"`
|
||||
- formato della chiave `toolsBySender`: `id:`, `e164:`, `username:`, `name:` oppure wildcard `"*"`
|
||||
(le chiavi legacy senza prefisso continuano a essere mappate solo a `id:`)
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Thread, sessioni e tag di risposta
|
||||
## Threading, sessioni e tag di risposta
|
||||
|
||||
- I DM vengono instradati come `direct`; i canali come `channel`; gli MPIM come `group`.
|
||||
- Con il valore predefinito `session.dmScope=main`, i DM di Slack confluiscono nella sessione principale dell'agente.
|
||||
- Sessioni dei canali: `agent:<agentId>:slack:channel:<channelId>`.
|
||||
- Le risposte nei thread possono creare suffissi di sessione thread (`:thread:<threadTs>`) quando applicabile.
|
||||
- `channels.slack.thread.historyScope` è `thread` per impostazione predefinita; `thread.inheritParent` è `false` per impostazione predefinita.
|
||||
- `channels.slack.thread.initialHistoryLimit` controlla quanti messaggi esistenti del thread vengono recuperati all'avvio di una nuova sessione thread (predefinito `20`; imposta `0` per disabilitare).
|
||||
- I DM sono instradati come `direct`; i canali come `channel`; gli MPIM come `group`.
|
||||
- Con `session.dmScope=main` predefinito, i DM di Slack confluiscono nella sessione principale dell'agente.
|
||||
- Sessioni canale: `agent:<agentId>:slack:channel:<channelId>`.
|
||||
- Le risposte nei thread possono creare suffissi di sessione del thread (`:thread:<threadTs>`) quando applicabile.
|
||||
- Il valore predefinito di `channels.slack.thread.historyScope` è `thread`; il valore predefinito di `thread.inheritParent` è `false`.
|
||||
- `channels.slack.thread.initialHistoryLimit` controlla quanti messaggi esistenti del thread vengono recuperati quando inizia una nuova sessione thread (predefinito `20`; imposta `0` per disabilitare).
|
||||
|
||||
Controlli del threading delle risposte:
|
||||
Controlli di threading delle risposte:
|
||||
|
||||
- `channels.slack.replyToMode`: `off|first|all|batched` (predefinito `off`)
|
||||
- `channels.slack.replyToModeByChatType`: per `direct|group|channel`
|
||||
- fallback legacy per le chat dirette: `channels.slack.dm.replyToMode`
|
||||
- fallback legacy per chat dirette: `channels.slack.dm.replyToMode`
|
||||
|
||||
Sono supportati tag di risposta manuali:
|
||||
|
||||
@ -356,9 +445,9 @@ Sono supportati tag di risposta manuali:
|
||||
|
||||
Nota: `replyToMode="off"` disabilita **tutto** il threading delle risposte in Slack, inclusi i tag espliciti `[[reply_to_*]]`. Questo differisce da Telegram, dove i tag espliciti vengono comunque rispettati in modalità `"off"`. La differenza riflette i modelli di threading delle piattaforme: i thread di Slack nascondono i messaggi dal canale, mentre le risposte di Telegram restano visibili nel flusso principale della chat.
|
||||
|
||||
## Reazioni di ack
|
||||
## Reazioni di conferma
|
||||
|
||||
`ackReaction` invia un'emoji di conferma mentre OpenClaw elabora un messaggio in ingresso.
|
||||
`ackReaction` invia un'emoji di conferma mentre OpenClaw sta elaborando un messaggio in ingresso.
|
||||
|
||||
Ordine di risoluzione:
|
||||
|
||||
@ -374,20 +463,20 @@ Note:
|
||||
|
||||
## Streaming del testo
|
||||
|
||||
`channels.slack.streaming` controlla il comportamento dell'anteprima live:
|
||||
`channels.slack.streaming` controlla il comportamento di anteprima in tempo reale:
|
||||
|
||||
- `off`: disabilita lo streaming dell'anteprima live.
|
||||
- `off`: disabilita lo streaming di anteprima in tempo reale.
|
||||
- `partial` (predefinito): sostituisce il testo di anteprima con l'ultimo output parziale.
|
||||
- `block`: aggiunge aggiornamenti di anteprima in blocchi.
|
||||
- `progress`: mostra il testo di stato dell'avanzamento durante la generazione, quindi invia il testo finale.
|
||||
- `block`: aggiunge aggiornamenti di anteprima a blocchi.
|
||||
- `progress`: mostra testo di stato dell'avanzamento durante la generazione, poi invia il testo finale.
|
||||
|
||||
`channels.slack.nativeStreaming` controlla lo streaming di testo nativo di Slack quando `streaming` è `partial` (predefinito: `true`).
|
||||
`channels.slack.nativeStreaming` controlla lo streaming nativo del testo Slack quando `streaming` è `partial` (predefinito: `true`).
|
||||
|
||||
- Per visualizzare lo streaming di testo nativo deve essere disponibile un thread di risposta. La selezione del thread continua comunque a seguire `replyToMode`. Senza di esso, viene usata la normale anteprima bozza.
|
||||
- I contenuti multimediali e i payload non testuali usano come fallback la consegna normale.
|
||||
- Se lo streaming fallisce a metà risposta, OpenClaw usa come fallback la consegna normale per i payload rimanenti.
|
||||
- Deve essere disponibile un thread di risposta perché lo streaming nativo del testo venga visualizzato. La selezione del thread continua comunque a seguire `replyToMode`. Senza thread, viene usata la normale anteprima bozza.
|
||||
- I contenuti multimediali e i payload non testuali tornano alla consegna normale.
|
||||
- Se lo streaming fallisce a metà risposta, OpenClaw torna alla consegna normale per i payload rimanenti.
|
||||
|
||||
Usa l'anteprima bozza invece dello streaming di testo nativo di Slack:
|
||||
Usa l'anteprima bozza invece dello streaming nativo del testo Slack:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -402,12 +491,12 @@ Usa l'anteprima bozza invece dello streaming di testo nativo di Slack:
|
||||
|
||||
Chiavi legacy:
|
||||
|
||||
- `channels.slack.streamMode` (`replace | status_final | append`) viene migrato automaticamente a `channels.slack.streaming`.
|
||||
- il booleano `channels.slack.streaming` viene migrato automaticamente a `channels.slack.nativeStreaming`.
|
||||
- `channels.slack.streamMode` (`replace | status_final | append`) viene migrato automaticamente in `channels.slack.streaming`.
|
||||
- il booleano `channels.slack.streaming` viene migrato automaticamente in `channels.slack.nativeStreaming`.
|
||||
|
||||
## Fallback della reazione di digitazione
|
||||
|
||||
`typingReaction` aggiunge una reazione temporanea al messaggio Slack in ingresso mentre OpenClaw elabora una risposta, quindi la rimuove quando l'esecuzione termina. Questo è particolarmente utile al di fuori delle risposte nei thread, che usano un indicatore di stato predefinito "is typing...".
|
||||
`typingReaction` aggiunge una reazione temporanea al messaggio Slack in ingresso mentre OpenClaw elabora una risposta, poi la rimuove al termine dell'esecuzione. È particolarmente utile al di fuori delle risposte nei thread, che usano un indicatore di stato predefinito "sta scrivendo...".
|
||||
|
||||
Ordine di risoluzione:
|
||||
|
||||
@ -419,20 +508,19 @@ Note:
|
||||
- Slack si aspetta shortcode (ad esempio `"hourglass_flowing_sand"`).
|
||||
- La reazione è best-effort e la pulizia viene tentata automaticamente dopo il completamento della risposta o del percorso di errore.
|
||||
|
||||
## Media, suddivisione e consegna
|
||||
## Media, suddivisione in blocchi e consegna
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Allegati in ingresso">
|
||||
Gli allegati di file Slack vengono scaricati da URL private ospitate da Slack (flusso di richiesta autenticato tramite token) e scritti nello store multimediale quando il recupero riesce e i limiti di dimensione lo consentono.
|
||||
|
||||
Il limite dimensionale di runtime per l'ingresso è per impostazione predefinita `20MB`, salvo override con `channels.slack.mediaMaxMb`.
|
||||
Gli allegati file di Slack vengono scaricati da URL privati ospitati da Slack (flusso di richiesta autenticato tramite token) e scritti nel media store quando il recupero riesce e i limiti di dimensione lo consentono.
|
||||
|
||||
Il limite dimensionale di runtime in ingresso è predefinito su `20MB`, salvo override tramite `channels.slack.mediaMaxMb`.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Testo e file in uscita">
|
||||
- i blocchi di testo usano `channels.slack.textChunkLimit` (predefinito 4000)
|
||||
- `channels.slack.chunkMode="newline"` abilita la suddivisione con priorità ai paragrafi
|
||||
- gli invii di file usano le API di upload di Slack e possono includere risposte nei thread (`thread_ts`)
|
||||
- `channels.slack.chunkMode="newline"` abilita la suddivisione prima per paragrafo
|
||||
- gli invii di file usano le API di caricamento Slack e possono includere risposte nei thread (`thread_ts`)
|
||||
- il limite dei media in uscita segue `channels.slack.mediaMaxMb` quando configurato; altrimenti gli invii del canale usano i valori predefiniti per tipo MIME dalla pipeline media
|
||||
</Accordion>
|
||||
|
||||
@ -442,24 +530,23 @@ Note:
|
||||
- `user:<id>` per i DM
|
||||
- `channel:<id>` per i canali
|
||||
|
||||
I DM di Slack vengono aperti tramite le API di conversazione di Slack quando si invia a target utente.
|
||||
|
||||
I DM di Slack vengono aperti tramite le API di conversazione di Slack quando si invia verso target utente.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Comandi e comportamento slash
|
||||
|
||||
- La modalità automatica dei comandi nativi è **off** per Slack (`commands.native: "auto"` non abilita i comandi nativi di Slack).
|
||||
- Abilita gli handler dei comandi nativi di Slack con `channels.slack.commands.native: true` (o globale `commands.native: true`).
|
||||
- Quando i comandi nativi sono abilitati, registra in Slack i comandi slash corrispondenti (nomi `/<command>`), con un'eccezione:
|
||||
- La modalità automatica dei comandi nativi è **disattivata** per Slack (`commands.native: "auto"` non abilita i comandi nativi di Slack).
|
||||
- Abilita i gestori dei comandi nativi di Slack con `channels.slack.commands.native: true` (o con `commands.native: true` globale).
|
||||
- Quando i comandi nativi sono abilitati, registra in Slack i corrispondenti slash command (nomi `/<command>`), con un'eccezione:
|
||||
- registra `/agentstatus` per il comando status (Slack riserva `/status`)
|
||||
- Se i comandi nativi non sono abilitati, puoi eseguire un singolo comando slash configurato tramite `channels.slack.slashCommand`.
|
||||
- I menu nativi degli argomenti ora adattano la loro strategia di rendering:
|
||||
- fino a 5 opzioni: blocchi pulsante
|
||||
- Se i comandi nativi non sono abilitati, puoi eseguire un singolo slash command configurato tramite `channels.slack.slashCommand`.
|
||||
- I menu argomenti nativi ora adattano la loro strategia di rendering:
|
||||
- fino a 5 opzioni: blocchi con pulsanti
|
||||
- 6-100 opzioni: menu di selezione statico
|
||||
- più di 100 opzioni: selezione esterna con filtraggio asincrono delle opzioni quando sono disponibili gli handler delle opzioni di interattività
|
||||
- se i valori delle opzioni codificati superano i limiti di Slack, il flusso usa come fallback i pulsanti
|
||||
- Per payload di opzioni lunghi, i menu degli argomenti dei comandi slash usano una finestra di conferma prima di inviare un valore selezionato.
|
||||
- più di 100 opzioni: selezione esterna con filtro asincrono delle opzioni quando sono disponibili i gestori delle opzioni di interattività
|
||||
- se i valori delle opzioni codificati superano i limiti di Slack, il flusso torna ai pulsanti
|
||||
- Per payload di opzioni lunghi, i menu degli argomenti dei comandi slash usano una finestra di conferma prima di inviare il valore selezionato.
|
||||
|
||||
Impostazioni predefinite del comando slash:
|
||||
|
||||
@ -472,11 +559,11 @@ Le sessioni slash usano chiavi isolate:
|
||||
|
||||
- `agent:<agentId>:slack:slash:<userId>`
|
||||
|
||||
e continuano comunque a instradare l'esecuzione del comando rispetto alla sessione della conversazione di destinazione (`CommandTargetSessionKey`).
|
||||
e continuano comunque a instradare l'esecuzione del comando verso la sessione della conversazione di destinazione (`CommandTargetSessionKey`).
|
||||
|
||||
## Risposte interattive
|
||||
|
||||
Slack può renderizzare controlli di risposta interattivi creati dall'agente, ma questa funzionalità è disabilitata per impostazione predefinita.
|
||||
Slack può visualizzare controlli di risposta interattivi creati dall'agente, ma questa funzionalità è disabilitata per impostazione predefinita.
|
||||
|
||||
Abilitala globalmente:
|
||||
|
||||
@ -519,27 +606,27 @@ Queste direttive vengono compilate in Slack Block Kit e instradano clic o selezi
|
||||
|
||||
Note:
|
||||
|
||||
- Si tratta di UI specifica di Slack. Gli altri canali non traducono le direttive Slack Block Kit nei propri sistemi di pulsanti.
|
||||
- I valori dei callback interattivi sono token opachi generati da OpenClaw, non valori grezzi creati dall'agente.
|
||||
- Se i blocchi interattivi generati superano i limiti di Slack Block Kit, OpenClaw usa come fallback la risposta di testo originale invece di inviare un payload blocks non valido.
|
||||
- Questa è un'interfaccia specifica di Slack. Gli altri canali non traducono le direttive Slack Block Kit nei propri sistemi di pulsanti.
|
||||
- I valori di callback interattivi sono token opachi generati da OpenClaw, non valori grezzi creati dall'agente.
|
||||
- Se i blocchi interattivi generati superano i limiti di Slack Block Kit, OpenClaw torna alla risposta testuale originale invece di inviare un payload blocks non valido.
|
||||
|
||||
## Approvazioni exec in Slack
|
||||
|
||||
Slack può fungere da client di approvazione nativo con pulsanti interattivi e interazioni, invece di usare come fallback la Web UI o il terminale.
|
||||
Slack può agire come client di approvazione nativo con pulsanti e interazioni interattive, invece di usare come fallback la Web UI o il terminale.
|
||||
|
||||
- Le approvazioni exec usano `channels.slack.execApprovals.*` per l'instradamento nativo di DM/canale.
|
||||
- Le approvazioni dei plugin possono comunque risolversi attraverso la stessa superficie nativa di pulsanti Slack quando la richiesta arriva già in Slack e il tipo di id approvazione è `plugin:`.
|
||||
- L'autorizzazione dell'approvatore continua a essere applicata: solo gli utenti identificati come approvatori possono approvare o negare richieste tramite Slack.
|
||||
- Le approvazioni exec usano `channels.slack.execApprovals.*` per l'instradamento nativo di DM/canali.
|
||||
- Le approvazioni dei plugin possono comunque risolversi attraverso la stessa interfaccia nativa a pulsanti di Slack quando la richiesta arriva già in Slack e il tipo di id approvazione è `plugin:`.
|
||||
- L'autorizzazione degli approvatori continua a essere applicata: solo gli utenti identificati come approvatori possono approvare o negare richieste tramite Slack.
|
||||
|
||||
Questo usa la stessa superficie condivisa dei pulsanti di approvazione degli altri canali. Quando `interactivity` è abilitato nelle impostazioni della tua app Slack, i prompt di approvazione vengono renderizzati come pulsanti Block Kit direttamente nella conversazione.
|
||||
Quando questi pulsanti sono presenti, rappresentano l'UX di approvazione primaria; OpenClaw
|
||||
Questo usa la stessa interfaccia condivisa a pulsanti di approvazione degli altri canali. Quando `interactivity` è abilitato nelle impostazioni della tua app Slack, i prompt di approvazione vengono visualizzati come pulsanti Block Kit direttamente nella conversazione.
|
||||
Quando questi pulsanti sono presenti, rappresentano l'esperienza utente primaria per l'approvazione; OpenClaw
|
||||
dovrebbe includere un comando manuale `/approve` solo quando il risultato dello strumento indica che le
|
||||
approvazioni in chat non sono disponibili o che l'approvazione manuale è l'unico percorso.
|
||||
|
||||
Percorso di configurazione:
|
||||
|
||||
- `channels.slack.execApprovals.enabled`
|
||||
- `channels.slack.execApprovals.approvers` (facoltativo; usa come fallback `commands.ownerAllowFrom` quando possibile)
|
||||
- `channels.slack.execApprovals.approvers` (opzionale; usa come fallback `commands.ownerAllowFrom` quando possibile)
|
||||
- `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, predefinito: `dm`)
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
@ -547,7 +634,7 @@ Slack abilita automaticamente le approvazioni exec native quando `enabled` non
|
||||
approvatore. Imposta `enabled: false` per disabilitare esplicitamente Slack come client di approvazione nativo.
|
||||
Imposta `enabled: true` per forzare l'attivazione delle approvazioni native quando gli approvatori vengono risolti.
|
||||
|
||||
Comportamento predefinito senza una configurazione esplicita delle approvazioni exec Slack:
|
||||
Comportamento predefinito senza configurazione esplicita delle approvazioni exec Slack:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -557,8 +644,8 @@ Comportamento predefinito senza una configurazione esplicita delle approvazioni
|
||||
}
|
||||
```
|
||||
|
||||
La configurazione nativa esplicita di Slack è necessaria solo quando vuoi sovrascrivere gli approvatori, aggiungere filtri o
|
||||
attivare la consegna nella chat di origine:
|
||||
La configurazione esplicita nativa Slack è necessaria solo quando vuoi sovrascrivere gli approvatori, aggiungere filtri o
|
||||
scegliere la consegna nella chat di origine:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -574,36 +661,36 @@ attivare la consegna nella chat di origine:
|
||||
}
|
||||
```
|
||||
|
||||
L'inoltro condiviso `approvals.exec` è separato. Usalo solo quando i prompt di approvazione exec devono anche
|
||||
essere instradati verso altre chat o target espliciti fuori banda. Anche l'inoltro condiviso `approvals.plugin` è
|
||||
L'inoltro condiviso `approvals.exec` è separato. Usalo solo quando i prompt di approvazione exec devono essere instradati anche
|
||||
ad altre chat o a target espliciti fuori banda. Anche l'inoltro condiviso `approvals.plugin` è
|
||||
separato; i pulsanti nativi di Slack possono comunque risolvere le approvazioni dei plugin quando tali richieste arrivano già
|
||||
in Slack.
|
||||
|
||||
Anche `/approve` nella stessa chat funziona nei canali e DM Slack che già supportano i comandi. Vedi [Approvazioni exec](/it/tools/exec-approvals) per il modello completo di inoltro delle approvazioni.
|
||||
Anche `/approve` nella stessa chat funziona nei canali e nei DM di Slack che supportano già i comandi. Vedi [Approvazioni exec](/it/tools/exec-approvals) per il modello completo di inoltro delle approvazioni.
|
||||
|
||||
## Eventi e comportamento operativo
|
||||
|
||||
- Le modifiche/eliminazioni dei messaggi e le trasmissioni del thread vengono mappate in eventi di sistema.
|
||||
- Gli eventi di aggiunta/rimozione di reazioni vengono mappati in eventi di sistema.
|
||||
- Gli eventi di ingresso/uscita membro, canale creato/rinominato e aggiunta/rimozione pin vengono mappati in eventi di sistema.
|
||||
- Le modifiche/eliminazioni dei messaggi e le trasmissioni dei thread vengono mappate in eventi di sistema.
|
||||
- Gli eventi di aggiunta/rimozione di reazione vengono mappati in eventi di sistema.
|
||||
- Gli eventi di ingresso/uscita dei membri, creazione/rinomina del canale e aggiunta/rimozione dei pin vengono mappati in eventi di sistema.
|
||||
- `channel_id_changed` può migrare le chiavi di configurazione del canale quando `configWrites` è abilitato.
|
||||
- I metadati topic/purpose del canale sono trattati come contesto non attendibile e possono essere iniettati nel contesto di instradamento.
|
||||
- Il messaggio iniziale del thread e il seeding iniziale del contesto della cronologia del thread vengono filtrati dalle allowlist mittente configurate quando applicabile.
|
||||
- Le azioni block e le interazioni modal emettono eventi di sistema strutturati `Slack interaction: ...` con campi payload dettagliati:
|
||||
- azioni block: valori selezionati, etichette, valori picker e metadati `workflow_*`
|
||||
- eventi modal `view_submission` e `view_closed` con metadati del canale instradato e input del modulo
|
||||
- I metadati di topic/purpose del canale sono trattati come contesto non attendibile e possono essere inseriti nel contesto di instradamento.
|
||||
- Il messaggio iniziale del thread e il seeding iniziale del contesto della cronologia del thread vengono filtrati dalle allowlist configurate dei mittenti quando applicabile.
|
||||
- Le azioni sui blocchi e le interazioni modali emettono eventi di sistema strutturati `Slack interaction: ...` con campi payload completi:
|
||||
- azioni sui blocchi: valori selezionati, etichette, valori picker e metadati `workflow_*`
|
||||
- eventi modali `view_submission` e `view_closed` con metadati del canale instradati e input del modulo
|
||||
|
||||
## Puntatori al riferimento di configurazione
|
||||
## Riferimenti alla configurazione
|
||||
|
||||
Riferimento principale:
|
||||
|
||||
- [Riferimento di configurazione - Slack](/it/gateway/configuration-reference#slack)
|
||||
|
||||
Campi Slack ad alto segnale:
|
||||
Campi Slack ad alto valore informativo:
|
||||
- modalità/autenticazione: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
|
||||
- accesso DM: `dm.enabled`, `dmPolicy`, `allowFrom` (legacy: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels`
|
||||
- interruttore di compatibilità: `dangerouslyAllowNameMatching` (break-glass; tienilo disattivato salvo necessità)
|
||||
- accesso canale: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
|
||||
- interruttore di compatibilità: `dangerouslyAllowNameMatching` (di emergenza; lascialo disattivato salvo necessità)
|
||||
- accesso ai canali: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
|
||||
- threading/cronologia: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
|
||||
- consegna: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `nativeStreaming`
|
||||
- operazioni/funzionalità: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
|
||||
@ -615,7 +702,7 @@ Riferimento principale:
|
||||
Controlla, in ordine:
|
||||
|
||||
- `groupPolicy`
|
||||
- allowlist canali (`channels.slack.channels`)
|
||||
- allowlist dei canali (`channels.slack.channels`)
|
||||
- `requireMention`
|
||||
- allowlist `users` per canale
|
||||
|
||||
@ -642,8 +729,8 @@ openclaw pairing list slack
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="La modalità socket non si connette">
|
||||
Convalida bot + app token e l'abilitazione di Socket Mode nelle impostazioni dell'app Slack.
|
||||
<Accordion title="La modalità Socket non si connette">
|
||||
Convalida i token bot + app e l'abilitazione di Socket Mode nelle impostazioni dell'app Slack.
|
||||
|
||||
Se `openclaw channels status --probe --json` mostra `botTokenStatus` o
|
||||
`appTokenStatus: "configured_unavailable"`, l'account Slack è
|
||||
@ -657,22 +744,22 @@ openclaw pairing list slack
|
||||
|
||||
- signing secret
|
||||
- percorso webhook
|
||||
- URL di richiesta Slack (Events + Interactivity + Slash Commands)
|
||||
- URL di richiesta Slack (Eventi + Interattività + Slash Commands)
|
||||
- `webhookPath` univoco per account HTTP
|
||||
|
||||
Se `signingSecretStatus: "configured_unavailable"` appare nelle
|
||||
panoramiche dell'account, l'account HTTP è configurato ma il runtime corrente non è riuscito
|
||||
a risolvere il signing secret supportato da SecretRef.
|
||||
Se `signingSecretStatus: "configured_unavailable"` appare nelle istantanee
|
||||
dell'account, l'account HTTP è configurato ma il runtime corrente non è riuscito a
|
||||
risolvere il signing secret supportato da SecretRef.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="I comandi nativi/slash non si attivano">
|
||||
Verifica se intendevi usare:
|
||||
Verifica se intendevi:
|
||||
|
||||
- modalità comandi nativi (`channels.slack.commands.native: true`) con comandi slash corrispondenti registrati in Slack
|
||||
- oppure modalità comando slash singolo (`channels.slack.slashCommand.enabled: true`)
|
||||
- modalità comando nativa (`channels.slack.commands.native: true`) con i corrispondenti slash command registrati in Slack
|
||||
- oppure modalità singolo slash command (`channels.slack.slashCommand.enabled: true`)
|
||||
|
||||
Controlla anche `commands.useAccessGroups` e le allowlist di canale/utente.
|
||||
Controlla anche `commands.useAccessGroups` e le allowlist di canali/utenti.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -682,7 +769,7 @@ openclaw pairing list slack
|
||||
- [Abbinamento](/it/channels/pairing)
|
||||
- [Gruppi](/it/channels/groups)
|
||||
- [Sicurezza](/it/gateway/security)
|
||||
- [Instradamento del canale](/it/channels/channel-routing)
|
||||
- [Instradamento dei canali](/it/channels/channel-routing)
|
||||
- [Risoluzione dei problemi](/it/channels/troubleshooting)
|
||||
- [Configurazione](/it/gateway/configuration)
|
||||
- [Comandi slash](/it/tools/slash-commands)
|
||||
|
||||
@ -1,116 +1,116 @@
|
||||
---
|
||||
read_when:
|
||||
- Vuoi che la promozione della memoria venga eseguita automaticamente
|
||||
- Vuoi capire cosa fa ogni fase del dreaming
|
||||
- Vuoi ottimizzare il consolidamento senza inquinare `MEMORY.md`
|
||||
summary: Consolidamento della memoria in background con fasi light, deep e REM più un Dream Diary
|
||||
title: Dreaming (sperimentale)
|
||||
- Vuoi capire cosa fa ogni fase del sogno
|
||||
- Vuoi regolare il consolidamento senza inquinare `MEMORY.md`
|
||||
summary: Consolidamento della memoria in background con fasi leggere, profonde e REM, più un Diario dei sogni
|
||||
title: Sognare (sperimentale)
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:06:15Z"
|
||||
generated_at: "2026-04-06T08:15:04Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f27da718176bebf59fe8a80fddd4fb5b6d814ac5647f6c1e8344bcfb328db9de
|
||||
source_hash: 36c4b1e70801d662090dc8ce20608c2f141c23cd7ce53c54e3dcf332c801fd4e
|
||||
source_path: concepts/dreaming.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Dreaming (sperimentale)
|
||||
# Sognare (sperimentale)
|
||||
|
||||
Dreaming è il sistema di consolidamento della memoria in background in `memory-core`.
|
||||
Aiuta OpenClaw a spostare segnali forti a breve termine nella memoria durevole, mantenendo
|
||||
Il sogno è il sistema di consolidamento della memoria in background in `memory-core`.
|
||||
Aiuta OpenClaw a spostare segnali forti a breve termine nella memoria duratura, mantenendo
|
||||
il processo spiegabile e verificabile.
|
||||
|
||||
Dreaming è **opt-in** ed è disabilitato per impostazione predefinita.
|
||||
Il sogno è **facoltativo** ed è disabilitato per impostazione predefinita.
|
||||
|
||||
## Cosa scrive dreaming
|
||||
## Cosa scrive il sogno
|
||||
|
||||
Dreaming mantiene due tipi di output:
|
||||
Il sogno mantiene due tipi di output:
|
||||
|
||||
- **Stato macchina** in `memory/.dreams/` (recall store, segnali di fase, checkpoint di ingestione, lock).
|
||||
- **Output leggibile dall'uomo** in `DREAMS.md` (o nell'esistente `dreams.md`) e file di report di fase facoltativi in `memory/dreaming/<phase>/YYYY-MM-DD.md`.
|
||||
- **Stato macchina** in `memory/.dreams/` (archivio di richiamo, segnali di fase, checkpoint di ingestione, lock).
|
||||
- **Output leggibile dagli esseri umani** in `DREAMS.md` (o `dreams.md` esistente) e file di report di fase facoltativi in `memory/dreaming/<phase>/YYYY-MM-DD.md`.
|
||||
|
||||
La promozione a lungo termine continua a scrivere solo in `MEMORY.md`.
|
||||
|
||||
## Modello a fasi
|
||||
## Modello di fase
|
||||
|
||||
Dreaming usa tre fasi cooperative:
|
||||
Il sogno usa tre fasi cooperative:
|
||||
|
||||
| Fase | Scopo | Scrittura persistente |
|
||||
| ----- | ----------------------------------------- | --------------------- |
|
||||
| Light | Ordina e prepara il materiale recente a breve termine | No |
|
||||
| Deep | Valuta e promuove i candidati durevoli | Sì (`MEMORY.md`) |
|
||||
| REM | Riflette su temi e idee ricorrenti | No |
|
||||
| Fase | Scopo | Scrittura duratura |
|
||||
| ----- | ----------------------------------------- | ------------------ |
|
||||
| Leggera | Ordinare e preparare il materiale recente a breve termine | No |
|
||||
| Profonda | Valutare e promuovere i candidati duraturi | Sì (`MEMORY.md`) |
|
||||
| REM | Riflettere su temi e idee ricorrenti | No |
|
||||
|
||||
Queste fasi sono dettagli interni di implementazione, non "modalità"
|
||||
separate configurate dall'utente.
|
||||
separate configurabili dall'utente.
|
||||
|
||||
### Fase light
|
||||
### Fase leggera
|
||||
|
||||
La fase light acquisisce segnali recenti di memoria giornaliera e tracce di recall, li deduplica
|
||||
e prepara le righe candidate.
|
||||
La fase leggera acquisisce segnali recenti della memoria giornaliera e tracce di richiamo, li deduplica
|
||||
e prepara righe candidate.
|
||||
|
||||
- Legge dallo stato di recall a breve termine e dai file recenti della memoria giornaliera.
|
||||
- Scrive un blocco gestito `## Light Sleep` quando l'archiviazione include output inline.
|
||||
- Registra segnali di rinforzo per il successivo ranking deep.
|
||||
- Legge dallo stato di richiamo a breve termine e dai file recenti della memoria giornaliera.
|
||||
- Scrive un blocco gestito `## Sonno leggero` quando l'archiviazione include output inline.
|
||||
- Registra segnali di rinforzo per la successiva classificazione profonda.
|
||||
- Non scrive mai in `MEMORY.md`.
|
||||
|
||||
### Fase deep
|
||||
### Fase profonda
|
||||
|
||||
La fase deep decide cosa diventa memoria a lungo termine.
|
||||
La fase profonda decide cosa diventa memoria a lungo termine.
|
||||
|
||||
- Classifica i candidati usando punteggio ponderato e soglie di accesso.
|
||||
- Classifica i candidati usando punteggi ponderati e soglie di filtro.
|
||||
- Richiede il superamento di `minScore`, `minRecallCount` e `minUniqueQueries`.
|
||||
- Reidrata gli snippet dai file giornalieri live prima della scrittura, quindi gli snippet obsoleti/eliminati vengono saltati.
|
||||
- Reidrata gli snippet dai file giornalieri attivi prima di scrivere, quindi gli snippet obsoleti o eliminati vengono saltati.
|
||||
- Aggiunge le voci promosse a `MEMORY.md`.
|
||||
- Scrive un riepilogo `## Deep Sleep` in `DREAMS.md` e facoltativamente scrive `memory/dreaming/deep/YYYY-MM-DD.md`.
|
||||
- Scrive un riepilogo `## Sonno profondo` in `DREAMS.md` e facoltativamente scrive `memory/dreaming/deep/YYYY-MM-DD.md`.
|
||||
|
||||
### Fase REM
|
||||
|
||||
La fase REM estrae pattern e segnali riflessivi.
|
||||
La fase REM estrae schemi e segnali riflessivi.
|
||||
|
||||
- Costruisce riepiloghi di temi e riflessioni a partire da tracce recenti a breve termine.
|
||||
- Scrive un blocco gestito `## REM Sleep` quando l'archiviazione include output inline.
|
||||
- Registra segnali di rinforzo REM usati dal ranking deep.
|
||||
- Costruisce riepiloghi di temi e riflessioni dalle recenti tracce a breve termine.
|
||||
- Scrive un blocco gestito `## Sonno REM` quando l'archiviazione include output inline.
|
||||
- Registra segnali di rinforzo REM usati dalla classificazione profonda.
|
||||
- Non scrive mai in `MEMORY.md`.
|
||||
|
||||
## Dream Diary
|
||||
## Diario dei sogni
|
||||
|
||||
Dreaming mantiene anche un **Dream Diary** narrativo in `DREAMS.md`.
|
||||
Il sogno mantiene anche un **Diario dei sogni** narrativo in `DREAMS.md`.
|
||||
Dopo che ogni fase ha accumulato materiale sufficiente, `memory-core` esegue un turno
|
||||
di subagent in background best-effort (usando il modello runtime predefinito) e aggiunge una breve voce del diario.
|
||||
in background best-effort del sottoagente (usando il modello runtime predefinito) e aggiunge una breve voce di diario.
|
||||
|
||||
Questo diario è destinato alla lettura umana nell'interfaccia Dreams, non è una fonte di promozione.
|
||||
Questo diario è pensato per la lettura umana nell'interfaccia Dreams, non è una fonte di promozione.
|
||||
|
||||
## Segnali di ranking deep
|
||||
## Segnali di classificazione profonda
|
||||
|
||||
Il ranking deep usa sei segnali base ponderati più il rinforzo di fase:
|
||||
La classificazione profonda usa sei segnali di base ponderati più il rinforzo di fase:
|
||||
|
||||
| Segnale | Peso | Descrizione |
|
||||
| ------------------- | ---- | ------------------------------------------------- |
|
||||
| Frequenza | 0.24 | Quanti segnali a breve termine ha accumulato la voce |
|
||||
| Rilevanza | 0.30 | Qualità media di recupero per la voce |
|
||||
| Diversità delle query | 0.15 | Contesti distinti query/giorno che l'hanno fatta emergere |
|
||||
| Recenza | 0.15 | Punteggio di freschezza con decadimento temporale |
|
||||
| Consolidamento | 0.10 | Forza di ricorrenza su più giorni |
|
||||
| Ricchezza concettuale | 0.06 | Densità di tag concettuali da snippet/percorso |
|
||||
| Segnale | Peso | Descrizione |
|
||||
| ------------------- | ------ | ------------------------------------------------- |
|
||||
| Frequenza | 0.24 | Quanti segnali a breve termine ha accumulato la voce |
|
||||
| Rilevanza | 0.30 | Qualità media di recupero per la voce |
|
||||
| Diversità delle query | 0.15 | Contesti distinti di query/giorno in cui è emersa |
|
||||
| Recenza | 0.15 | Punteggio di freschezza con decadimento temporale |
|
||||
| Consolidamento | 0.10 | Forza di ricorrenza su più giorni |
|
||||
| Ricchezza concettuale | 0.06 | Densità dei tag concettuali da snippet/percorso |
|
||||
|
||||
I riscontri delle fasi light e REM aggiungono un piccolo incremento con decadimento della recenza da
|
||||
I riscontri delle fasi leggera e REM aggiungono un piccolo incremento con decadimento di recenza da
|
||||
`memory/.dreams/phase-signals.json`.
|
||||
|
||||
## Pianificazione
|
||||
|
||||
Quando è abilitato, `memory-core` gestisce automaticamente un job cron per una
|
||||
scansione completa del dreaming. Ogni scansione esegue le fasi in ordine: light -> REM -> deep.
|
||||
Quando è abilitato, `memory-core` gestisce automaticamente un job cron per un ciclo
|
||||
completo di sogno. Ogni ciclo esegue le fasi in ordine: leggera -> REM -> profonda.
|
||||
|
||||
Comportamento predefinito della cadenza:
|
||||
Comportamento predefinito della frequenza:
|
||||
|
||||
| Impostazione | Predefinito |
|
||||
| Impostazione | Predefinito |
|
||||
| -------------------- | ----------- |
|
||||
| `dreaming.frequency` | `0 3 * * *` |
|
||||
|
||||
## Avvio rapido
|
||||
|
||||
Abilitare dreaming:
|
||||
Abilita il sogno:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -128,7 +128,7 @@ Abilitare dreaming:
|
||||
}
|
||||
```
|
||||
|
||||
Abilitare dreaming con una cadenza di scansione personalizzata:
|
||||
Abilita il sogno con una frequenza di ciclo personalizzata:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -157,7 +157,7 @@ Abilitare dreaming con una cadenza di scansione personalizzata:
|
||||
/dreaming help
|
||||
```
|
||||
|
||||
## Workflow CLI
|
||||
## Flusso di lavoro CLI
|
||||
|
||||
Usa la promozione CLI per l'anteprima o l'applicazione manuale:
|
||||
|
||||
@ -168,20 +168,35 @@ openclaw memory promote --limit 5
|
||||
openclaw memory status --deep
|
||||
```
|
||||
|
||||
`memory promote` manuale usa per impostazione predefinita le soglie della fase deep, salvo override
|
||||
tramite flag CLI.
|
||||
Il comando manuale `memory promote` usa per impostazione predefinita le soglie della fase profonda, salvo override
|
||||
tramite flag della CLI.
|
||||
|
||||
Spiega perché un candidato specifico verrebbe o non verrebbe promosso:
|
||||
|
||||
```bash
|
||||
openclaw memory promote-explain "router vlan"
|
||||
openclaw memory promote-explain "router vlan" --json
|
||||
```
|
||||
|
||||
Visualizza in anteprima riflessioni REM, verità candidate e output della promozione profonda senza
|
||||
scrivere nulla:
|
||||
|
||||
```bash
|
||||
openclaw memory rem-harness
|
||||
openclaw memory rem-harness --json
|
||||
```
|
||||
|
||||
## Valori predefiniti principali
|
||||
|
||||
Tutte le impostazioni si trovano in `plugins.entries.memory-core.config.dreaming`.
|
||||
|
||||
| Chiave | Predefinito |
|
||||
| Chiave | Predefinito |
|
||||
| ----------- | ----------- |
|
||||
| `enabled` | `false` |
|
||||
| `frequency` | `0 3 * * *` |
|
||||
|
||||
La policy delle fasi, le soglie e il comportamento di archiviazione sono dettagli interni di implementazione
|
||||
(non configurazione esposta all'utente).
|
||||
La policy di fase, le soglie e il comportamento di archiviazione sono dettagli interni di implementazione
|
||||
(non configurazione visibile all'utente).
|
||||
|
||||
Vedi [Riferimento della configurazione della memoria](/it/reference/memory-config#dreaming-experimental)
|
||||
per l'elenco completo delle chiavi.
|
||||
@ -190,15 +205,15 @@ per l'elenco completo delle chiavi.
|
||||
|
||||
Quando è abilitata, la scheda **Dreams** del Gateway mostra:
|
||||
|
||||
- stato corrente di abilitazione di dreaming
|
||||
- stato a livello di fase e presenza della scansione gestita
|
||||
- stato attuale di abilitazione del sogno
|
||||
- stato a livello di fase e presenza del ciclo gestito
|
||||
- conteggi di breve termine, lungo termine e promossi oggi
|
||||
- orario della prossima esecuzione pianificata
|
||||
- un lettore Dream Diary espandibile basato su `doctor.memory.dreamDiary`
|
||||
- un lettore espandibile del Diario dei sogni basato su `doctor.memory.dreamDiary`
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Memory](/it/concepts/memory)
|
||||
- [Memory Search](/it/concepts/memory-search)
|
||||
- [memory CLI](/cli/memory)
|
||||
- [Memoria](/it/concepts/memory)
|
||||
- [Ricerca nella memoria](/it/concepts/memory-search)
|
||||
- [CLI memory](/cli/memory)
|
||||
- [Riferimento della configurazione della memoria](/it/reference/memory-config)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -3,79 +3,81 @@ read_when:
|
||||
- Vedi l'avviso OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED
|
||||
- Vedi l'avviso OPENCLAW_EXTENSION_API_DEPRECATED
|
||||
- Stai aggiornando un plugin alla moderna architettura dei plugin
|
||||
- Mantieni un plugin OpenClaw esterno
|
||||
- Mantieni un plugin esterno di OpenClaw
|
||||
sidebarTitle: Migrate to SDK
|
||||
summary: Migra dal layer legacy di retrocompatibilità al moderno Plugin SDK
|
||||
summary: Migra dal livello legacy di retrocompatibilità al moderno Plugin SDK
|
||||
title: Migrazione del Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:10:03Z"
|
||||
generated_at: "2026-04-06T08:16:01Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b71ce69b30c3bb02da1b263b1d11dc3214deae5f6fc708515e23b5a1c7bb7c8f
|
||||
source_hash: 94f12d1376edd8184714cc4dbea4a88fa8ed652f65e9365ede6176f3bf441b33
|
||||
source_path: plugins/sdk-migration.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Migrazione del Plugin SDK
|
||||
|
||||
OpenClaw è passato da un ampio layer di retrocompatibilità a una moderna
|
||||
architettura dei plugin con importazioni mirate e documentate. Se il tuo plugin è stato creato prima
|
||||
della nuova architettura, questa guida ti aiuta a migrare.
|
||||
OpenClaw è passato da un ampio livello di retrocompatibilità a una moderna
|
||||
architettura dei plugin con importazioni mirate e documentate. Se il tuo plugin
|
||||
è stato creato prima della nuova architettura, questa guida ti aiuterà nella
|
||||
migrazione.
|
||||
|
||||
## Cosa sta cambiando
|
||||
|
||||
Il vecchio sistema di plugin forniva due superfici molto ampie che permettevano ai plugin di importare
|
||||
qualsiasi cosa servisse 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 accesso:
|
||||
|
||||
- **`openclaw/plugin-sdk/compat`** — una singola importazione che riesportava decine di
|
||||
helper. È stata introdotta per mantenere funzionanti i vecchi plugin basati su hook mentre la
|
||||
nuova architettura dei plugin veniva costruita.
|
||||
- **`openclaw/extension-api`** — un bridge che dava ai plugin accesso diretto agli
|
||||
helper lato host come l'embedded agent runner.
|
||||
- **`openclaw/plugin-sdk/compat`** — una singola importazione che riesportava
|
||||
decine di helper. È stata introdotta 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**. Funzionano ancora 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 a runtime,
|
||||
ma i nuovi plugin non devono usarle e i plugin esistenti dovrebbero migrare prima
|
||||
che la prossima major release le rimuova.
|
||||
|
||||
<Warning>
|
||||
Il layer di retrocompatibilità verrà rimosso in una futura major release.
|
||||
I plugin che continuano a importare da queste superfici smetteranno di funzionare quando ciò accadrà.
|
||||
Il livello di retrocompatibilità verrà rimosso in una futura major release.
|
||||
I plugin che importano ancora da queste superfici smetteranno di funzionare quando ciò accadrà.
|
||||
</Warning>
|
||||
|
||||
## Perché questo è cambiato
|
||||
## Perché è cambiato
|
||||
|
||||
Il vecchio approccio causava problemi:
|
||||
|
||||
- **Avvio lento** — importare un helper caricava decine di moduli non correlati
|
||||
- **Dipendenze circolari** — le riesportazioni ampie rendevano facile creare cicli di importazione
|
||||
- **Superficie API poco chiara** — non c'era modo di capire quali esportazioni fossero stabili rispetto a quelle interne
|
||||
- **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 importazione (`openclaw/plugin-sdk/\<subpath\>`)
|
||||
è un modulo piccolo e autosufficiente con uno scopo chiaro e un contratto documentato.
|
||||
|
||||
Sono state rimosse anche le vecchie superfici di comodo dei provider per i canali bundled. Le importazioni
|
||||
Anche le vecchie convenience seam dei provider per i canali bundled non esistono più. Importazioni
|
||||
come `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`,
|
||||
superfici helper con marchio del canale e
|
||||
le helper seam con branding del canale e
|
||||
`openclaw/plugin-sdk/telegram-core` erano scorciatoie private del mono-repo, non
|
||||
contratti plugin stabili. Usa invece sottopercorsi SDK generici e stretti. All'interno del
|
||||
workspace dei plugin bundled, mantieni gli helper di proprietà del provider nel proprio
|
||||
`api.ts` o `runtime-api.ts` di quel plugin.
|
||||
contratti stabili per i plugin. Usa invece i sotto-percorsi SDK generici e mirati. All'interno del
|
||||
workspace dei plugin bundled, mantieni gli helper di proprietà del provider nel file
|
||||
`api.ts` o `runtime-api.ts` del plugin stesso.
|
||||
|
||||
Esempi attuali di provider bundled:
|
||||
|
||||
- Anthropic mantiene gli helper di stream specifici di Claude nella propria superficie `api.ts` /
|
||||
- Anthropic mantiene gli helper di stream specifici per Claude nel proprio `api.ts` /
|
||||
`contract-api.ts`
|
||||
- OpenAI mantiene builder provider, helper per i modelli predefiniti e builder di provider
|
||||
realtime nel proprio `api.ts`
|
||||
- OpenRouter mantiene nel proprio `api.ts` il builder del provider e gli helper di onboarding/configurazione
|
||||
- OpenAI mantiene builder dei provider, helper per i modelli predefiniti e 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 migrare
|
||||
|
||||
<Steps>
|
||||
<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 modalità fail-closed a meno che tu non passi esplicitamente
|
||||
`.cmd`/`.bat` non risolti ora falliscono in modo chiuso, a meno che tu non passi esplicitamente
|
||||
`allowShellFallback: true`.
|
||||
|
||||
```typescript
|
||||
@ -92,7 +94,7 @@ Esempi attuali di provider bundled:
|
||||
```
|
||||
|
||||
Se il tuo chiamante non dipende intenzionalmente dal fallback della shell, non impostare
|
||||
`allowShellFallback` e gestisci invece l'errore lanciato.
|
||||
`allowShellFallback` e gestisci invece l'errore sollevato.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -107,7 +109,7 @@ Esempi attuali di provider bundled:
|
||||
</Step>
|
||||
|
||||
<Step title="Sostituisci con importazioni mirate">
|
||||
Ogni esportazione della vecchia superficie corrisponde a uno specifico percorso di importazione moderno:
|
||||
Ogni export dalla vecchia superficie corrisponde a uno specifico percorso di importazione moderno:
|
||||
|
||||
```typescript
|
||||
// Before (deprecated backwards-compatibility layer)
|
||||
@ -145,11 +147,11 @@ Esempi attuali di provider bundled:
|
||||
| `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
|
||||
| `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
|
||||
| `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
|
||||
| helper dell'archivio sessioni | `api.runtime.agent.session.*` |
|
||||
| helper del session store | `api.runtime.agent.session.*` |
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Compila e testa">
|
||||
<Step title="Compila ed esegui i test">
|
||||
```bash
|
||||
pnpm build
|
||||
pnpm test -- my-plugin/
|
||||
@ -160,158 +162,166 @@ Esempi attuali di provider bundled:
|
||||
## Riferimento dei percorsi di importazione
|
||||
|
||||
<Accordion title="Tabella dei percorsi di importazione comuni">
|
||||
| Percorso di importazione | Scopo | Esportazioni principali |
|
||||
| Percorso di importazione | Scopo | Export chiave |
|
||||
| --- | --- | --- |
|
||||
| `plugin-sdk/plugin-entry` | Helper canonico del punto di ingresso plugin | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | Riesportazione legacy ombrello per definizioni/builder di entry dei canali | `defineChannelPluginEntry`, `createChatChannelPlugin` |
|
||||
| `plugin-sdk/config-schema` | Esportazione dello schema di configurazione root | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | Helper di entry per singolo provider | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/channel-core` | Definizioni e builder focalizzati per le entry dei canali | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/setup` | Helper condivisi del wizard di setup | Prompt di allowlist, builder dello stato di setup |
|
||||
| `plugin-sdk/setup-runtime` | Helper runtime per il setup | Adattatori di patch setup import-safe, helper per note di lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proxy di setup delegati |
|
||||
| `plugin-sdk/setup-adapter-runtime` | Helper per l'adattatore di setup | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | Helper degli strumenti di setup | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | Helper multi-account | Helper per elenco account/config/action-gate |
|
||||
| `plugin-sdk/account-id` | Helper per l'ID account | `DEFAULT_ACCOUNT_ID`, normalizzazione dell'ID account |
|
||||
| `plugin-sdk/account-resolution` | Helper per la lookup degli account | Helper di lookup account + fallback predefinito |
|
||||
| `plugin-sdk/account-helpers` | Helper ristretti per gli account | Helper per elenco account/azioni account |
|
||||
| `plugin-sdk/channel-setup` | Adattatori del wizard di setup | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, più `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/channel-pairing` | Primitive di pairing DM | `createChannelPairingController` |
|
||||
| `plugin-sdk/plugin-entry` | Helper canonico per l'entry del plugin | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | Riesportazione legacy ombrello per definizioni/builder dell'entry del canale | `defineChannelPluginEntry`, `createChatChannelPlugin` |
|
||||
| `plugin-sdk/config-schema` | Export dello schema di configurazione root | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | Helper di entry per 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 della procedura guidata di setup | Prompt allowlist, builder dello stato di setup |
|
||||
| `plugin-sdk/setup-runtime` | Helper runtime per il setup | Adattatori patch di setup sicuri per l'importazione, helper per note di lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, proxy di setup delegati |
|
||||
| `plugin-sdk/setup-adapter-runtime` | Helper per gli adattatori 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/configurazione/azione-gate degli account |
|
||||
| `plugin-sdk/account-id` | Helper per account-id | `DEFAULT_ACCOUNT_ID`, normalizzazione di account-id |
|
||||
| `plugin-sdk/account-resolution` | Helper per la ricerca degli account | Helper per ricerca account + fallback predefinito |
|
||||
| `plugin-sdk/account-helpers` | Helper mirati per gli account | Helper per elenco account/azioni account |
|
||||
| `plugin-sdk/channel-setup` | Adattatori della procedura guidata di setup | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, più `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/channel-pairing` | Primitive di abbinamento DM | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | Wiring di prefisso risposta + digitazione | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | Factory di adattatori config | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | Builder di schema config | Tipi di schema della configurazione del canale |
|
||||
| `plugin-sdk/telegram-command-config` | Helper della configurazione dei comandi Telegram | Normalizzazione del nome del comando, trim della descrizione, validazione di duplicati/conflitti |
|
||||
| `plugin-sdk/channel-config-helpers` | Factory degli adattatori di configurazione | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | Builder dello schema di configurazione | Tipi di schema di configurazione del canale |
|
||||
| `plugin-sdk/telegram-command-config` | Helper di configurazione dei comandi Telegram | Normalizzazione dei nomi dei comandi, trimming delle descrizioni, validazione di duplicati/conflitti |
|
||||
| `plugin-sdk/channel-policy` | Risoluzione delle policy gruppo/DM | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | Tracciamento dello stato dell'account | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | Helper per l'envelope inbound | Helper condivisi per route + builder dell'envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Helper per le risposte inbound | Helper condivisi per record-and-dispatch |
|
||||
| `plugin-sdk/messaging-targets` | Parsing dei target di messaggistica | Helper per parsing/matching dei target |
|
||||
| `plugin-sdk/outbound-media` | Helper per i media outbound | Caricamento condiviso dei media outbound |
|
||||
| `plugin-sdk/outbound-runtime` | Helper runtime outbound | Helper delegati per identità/send outbound |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Helper per i thread binding | Lifecycle dei thread binding e helper degli adattatori |
|
||||
| `plugin-sdk/agent-media-payload` | Helper legacy per il payload media | Builder del payload media agente per layout di campi legacy |
|
||||
| `plugin-sdk/channel-runtime` | Shim di compatibilità deprecato | Solo utility runtime legacy del canale |
|
||||
| `plugin-sdk/channel-send-result` | Tipi del risultato di invio | Tipi del risultato della risposta |
|
||||
| `plugin-sdk/channel-lifecycle` | Tracciamento dello stato degli account | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | Helper per inbound envelope | Helper condivisi di route + builder di envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Helper per le risposte in ingresso | Helper condivisi di registrazione e dispatch |
|
||||
| `plugin-sdk/messaging-targets` | Parsing dei target di messaggistica | Helper per parsing/corrispondenza dei target |
|
||||
| `plugin-sdk/outbound-media` | Helper per media in uscita | Caricamento condiviso dei media in uscita |
|
||||
| `plugin-sdk/outbound-runtime` | Helper runtime in uscita | Helper per identità in uscita/delegati di invio |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Helper per thread-binding | Ciclo di vita dei thread-binding e helper degli adattatori |
|
||||
| `plugin-sdk/agent-media-payload` | Helper legacy per media payload | Builder del media payload dell'agente per layout legacy dei campi |
|
||||
| `plugin-sdk/channel-runtime` | Shim di compatibilità deprecato | Solo utility legacy del runtime del canale |
|
||||
| `plugin-sdk/channel-send-result` | Tipi di risultato dell'invio | Tipi di risultato della risposta |
|
||||
| `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 ristretti dell'ambiente runtime | 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 della pipeline hook | Helper condivisi per pipeline di webhook/hook interni |
|
||||
| `plugin-sdk/runtime-env` | Helper mirati per runtime env | Helper per logger/runtime env, timeout, retry e backoff |
|
||||
| `plugin-sdk/plugin-runtime` | Helper runtime condivisi del plugin | Helper per comandi/hook/http/interattività del plugin |
|
||||
| `plugin-sdk/hook-runtime` | Helper della pipeline di hook | Helper condivisi della pipeline di webhook/internal hook |
|
||||
| `plugin-sdk/lazy-runtime` | Helper runtime lazy | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Helper di processo | Helper exec condivisi |
|
||||
| `plugin-sdk/cli-runtime` | Helper runtime CLI | Formattazione dei comandi, attese, helper di versione |
|
||||
| `plugin-sdk/gateway-runtime` | Helper del gateway | Client gateway e helper di patch dello stato dei canali |
|
||||
| `plugin-sdk/process-runtime` | Helper di processo | Helper condivisi di exec |
|
||||
| `plugin-sdk/cli-runtime` | Helper runtime della CLI | Formattazione dei comandi, attese, helper per la versione |
|
||||
| `plugin-sdk/gateway-runtime` | Helper del gateway | Client del gateway e helper patch dello stato dei canali |
|
||||
| `plugin-sdk/config-runtime` | Helper di configurazione | Helper di caricamento/scrittura della configurazione |
|
||||
| `plugin-sdk/telegram-command-config` | Helper dei comandi Telegram | Helper di validazione dei comandi Telegram con fallback stabile quando la superficie contrattuale Telegram bundled non è disponibile |
|
||||
| `plugin-sdk/approval-runtime` | Helper per i prompt di approvazione | Payload di approvazione exec/plugin, helper di capability/profilo di approvazione, helper runtime/instradamento di approvazione nativa |
|
||||
| `plugin-sdk/approval-auth-runtime` | Helper auth delle approvazioni | Risoluzione dell'approvatore, auth per azione nella stessa chat |
|
||||
| `plugin-sdk/approval-client-runtime` | Helper client delle approvazioni | Helper nativi di profilo/filtro per approvazione exec |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Helper delivery delle approvazioni | Adattatori di capability/delivery per approvazione nativa |
|
||||
| `plugin-sdk/approval-native-runtime` | Helper per il target di approvazione | Helper di binding target/account per approvazione nativa |
|
||||
| `plugin-sdk/approval-reply-runtime` | Helper per le risposte di approvazione | Helper di payload di risposta per approvazione exec/plugin |
|
||||
| `plugin-sdk/security-runtime` | Helper di sicurezza | Helper condivisi per trust, controllo DM, contenuti esterni e raccolta dei segreti |
|
||||
| `plugin-sdk/ssrf-policy` | Helper della policy SSRF | Helper di allowlist host e policy di rete privata |
|
||||
| `plugin-sdk/ssrf-runtime` | Helper runtime SSRF | Pinned-dispatcher, fetch protetto, helper di policy SSRF |
|
||||
| `plugin-sdk/collection-runtime` | Helper di cache limitata | `pruneMapToMaxSize` |
|
||||
| `plugin-sdk/diagnostic-runtime` | Helper di gating diagnostico | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
|
||||
| `plugin-sdk/error-runtime` | Helper di formattazione degli errori | `formatUncaughtError`, `isApprovalNotFoundError`, helper del grafo degli errori |
|
||||
| `plugin-sdk/fetch-runtime` | Helper di fetch/proxy incapsulati | `resolveFetch`, helper proxy |
|
||||
| `plugin-sdk/telegram-command-config` | Helper per comandi Telegram | Helper di validazione dei comandi Telegram con fallback stabile 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 nativi di routing/runtime dell'approvazione |
|
||||
| `plugin-sdk/approval-auth-runtime` | Helper auth per approvazione | Risoluzione degli approvatori, auth di azione nella stessa chat |
|
||||
| `plugin-sdk/approval-client-runtime` | Helper client per approvazione | Helper per profilo/filtro di approvazione nativa di exec |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Helper di delivery per approvazione | Adattatori nativi di capability/delivery dell'approvazione |
|
||||
| `plugin-sdk/approval-native-runtime` | Helper target per approvazione | Helper nativi per target/account binding dell'approvazione |
|
||||
| `plugin-sdk/approval-reply-runtime` | Helper per risposte di approvazione | Helper per payload di risposta di approvazione exec/plugin |
|
||||
| `plugin-sdk/security-runtime` | Helper di sicurezza | Helper condivisi per trust, gating DM, contenuti esterni e raccolta dei segreti |
|
||||
| `plugin-sdk/ssrf-policy` | Helper per policy SSRF | Helper per allowlist host e policy di rete privata |
|
||||
| `plugin-sdk/ssrf-runtime` | Helper runtime SSRF | Pinned-dispatcher, fetch protetto, helper per policy SSRF |
|
||||
| `plugin-sdk/collection-runtime` | Helper per cache bounded | `pruneMapToMaxSize` |
|
||||
| `plugin-sdk/diagnostic-runtime` | Helper per gating diagnostico | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
|
||||
| `plugin-sdk/error-runtime` | Helper di formattazione degli errori | `formatUncaughtError`, `isApprovalNotFoundError`, helper per grafi di errore |
|
||||
| `plugin-sdk/fetch-runtime` | Helper per fetch/proxy wrapped | `resolveFetch`, helper proxy |
|
||||
| `plugin-sdk/host-runtime` | Helper di normalizzazione host | `normalizeHostname`, `normalizeScpRemoteHost` |
|
||||
| `plugin-sdk/retry-runtime` | Helper di retry | `RetryConfig`, `retryAsync`, esecutori di policy |
|
||||
| `plugin-sdk/allow-from` | Formattazione della allowlist | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/allowlist-resolution` | Mappatura dell'input della allowlist | `mapAllowlistResolutionInputs` |
|
||||
| `plugin-sdk/command-auth` | Gating dei comandi e helper della superficie dei comandi | `resolveControlCommandGate`, helper di autorizzazione del mittente, helper del registro comandi |
|
||||
| `plugin-sdk/secret-input` | Parsing dell'input dei segreti | Helper per l'input dei segreti |
|
||||
| `plugin-sdk/webhook-ingress` | Helper per richieste webhook | Utility per i target webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Helper delle guardie per il body del webhook | Helper per lettura/limite del body della richiesta |
|
||||
| `plugin-sdk/reply-runtime` | Runtime condiviso della risposta | Dispatch inbound, heartbeat, pianificatore di risposte, chunking |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Helper ristretti per il dispatch delle risposte | Helper di finalize + provider dispatch |
|
||||
| `plugin-sdk/reply-history` | Helper della cronologia delle risposte | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | Pianificazione del riferimento della risposta | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Helper dei chunk di risposta | Helper di chunking del testo/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Helper dell'archivio sessioni | Helper per percorso dell'archivio + updated-at |
|
||||
| `plugin-sdk/state-paths` | Helper dei percorsi di stato | Helper per directory di stato e OAuth |
|
||||
| `plugin-sdk/routing` | Helper di routing/chiave di sessione | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helper di normalizzazione della chiave di sessione |
|
||||
| `plugin-sdk/status-helpers` | Helper dello stato del canale | Builder del riepilogo di stato canale/account, valori predefiniti dello stato runtime, helper per i metadati dei problemi |
|
||||
| `plugin-sdk/target-resolver-runtime` | Helper del risolutore del target | Helper condivisi del risolutore del target |
|
||||
| `plugin-sdk/string-normalization-runtime` | Helper di normalizzazione delle 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/allow-from` | Formattazione allowlist | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/allowlist-resolution` | Mappatura input dell'allowlist | `mapAllowlistResolutionInputs` |
|
||||
| `plugin-sdk/command-auth` | Gating dei comandi e helper per la superficie dei comandi | `resolveControlCommandGate`, helper di autorizzazione del mittente, helper del registro comandi |
|
||||
| `plugin-sdk/secret-input` | Parsing dell'input segreto | Helper per input segreti |
|
||||
| `plugin-sdk/webhook-ingress` | Helper per richieste webhook | Utility per target webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Helper guard per il body dei webhook | Helper per lettura/limite del body della richiesta |
|
||||
| `plugin-sdk/reply-runtime` | Runtime condiviso delle risposte | Dispatch in ingresso, heartbeat, pianificatore delle risposte, chunking |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Helper mirati per 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 delle risposte | 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 i percorsi di stato | Helper per directory di stato e OAuth |
|
||||
| `plugin-sdk/routing` | Helper per routing/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helper di normalizzazione 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 delle stringhe | Helper per normalizzazione di slug/stringhe |
|
||||
| `plugin-sdk/request-url` | Helper per URL della richiesta | Estrae URL stringa da input simili a richieste |
|
||||
| `plugin-sdk/run-command` | Helper per comandi temporizzati | Runner di comandi temporizzati con stdout/stderr normalizzati |
|
||||
| `plugin-sdk/param-readers` | Lettori di parametri | Lettori comuni di parametri tool/CLI |
|
||||
| `plugin-sdk/tool-send` | Estrazione del send del tool | Estrai campi target di invio canonici dagli argomenti del tool |
|
||||
| `plugin-sdk/temp-path` | Helper per i percorsi temporanei | Helper condivisi per i percorsi di download temporaneo |
|
||||
| `plugin-sdk/logging-core` | Helper di logging | Logger del sottosistema e helper di redazione |
|
||||
| `plugin-sdk/markdown-table-runtime` | Helper per tabelle Markdown | Helper per la modalità tabelle Markdown |
|
||||
| `plugin-sdk/reply-payload` | Tipi della risposta del messaggio | Tipi del payload della risposta |
|
||||
| `plugin-sdk/provider-setup` | Helper curati di setup del provider locale/self-hosted | Helper di discovery/configurazione del provider self-hosted |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Helper focalizzati di setup del provider self-hosted compatibile con OpenAI | Gli stessi helper di discovery/configurazione del provider self-hosted |
|
||||
| `plugin-sdk/provider-auth-runtime` | Helper runtime auth del provider | Helper runtime per la risoluzione della chiave API |
|
||||
| `plugin-sdk/provider-auth-api-key` | Helper di setup della chiave API del provider | Helper di onboarding/scrittura profilo per chiave API |
|
||||
| `plugin-sdk/provider-auth-result` | Helper del risultato auth del provider | Builder standard del risultato auth OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Helper di login interattivo del provider | Helper condivisi di login interattivo |
|
||||
| `plugin-sdk/provider-env-vars` | Helper per env var del provider | Helper di lookup delle env var auth del provider |
|
||||
| `plugin-sdk/provider-model-shared` | Helper condivisi per modello/replay del provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder condivisi della policy di replay, helper degli endpoint del provider e helper di normalizzazione dell'ID del modello |
|
||||
| `plugin-sdk/provider-catalog-shared` | Helper condivisi per il catalogo del provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/param-readers` | Lettori di parametri | Lettori comuni di parametri di tool/CLI |
|
||||
| `plugin-sdk/tool-send` | Estrazione dell'invio del tool | Estrae i 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 markdown table | Helper per modalità markdown table |
|
||||
| `plugin-sdk/reply-payload` | Tipi di risposta del messaggio | Tipi di payload della risposta |
|
||||
| `plugin-sdk/provider-setup` | Helper curati per setup di provider locali/self-hosted | Helper per scoperta/configurazione di provider self-hosted |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Helper mirati per setup di provider self-hosted compatibili con OpenAI | Gli stessi helper per scoperta/configurazione di provider self-hosted |
|
||||
| `plugin-sdk/provider-auth-runtime` | Helper auth runtime del provider | Helper runtime per risoluzione delle API key |
|
||||
| `plugin-sdk/provider-auth-api-key` | Helper per setup delle API key del provider | Helper per onboarding/scrittura del profilo delle API key |
|
||||
| `plugin-sdk/provider-auth-result` | Helper per auth-result del provider | Builder standard di auth-result 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 auth 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 normalizzazione degli id modello |
|
||||
| `plugin-sdk/provider-catalog-shared` | Helper condivisi per cataloghi provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-onboard` | Patch di onboarding del provider | Helper di configurazione dell'onboarding |
|
||||
| `plugin-sdk/provider-http` | Helper HTTP del provider | Helper generici per capability HTTP/endpoint del provider |
|
||||
| `plugin-sdk/provider-web-fetch` | Helper web-fetch del provider | Helper di registrazione/cache del provider web-fetch |
|
||||
| `plugin-sdk/provider-web-search` | Helper web-search del provider | Helper di registrazione/cache/configurazione del provider web-search |
|
||||
| `plugin-sdk/provider-tools` | Helper di compatibilità tool/schema del provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pulizia dello schema Gemini + diagnostica, e helper di compatibilità xAI come `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-http` | Helper HTTP del provider | Helper generici per HTTP/capability degli endpoint del provider |
|
||||
| `plugin-sdk/provider-web-fetch` | Helper per web-fetch del provider | Helper per registrazione/cache del provider web-fetch |
|
||||
| `plugin-sdk/provider-web-search` | Helper per web-search del provider | Helper per registrazione/cache/configurazione del provider web-search |
|
||||
| `plugin-sdk/provider-tools` | Helper di compatibilità tool/schema del provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pulizia dello schema Gemini + diagnostica 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 degli stream del provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, tipi di wrapper degli 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 di fetch/transform/store dei media più builder del payload media |
|
||||
| `plugin-sdk/media-understanding` | Helper di media-understanding | Tipi del provider di media understanding più esportazioni helper lato provider per immagini/audio |
|
||||
| `plugin-sdk/text-runtime` | Helper testuali condivisi | Rimozione del testo visibile all'assistant, helper di render/chunking/tabella markdown, helper di redazione, helper di directive-tag, utility di testo sicuro e helper correlati di testo/logging |
|
||||
| `plugin-sdk/text-chunking` | Helper di chunking del testo | Helper di chunking del testo outbound |
|
||||
| `plugin-sdk/speech` | Helper speech | Tipi del provider speech più helper lato provider per direttive, registro e validazione |
|
||||
| `plugin-sdk/speech-core` | Core speech condiviso | Tipi del provider speech, registro, direttive, 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 generazione immagini | Tipi per generazione immagini, failover, auth e helper del registro |
|
||||
| `plugin-sdk/music-generation` | Helper per generazione musicale | Tipi provider/richiesta/risultato per generazione musicale |
|
||||
| `plugin-sdk/music-generation-core` | Core condiviso per generazione musicale | Tipi per generazione musicale, helper di failover, lookup provider e parsing dei riferimenti modello |
|
||||
| `plugin-sdk/video-generation` | Helper per generazione video | Tipi provider/richiesta/risultato per generazione video |
|
||||
| `plugin-sdk/video-generation-core` | Core condiviso per generazione video | Tipi per generazione video, helper di failover, lookup provider e parsing dei riferimenti modello |
|
||||
| `plugin-sdk/interactive-runtime` | Helper di risposta interattiva | Normalizzazione/riduzione del payload di risposta interattiva |
|
||||
| `plugin-sdk/channel-config-primitives` | Primitive della configurazione del canale | Primitive ristrette dello schema config del canale |
|
||||
| `plugin-sdk/provider-stream` | Helper wrapper degli stream del provider | `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/keyed-async-queue` | Coda async ordinata | `KeyedAsyncQueue` |
|
||||
| `plugin-sdk/media-runtime` | Helper media condivisi | Helper per fetch/trasformazione/storage dei media più builder di media payload |
|
||||
| `plugin-sdk/media-generation-runtime` | Helper condivisi per media-generation | Helper condivisi per failover, selezione dei candidati e messaggi di modello mancante per generazione di immagini/video/musica |
|
||||
| `plugin-sdk/media-understanding` | Helper per media-understanding | Tipi di provider media-understanding più export di helper immagine/audio lato provider |
|
||||
| `plugin-sdk/text-runtime` | Helper di testo condivisi | Rimozione del testo visibile all'assistente, helper di rendering/chunking/tabelle markdown, helper di redazione, helper directive-tag, utility di testo sicuro e relativi helper di testo/logging |
|
||||
| `plugin-sdk/text-chunking` | Helper per chunking del testo | Helper per chunking del testo in uscita |
|
||||
| `plugin-sdk/speech` | Helper speech | Tipi di provider speech più export di helper lato provider per direttive, registry e validazione |
|
||||
| `plugin-sdk/speech-core` | Core speech condiviso | Tipi di provider speech, registry, direttive, normalizzazione |
|
||||
| `plugin-sdk/realtime-transcription` | Helper per trascrizione realtime | Tipi di provider e helper del registry |
|
||||
| `plugin-sdk/realtime-voice` | Helper per voce realtime | Tipi di provider e helper del registry |
|
||||
| `plugin-sdk/image-generation-core` | Core condiviso per image-generation | Tipi, failover, auth e helper del registry per image-generation |
|
||||
| `plugin-sdk/music-generation` | Helper per music-generation | Tipi di provider/richiesta/risultato per music-generation |
|
||||
| `plugin-sdk/music-generation-core` | Core condiviso per music-generation | Tipi di music-generation, helper di failover, lookup dei provider e parsing di model-ref |
|
||||
| `plugin-sdk/video-generation` | Helper per video-generation | Tipi di provider/richiesta/risultato per video-generation |
|
||||
| `plugin-sdk/video-generation-core` | Core condiviso per video-generation | Tipi di video-generation, helper di failover, lookup dei 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 dello schema di configurazione del canale |
|
||||
| `plugin-sdk/channel-config-writes` | Helper di scrittura della configurazione del canale | Helper di autorizzazione per la scrittura della configurazione del canale |
|
||||
| `plugin-sdk/channel-plugin-common` | Prelude condivisa del canale | Esportazioni della prelude condivisa del plugin canale |
|
||||
| `plugin-sdk/channel-status` | Helper dello stato del canale | Helper condivisi per snapshot/riepilogo dello stato del canale |
|
||||
| `plugin-sdk/allowlist-config-edit` | Helper della configurazione allowlist | Helper per modifica/lettura della configurazione allowlist |
|
||||
| `plugin-sdk/group-access` | Helper di accesso al gruppo | Helper condivisi per le decisioni di accesso al gruppo |
|
||||
| `plugin-sdk/direct-dm` | Helper direct-DM | Helper condivisi per auth/guard dei direct-DM |
|
||||
| `plugin-sdk/channel-plugin-common` | Prelude condiviso del canale | Export condivisi del preludio del plugin del canale |
|
||||
| `plugin-sdk/channel-status` | Helper per stato del canale | Helper condivisi per snapshot/riepilogo dello stato del canale |
|
||||
| `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 decisioni di accesso ai gruppi |
|
||||
| `plugin-sdk/direct-dm` | Helper per direct-DM | Helper condivisi per auth/guard di direct-DM |
|
||||
| `plugin-sdk/extension-shared` | Helper condivisi delle estensioni | Primitive helper per canali passivi/stato |
|
||||
| `plugin-sdk/webhook-targets` | Helper per i target webhook | Registro dei target webhook e helper di installazione delle route |
|
||||
| `plugin-sdk/webhook-path` | Helper del percorso webhook | Helper di normalizzazione del percorso webhook |
|
||||
| `plugin-sdk/web-media` | Helper condivisi per i media web | Helper di caricamento dei media remoti/locali |
|
||||
| `plugin-sdk/zod` | Riesportazione Zod | Riesportazione di `zod` per i consumatori del Plugin SDK |
|
||||
| `plugin-sdk/memory-core` | Helper bundled memory-core | Superficie helper di memory manager/config/file/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Facade runtime del motore memory | Facade runtime di indicizzazione/ricerca memory |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Motore foundation host memory | Esportazioni del motore foundation host memory |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Motore embeddings host memory | Esportazioni del motore embeddings host memory |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Motore QMD host memory | Esportazioni del motore QMD host memory |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Motore storage host memory | Esportazioni del motore storage host memory |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Helper multimodali host memory | Helper multimodali host memory |
|
||||
| `plugin-sdk/memory-core-host-query` | Helper query host memory | Helper query host memory |
|
||||
| `plugin-sdk/memory-core-host-secret` | Helper secret host memory | Helper secret host memory |
|
||||
| `plugin-sdk/memory-core-host-status` | Helper stato host memory | Helper stato host memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI host memory | Helper runtime CLI host memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Runtime core host memory | Helper runtime core host memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host memory | Helper file/runtime host memory |
|
||||
| `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 di normalizzazione dei percorsi webhook |
|
||||
| `plugin-sdk/web-media` | Helper web media condivisi | Helper per caricamento di media remoti/locali |
|
||||
| `plugin-sdk/zod` | Riesportazione di zod | Riesporta `zod` per i consumer del Plugin SDK |
|
||||
| `plugin-sdk/memory-core` | Helper bundled 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 host di memoria | Export del motore foundation host di memoria |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Motore embedding host di memoria | Export del motore embedding host di memoria |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Motore QMD host di memoria | Export del motore QMD host di memoria |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Motore storage host di memoria | Export del motore storage host di memoria |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Helper multimodali host di memoria | Helper multimodali host di memoria |
|
||||
| `plugin-sdk/memory-core-host-query` | Helper query host di memoria | Helper query host di memoria |
|
||||
| `plugin-sdk/memory-core-host-secret` | Helper secret host di memoria | Helper secret host di memoria |
|
||||
| `plugin-sdk/memory-core-host-events` | Helper per journal degli eventi host di memoria | Helper per journal degli eventi host di memoria |
|
||||
| `plugin-sdk/memory-core-host-status` | Helper stato host di memoria | Helper stato host di memoria |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI host di memoria | Helper runtime CLI host di memoria |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Runtime core host di memoria | Helper runtime core host di memoria |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host di memoria | Helper file/runtime host di memoria |
|
||||
| `plugin-sdk/memory-host-core` | Alias runtime core host di memoria | Alias vendor-neutral per helper runtime core host di memoria |
|
||||
| `plugin-sdk/memory-host-events` | Alias journal eventi host di memoria | Alias vendor-neutral per helper journal eventi host di memoria |
|
||||
| `plugin-sdk/memory-host-files` | Alias file/runtime host di memoria | Alias vendor-neutral per helper file/runtime host di memoria |
|
||||
| `plugin-sdk/memory-host-markdown` | Helper managed markdown | Helper condivisi managed-markdown per plugin adiacenti alla memoria |
|
||||
| `plugin-sdk/memory-host-search` | Facade di ricerca della memoria attiva | Facade runtime lazy del gestore di ricerca della memoria attiva |
|
||||
| `plugin-sdk/memory-host-status` | Alias stato host di memoria | Alias vendor-neutral per helper stato host di memoria |
|
||||
| `plugin-sdk/memory-lancedb` | Helper bundled memory-lancedb | Superficie helper memory-lancedb |
|
||||
| `plugin-sdk/testing` | Utility di test | Helper e mock di test |
|
||||
</Accordion>
|
||||
|
||||
Questa tabella è intenzionalmente il sottoinsieme comune per la migrazione, non l'intera
|
||||
superficie dell'SDK. L'elenco completo degli oltre 200 entrypoint si trova in
|
||||
superficie dell'SDK. L'elenco completo di oltre 200 entrypoint si trova in
|
||||
`scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
Questo elenco include ancora alcune superfici helper dei plugin bundled come
|
||||
Questo elenco include ancora alcune helper seam dei plugin bundled, come
|
||||
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
|
||||
`plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Restano esportate per
|
||||
manutenzione e compatibilità dei plugin bundled, ma sono intenzionalmente
|
||||
omesse dalla tabella comune di migrazione e non sono la destinazione consigliata per
|
||||
`plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Rimangono esportate per
|
||||
la manutenzione e la compatibilità dei plugin bundled, ma sono intenzionalmente
|
||||
omesse dalla tabella di migrazione comune e non sono il target consigliato per
|
||||
nuovo codice plugin.
|
||||
|
||||
La stessa regola si applica ad altre famiglie di helper bundled come:
|
||||
@ -320,7 +330,7 @@ La stessa regola si applica ad altre famiglie di helper bundled come:
|
||||
- Matrix: `plugin-sdk/matrix*`
|
||||
- LINE: `plugin-sdk/line*`
|
||||
- IRC: `plugin-sdk/irc*`
|
||||
- superfici helper/plugin bundled come `plugin-sdk/googlechat`,
|
||||
- superfici bundled helper/plugin 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`,
|
||||
@ -329,18 +339,18 @@ La stessa regola si applica ad altre famiglie di helper bundled come:
|
||||
`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 ristretta
|
||||
superficie helper dei token `DEFAULT_COPILOT_API_BASE_URL`,
|
||||
`plugin-sdk/github-copilot-token` espone attualmente la superficie mirata degli helper token
|
||||
`DEFAULT_COPILOT_API_BASE_URL`,
|
||||
`deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken`.
|
||||
|
||||
Usa l'importazione più stretta che corrisponde al lavoro da svolgere. Se non riesci a trovare un'esportazione,
|
||||
controlla il sorgente in `src/plugin-sdk/` o chiedi su Discord.
|
||||
Usa l'importazione più mirata che corrisponde al compito. Se non riesci a trovare un export,
|
||||
controlla il codice sorgente in `src/plugin-sdk/` o chiedi su Discord.
|
||||
|
||||
## Timeline di rimozione
|
||||
## Tempistiche di rimozione
|
||||
|
||||
| Quando | Cosa succede |
|
||||
| ---------------------- | ---------------------------------------------------------------------- |
|
||||
| **Adesso** | Le superfici deprecate emettono avvisi a runtime |
|
||||
| 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 smetteranno di funzionare |
|
||||
|
||||
Tutti i plugin core sono già stati migrati. I plugin esterni dovrebbero migrare
|
||||
@ -348,7 +358,7 @@ prima della prossima major release.
|
||||
|
||||
## Sopprimere temporaneamente gli avvisi
|
||||
|
||||
Imposta queste variabili d'ambiente mentre lavori alla migrazione:
|
||||
Imposta queste variabili di ambiente mentre lavori alla migrazione:
|
||||
|
||||
```bash
|
||||
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
|
||||
@ -360,8 +370,8 @@ Questa è una via di fuga temporanea, non una soluzione permanente.
|
||||
## Correlati
|
||||
|
||||
- [Per iniziare](/it/plugins/building-plugins) — crea il tuo primo plugin
|
||||
- [Panoramica SDK](/it/plugins/sdk-overview) — riferimento completo delle importazioni per sottopercorso
|
||||
- [Plugin canale](/it/plugins/sdk-channel-plugins) — creazione di plugin canale
|
||||
- [Plugin provider](/it/plugins/sdk-provider-plugins) — creazione di plugin provider
|
||||
- [Interni dei plugin](/it/plugins/architecture) — approfondimento sull'architettura
|
||||
- [Manifesto plugin](/it/plugins/manifest) — riferimento dello schema del manifesto
|
||||
- [Panoramica dell'SDK](/it/plugins/sdk-overview) — riferimento completo delle importazioni per sottopercorso
|
||||
- [Plugin di canale](/it/plugins/sdk-channel-plugins) — creare plugin di canale
|
||||
- [Plugin provider](/it/plugins/sdk-provider-plugins) — creare plugin provider
|
||||
- [Elementi interni dei plugin](/it/plugins/architecture) — approfondimento sull'architettura
|
||||
- [Manifest del plugin](/it/plugins/manifest) — riferimento dello schema del manifest
|
||||
|
||||
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- Devi sapere da quale sottopercorso SDK importare
|
||||
- Devi sapere da quale sottopercorso dell'SDK importare
|
||||
- Vuoi un riferimento per tutti i metodi di registrazione su OpenClawPluginApi
|
||||
- Stai cercando una specifica esportazione dell'SDK
|
||||
sidebarTitle: SDK Overview
|
||||
summary: Riferimento della mappa di importazione, dell'API di registrazione e dell'architettura SDK
|
||||
title: Panoramica del Plugin SDK
|
||||
summary: Mappa di importazione, riferimento dell'API di registrazione e architettura dell'SDK
|
||||
title: Panoramica dell'SDK plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:10:57Z"
|
||||
generated_at: "2026-04-06T08:16:19Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: d801641f26f39dc21490d2a69a337ff1affb147141360916b8b58a267e9f822a
|
||||
source_hash: acd2887ef52c66b2f234858d812bb04197ecd0bfb3e4f7bf3622f8fdc765acad
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Panoramica del Plugin SDK
|
||||
# Panoramica dell'SDK plugin
|
||||
|
||||
Il plugin SDK è il contratto tipizzato tra plugin e core. Questa pagina è il
|
||||
riferimento per **cosa importare** e **cosa puoi registrare**.
|
||||
L'SDK plugin è il contratto tipizzato tra i plugin e il core. Questa pagina è il
|
||||
riferimento per **cosa importare** e **cosa è possibile registrare**.
|
||||
|
||||
<Tip>
|
||||
**Cerchi una guida pratica?**
|
||||
- Primo plugin? Inizia con [Getting Started](/it/plugins/building-plugins)
|
||||
- Plugin canale? Vedi [Channel Plugins](/it/plugins/sdk-channel-plugins)
|
||||
- Plugin provider? Vedi [Provider Plugins](/it/plugins/sdk-provider-plugins)
|
||||
- Primo plugin? Inizia con [Introduzione](/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)
|
||||
</Tip>
|
||||
|
||||
## Convenzione di importazione
|
||||
@ -37,7 +37,7 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
```
|
||||
|
||||
Ogni sottopercorso è un modulo piccolo e autosufficiente. Questo mantiene
|
||||
l'avvio rapido e previene problemi di dipendenze circolari. Per gli helper di
|
||||
l'avvio rapido e previene i 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 per
|
||||
gli helper condivisi come `buildChannelConfigSchema`.
|
||||
@ -45,26 +45,26 @@ gli helper condivisi come `buildChannelConfigSchema`.
|
||||
Non aggiungere né dipendere da seam di convenienza con nome del provider come
|
||||
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp` o
|
||||
seam helper con branding del canale. I plugin bundled dovrebbero comporre
|
||||
seam di helper a marchio 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 al plugin oppure aggiungere un contratto SDK
|
||||
generico e ristretto quando l'esigenza è davvero cross-channel.
|
||||
generico e ristretto quando l'esigenza è davvero trasversale ai canali.
|
||||
|
||||
La mappa di export generata contiene ancora un piccolo insieme di seam helper di plugin bundled
|
||||
come `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
La mappa di esportazione generata contiene ancora un piccolo insieme di
|
||||
seam helper per plugin inclusi come `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` e `plugin-sdk/matrix*`. Questi
|
||||
sottopercorsi esistono solo per manutenzione e compatibilità dei plugin bundled;
|
||||
sono volutamente omessi dalla tabella comune qui sotto e non sono il percorso di
|
||||
importazione consigliato per nuovi plugin di terze parti.
|
||||
sottopercorsi esistono solo per la manutenzione e la compatibilità dei plugin inclusi;
|
||||
sono intenzionalmente omessi dalla tabella comune qui sotto e non sono il
|
||||
percorso di importazione consigliato per nuovi plugin di terze parti.
|
||||
|
||||
## Riferimento dei sottopercorsi
|
||||
|
||||
I sottopercorsi usati più comunemente, raggruppati per scopo. L'elenco completo generato di
|
||||
oltre 200 sottopercorsi si trova in `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
I sottopercorsi più comunemente 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 bundled compaiono ancora in questo elenco generato.
|
||||
Trattali come superfici di dettaglio implementativo/compatibilità a meno che una pagina della documentazione
|
||||
non ne promuova esplicitamente una come pubblica.
|
||||
I sottopercorsi helper riservati per plugin inclusi compaiono ancora in
|
||||
quell'elenco generato. Trattali come superfici di dettaglio implementativo/compatibilità
|
||||
a meno che una pagina della documentazione non ne promuova esplicitamente uno come pubblico.
|
||||
|
||||
### Entry del plugin
|
||||
|
||||
@ -76,208 +76,216 @@ non ne promuova esplicitamente una come pubblica.
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Sottopercorsi dei canali">
|
||||
<Accordion title="Sottopercorsi del canale">
|
||||
| Sottopercorso | Esportazioni chiave |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/config-schema` | Export dello schema Zod radice di `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, più `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | Helper condivisi per setup wizard, prompt allowlist, builder dello stato di setup |
|
||||
| `plugin-sdk/config-schema` | Esportazione dello schema Zod radice `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, oltre a `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | Helper condivisi per il wizard di configurazione, prompt per allowlist, builder dello stato della 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 config/action-gate multi-account, helper di fallback per account predefinito |
|
||||
| `plugin-sdk/account-core` | Helper di config/action-gate multi-account e helper di fallback per account predefinito |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helper di normalizzazione dell'ID account |
|
||||
| `plugin-sdk/account-resolution` | Ricerca account + helper di fallback al predefinito |
|
||||
| `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 di schema config del canale |
|
||||
| `plugin-sdk/telegram-command-config` | Helper di normalizzazione/validazione dei comandi personalizzati Telegram con fallback al contratto bundled |
|
||||
| `plugin-sdk/channel-config-schema` | Tipi di schema della configurazione del canale |
|
||||
| `plugin-sdk/telegram-command-config` | Helper di normalizzazione/validazione dei comandi personalizzati di Telegram con fallback al contratto incluso |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | Helper condivisi per route inbound + builder dell'envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Helper condivisi per registrazione e dispatch inbound |
|
||||
| `plugin-sdk/messaging-targets` | Helper per parsing/corrispondenza dei target |
|
||||
| `plugin-sdk/outbound-media` | Helper condivisi per il caricamento dei media in uscita |
|
||||
| `plugin-sdk/outbound-runtime` | Helper per identità/delegati di invio in uscita |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Helper per ciclo di vita e adapter dei thread binding |
|
||||
| `plugin-sdk/inbound-envelope` | Helper condivisi di instradamento in ingresso + builder di envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Helper condivisi di registrazione e dispatch in ingresso |
|
||||
| `plugin-sdk/messaging-targets` | Helper di parsing/corrispondenza dei target |
|
||||
| `plugin-sdk/outbound-media` | Helper condivisi di caricamento dei media in uscita |
|
||||
| `plugin-sdk/outbound-runtime` | Helper di delega per identità/invio in uscita |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Helper di lifecycle e adapter per thread-binding |
|
||||
| `plugin-sdk/agent-media-payload` | Builder legacy del payload media dell'agente |
|
||||
| `plugin-sdk/conversation-runtime` | Helper per binding di conversazione/thread, pairing e binding configurati |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Helper per snapshot di config runtime |
|
||||
| `plugin-sdk/runtime-group-policy` | Helper per la risoluzione della group policy runtime |
|
||||
| `plugin-sdk/conversation-runtime` | Helper per binding conversazione/thread, pairing e binding configurato |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Helper per snapshot della config 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 ristrette di schema config del canale |
|
||||
| `plugin-sdk/channel-config-writes` | Helper di autorizzazione alle scritture config del canale |
|
||||
| `plugin-sdk/channel-plugin-common` | Export di preambolo condivisi per i plugin canale |
|
||||
| `plugin-sdk/allowlist-config-edit` | Helper di lettura/modifica config allowlist |
|
||||
| `plugin-sdk/channel-config-primitives` | Primitive ristrette per lo schema di configurazione del canale |
|
||||
| `plugin-sdk/channel-config-writes` | Helper di autorizzazione per la scrittura della configurazione del canale |
|
||||
| `plugin-sdk/channel-plugin-common` | Esportazioni prelude condivise del plugin di canale |
|
||||
| `plugin-sdk/allowlist-config-edit` | Helper di modifica/lettura della configurazione dell'allowlist |
|
||||
| `plugin-sdk/group-access` | Helper condivisi per le decisioni di accesso ai gruppi |
|
||||
| `plugin-sdk/direct-dm` | Helper condivisi di auth/guard per DM diretti |
|
||||
| `plugin-sdk/interactive-runtime` | Helper di normalizzazione/riduzione del payload delle risposte interattive |
|
||||
| `plugin-sdk/channel-inbound` | Helper per debounce, corrispondenza menzioni, envelope |
|
||||
| `plugin-sdk/direct-dm` | Helper condivisi di autenticazione/protezione direct-DM |
|
||||
| `plugin-sdk/interactive-runtime` | Helper di normalizzazione/riduzione del payload di risposta interattiva |
|
||||
| `plugin-sdk/channel-inbound` | Debounce, corrispondenza delle menzioni, helper di envelope |
|
||||
| `plugin-sdk/channel-send-result` | Tipi del risultato di risposta |
|
||||
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
|
||||
| `plugin-sdk/channel-targets` | Helper per parsing/corrispondenza dei target |
|
||||
| `plugin-sdk/channel-targets` | Helper di parsing/corrispondenza dei target |
|
||||
| `plugin-sdk/channel-contract` | Tipi del contratto del canale |
|
||||
| `plugin-sdk/channel-feedback` | Wiring di feedback/reazioni |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Sottopercorsi dei provider">
|
||||
<Accordion title="Sottopercorsi provider">
|
||||
| Sottopercorso | Esportazioni chiave |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/provider-setup` | Helper di setup curati per provider locali/self-hosted |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Helper di setup focalizzati per provider self-hosted compatibili OpenAI |
|
||||
| `plugin-sdk/provider-auth-runtime` | Helper di risoluzione runtime della chiave API per i plugin provider |
|
||||
| `plugin-sdk/provider-setup` | Helper selezionati di configurazione del provider locale/self-hosted |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Helper focalizzati di configurazione del provider self-hosted compatibile con OpenAI |
|
||||
| `plugin-sdk/provider-auth-runtime` | Helper runtime di risoluzione della chiave API per plugin provider |
|
||||
| `plugin-sdk/provider-auth-api-key` | Helper di onboarding/scrittura profilo per chiavi API |
|
||||
| `plugin-sdk/provider-auth-result` | Builder standard del risultato auth OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Helper condivisi di login interattivo per i plugin provider |
|
||||
| `plugin-sdk/provider-env-vars` | Helper di lookup delle variabili env auth dei provider |
|
||||
| `plugin-sdk/provider-auth-result` | Builder standard del risultato di autenticazione OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Helper condivisi di login interattivo per plugin provider |
|
||||
| `plugin-sdk/provider-env-vars` | Helper di ricerca delle variabili d'ambiente di autenticazione del provider |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder condivisi di replay-policy, helper per endpoint provider e helper di normalizzazione model-id come `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, builder condivisi di replay-policy, helper per endpoint provider e helper di normalizzazione dell'ID modello come `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-http` | Helper generici di capacità HTTP/endpoint provider |
|
||||
| `plugin-sdk/provider-web-fetch` | Helper di registrazione/cache per provider web-fetch |
|
||||
| `plugin-sdk/provider-web-search` | Helper di registrazione/cache/config per provider web-search |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, pulizia schema Gemini + diagnostica e helper di compatibilità xAI come `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-http` | Helper generici di capacità HTTP/endpoint del provider |
|
||||
| `plugin-sdk/provider-web-fetch` | Helper di registrazione/cache del provider web-fetch |
|
||||
| `plugin-sdk/provider-web-search` | Helper di registrazione/cache/config 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-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 di patch config per onboarding |
|
||||
| `plugin-sdk/global-singleton` | Helper per singleton/mappe/cache locali al processo |
|
||||
| `plugin-sdk/provider-onboard` | Helper di patch della configurazione di onboarding |
|
||||
| `plugin-sdk/global-singleton` | Helper di singleton/map/cache locali al processo |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Sottopercorsi auth e sicurezza">
|
||||
<Accordion title="Sottopercorsi di autenticazione e sicurezza">
|
||||
| Sottopercorso | Esportazioni chiave |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper per registro comandi, helper di autorizzazione del mittente |
|
||||
| `plugin-sdk/approval-auth-runtime` | Helper per risoluzione degli approvatori e auth delle azioni nella stessa chat |
|
||||
| `plugin-sdk/approval-client-runtime` | Helper per profili/filtri di approvazione exec nativi |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Adapter per capacità/consegna delle approvazioni native |
|
||||
| `plugin-sdk/approval-native-runtime` | Helper per target di approvazione nativa + binding account |
|
||||
| `plugin-sdk/approval-reply-runtime` | Helper per payload di risposta di approvazione exec/plugin |
|
||||
| `plugin-sdk/command-auth-native` | Auth dei comandi nativi + helper per target sessione nativa |
|
||||
| `plugin-sdk/command-detection` | Helper condivisi di rilevamento dei comandi |
|
||||
| `plugin-sdk/command-surface` | Helper per normalizzazione del corpo del comando e command-surface |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper del registro comandi, helper di autorizzazione del mittente |
|
||||
| `plugin-sdk/approval-auth-runtime` | Risoluzione dell'approvatore e helper di action-auth nella stessa chat |
|
||||
| `plugin-sdk/approval-client-runtime` | Helper nativi per profilo/filtro di approvazione exec |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Adapter nativi per capacità/consegna dell'approvazione |
|
||||
| `plugin-sdk/approval-native-runtime` | Helper nativi per target di approvazione + binding account |
|
||||
| `plugin-sdk/approval-reply-runtime` | Helper per il payload di risposta di approvazione exec/plugin |
|
||||
| `plugin-sdk/command-auth-native` | Autenticazione nativa dei comandi + helper nativi per target di sessione |
|
||||
| `plugin-sdk/command-detection` | Helper condivisi per il rilevamento dei comandi |
|
||||
| `plugin-sdk/command-surface` | Normalizzazione del corpo del comando e helper della superficie dei comandi |
|
||||
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/security-runtime` | Helper condivisi per trust, gating DM, contenuti esterni e raccolta segreti |
|
||||
| `plugin-sdk/ssrf-policy` | Helper per policy SSRF con allowlist host e rete privata |
|
||||
| `plugin-sdk/security-runtime` | Helper condivisi per trust, gating DM, contenuto esterno e raccolta di secret |
|
||||
| `plugin-sdk/ssrf-policy` | Helper di policy SSRF per allowlist host e reti private |
|
||||
| `plugin-sdk/ssrf-runtime` | Helper per pinned-dispatcher, fetch protetto da SSRF e policy SSRF |
|
||||
| `plugin-sdk/secret-input` | Helper per parsing dell'input segreto |
|
||||
| `plugin-sdk/webhook-ingress` | Helper per richiesta/target webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Helper per dimensione body richiesta/timeout |
|
||||
| `plugin-sdk/secret-input` | Helper di parsing degli input secret |
|
||||
| `plugin-sdk/webhook-ingress` | Helper per richieste/target webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Helper per dimensione body/timeout della richiesta |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Sottopercorsi runtime e storage">
|
||||
| Sottopercorso | Esportazioni chiave |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/runtime` | Helper ampi per runtime/logging/backup/installazione plugin |
|
||||
| `plugin-sdk/runtime` | Ampi helper di runtime/logging/backup/installazione plugin |
|
||||
| `plugin-sdk/runtime-env` | Helper ristretti per env runtime, logger, timeout, retry e backoff |
|
||||
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/plugin-runtime` | Helper condivisi per comando/hook/http/interattivi dei plugin |
|
||||
| `plugin-sdk/hook-runtime` | Helper condivisi per la pipeline di hook webhook/interni |
|
||||
| `plugin-sdk/plugin-runtime` | Helper condivisi per comandi/hook/http/interattività del plugin |
|
||||
| `plugin-sdk/hook-runtime` | Helper condivisi per la pipeline di webhook/hook interni |
|
||||
| `plugin-sdk/lazy-runtime` | Helper di importazione/binding runtime lazy come `createLazyRuntimeModule`, `createLazyRuntimeMethod` e `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Helper di esecuzione 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 config |
|
||||
| `plugin-sdk/telegram-command-config` | Normalizzazione di nome/descrizione dei comandi Telegram e controlli di duplicati/conflitti, anche quando la superficie di contratto Telegram bundled non è disponibile |
|
||||
| `plugin-sdk/approval-runtime` | Helper per approvazione exec/plugin, builder di approval-capability, helper auth/profilo, helper di routing/runtime nativi |
|
||||
| `plugin-sdk/reply-runtime` | Helper condivisi per runtime inbound/risposta, chunking, dispatch, heartbeat, pianificatore delle risposte |
|
||||
| `plugin-sdk/process-runtime` | Helper di esecuzione dei processi |
|
||||
| `plugin-sdk/cli-runtime` | Helper CLI di formattazione, attesa e versione |
|
||||
| `plugin-sdk/gateway-runtime` | Helper del client gateway e di patch dello stato del canale |
|
||||
| `plugin-sdk/config-runtime` | Helper di caricamento/scrittura della configurazione |
|
||||
| `plugin-sdk/telegram-command-config` | Normalizzazione di nome/descrizione del comando Telegram e controlli di duplicati/conflitti, anche quando la superficie contrattuale Telegram inclusa non è disponibile |
|
||||
| `plugin-sdk/approval-runtime` | Helper di approvazione exec/plugin, builder di capacità di approvazione, helper di autenticazione/profilo, helper nativi di instradamento/runtime |
|
||||
| `plugin-sdk/reply-runtime` | Helper condivisi di runtime inbound/reply, chunking, dispatch, heartbeat, pianificatore di risposte |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Helper ristretti per dispatch/finalizzazione della risposta |
|
||||
| `plugin-sdk/reply-history` | Helper condivisi per la cronologia delle risposte a breve finestra come `buildHistoryContext`, `recordPendingHistoryEntry` e `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Helper ristretti per chunking di testo/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Helper per percorso store sessione + updated-at |
|
||||
| `plugin-sdk/state-paths` | Helper per percorsi state/OAuth dir |
|
||||
| `plugin-sdk/routing` | Helper per route/session-key/account binding come `resolveAgentRoute`, `buildAgentSessionKey` e `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Helper condivisi per riepilogo stato canale/account, valori predefiniti dello stato runtime e metadati dei problemi |
|
||||
| `plugin-sdk/target-resolver-runtime` | Helper condivisi per resolver dei target |
|
||||
| `plugin-sdk/session-store-runtime` | Helper per percorso dello store di sessione + updated-at |
|
||||
| `plugin-sdk/state-paths` | Helper di percorso per directory di stato/OAuth |
|
||||
| `plugin-sdk/routing` | Helper per route/session-key/binding account come `resolveAgentRoute`, `buildAgentSessionKey` e `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Helper condivisi per il riepilogo dello stato di canale/account, valori predefiniti dello stato runtime e helper dei metadati dei problemi |
|
||||
| `plugin-sdk/target-resolver-runtime` | Helper condivisi per la risoluzione dei target |
|
||||
| `plugin-sdk/string-normalization-runtime` | Helper di normalizzazione slug/stringhe |
|
||||
| `plugin-sdk/request-url` | Estrae URL stringa da input simili a fetch/request |
|
||||
| `plugin-sdk/run-command` | Runner di comandi temporizzato con risultati stdout/stderr normalizzati |
|
||||
| `plugin-sdk/param-readers` | Reader comuni dei parametri tool/CLI |
|
||||
| `plugin-sdk/tool-send` | Estrae campi canonicali del target di invio dagli argomenti dello strumento |
|
||||
| `plugin-sdk/request-url` | Estrae URL stringa da input simili a fetch/richiesta |
|
||||
| `plugin-sdk/run-command` | Runner di comandi con timing e risultati stdout/stderr normalizzati |
|
||||
| `plugin-sdk/param-readers` | Lettori comuni di parametri per tool/CLI |
|
||||
| `plugin-sdk/tool-send` | Estrae i campi del target di invio canonico dagli argomenti del tool |
|
||||
| `plugin-sdk/temp-path` | Helper condivisi per percorsi temporanei di download |
|
||||
| `plugin-sdk/logging-core` | Helper per logger del sottosistema e redazione |
|
||||
| `plugin-sdk/logging-core` | Helper di logger del sottosistema e redazione |
|
||||
| `plugin-sdk/markdown-table-runtime` | Helper per la modalità tabella Markdown |
|
||||
| `plugin-sdk/json-store` | Piccoli helper di lettura/scrittura stato JSON |
|
||||
| `plugin-sdk/json-store` | Piccoli helper di lettura/scrittura dello stato JSON |
|
||||
| `plugin-sdk/file-lock` | Helper di file-lock rientrante |
|
||||
| `plugin-sdk/persistent-dedupe` | Helper per cache dedupe persistente su disco |
|
||||
| `plugin-sdk/acp-runtime` | Helper per runtime/sessione ACP e reply-dispatch |
|
||||
| `plugin-sdk/agent-config-primitives` | Primitive ristrette di schema config runtime dell'agente |
|
||||
| `plugin-sdk/boolean-param` | Reader flessibile di parametri booleani |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Helper di risoluzione per matching di nomi pericolosi |
|
||||
| `plugin-sdk/persistent-dedupe` | Helper di cache dedupe persistente su disco |
|
||||
| `plugin-sdk/acp-runtime` | Helper di runtime/sessione ACP e reply-dispatch |
|
||||
| `plugin-sdk/agent-config-primitives` | Primitive ristrette per lo schema di configurazione runtime dell'agente |
|
||||
| `plugin-sdk/boolean-param` | Lettore permissivo di parametri booleani |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Helper di risoluzione per la corrispondenza di nomi pericolosi |
|
||||
| `plugin-sdk/device-bootstrap` | Helper per bootstrap del dispositivo e token di pairing |
|
||||
| `plugin-sdk/extension-shared` | Primitive condivise per canali passivi e helper di stato |
|
||||
| `plugin-sdk/models-provider-runtime` | Helper di risposta del comando `/models`/provider |
|
||||
| `plugin-sdk/skill-commands-runtime` | Helper di elenco dei comandi Skills |
|
||||
| `plugin-sdk/native-command-registry` | Helper per registro/build/serializzazione dei comandi nativi |
|
||||
| `plugin-sdk/models-provider-runtime` | Helper di risposta per comando `/models`/provider |
|
||||
| `plugin-sdk/skill-commands-runtime` | Helper per l'elenco dei comandi di Skills |
|
||||
| `plugin-sdk/native-command-registry` | Helper nativi di registro/build/serializzazione dei comandi |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Helper di rilevamento endpoint Z.AI |
|
||||
| `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 errori, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | Helper per fetch incapsulato, proxy e lookup fissati |
|
||||
| `plugin-sdk/host-runtime` | Helper di normalizzazione per hostname e host SCP |
|
||||
| `plugin-sdk/retry-runtime` | Helper per config retry e runner retry |
|
||||
| `plugin-sdk/agent-runtime` | Helper per agent dir/identity/workspace |
|
||||
| `plugin-sdk/directory-runtime` | Query/dedup delle directory supportata dalla config |
|
||||
| `plugin-sdk/infra-runtime` | Helper di eventi di sistema/heartbeat |
|
||||
| `plugin-sdk/collection-runtime` | Piccoli helper di cache limitata |
|
||||
| `plugin-sdk/diagnostic-runtime` | Helper di 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 incapsulato, proxy e ricerca pinned |
|
||||
| `plugin-sdk/host-runtime` | Helper di normalizzazione hostname e host SCP |
|
||||
| `plugin-sdk/retry-runtime` | Helper di configurazione retry ed esecuzione retry |
|
||||
| `plugin-sdk/agent-runtime` | Helper per directory/identità/workspace dell'agente |
|
||||
| `plugin-sdk/directory-runtime` | Query/dedup di directory basata su config |
|
||||
| `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/transform/store dei media più builder del payload media |
|
||||
| `plugin-sdk/media-understanding` | Tipi del provider media understanding più export helper lato provider per immagini/audio |
|
||||
| `plugin-sdk/text-runtime` | Helper condivisi per testo/markdown/logging come stripping del testo visibile all'assistente, helper di rendering/chunking/tabella markdown, helper di redazione, helper per tag direttiva e utility di testo sicuro |
|
||||
| `plugin-sdk/media-runtime` | Helper condivisi per fetch/transform/store dei media più builder di payload media |
|
||||
| `plugin-sdk/media-generation-runtime` | Helper condivisi per failover della generazione media, selezione candidati e messaggistica per modelli mancanti |
|
||||
| `plugin-sdk/media-understanding` | Tipi provider per media understanding più esportazioni helper orientate al provider per immagini/audio |
|
||||
| `plugin-sdk/text-runtime` | Helper condivisi per testo/markdown/logging come rimozione del testo visibile all'assistente, helper di render/chunking/tabella Markdown, helper di redazione, helper di directive-tag e utility di testo sicuro |
|
||||
| `plugin-sdk/text-chunking` | Helper per chunking del testo in uscita |
|
||||
| `plugin-sdk/speech` | Tipi del provider speech più export helper lato provider per directive, registro e validazione |
|
||||
| `plugin-sdk/speech-core` | Tipi condivisi del provider speech, helper per registro, directive e normalizzazione |
|
||||
| `plugin-sdk/realtime-transcription` | Tipi del provider di trascrizione realtime e helper del registro |
|
||||
| `plugin-sdk/realtime-voice` | Tipi del provider voce realtime e helper del registro |
|
||||
| `plugin-sdk/image-generation` | Tipi del provider per generazione immagini |
|
||||
| `plugin-sdk/image-generation-core` | Tipi condivisi di generazione immagini, helper per failover, auth e registro |
|
||||
| `plugin-sdk/music-generation` | Tipi di provider/richiesta/risultato per generazione musicale |
|
||||
| `plugin-sdk/music-generation-core` | Tipi condivisi di generazione musicale, helper per failover, ricerca provider e parsing model-ref |
|
||||
| `plugin-sdk/video-generation` | Tipi di provider/richiesta/risultato per generazione video |
|
||||
| `plugin-sdk/video-generation-core` | Tipi condivisi di generazione video, helper per failover, ricerca provider e parsing model-ref |
|
||||
| `plugin-sdk/webhook-targets` | Registro dei target webhook e helper per installazione delle route |
|
||||
| `plugin-sdk/speech` | Tipi provider speech più helper orientati al provider per directive, registro e validazione |
|
||||
| `plugin-sdk/speech-core` | Tipi provider speech condivisi, helper di registro, directive e normalizzazione |
|
||||
| `plugin-sdk/realtime-transcription` | Tipi provider di trascrizione realtime e helper di registro |
|
||||
| `plugin-sdk/realtime-voice` | Tipi provider di voce realtime e helper di registro |
|
||||
| `plugin-sdk/image-generation` | Tipi provider di generazione immagini |
|
||||
| `plugin-sdk/image-generation-core` | Tipi condivisi di generazione immagini, helper di failover, autenticazione e registro |
|
||||
| `plugin-sdk/music-generation` | Tipi provider/richiesta/risultato per generazione musicale |
|
||||
| `plugin-sdk/music-generation-core` | Tipi condivisi di generazione musicale, helper di failover, ricerca provider e parsing model-ref |
|
||||
| `plugin-sdk/video-generation` | Tipi provider/richiesta/risultato per generazione video |
|
||||
| `plugin-sdk/video-generation-core` | Tipi condivisi di generazione video, helper di failover, ricerca provider e parsing model-ref |
|
||||
| `plugin-sdk/webhook-targets` | Registro dei target webhook e helper di installazione route |
|
||||
| `plugin-sdk/webhook-path` | Helper di normalizzazione del percorso webhook |
|
||||
| `plugin-sdk/web-media` | Helper condivisi per il caricamento di media remoti/locali |
|
||||
| `plugin-sdk/zod` | `zod` riesportato per i consumer del plugin SDK |
|
||||
| `plugin-sdk/web-media` | Helper condivisi di caricamento media remoti/locali |
|
||||
| `plugin-sdk/zod` | `zod` riesportato per i consumatori dell'SDK plugin |
|
||||
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Sottopercorsi memory">
|
||||
| Sottopercorso | Esportazioni chiave |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/memory-core` | Superficie helper bundled memory-core per helper di manager/config/file/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Facciata runtime per indice/ricerca memory |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Export del motore foundation dell'host memory |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Export del motore embeddings dell'host memory |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Export del motore QMD dell'host memory |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Export del motore storage dell'host memory |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Helper multimodali dell'host memory |
|
||||
| `plugin-sdk/memory-core-host-query` | Helper di query dell'host memory |
|
||||
| `plugin-sdk/memory-core-host-secret` | Helper dei segreti dell'host memory |
|
||||
| `plugin-sdk/memory-core-host-status` | Helper di stato dell'host memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Helper runtime CLI dell'host memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Helper runtime core dell'host memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime dell'host memory |
|
||||
| `plugin-sdk/memory-lancedb` | Superficie helper bundled memory-lancedb |
|
||||
| `plugin-sdk/memory-core` | Superficie helper `memory-core` inclusa per helper di manager/config/file/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Facade runtime di indice/ricerca memory |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Esportazioni del motore foundation host memory |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Esportazioni del motore embedding host memory |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Esportazioni del motore QMD host memory |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Esportazioni del motore storage host memory |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Helper multimodali host memory |
|
||||
| `plugin-sdk/memory-core-host-query` | Helper query host memory |
|
||||
| `plugin-sdk/memory-core-host-secret` | Helper secret host memory |
|
||||
| `plugin-sdk/memory-core-host-events` | Helper journal degli eventi host memory |
|
||||
| `plugin-sdk/memory-core-host-status` | Helper di stato host memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Helper runtime CLI host memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Helper runtime core host memory |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Helper file/runtime host memory |
|
||||
| `plugin-sdk/memory-host-core` | Alias neutrale rispetto al vendor per helper runtime core host memory |
|
||||
| `plugin-sdk/memory-host-events` | Alias neutrale rispetto al vendor per helper journal degli eventi host memory |
|
||||
| `plugin-sdk/memory-host-files` | Alias neutrale rispetto al vendor per helper file/runtime host memory |
|
||||
| `plugin-sdk/memory-host-markdown` | Helper condivisi di markdown gestito per plugin adiacenti a memory |
|
||||
| `plugin-sdk/memory-host-search` | Facade runtime della memory attiva per l'accesso al search-manager |
|
||||
| `plugin-sdk/memory-host-status` | Alias neutrale rispetto al vendor per helper di stato host memory |
|
||||
| `plugin-sdk/memory-lancedb` | Superficie helper `memory-lancedb` inclusa |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Sottopercorsi helper bundled riservati">
|
||||
| Famiglia | Sottopercorsi correnti | Utilizzo previsto |
|
||||
<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 bundled (`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 bundled |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Superficie helper/runtime LINE bundled |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Superficie helper IRC bundled |
|
||||
| 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/compatibilità dei canali bundled |
|
||||
| Helper auth/plugin-specifici | `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 per funzionalità/plugin bundled; `plugin-sdk/github-copilot-token` attualmente esporta `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken` |
|
||||
| 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` rimane 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 per 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 per funzionalità/plugin inclusi; `plugin-sdk/github-copilot-token` esporta attualmente `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` e `resolveCopilotApiToken` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -290,7 +298,7 @@ metodi:
|
||||
|
||||
| Metodo | Cosa registra |
|
||||
| ------------------------------------------------ | -------------------------------- |
|
||||
| `api.registerProvider(...)` | Inferenza testuale (LLM) |
|
||||
| `api.registerProvider(...)` | Inferenza del testo (LLM) |
|
||||
| `api.registerChannel(...)` | Canale di messaggistica |
|
||||
| `api.registerSpeechProvider(...)` | Sintesi text-to-speech / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Trascrizione realtime in streaming |
|
||||
@ -299,42 +307,44 @@ metodi:
|
||||
| `api.registerImageGenerationProvider(...)` | Generazione di immagini |
|
||||
| `api.registerMusicGenerationProvider(...)` | Generazione musicale |
|
||||
| `api.registerVideoGenerationProvider(...)` | Generazione video |
|
||||
| `api.registerWebFetchProvider(...)` | Provider di web fetch / scraping |
|
||||
| `api.registerWebFetchProvider(...)` | Provider di web fetch / scrape |
|
||||
| `api.registerWebSearchProvider(...)` | Ricerca web |
|
||||
|
||||
### Strumenti e comandi
|
||||
### Tool e comandi
|
||||
|
||||
| Metodo | Cosa registra |
|
||||
| ------------------------------- | --------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Strumento dell'agente (obbligatorio o `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Comando personalizzato (bypassa l'LLM) |
|
||||
| Metodo | Cosa registra |
|
||||
| ------------------------------- | -------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Tool dell'agente (obbligatorio o `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Comando personalizzato (bypassa l'LLM) |
|
||||
|
||||
### Infrastruttura
|
||||
|
||||
| Metodo | Cosa registra |
|
||||
| ---------------------------------------------- | --------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Hook evento |
|
||||
| `api.registerHttpRoute(params)` | Endpoint HTTP gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | Metodo RPC gateway |
|
||||
| `api.registerCli(registrar, opts?)` | Sottocomando CLI |
|
||||
| `api.registerService(service)` | Servizio in background |
|
||||
| `api.registerInteractiveHandler(registration)` | Gestore interattivo |
|
||||
| Metodo | Cosa registra |
|
||||
| ---------------------------------------------- | -------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Hook di 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)` | Handler interattivo |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Sezione di prompt additiva adiacente a memory |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Corpus additivo di ricerca/lettura memory |
|
||||
|
||||
I namespace amministrativi core riservati (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) rimangono 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 posseduti dal plugin.
|
||||
I namespace amministrativi del core riservati (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) restano sempre `operator.admin`, anche se un plugin prova ad assegnare
|
||||
uno scope più ristretto a un metodo gateway. Preferisci prefissi specifici del plugin per
|
||||
i metodi di proprietà del plugin.
|
||||
|
||||
### Metadati di registrazione CLI
|
||||
### Metadati di registrazione della CLI
|
||||
|
||||
`api.registerCli(registrar, opts?)` accetta due tipi di metadati di primo livello:
|
||||
|
||||
- `commands`: root di comando esplicite possedute dal registrar
|
||||
- `descriptors`: descrittori di comando in fase di parsing usati per help della CLI root,
|
||||
routing e registrazione CLI lazy del plugin
|
||||
- `commands`: radici di comando esplicite possedute dal registrar
|
||||
- `descriptors`: descrittori di comando in fase di parsing usati per l'help della CLI radice,
|
||||
l'instradamento 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 root di comando di primo livello esposta da quel
|
||||
Se vuoi che un comando del plugin resti caricato lazy nel normale percorso della CLI radice,
|
||||
fornisci `descriptors` che coprano ogni radice di comando di primo livello esposta da quel
|
||||
registrar.
|
||||
|
||||
```typescript
|
||||
@ -347,7 +357,7 @@ api.registerCli(
|
||||
descriptors: [
|
||||
{
|
||||
name: "matrix",
|
||||
description: "Manage Matrix accounts, verification, devices, and profile state",
|
||||
description: "Gestisci account Matrix, verifica, dispositivi e stato del profilo",
|
||||
hasSubcommands: true,
|
||||
},
|
||||
],
|
||||
@ -355,66 +365,67 @@ 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 in fase di parsing.
|
||||
Usa `commands` da solo solo quando non hai bisogno della registrazione lazy della CLI radice.
|
||||
Questo percorso di compatibilità eager rimane supportato, ma non installa
|
||||
placeholder basati su descriptor per il caricamento lazy in fase di parsing.
|
||||
|
||||
### Slot esclusivi
|
||||
|
||||
| Metodo | Cosa registra |
|
||||
| ------------------------------------------ | -------------------------------------- |
|
||||
| Metodo | Cosa registra |
|
||||
| ------------------------------------------ | ------------------------------------ |
|
||||
| `api.registerContextEngine(id, factory)` | Motore di contesto (uno attivo alla volta) |
|
||||
| `api.registerMemoryPromptSection(builder)` | Builder di sezione del prompt memory |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Resolver del piano di flush memory |
|
||||
| `api.registerMemoryRuntime(runtime)` | Adapter runtime memory |
|
||||
| `api.registerMemoryPromptSection(builder)` | Builder della sezione del prompt memory |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Resolver del piano di flush memory |
|
||||
| `api.registerMemoryRuntime(runtime)` | Adapter runtime memory |
|
||||
|
||||
### Adapter di embedding memory
|
||||
|
||||
| Metodo | Cosa registra |
|
||||
| ---------------------------------------------- | -------------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter di embedding memory per il plugin attivo |
|
||||
| Metodo | Cosa registra |
|
||||
| ---------------------------------------------- | --------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter di embedding memory per il plugin attivo |
|
||||
|
||||
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` e
|
||||
`registerMemoryRuntime` sono esclusivi dei plugin memory.
|
||||
- `registerMemoryEmbeddingProvider` consente al plugin memory attivo di registrare uno
|
||||
o più ID di adapter embedding (per esempio `openai`, `gemini` o un ID personalizzato definito dal plugin).
|
||||
- La config utente come `agents.defaults.memorySearch.provider` e
|
||||
`agents.defaults.memorySearch.fallback` viene risolta rispetto a quegli ID di adapter
|
||||
registrati.
|
||||
- `registerMemoryEmbeddingProvider` consente al plugin memory attivo di registrare
|
||||
uno o più ID di adapter di 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 adapter registrati.
|
||||
|
||||
### Eventi e ciclo di vita
|
||||
### Eventi e lifecycle
|
||||
|
||||
| Metodo | Cosa fa |
|
||||
| -------------------------------------------- | --------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Hook del ciclo di vita tipizzato |
|
||||
| Metodo | Cosa fa |
|
||||
| -------------------------------------------- | -------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Hook lifecycle tipizzato |
|
||||
| `api.onConversationBindingResolved(handler)` | Callback di binding della conversazione |
|
||||
|
||||
### Semantica delle decisioni degli hook
|
||||
|
||||
- `before_tool_call`: restituire `{ block: true }` è terminale. Una volta che un gestore lo imposta, i gestori a priorità più bassa vengono saltati.
|
||||
- `before_tool_call`: restituire `{ block: false }` è trattato come nessuna decisione (uguale a omettere `block`), non come override.
|
||||
- `before_install`: restituire `{ block: true }` è terminale. Una volta che un gestore lo imposta, i gestori a priorità più bassa vengono saltati.
|
||||
- `before_install`: restituire `{ block: false }` è trattato come nessuna decisione (uguale a omettere `block`), non come override.
|
||||
- `reply_dispatch`: restituire `{ handled: true, ... }` è terminale. Una volta che un gestore rivendica il dispatch, i gestori a priorità più bassa 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 a priorità più bassa vengono saltati.
|
||||
- `message_sending`: restituire `{ cancel: false }` è trattato come nessuna decisione (uguale a omettere `cancel`), non come override.
|
||||
- `before_tool_call`: restituire `{ block: true }` è terminale. Una volta che un handler lo imposta, gli handler a 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 handler lo imposta, gli handler a 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 handler rivendica il dispatch, gli handler a priorità inferiore e il percorso predefinito di dispatch del modello vengono saltati.
|
||||
- `message_sending`: restituire `{ cancel: true }` è terminale. Una volta che un handler lo imposta, gli handler a priorità inferiore vengono saltati.
|
||||
- `message_sending`: restituire `{ cancel: false }` viene trattato come nessuna decisione (come omettere `cancel`), non come override.
|
||||
|
||||
### Campi dell'oggetto API
|
||||
|
||||
| Campo | Tipo | Descrizione |
|
||||
| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | ID del plugin |
|
||||
| `api.name` | `string` | Nome visualizzato |
|
||||
| `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 (facoltativa) |
|
||||
| `api.config` | `OpenClawConfig` | Snapshot della config corrente (snapshot runtime in-memory attivo quando disponibile) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Config 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.registrationMode` | `PluginRegistrationMode` | Modalità di caricamento corrente; `"setup-runtime"` è la finestra leggera di avvio/setup pre-full-entry |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Risolve il percorso relativo alla root del plugin |
|
||||
| Campo | Tipo | Descrizione |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | ID del plugin |
|
||||
| `api.name` | `string` | Nome visualizzato |
|
||||
| `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 radice del plugin (facoltativa) |
|
||||
| `api.config` | `OpenClawConfig` | Snapshot della configurazione corrente (snapshot runtime in memoria attivo 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.registrationMode` | `PluginRegistrationMode` | Modalità di caricamento corrente; `"setup-runtime"` è la finestra leggera di avvio/configurazione prima della full-entry |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Risolve un percorso relativo alla radice del plugin |
|
||||
|
||||
## Convenzione dei moduli interni
|
||||
|
||||
@ -422,49 +433,49 @@ All'interno del tuo plugin, usa file barrel locali per le importazioni interne:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
api.ts # Export pubblici per consumer esterni
|
||||
runtime-api.ts # Export runtime solo interni
|
||||
api.ts # Esportazioni pubbliche per i consumatori esterni
|
||||
runtime-api.ts # Esportazioni runtime solo interne
|
||||
index.ts # Punto di ingresso del plugin
|
||||
setup-entry.ts # Entry leggera solo setup (facoltativa)
|
||||
setup-entry.ts # Entry leggera solo per la configurazione (facoltativa)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
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
|
||||
dal codice di produzione. Instrada le importazioni interne attraverso `./api.ts` o
|
||||
`./runtime-api.ts`. Il percorso SDK è solo il contratto esterno.
|
||||
</Warning>
|
||||
|
||||
Le superfici pubbliche dei plugin bundled caricate tramite facade (`api.ts`, `runtime-api.ts`,
|
||||
Le superfici pubbliche dei plugin inclusi caricate tramite facade (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` e file di entry pubblici simili) ora preferiscono lo
|
||||
snapshot attivo della config runtime quando OpenClaw è già in esecuzione. Se non esiste ancora
|
||||
uno snapshot runtime, usano come fallback il file di config risolto su disco.
|
||||
snapshot della configurazione runtime attivo quando OpenClaw è già in esecuzione. Se non esiste ancora
|
||||
uno snapshot runtime, fanno fallback al file di configurazione risolto su disco.
|
||||
|
||||
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 bundled attuale: il provider Anthropic mantiene i propri helper
|
||||
stream Claude nel proprio seam pubblico `api.ts` / `contract-api.ts` invece di
|
||||
promuovere la logica degli header beta Anthropic e `service_tier` in un contratto
|
||||
Anche i plugin provider possono esporre un barrel contrattuale 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
|
||||
generico `plugin-sdk/*`.
|
||||
|
||||
Altri esempi bundled attuali:
|
||||
Altri esempi inclusi attuali:
|
||||
|
||||
- `@openclaw/openai-provider`: `api.ts` esporta builder dei provider,
|
||||
helper dei modelli predefiniti e builder dei provider realtime
|
||||
- `@openclaw/openai-provider`: `api.ts` esporta builder di provider,
|
||||
helper di modelli predefiniti e builder di provider realtime
|
||||
- `@openclaw/openrouter-provider`: `api.ts` esporta il builder del provider più
|
||||
helper di onboarding/config
|
||||
helper di onboarding/configurazione
|
||||
|
||||
<Warning>
|
||||
Anche il codice di produzione delle estensioni dovrebbe evitare importazioni
|
||||
Anche il codice di produzione delle estensioni dovrebbe evitare le 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 alla capacità invece di accoppiare due plugin tra loro.
|
||||
superficie orientata alle capacità invece di accoppiare due plugin tra loro.
|
||||
</Warning>
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Entry Points](/it/plugins/sdk-entrypoints) — opzioni di `definePluginEntry` e `defineChannelPluginEntry`
|
||||
- [Runtime Helpers](/it/plugins/sdk-runtime) — riferimento completo del namespace `api.runtime`
|
||||
- [Setup and Config](/it/plugins/sdk-setup) — packaging, manifest, schemi di config
|
||||
- [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 delle capacità
|
||||
- [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 config](/it/plugins/sdk-setup) — packaging, manifest, schemi di configurazione
|
||||
- [Test](/it/plugins/sdk-testing) — utility di test e regole lint
|
||||
- [Migrazione dell'SDK](/it/plugins/sdk-migration) — migrazione dalle superfici deprecate
|
||||
- [Interni dei plugin](/it/plugins/architecture) — architettura approfondita e modello di capacità
|
||||
|
||||
@ -2,30 +2,30 @@
|
||||
read_when:
|
||||
- Generazione di immagini tramite l'agente
|
||||
- Configurazione dei provider e dei modelli per la generazione di immagini
|
||||
- Comprensione dei parametri dello strumento `image_generate`
|
||||
summary: Genera e modifica immagini usando i provider configurati (OpenAI, Google Gemini, fal, MiniMax, ComfyUI, Vydra)
|
||||
- Comprensione dei parametri dello strumento image_generate
|
||||
summary: Genera e modifica immagini utilizzando i provider configurati (OpenAI, Google Gemini, fal, MiniMax, ComfyUI, Vydra)
|
||||
title: Generazione di immagini
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:12:38Z"
|
||||
generated_at: "2026-04-06T08:15:08Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: dde416dd1441a06605db85b5813cf61ccfc525813d6db430b7b7dfa53d6a3134
|
||||
source_hash: 903cc522c283a8da2cbd449ae3e25f349a74d00ecfdaf0f323fd8aa3f2107aea
|
||||
source_path: tools/image-generation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Generazione di immagini
|
||||
|
||||
Lo strumento `image_generate` consente all'agente di creare e modificare immagini usando i provider configurati. Le immagini generate vengono recapitate automaticamente come allegati multimediali nella risposta dell'agente.
|
||||
Lo strumento `image_generate` consente all'agente di creare e modificare immagini utilizzando i provider configurati. Le immagini generate vengono recapitate automaticamente come allegati multimediali nella risposta dell'agente.
|
||||
|
||||
<Note>
|
||||
Lo strumento appare solo quando è disponibile almeno un provider di generazione di immagini. Se non vedi `image_generate` tra gli strumenti del tuo agente, configura `agents.defaults.imageGenerationModel` o imposta una chiave API del provider.
|
||||
Lo strumento appare solo quando è disponibile almeno un provider per la generazione di immagini. Se non vedi `image_generate` tra gli strumenti del tuo agente, configura `agents.defaults.imageGenerationModel` oppure imposta una chiave API di un provider.
|
||||
</Note>
|
||||
|
||||
## Avvio rapido
|
||||
|
||||
1. Imposta una chiave API per almeno un provider (ad esempio `OPENAI_API_KEY` o `GEMINI_API_KEY`).
|
||||
2. Facoltativamente imposta il tuo modello preferito:
|
||||
1. Imposta una chiave API per almeno un provider, ad esempio `OPENAI_API_KEY` o `GEMINI_API_KEY`.
|
||||
2. Facoltativamente, imposta il modello preferito:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -41,20 +41,20 @@ Lo strumento appare solo quando è disponibile almeno un provider di generazione
|
||||
|
||||
3. Chiedi all'agente: _"Genera un'immagine di una simpatica mascotte aragosta."_
|
||||
|
||||
L'agente chiama automaticamente `image_generate`. Non serve alcuna allowlist degli strumenti — è abilitato per impostazione predefinita quando un provider è disponibile.
|
||||
L'agente chiama automaticamente `image_generate`. Non è necessario alcun allowlist degli strumenti: è abilitato per impostazione predefinita quando è disponibile un provider.
|
||||
|
||||
## Provider supportati
|
||||
|
||||
| Provider | Modello predefinito | Supporto modifica | Chiave API |
|
||||
| -------- | ------------------------------- | ---------------------------------- | ------------------------------------------------------ |
|
||||
| OpenAI | `gpt-image-1` | Sì (fino a 5 immagini) | `OPENAI_API_KEY` |
|
||||
| Google | `gemini-3.1-flash-image-preview` | Sì | `GEMINI_API_KEY` o `GOOGLE_API_KEY` |
|
||||
| fal | `fal-ai/flux/dev` | Sì | `FAL_KEY` |
|
||||
| MiniMax | `image-01` | Sì (riferimento del soggetto) | `MINIMAX_API_KEY` o OAuth MiniMax (`minimax-portal`) |
|
||||
| ComfyUI | `workflow` | Sì (1 immagine, configurata dal workflow) | `COMFY_API_KEY` o `COMFY_CLOUD_API_KEY` per il cloud |
|
||||
| Vydra | `grok-imagine` | No | `VYDRA_API_KEY` |
|
||||
| Provider | Modello predefinito | Supporto per la modifica | Chiave API |
|
||||
| -------- | -------------------------------- | ----------------------------------- | ----------------------------------------------------- |
|
||||
| OpenAI | `gpt-image-1` | Sì (fino a 5 immagini) | `OPENAI_API_KEY` |
|
||||
| Google | `gemini-3.1-flash-image-preview` | Sì | `GEMINI_API_KEY` o `GOOGLE_API_KEY` |
|
||||
| fal | `fal-ai/flux/dev` | Sì | `FAL_KEY` |
|
||||
| MiniMax | `image-01` | Sì (riferimento al soggetto) | `MINIMAX_API_KEY` o OAuth MiniMax (`minimax-portal`) |
|
||||
| ComfyUI | `workflow` | Sì (1 immagine, configurata tramite workflow) | `COMFY_API_KEY` o `COMFY_CLOUD_API_KEY` per il cloud |
|
||||
| Vydra | `grok-imagine` | No | `VYDRA_API_KEY` |
|
||||
|
||||
Usa `action: "list"` per ispezionare provider e modelli disponibili a runtime:
|
||||
Usa `action: "list"` per esaminare i provider e i modelli disponibili in fase di esecuzione:
|
||||
|
||||
```
|
||||
/tool image_generate action=list
|
||||
@ -62,20 +62,20 @@ Usa `action: "list"` per ispezionare provider e modelli disponibili a runtime:
|
||||
|
||||
## Parametri dello strumento
|
||||
|
||||
| Parametro | Tipo | Descrizione |
|
||||
| ------------- | -------- | ---------------------------------------------------------------------------------- |
|
||||
| `prompt` | string | Prompt di generazione dell'immagine (obbligatorio per `action: "generate"`) |
|
||||
| `action` | string | `"generate"` (predefinito) o `"list"` per ispezionare i provider |
|
||||
| `model` | string | Override provider/modello, ad esempio `openai/gpt-image-1` |
|
||||
| `image` | string | Singolo percorso immagine di riferimento o URL per la modalità modifica |
|
||||
| `images` | string[] | Più immagini di riferimento per la modalità modifica (fino a 5) |
|
||||
| `size` | string | Suggerimento di dimensione: `1024x1024`, `1536x1024`, `1024x1536`, `1024x1792`, `1792x1024` |
|
||||
| `aspectRatio` | string | Rapporto di aspetto: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
|
||||
| `resolution` | string | Suggerimento di risoluzione: `1K`, `2K` o `4K` |
|
||||
| `count` | number | Numero di immagini da generare (1–4) |
|
||||
| `filename` | string | Suggerimento per il nome del file di output |
|
||||
| Parametro | Tipo | Descrizione |
|
||||
| ------------- | -------- | ------------------------------------------------------------------------------------ |
|
||||
| `prompt` | string | Prompt per la generazione di immagini (obbligatorio per `action: "generate"`) |
|
||||
| `action` | string | `"generate"` (predefinito) oppure `"list"` per esaminare i provider |
|
||||
| `model` | string | Override di provider/modello, ad esempio `openai/gpt-image-1` |
|
||||
| `image` | string | Percorso o URL di una singola immagine di riferimento per la modalità modifica |
|
||||
| `images` | string[] | Più immagini di riferimento per la modalità modifica (fino a 5) |
|
||||
| `size` | string | Indicazione della dimensione: `1024x1024`, `1536x1024`, `1024x1536`, `1024x1792`, `1792x1024` |
|
||||
| `aspectRatio` | string | Rapporto d'aspetto: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
|
||||
| `resolution` | string | Indicazione della risoluzione: `1K`, `2K` o `4K` |
|
||||
| `count` | number | Numero di immagini da generare (1–4) |
|
||||
| `filename` | string | Indicazione del nome file di output |
|
||||
|
||||
Non tutti i provider supportano tutti i parametri. Lo strumento passa ciò che ciascun provider supporta, ignora il resto e segnala gli override scartati nel risultato dello strumento.
|
||||
Non tutti i provider supportano tutti i parametri. Lo strumento passa ciò che ogni provider supporta, ignora il resto e segnala gli override scartati nel risultato dello strumento.
|
||||
|
||||
## Configurazione
|
||||
|
||||
@ -94,58 +94,57 @@ Non tutti i provider supportano tutti i parametri. Lo strumento passa ciò che c
|
||||
}
|
||||
```
|
||||
|
||||
### Ordine di selezione del provider
|
||||
### Ordine di selezione dei provider
|
||||
|
||||
Quando genera un'immagine, OpenClaw prova i provider in questo ordine:
|
||||
|
||||
1. Il parametro **`model`** della chiamata allo strumento (se l'agente ne specifica uno)
|
||||
1. **Parametro `model`** della chiamata allo strumento (se l'agente ne specifica uno)
|
||||
2. **`imageGenerationModel.primary`** dalla configurazione
|
||||
3. **`imageGenerationModel.fallbacks`** nell'ordine indicato
|
||||
4. **Rilevamento automatico** — usa solo i valori predefiniti dei provider supportati dall'autenticazione:
|
||||
4. **Rilevamento automatico** — usa solo i provider predefiniti supportati dall'autenticazione:
|
||||
- prima il provider predefinito corrente
|
||||
- poi i restanti provider di generazione di immagini registrati in ordine di ID provider
|
||||
- poi i restanti provider di generazione di immagini registrati, in ordine di provider id
|
||||
|
||||
Se un provider fallisce (errore di autenticazione, rate limit, ecc.), il candidato successivo viene provato automaticamente. Se falliscono tutti, l'errore include i dettagli di ogni tentativo.
|
||||
Se un provider non riesce (errore di autenticazione, limite di velocità, ecc.), viene provato automaticamente il candidato successivo. Se falliscono tutti, l'errore include i dettagli di ogni tentativo.
|
||||
|
||||
Note:
|
||||
|
||||
- Il rilevamento automatico è consapevole dell'autenticazione. Un provider predefinito entra nell'elenco dei candidati solo quando OpenClaw può effettivamente autenticare quel provider.
|
||||
- Usa `action: "list"` per ispezionare i provider attualmente registrati, i loro
|
||||
modelli predefiniti e i suggerimenti sulle env var di autenticazione.
|
||||
- Usa `action: "list"` per esaminare i provider attualmente registrati, i loro modelli predefiniti e i suggerimenti sulle variabili d'ambiente per l'autenticazione.
|
||||
|
||||
### Modifica delle immagini
|
||||
|
||||
OpenAI, Google, fal, MiniMax e ComfyUI supportano la modifica di immagini di riferimento. Passa un percorso immagine di riferimento o un URL:
|
||||
OpenAI, Google, fal, MiniMax e ComfyUI supportano la modifica di immagini di riferimento. Passa un percorso o un URL di un'immagine di riferimento:
|
||||
|
||||
```
|
||||
"Genera una versione acquerello di questa foto" + image: "/path/to/photo.jpg"
|
||||
"Genera una versione ad acquerello di questa foto" + image: "/path/to/photo.jpg"
|
||||
```
|
||||
|
||||
OpenAI e Google supportano fino a 5 immagini di riferimento tramite il parametro `images`. fal, MiniMax e ComfyUI ne supportano 1.
|
||||
|
||||
La generazione di immagini MiniMax è disponibile tramite entrambi i percorsi auth MiniMax bundled:
|
||||
La generazione di immagini MiniMax è disponibile tramite entrambi i percorsi di autenticazione MiniMax inclusi:
|
||||
|
||||
- `minimax/image-01` per configurazioni con chiave API
|
||||
- `minimax-portal/image-01` per configurazioni OAuth
|
||||
- `minimax/image-01` per le configurazioni con chiave API
|
||||
- `minimax-portal/image-01` per le configurazioni con OAuth
|
||||
|
||||
## Capability dei provider
|
||||
## Capacità dei provider
|
||||
|
||||
| Capability | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra |
|
||||
| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ----- |
|
||||
| Generazione | Sì (fino a 4) | Sì (fino a 4) | Sì (fino a 4) | Sì (fino a 9) | Sì (output definiti dal workflow) | Sì (1) |
|
||||
| Modifica/riferimento | Sì (fino a 5 immagini) | Sì (fino a 5 immagini) | Sì (1 immagine) | Sì (1 immagine, riferimento soggetto) | Sì (1 immagine, configurata dal workflow) | No |
|
||||
| Controllo dimensione | Sì | Sì | Sì | No | No | No |
|
||||
| Rapporto di aspetto | No | Sì | Sì (solo generazione) | Sì | No | No |
|
||||
| Risoluzione (1K/2K/4K) | No | Sì | Sì | No | No | No |
|
||||
| Capacità | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra |
|
||||
| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- |
|
||||
| Generazione | Sì (fino a 4) | Sì (fino a 4) | Sì (fino a 4) | Sì (fino a 9) | Sì (output definiti dal workflow) | Sì (1) |
|
||||
| Modifica/riferimento | Sì (fino a 5 immagini) | Sì (fino a 5 immagini) | Sì (1 immagine) | Sì (1 immagine, rif. soggetto) | Sì (1 immagine, configurata tramite workflow) | No |
|
||||
| Controllo dimensione | Sì | Sì | Sì | No | No | No |
|
||||
| Rapporto d'aspetto | No | Sì | Sì (solo generazione) | Sì | No | No |
|
||||
| Risoluzione (1K/2K/4K) | No | Sì | Sì | No | No | No |
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Panoramica degli strumenti](/it/tools) — tutti gli strumenti agente disponibili
|
||||
- [fal](/providers/fal) — configurazione del provider immagini e video fal
|
||||
- [ComfyUI](/providers/comfy) — configurazione del workflow locale ComfyUI e Comfy Cloud
|
||||
- [Google (Gemini)](/it/providers/google) — configurazione del provider immagini Gemini
|
||||
- [MiniMax](/it/providers/minimax) — configurazione del provider immagini MiniMax
|
||||
- [Panoramica degli strumenti](/it/tools) — tutti gli strumenti dell'agente disponibili
|
||||
- [fal](/it/providers/fal) — configurazione del provider di immagini e video fal
|
||||
- [ComfyUI](/it/providers/comfy) — configurazione locale di ComfyUI e dei workflow Comfy Cloud
|
||||
- [Google (Gemini)](/it/providers/google) — configurazione del provider di immagini Gemini
|
||||
- [MiniMax](/it/providers/minimax) — configurazione del provider di immagini MiniMax
|
||||
- [OpenAI](/it/providers/openai) — configurazione del provider OpenAI Images
|
||||
- [Vydra](/providers/vydra) — configurazione di immagini, video e speech Vydra
|
||||
- [Riferimento di configurazione](/it/gateway/configuration-reference#agent-defaults) — configurazione `imageGenerationModel`
|
||||
- [Vydra](/it/providers/vydra) — configurazione di immagini, video e voce per Vydra
|
||||
- [Riferimento della configurazione](/it/gateway/configuration-reference#agent-defaults) — configurazione `imageGenerationModel`
|
||||
- [Modelli](/it/concepts/models) — configurazione dei modelli e failover
|
||||
|
||||
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- Generazione di video tramite l'agent
|
||||
- Configurazione dei provider e dei modelli di generazione video
|
||||
- Generazione di video tramite l'agente
|
||||
- Configurazione dei provider e dei modelli per la generazione video
|
||||
- Comprensione dei parametri dello strumento video_generate
|
||||
summary: Genera video da testo, immagini o video esistenti usando 12 backend provider
|
||||
title: Generazione di video
|
||||
summary: Genera video da testo, immagini o video esistenti utilizzando 12 backend provider
|
||||
title: Generazione video
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:13:31Z"
|
||||
generated_at: "2026-04-06T08:15:18Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 4afec87368232221db1aa5a3980254093d6a961b17271b2dcbf724e6bd455b16
|
||||
source_hash: 90d8a392b35adbd899232b02c55c10895b9d7ffc9858d6ca448f2e4e4a57f12f
|
||||
source_path: tools/video-generation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Generazione di video
|
||||
# Generazione video
|
||||
|
||||
Gli agent OpenClaw possono generare video da prompt di testo, immagini di riferimento o video esistenti. Sono supportati dodici backend provider, ciascuno con opzioni di modello, modalità di input e set di funzionalità differenti. L'agent sceglie automaticamente il provider corretto in base alla tua configurazione e alle API key disponibili.
|
||||
Gli agenti OpenClaw possono generare video da prompt di testo, immagini di riferimento o video esistenti. Sono supportati dodici backend provider, ciascuno con diverse opzioni di modello, modalità di input e set di funzionalità. L'agente sceglie automaticamente il provider corretto in base alla tua configurazione e alle chiavi API disponibili.
|
||||
|
||||
<Note>
|
||||
Lo strumento `video_generate` compare solo quando è disponibile almeno un provider di generazione video. Se non lo vedi tra gli strumenti del tuo agent, imposta una API key del provider o configura `agents.defaults.videoGenerationModel`.
|
||||
Lo strumento `video_generate` appare solo quando è disponibile almeno un provider per la generazione video. Se non lo vedi tra gli strumenti del tuo agente, imposta una chiave API del provider o configura `agents.defaults.videoGenerationModel`.
|
||||
</Note>
|
||||
|
||||
## Guida rapida
|
||||
## Avvio rapido
|
||||
|
||||
1. Imposta una API key per un provider supportato:
|
||||
1. Imposta una chiave API per qualsiasi provider supportato:
|
||||
|
||||
```bash
|
||||
export GEMINI_API_KEY="your-key"
|
||||
@ -36,58 +36,58 @@ export GEMINI_API_KEY="your-key"
|
||||
openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
|
||||
```
|
||||
|
||||
3. Chiedi all'agent:
|
||||
3. Chiedi all'agente:
|
||||
|
||||
> Genera un video cinematografico di 5 secondi di un'aragosta amichevole che fa surf al tramonto.
|
||||
|
||||
L'agent chiama automaticamente `video_generate`. Non è necessaria alcuna allowlist degli strumenti.
|
||||
L'agente chiama automaticamente `video_generate`. Non è necessaria alcuna allowlist degli strumenti.
|
||||
|
||||
## Cosa succede quando generi un video
|
||||
|
||||
La generazione video è asincrona. Quando l'agent chiama `video_generate` in una sessione:
|
||||
La generazione video è asincrona. Quando l'agente chiama `video_generate` in una sessione:
|
||||
|
||||
1. OpenClaw invia la richiesta al provider e restituisce immediatamente un ID attività.
|
||||
2. Il provider elabora il job in background (tipicamente da 30 secondi a 5 minuti a seconda del provider e della risoluzione).
|
||||
2. Il provider elabora il lavoro in background (in genere da 30 secondi a 5 minuti a seconda del provider e della risoluzione).
|
||||
3. Quando il video è pronto, OpenClaw riattiva la stessa sessione con un evento interno di completamento.
|
||||
4. L'agent pubblica il video completato nella conversazione originale.
|
||||
4. L'agente pubblica il video completato nella conversazione originale.
|
||||
|
||||
Mentre un job è in corso, chiamate duplicate a `video_generate` nella stessa sessione restituiscono lo stato corrente dell'attività invece di avviare un'altra generazione. Usa `openclaw tasks list` o `openclaw tasks show <taskId>` per controllare l'avanzamento dalla CLI.
|
||||
Mentre un'attività è in corso, le chiamate duplicate a `video_generate` nella stessa sessione restituiscono lo stato corrente dell'attività invece di avviare un'altra generazione. Usa `openclaw tasks list` o `openclaw tasks show <taskId>` per controllare l'avanzamento dalla CLI.
|
||||
|
||||
Al di fuori delle esecuzioni dell'agent supportate da sessione (ad esempio invocazioni dirette dello strumento), lo strumento usa come fallback la generazione inline e restituisce il percorso finale del media nello stesso turno.
|
||||
Al di fuori delle esecuzioni dell'agente supportate da sessione (ad esempio, invocazioni dirette degli strumenti), lo strumento torna alla generazione inline e restituisce il percorso finale del file multimediale nello stesso turno.
|
||||
|
||||
## Provider supportati
|
||||
|
||||
| Provider | Modello predefinito | Testo | Riferimento immagine | Riferimento video | API key |
|
||||
| -------- | ------------------------------- | ----- | -------------------- | ----------------- | ---------------------------------------- |
|
||||
| Alibaba | `wan2.6-t2v` | Sì | Sì (URL remoto) | Sì (URL remoto) | `MODELSTUDIO_API_KEY` |
|
||||
| BytePlus | `seedance-1-0-lite-t2v-250428` | Sì | 1 immagine | No | `BYTEPLUS_API_KEY` |
|
||||
| ComfyUI | `workflow` | Sì | 1 immagine | No | `COMFY_API_KEY` o `COMFY_CLOUD_API_KEY` |
|
||||
| fal | `fal-ai/minimax/video-01-live` | Sì | 1 immagine | No | `FAL_KEY` |
|
||||
| Google | `veo-3.1-fast-generate-preview` | Sì | 1 immagine | 1 video | `GEMINI_API_KEY` |
|
||||
| MiniMax | `MiniMax-Hailuo-2.3` | Sì | 1 immagine | No | `MINIMAX_API_KEY` |
|
||||
| OpenAI | `sora-2` | Sì | 1 immagine | 1 video | `OPENAI_API_KEY` |
|
||||
| Qwen | `wan2.6-t2v` | Sì | Sì (URL remoto) | Sì (URL remoto) | `QWEN_API_KEY` |
|
||||
| Runway | `gen4.5` | Sì | 1 immagine | 1 video | `RUNWAYML_API_SECRET` |
|
||||
| Together | `Wan-AI/Wan2.2-T2V-A14B` | Sì | 1 immagine | No | `TOGETHER_API_KEY` |
|
||||
| Vydra | `veo3` | Sì | 1 immagine (`kling`) | No | `VYDRA_API_KEY` |
|
||||
| xAI | `grok-imagine-video` | Sì | 1 immagine | 1 video | `XAI_API_KEY` |
|
||||
| Provider | Modello predefinito | Testo | Immagine rif. | Video rif. | Chiave API |
|
||||
| -------- | ------------------------------- | ----- | ----------------- | ---------------- | ----------------------------------------- |
|
||||
| Alibaba | `wan2.6-t2v` | Sì | Sì (URL remoto) | Sì (URL remoto) | `MODELSTUDIO_API_KEY` |
|
||||
| BytePlus | `seedance-1-0-lite-t2v-250428` | Sì | 1 immagine | No | `BYTEPLUS_API_KEY` |
|
||||
| ComfyUI | `workflow` | Sì | 1 immagine | No | `COMFY_API_KEY` o `COMFY_CLOUD_API_KEY` |
|
||||
| fal | `fal-ai/minimax/video-01-live` | Sì | 1 immagine | No | `FAL_KEY` |
|
||||
| Google | `veo-3.1-fast-generate-preview` | Sì | 1 immagine | 1 video | `GEMINI_API_KEY` |
|
||||
| MiniMax | `MiniMax-Hailuo-2.3` | Sì | 1 immagine | No | `MINIMAX_API_KEY` |
|
||||
| OpenAI | `sora-2` | Sì | 1 immagine | 1 video | `OPENAI_API_KEY` |
|
||||
| Qwen | `wan2.6-t2v` | Sì | Sì (URL remoto) | Sì (URL remoto) | `QWEN_API_KEY` |
|
||||
| Runway | `gen4.5` | Sì | 1 immagine | 1 video | `RUNWAYML_API_SECRET` |
|
||||
| Together | `Wan-AI/Wan2.2-T2V-A14B` | Sì | 1 immagine | No | `TOGETHER_API_KEY` |
|
||||
| Vydra | `veo3` | Sì | 1 immagine (`kling`) | No | `VYDRA_API_KEY` |
|
||||
| xAI | `grok-imagine-video` | Sì | 1 immagine | 1 video | `XAI_API_KEY` |
|
||||
|
||||
Alcuni provider accettano variabili env API key aggiuntive o alternative. Vedi le singole [pagine provider](#related) per i dettagli.
|
||||
Alcuni provider accettano variabili d'ambiente aggiuntive o alternative per la chiave API. Consulta le singole [pagine dei provider](#related) per i dettagli.
|
||||
|
||||
Esegui `video_generate action=list` per ispezionare i provider e i modelli disponibili a runtime.
|
||||
Esegui `video_generate action=list` per esaminare i provider e i modelli disponibili in fase di esecuzione.
|
||||
|
||||
## Parametri dello strumento
|
||||
|
||||
### Obbligatori
|
||||
|
||||
| Parametro | Tipo | Descrizione |
|
||||
| --------- | ------ | ------------------------------------------------------------------------------ |
|
||||
| Parametro | Tipo | Descrizione |
|
||||
| --------- | ------ | --------------------------------------------------------------------------- |
|
||||
| `prompt` | string | Descrizione testuale del video da generare (obbligatoria per `action: "generate"`) |
|
||||
|
||||
### Input di contenuto
|
||||
|
||||
| Parametro | Tipo | Descrizione |
|
||||
| --------- | -------- | ---------------------------------------- |
|
||||
| Parametro | Tipo | Descrizione |
|
||||
| --------- | -------- | --------------------------------------- |
|
||||
| `image` | string | Singola immagine di riferimento (percorso o URL) |
|
||||
| `images` | string[] | Immagini di riferimento multiple (fino a 5) |
|
||||
| `video` | string | Singolo video di riferimento (percorso o URL) |
|
||||
@ -95,41 +95,41 @@ Esegui `video_generate action=list` per ispezionare i provider e i modelli dispo
|
||||
|
||||
### Controlli di stile
|
||||
|
||||
| Parametro | Tipo | Descrizione |
|
||||
| ----------------- | ------- | ------------------------------------------------------------------------ |
|
||||
| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
|
||||
| `resolution` | string | `480P`, `720P` o `1080P` |
|
||||
| `durationSeconds` | number | Durata target in secondi (arrotondata al valore supportato più vicino dal provider) |
|
||||
| `size` | string | Suggerimento di dimensione quando il provider lo supporta |
|
||||
| `audio` | boolean | Abilita l'audio generato quando supportato |
|
||||
| `watermark` | boolean | Attiva/disattiva la filigrana del provider quando supportata |
|
||||
| Parametro | Tipo | Descrizione |
|
||||
| ---------------- | ------- | ---------------------------------------------------------------------- |
|
||||
| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` |
|
||||
| `resolution` | string | `480P`, `720P` o `1080P` |
|
||||
| `durationSeconds`| number | Durata target in secondi (arrotondata al valore supportato dal provider più vicino) |
|
||||
| `size` | string | Indicazione di dimensione quando il provider la supporta |
|
||||
| `audio` | boolean | Abilita l'audio generato quando supportato |
|
||||
| `watermark` | boolean | Attiva o disattiva il watermark del provider quando supportato |
|
||||
|
||||
### Avanzati
|
||||
|
||||
| Parametro | Tipo | Descrizione |
|
||||
| ---------- | ------ | ------------------------------------------------ |
|
||||
| `action` | string | `"generate"` (predefinito), `"status"` o `"list"` |
|
||||
| `model` | string | Override provider/model (ad esempio `runway/gen4.5`) |
|
||||
| `model` | string | Override di provider/modello (ad es. `runway/gen4.5`) |
|
||||
| `filename` | string | Suggerimento per il nome del file di output |
|
||||
|
||||
Non tutti i provider supportano tutti i parametri. Gli override non supportati vengono ignorati su base best-effort e segnalati come avvisi nel risultato dello strumento. I limiti rigidi delle capability (come troppi input di riferimento) falliscono prima dell'invio.
|
||||
Non tutti i provider supportano tutti i parametri. Gli override non supportati vengono ignorati in base al miglior sforzo e segnalati come avvisi nel risultato dello strumento. I limiti rigidi di capacità (come un numero eccessivo di input di riferimento) falliscono prima dell'invio.
|
||||
|
||||
## Azioni
|
||||
|
||||
- **generate** (predefinita) -- crea un video dal prompt fornito e dagli eventuali input di riferimento.
|
||||
- **generate** (predefinita) -- crea un video a partire dal prompt fornito e dagli input di riferimento facoltativi.
|
||||
- **status** -- controlla lo stato dell'attività video in corso per la sessione corrente senza avviare un'altra generazione.
|
||||
- **list** -- mostra provider, modelli disponibili e relative capability.
|
||||
- **list** -- mostra i provider, i modelli e le relative capacità disponibili.
|
||||
|
||||
## Selezione del modello
|
||||
|
||||
Quando genera un video, OpenClaw risolve il modello in questo ordine:
|
||||
|
||||
1. **Parametro dello strumento `model`** -- se l'agent ne specifica uno nella chiamata.
|
||||
1. **Parametro dello strumento `model`** -- se l'agente ne specifica uno nella chiamata.
|
||||
2. **`videoGenerationModel.primary`** -- dalla configurazione.
|
||||
3. **`videoGenerationModel.fallbacks`** -- provati in ordine.
|
||||
4. **Rilevamento automatico** -- usa i provider che hanno auth valida, iniziando dal provider predefinito corrente, poi i provider rimanenti in ordine alfabetico.
|
||||
4. **Rilevamento automatico** -- usa i provider con autenticazione valida, iniziando dal provider predefinito corrente, poi i provider rimanenti in ordine alfabetico.
|
||||
|
||||
Se un provider fallisce, viene provato automaticamente il candidato successivo. Se tutti i candidati falliscono, l'errore include i dettagli di ogni tentativo.
|
||||
Se un provider fallisce, il candidato successivo viene provato automaticamente. Se tutti i candidati falliscono, l'errore include i dettagli di ogni tentativo.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -146,24 +146,24 @@ Se un provider fallisce, viene provato automaticamente il candidato successivo.
|
||||
|
||||
## Note sui provider
|
||||
|
||||
| Provider | Note |
|
||||
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Alibaba | Usa l'endpoint asincrono DashScope/Model Studio. Le immagini e i video di riferimento devono essere URL remoti `http(s)`. |
|
||||
| BytePlus | Solo un'immagine di riferimento. |
|
||||
| ComfyUI | Esecuzione locale o cloud guidata da workflow. Supporta text-to-video e image-to-video tramite il grafo configurato. |
|
||||
| fal | Usa un flusso supportato da coda per job di lunga durata. Solo un'immagine di riferimento. |
|
||||
| Google | Usa Gemini/Veo. Supporta un'immagine o un video di riferimento. |
|
||||
| MiniMax | Solo un'immagine di riferimento. |
|
||||
| OpenAI | Viene inoltrato solo l'override `size`. Gli altri override di stile (`aspectRatio`, `resolution`, `audio`, `watermark`) vengono ignorati con un avviso. |
|
||||
| Qwen | Stesso backend DashScope di Alibaba. Gli input di riferimento devono essere URL remoti `http(s)`; i file locali vengono rifiutati in anticipo. |
|
||||
| Runway | Supporta file locali tramite data URI. Video-to-video richiede `runway/gen4_aleph`. Le esecuzioni solo testo espongono rapporti d'aspetto `16:9` e `9:16`. |
|
||||
| Together | Solo un'immagine di riferimento. |
|
||||
| Vydra | Usa direttamente `https://www.vydra.ai/api/v1` per evitare redirect che perdono auth. `veo3` è integrato solo come text-to-video; `kling` richiede un URL immagine remoto. |
|
||||
| xAI | Supporta flussi text-to-video, image-to-video e modifica/estensione di video remoti. |
|
||||
| Provider | Note |
|
||||
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Alibaba | Usa l'endpoint asincrono DashScope/Model Studio. Le immagini e i video di riferimento devono essere URL `http(s)` remoti. |
|
||||
| BytePlus | Solo un'immagine di riferimento. |
|
||||
| ComfyUI | Esecuzione locale o cloud basata su workflow. Supporta text-to-video e image-to-video tramite il grafo configurato. |
|
||||
| fal | Usa un flusso supportato da coda per lavori di lunga durata. Solo un'immagine di riferimento. |
|
||||
| Google | Usa Gemini/Veo. Supporta un'immagine o un video di riferimento. |
|
||||
| MiniMax | Solo un'immagine di riferimento. |
|
||||
| OpenAI | Viene inoltrato solo l'override `size`. Gli altri override di stile (`aspectRatio`, `resolution`, `audio`, `watermark`) vengono ignorati con un avviso. |
|
||||
| Qwen | Stesso backend DashScope di Alibaba. Gli input di riferimento devono essere URL `http(s)` remoti; i file locali vengono rifiutati in anticipo. |
|
||||
| Runway | Supporta file locali tramite URI di dati. Video-to-video richiede `runway/gen4_aleph`. Le esecuzioni solo testo espongono i rapporti d'aspetto `16:9` e `9:16`. |
|
||||
| Together | Solo un'immagine di riferimento. |
|
||||
| Vydra | Usa direttamente `https://www.vydra.ai/api/v1` per evitare reindirizzamenti che eliminano l'autenticazione. `veo3` è incluso solo come text-to-video; `kling` richiede un URL immagine remoto. |
|
||||
| xAI | Supporta flussi text-to-video, image-to-video e di modifica/estensione video remota. |
|
||||
|
||||
## Configurazione
|
||||
|
||||
Imposta il modello di generazione video predefinito nella configurazione OpenClaw:
|
||||
Imposta il modello predefinito per la generazione video nella configurazione di OpenClaw:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -187,18 +187,18 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2
|
||||
## Correlati
|
||||
|
||||
- [Panoramica degli strumenti](/it/tools)
|
||||
- [Attività in background](/it/automation/tasks) -- tracciamento delle attività per la generazione video asincrona
|
||||
- [Alibaba Model Studio](/providers/alibaba)
|
||||
- [BytePlus](/providers/byteplus)
|
||||
- [ComfyUI](/providers/comfy)
|
||||
- [fal](/providers/fal)
|
||||
- [Attività in background](/it/automation/tasks) -- monitoraggio delle attività per la generazione video asincrona
|
||||
- [Alibaba Model Studio](/it/providers/alibaba)
|
||||
- [BytePlus](/it/concepts/model-providers#byteplus-international)
|
||||
- [ComfyUI](/it/providers/comfy)
|
||||
- [fal](/it/providers/fal)
|
||||
- [Google (Gemini)](/it/providers/google)
|
||||
- [MiniMax](/it/providers/minimax)
|
||||
- [OpenAI](/it/providers/openai)
|
||||
- [Qwen](/it/providers/qwen)
|
||||
- [Runway](/providers/runway)
|
||||
- [Runway](/it/providers/runway)
|
||||
- [Together AI](/it/providers/together)
|
||||
- [Vydra](/providers/vydra)
|
||||
- [Vydra](/it/providers/vydra)
|
||||
- [xAI](/it/providers/xai)
|
||||
- [Riferimento configurazione](/it/gateway/configuration-reference#agent-defaults)
|
||||
- [Riferimento della configurazione](/it/gateway/configuration-reference#agent-defaults)
|
||||
- [Modelli](/it/concepts/models)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user