chore(i18n): refresh it translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
d72979a74a
commit
0ff13a0571
@ -4,21 +4,21 @@ read_when:
|
||||
summary: Stato del supporto del bot Discord, capacità e configurazione
|
||||
title: Discord
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T08:23:13Z"
|
||||
generated_at: "2026-04-23T13:57:56Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0bee2c419651701f7ab57e46a4c0c473c83596eb9bd2156bac3c6117513236ab
|
||||
source_hash: 1160a0b221bc3251722a81c00c65ee7c2001efce345248727f1f3c8580a0e953
|
||||
source_path: channels/discord.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Discord (API Bot)
|
||||
|
||||
Stato: pronto per DM e canali del server tramite il gateway ufficiale di Discord.
|
||||
Stato: pronto per DM e canali guild tramite il gateway Discord ufficiale.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Abbinamento" icon="link" href="/it/channels/pairing">
|
||||
Le DM di Discord usano per impostazione predefinita la modalità di abbinamento.
|
||||
I DM di Discord usano per impostazione predefinita la modalità di abbinamento.
|
||||
</Card>
|
||||
<Card title="Comandi slash" icon="terminal" href="/it/tools/slash-commands">
|
||||
Comportamento nativo dei comandi e catalogo dei comandi.
|
||||
@ -36,15 +36,15 @@ Dovrai creare una nuova applicazione con un bot, aggiungere il bot al tuo server
|
||||
<Step title="Crea un'applicazione Discord e un bot">
|
||||
Vai al [Discord Developer Portal](https://discord.com/developers/applications) e fai clic su **New Application**. Assegnale un nome come "OpenClaw".
|
||||
|
||||
Fai clic su **Bot** nella barra laterale. Imposta **Username** con il nome che dai al tuo agente OpenClaw.
|
||||
Fai clic su **Bot** nella barra laterale. Imposta **Username** su come chiami il tuo agente OpenClaw.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Abilita gli intent privilegiati">
|
||||
Sempre nella pagina **Bot**, scorri verso il basso fino a **Privileged Gateway Intents** e abilita:
|
||||
Sempre nella pagina **Bot**, scorri fino a **Privileged Gateway Intents** e abilita:
|
||||
|
||||
- **Message Content Intent** (obbligatorio)
|
||||
- **Server Members Intent** (consigliato; obbligatorio per allowlist di ruoli e corrispondenza nome-ID)
|
||||
- **Server Members Intent** (consigliato; obbligatorio per le allowlist dei ruoli e l'abbinamento da nome a ID)
|
||||
- **Presence Intent** (facoltativo; necessario solo per gli aggiornamenti di presenza)
|
||||
|
||||
</Step>
|
||||
@ -53,7 +53,7 @@ Dovrai creare una nuova applicazione con un bot, aggiungere il bot al tuo server
|
||||
Torna in alto nella pagina **Bot** e fai clic su **Reset Token**.
|
||||
|
||||
<Note>
|
||||
Nonostante il nome, questo genera il tuo primo token — non viene "reimpostato" nulla.
|
||||
Nonostante il nome, questo genera il tuo primo token — non viene “reimpostato” nulla.
|
||||
</Note>
|
||||
|
||||
Copia il token e salvalo da qualche parte. Questo è il tuo **Bot Token** e ti servirà tra poco.
|
||||
@ -61,9 +61,9 @@ Dovrai creare una nuova applicazione con un bot, aggiungere il bot al tuo server
|
||||
</Step>
|
||||
|
||||
<Step title="Genera un URL di invito e aggiungi il bot al tuo server">
|
||||
Fai clic su **OAuth2** nella barra laterale. Genererai un URL di invito con i permessi corretti per aggiungere il bot al tuo server.
|
||||
Fai clic su **OAuth2** nella barra laterale. Genererai un URL di invito con le autorizzazioni corrette per aggiungere il bot al tuo server.
|
||||
|
||||
Scorri verso il basso fino a **OAuth2 URL Generator** e abilita:
|
||||
Scorri fino a **OAuth2 URL Generator** e abilita:
|
||||
|
||||
- `bot`
|
||||
- `applications.commands`
|
||||
@ -79,31 +79,31 @@ Dovrai creare una nuova applicazione con un bot, aggiungere il bot al tuo server
|
||||
- Attach Files
|
||||
- Add Reactions (facoltativo)
|
||||
|
||||
Questo è l'insieme minimo di base per i normali canali di testo. Se prevedi di pubblicare nei thread di Discord, inclusi i flussi di lavoro dei canali forum o multimediali che creano o continuano un thread, abilita anche **Send Messages in Threads**.
|
||||
Copia l'URL generato in fondo, incollalo nel browser, seleziona il tuo server e fai clic su **Continue** per connetterlo. Ora dovresti vedere il tuo bot nel server Discord.
|
||||
Questo è l'insieme di base per i normali canali di testo. Se prevedi di pubblicare nei thread Discord, inclusi i flussi di lavoro dei canali forum o media che creano o continuano un thread, abilita anche **Send Messages in Threads**.
|
||||
Copia l'URL generato in fondo, incollalo nel browser, seleziona il tuo server e fai clic su **Continue** per collegarti. Ora dovresti vedere il tuo bot nel server Discord.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Abilita la Developer Mode e raccogli i tuoi ID">
|
||||
Tornando all'app Discord, devi abilitare la Developer Mode per poter copiare gli ID interni.
|
||||
<Step title="Abilita la modalità sviluppatore e raccogli i tuoi ID">
|
||||
Tornato nell'app Discord, devi abilitare la modalità sviluppatore per poter copiare gli ID interni.
|
||||
|
||||
1. Fai clic su **User Settings** (icona a ingranaggio accanto al tuo avatar) → **Advanced** → attiva **Developer Mode**
|
||||
2. Fai clic destro sull'**icona del server** nella barra laterale → **Copy Server ID**
|
||||
3. Fai clic destro sul **tuo avatar** → **Copy User ID**
|
||||
1. Fai clic su **User Settings** (icona dell'ingranaggio accanto al tuo avatar) → **Advanced** → attiva **Developer Mode**
|
||||
2. Fai clic con il pulsante destro sull'**icona del server** nella barra laterale → **Copy Server ID**
|
||||
3. Fai clic con il pulsante destro sul tuo **avatar** → **Copy User ID**
|
||||
|
||||
Salva il tuo **Server ID** e **User ID** insieme al Bot Token: invierai tutti e tre a OpenClaw nel passaggio successivo.
|
||||
Salva **Server ID** e **User ID** insieme al tuo Bot Token — invierai tutti e tre a OpenClaw nel passaggio successivo.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Consenti DM dai membri del server">
|
||||
Perché l'abbinamento funzioni, Discord deve consentire al tuo bot di inviarti DM. Fai clic destro sull'**icona del server** → **Privacy Settings** → attiva **Direct Messages**.
|
||||
<Step title="Consenti i DM dai membri del server">
|
||||
Perché l'abbinamento funzioni, Discord deve consentire al tuo bot di inviarti DM. Fai clic con il pulsante destro sull'**icona del server** → **Privacy Settings** → attiva **Direct Messages**.
|
||||
|
||||
Questo consente ai membri del server (inclusi i bot) di inviarti DM. Lascialo abilitato se vuoi usare le DM di Discord con OpenClaw. Se prevedi di usare solo i canali del server, puoi disabilitare i DM dopo l'abbinamento.
|
||||
Questo consente ai membri del server (inclusi i bot) di inviarti DM. Mantieni questa opzione abilitata se vuoi usare i DM di Discord con OpenClaw. Se prevedi di usare solo i canali guild, puoi disabilitare i DM dopo l'abbinamento.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Imposta in modo sicuro il token del tuo bot (non inviarlo in chat)">
|
||||
Il token del tuo bot Discord è un segreto (come una password). Impostalo sulla macchina che esegue OpenClaw prima di inviare un messaggio al tuo agente.
|
||||
Il token del tuo bot Discord è un segreto (come una password). Impostalo sulla macchina che esegue OpenClaw prima di inviare messaggi al tuo agente.
|
||||
|
||||
```bash
|
||||
export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
|
||||
@ -121,9 +121,9 @@ openclaw gateway
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Chiedi al tuo agente">
|
||||
Chatta con il tuo agente OpenClaw su qualsiasi canale esistente (ad esempio Telegram) e diglielo. Se Discord è il tuo primo canale, usa invece la scheda CLI / config.
|
||||
Scrivi al tuo agente OpenClaw su un qualsiasi canale esistente (ad esempio Telegram) e diglielo. Se Discord è il tuo primo canale, usa invece la scheda CLI / config.
|
||||
|
||||
> "Ho già impostato il token del mio bot Discord nella config. Completa la configurazione di Discord con User ID `<user_id>` e Server ID `<server_id>`."
|
||||
> "Ho già impostato il token del mio bot Discord nella configurazione. Per favore completa la configurazione di Discord con User ID `<user_id>` e Server ID `<server_id>`."
|
||||
</Tab>
|
||||
<Tab title="CLI / config">
|
||||
Se preferisci una configurazione basata su file, imposta:
|
||||
@ -149,7 +149,7 @@ openclaw gateway
|
||||
DISCORD_BOT_TOKEN=...
|
||||
```
|
||||
|
||||
Sono supportati valori `token` in testo normale. Sono supportati anche valori SecretRef per `channels.discord.token` nei provider env/file/exec. Vedi [Gestione dei segreti](/it/gateway/secrets).
|
||||
I valori `token` in testo semplice sono supportati. Sono supportati anche i valori SecretRef per `channels.discord.token` tramite provider env/file/exec. Vedi [Secrets Management](/it/gateway/secrets).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -157,7 +157,7 @@ DISCORD_BOT_TOKEN=...
|
||||
</Step>
|
||||
|
||||
<Step title="Approva il primo abbinamento DM">
|
||||
Attendi che il gateway sia in esecuzione, poi invia un DM al tuo bot su Discord. Risponderà con un codice di abbinamento.
|
||||
Attendi che il gateway sia in esecuzione, quindi invia un DM al tuo bot in Discord. Risponderà con un codice di abbinamento.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Chiedi al tuo agente">
|
||||
@ -177,27 +177,27 @@ openclaw pairing approve discord <CODE>
|
||||
|
||||
I codici di abbinamento scadono dopo 1 ora.
|
||||
|
||||
Ora dovresti essere in grado di chattare con il tuo agente su Discord tramite DM.
|
||||
Ora dovresti poter chattare con il tuo agente in Discord tramite DM.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
La risoluzione del token tiene conto dell'account. I valori del token nella config hanno priorità sul fallback env. `DISCORD_BOT_TOKEN` viene usato solo per l'account predefinito.
|
||||
Per chiamate outbound avanzate (azioni del canale/strumento message), un `token` esplicito per chiamata viene usato per quella chiamata. Questo vale per le azioni di invio e di lettura/sonda (ad esempio read/search/fetch/thread/pins/permissions). Le impostazioni di policy/retry dell'account continuano comunque a provenire dall'account selezionato nello snapshot di runtime attivo.
|
||||
La risoluzione del token tiene conto dell'account. I valori del token nella configurazione hanno la precedenza sul fallback env. `DISCORD_BOT_TOKEN` viene usato solo per l'account predefinito.
|
||||
Per le chiamate avanzate in uscita (strumento messaggi/azioni del canale), un `token` esplicito per chiamata viene usato per quella chiamata. Questo vale per le azioni di invio e di lettura/sonda (ad esempio read/search/fetch/thread/pins/permissions). Le impostazioni di policy/account e retry continuano comunque a provenire dall'account selezionato nello snapshot di runtime attivo.
|
||||
</Note>
|
||||
|
||||
## Consigliato: configura un'area di lavoro del server
|
||||
## Consigliato: configura un workspace guild
|
||||
|
||||
Una volta che le DM funzionano, puoi configurare il tuo server Discord come un'area di lavoro completa in cui ogni canale ottiene la propria sessione agente con il proprio contesto. Questa è l'opzione consigliata per server privati in cui ci siete solo tu e il tuo bot.
|
||||
Una volta che i DM funzionano, puoi configurare il tuo server Discord come workspace completo in cui ogni canale ottiene la propria sessione agente con il proprio contesto. Questo è consigliato per i server privati in cui ci siete solo tu e il tuo bot.
|
||||
|
||||
<Steps>
|
||||
<Step title="Aggiungi il tuo server all'allowlist dei server">
|
||||
Questo consente al tuo agente di rispondere in qualsiasi canale del tuo server, non solo nelle DM.
|
||||
<Step title="Aggiungi il tuo server alla allowlist delle guild">
|
||||
Questo consente al tuo agente di rispondere in qualsiasi canale del tuo server, non solo nei DM.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Chiedi al tuo agente">
|
||||
> "Aggiungi il mio Server ID Discord `<server_id>` all'allowlist dei server"
|
||||
> "Aggiungi il mio Server ID Discord `<server_id>` alla allowlist delle guild"
|
||||
</Tab>
|
||||
<Tab title="Config">
|
||||
|
||||
@ -223,14 +223,14 @@ Una volta che le DM funzionano, puoi configurare il tuo server Discord come un'a
|
||||
</Step>
|
||||
|
||||
<Step title="Consenti risposte senza @mention">
|
||||
Per impostazione predefinita, il tuo agente risponde nei canali del server solo quando viene menzionato con @. Per un server privato, probabilmente vorrai che risponda a ogni messaggio.
|
||||
Per impostazione predefinita, il tuo agente risponde nei canali guild solo quando viene @menzionato. Per un server privato, probabilmente vorrai che risponda a ogni messaggio.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Chiedi al tuo agente">
|
||||
> "Consenti al mio agente di rispondere su questo server senza dover essere menzionato con @"
|
||||
> "Consenti al mio agente di rispondere su questo server senza dover essere @menzionato"
|
||||
</Tab>
|
||||
<Tab title="Config">
|
||||
Imposta `requireMention: false` nella configurazione del server:
|
||||
Imposta `requireMention: false` nella configurazione della tua guild:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -251,40 +251,40 @@ Una volta che le DM funzionano, puoi configurare il tuo server Discord come un'a
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Pianifica la memoria nei canali del server">
|
||||
Per impostazione predefinita, la memoria a lungo termine (MEMORY.md) viene caricata solo nelle sessioni DM. I canali del server non caricano automaticamente MEMORY.md.
|
||||
<Step title="Pianifica la memoria nei canali guild">
|
||||
Per impostazione predefinita, la memoria a lungo termine (MEMORY.md) viene caricata solo nelle sessioni DM. I canali guild non caricano automaticamente MEMORY.md.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Chiedi al tuo agente">
|
||||
> "Quando faccio domande nei canali Discord, usa memory_search o memory_get se ti serve un contesto a lungo termine da MEMORY.md."
|
||||
> "Quando faccio domande nei canali Discord, usa memory_search o memory_get se ti serve contesto a lungo termine da MEMORY.md."
|
||||
</Tab>
|
||||
<Tab title="Manuale">
|
||||
Se ti serve un contesto condiviso in ogni canale, inserisci le istruzioni stabili in `AGENTS.md` o `USER.md` (vengono iniettati in ogni sessione). Mantieni le note a lungo termine in `MEMORY.md` e accedivi su richiesta con gli strumenti di memoria.
|
||||
Se hai bisogno di contesto condiviso in ogni canale, inserisci le istruzioni stabili in `AGENTS.md` o `USER.md` (vengono iniettati in ogni sessione). Mantieni le note a lungo termine in `MEMORY.md` e accedivi su richiesta con gli strumenti di memoria.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Ora crea alcuni canali sul tuo server Discord e inizia a chattare. Il tuo agente può vedere il nome del canale e ogni canale riceve la propria sessione isolata, quindi puoi configurare `#coding`, `#home`, `#research` o qualunque altra cosa si adatti al tuo flusso di lavoro.
|
||||
Ora crea alcuni canali sul tuo server Discord e inizia a chattare. Il tuo agente può vedere il nome del canale e ogni canale ottiene la propria sessione isolata — così puoi configurare `#coding`, `#home`, `#research` o qualsiasi altra cosa si adatti al tuo flusso di lavoro.
|
||||
|
||||
## Modello di runtime
|
||||
|
||||
- Il Gateway gestisce la connessione Discord.
|
||||
- L'instradamento delle risposte è deterministico: i messaggi in ingresso da Discord ricevono risposta su Discord.
|
||||
- L'instradamento delle risposte è deterministico: i messaggi in ingresso da Discord rispondono di nuovo su Discord.
|
||||
- Per impostazione predefinita (`session.dmScope=main`), le chat dirette condividono la sessione principale dell'agente (`agent:main:main`).
|
||||
- I canali del server hanno chiavi di sessione isolate (`agent:<agentId>:discord:channel:<channelId>`).
|
||||
- I canali guild sono chiavi di sessione isolate (`agent:<agentId>:discord:channel:<channelId>`).
|
||||
- I DM di gruppo vengono ignorati per impostazione predefinita (`channels.discord.dm.groupEnabled=false`).
|
||||
- I comandi slash nativi vengono eseguiti in sessioni di comando isolate (`agent:<agentId>:discord:slash:<userId>`), pur mantenendo `CommandTargetSessionKey` per la sessione di conversazione instradata.
|
||||
- I comandi slash nativi vengono eseguiti in sessioni di comando isolate (`agent:<agentId>:discord:slash:<userId>`), pur trasportando `CommandTargetSessionKey` verso la sessione di conversazione instradata.
|
||||
|
||||
## Canali forum
|
||||
|
||||
I canali forum e multimediali di Discord accettano solo post nei thread. OpenClaw supporta due modi per crearli:
|
||||
I canali forum e media di Discord accettano solo post in thread. OpenClaw supporta due modi per crearli:
|
||||
|
||||
- Invia un messaggio al forum padre (`channel:<forumId>`) per creare automaticamente un thread. Il titolo del thread usa la prima riga non vuota del tuo messaggio.
|
||||
- Invia un messaggio al padre forum (`channel:<forumId>`) per creare automaticamente un thread. Il titolo del thread usa la prima riga non vuota del tuo messaggio.
|
||||
- Usa `openclaw message thread create` per creare direttamente un thread. Non passare `--message-id` per i canali forum.
|
||||
|
||||
Esempio: invio al forum padre per creare un thread
|
||||
Esempio: invia al padre forum per creare un thread
|
||||
|
||||
```bash
|
||||
openclaw message send --channel discord --target channel:<forumId> \
|
||||
@ -298,11 +298,11 @@ openclaw message thread create --channel discord --target channel:<forumId> \
|
||||
--thread-name "Titolo dell'argomento" --message "Corpo del post"
|
||||
```
|
||||
|
||||
I forum padre non accettano componenti Discord. Se ti servono componenti, inviali al thread stesso (`channel:<threadId>`).
|
||||
I padri forum non accettano componenti Discord. Se hai bisogno di componenti, invia al thread stesso (`channel:<threadId>`).
|
||||
|
||||
## Componenti interattivi
|
||||
|
||||
OpenClaw supporta i contenitori dei componenti v2 di Discord per i messaggi dell'agente. Usa lo strumento message con un payload `components`. I risultati delle interazioni vengono instradati di nuovo all'agente come normali messaggi in ingresso e seguono le impostazioni esistenti di Discord `replyToMode`.
|
||||
OpenClaw supporta i contenitori components v2 di Discord per i messaggi dell'agente. Usa lo strumento messaggi con un payload `components`. I risultati delle interazioni vengono instradati di nuovo all'agente come normali messaggi in ingresso e seguono le impostazioni Discord `replyToMode` esistenti.
|
||||
|
||||
Blocchi supportati:
|
||||
|
||||
@ -310,17 +310,17 @@ Blocchi supportati:
|
||||
- Le righe di azione consentono fino a 5 pulsanti o un singolo menu di selezione
|
||||
- Tipi di selezione: `string`, `user`, `role`, `mentionable`, `channel`
|
||||
|
||||
Per impostazione predefinita, i componenti sono monouso. Imposta `components.reusable=true` per consentire a pulsanti, selezioni e moduli di essere usati più volte fino alla loro scadenza.
|
||||
Per impostazione predefinita, i componenti sono monouso. Imposta `components.reusable=true` per consentire che pulsanti, selettori e moduli vengano usati più volte fino alla loro scadenza.
|
||||
|
||||
Per limitare chi può fare clic su un pulsante, imposta `allowedUsers` su quel pulsante (ID utente Discord, tag o `*`). Quando configurato, gli utenti non corrispondenti ricevono un rifiuto effimero.
|
||||
|
||||
I comandi slash `/model` e `/models` aprono un selettore interattivo del modello con menu a discesa per provider e modello più un passaggio di invio. A meno che `commands.modelsWrite=false`, `/models add` supporta anche l'aggiunta di una nuova voce provider/modello dalla chat, e i modelli appena aggiunti compaiono senza riavviare il gateway. La risposta del selettore è effimera e solo l'utente che ha invocato il comando può usarla.
|
||||
I comandi slash `/model` e `/models` aprono un selettore di modelli interattivo con menu a discesa per provider e modello più un passaggio Submit. A meno che `commands.modelsWrite=false`, `/models add` supporta anche l'aggiunta di una nuova voce provider/modello dalla chat e i modelli appena aggiunti compaiono senza riavviare il gateway. La risposta del selettore è effimera e solo l'utente che lo invoca può usarla.
|
||||
|
||||
Allegati di file:
|
||||
Allegati file:
|
||||
|
||||
- I blocchi `file` devono puntare a un riferimento allegato (`attachment://<filename>`)
|
||||
- Fornisci l'allegato tramite `media`/`path`/`filePath` (file singolo); usa `media-gallery` per più file
|
||||
- Usa `filename` per sovrascrivere il nome di caricamento quando deve corrispondere al riferimento dell'allegato
|
||||
- Usa `filename` per sovrascrivere il nome di caricamento quando deve corrispondere al riferimento allegato
|
||||
|
||||
Moduli modali:
|
||||
|
||||
@ -385,20 +385,20 @@ Esempio:
|
||||
## Controllo degli accessi e instradamento
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Criterio DM">
|
||||
`channels.discord.dmPolicy` controlla l'accesso DM (legacy: `channels.discord.dm.policy`):
|
||||
<Tab title="Policy DM">
|
||||
`channels.discord.dmPolicy` controlla l'accesso ai DM (legacy: `channels.discord.dm.policy`):
|
||||
|
||||
- `pairing` (predefinito)
|
||||
- `allowlist`
|
||||
- `open` (richiede che `channels.discord.allowFrom` includa `"*"`; legacy: `channels.discord.dm.allowFrom`)
|
||||
- `disabled`
|
||||
|
||||
Se il criterio DM non è open, gli utenti sconosciuti vengono bloccati (oppure viene richiesto l'abbinamento in modalità `pairing`).
|
||||
Se la policy DM non è open, gli utenti sconosciuti vengono bloccati (oppure viene richiesto l'abbinamento in modalità `pairing`).
|
||||
|
||||
Precedenza multi-account:
|
||||
|
||||
- `channels.discord.accounts.default.allowFrom` si applica solo all'account `default`.
|
||||
- Gli account con nome ereditano `channels.discord.allowFrom` quando il loro `allowFrom` non è impostato.
|
||||
- Gli account con nome ereditano `channels.discord.allowFrom` quando il proprio `allowFrom` non è impostato.
|
||||
- Gli account con nome non ereditano `channels.discord.accounts.default.allowFrom`.
|
||||
|
||||
Formato del target DM per la consegna:
|
||||
@ -406,12 +406,12 @@ Esempio:
|
||||
- `user:<id>`
|
||||
- menzione `<@id>`
|
||||
|
||||
Gli ID numerici non qualificati sono ambigui e vengono rifiutati, a meno che non venga fornito esplicitamente un tipo di target utente/canale.
|
||||
Gli ID numerici semplici sono ambigui e vengono rifiutati a meno che non sia fornito un tipo di target utente/canale esplicito.
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Criterio del server">
|
||||
La gestione del server è controllata da `channels.discord.groupPolicy`:
|
||||
<Tab title="Policy guild">
|
||||
La gestione delle guild è controllata da `channels.discord.groupPolicy`:
|
||||
|
||||
- `open`
|
||||
- `allowlist`
|
||||
@ -421,12 +421,12 @@ Esempio:
|
||||
|
||||
Comportamento di `allowlist`:
|
||||
|
||||
- il server deve corrispondere a `channels.discord.guilds` (preferito `id`, slug accettato)
|
||||
- allowlist facoltative dei mittenti: `users` (consigliati ID stabili) e `roles` (solo ID di ruolo); se uno dei due è configurato, i mittenti sono consentiti quando corrispondono a `users` O `roles`
|
||||
- la corrispondenza diretta per nome/tag è disabilitata per impostazione predefinita; abilita `channels.discord.dangerouslyAllowNameMatching: true` solo come modalità di compatibilità d'emergenza
|
||||
- la guild deve corrispondere a `channels.discord.guilds` (`id` preferito, slug accettato)
|
||||
- allowlist facoltative del mittente: `users` (consigliati ID stabili) e `roles` (solo ID di ruolo); se una delle due è configurata, i mittenti sono consentiti quando corrispondono a `users` O `roles`
|
||||
- la corrispondenza diretta nome/tag è disabilitata per impostazione predefinita; abilita `channels.discord.dangerouslyAllowNameMatching: true` solo come modalità di compatibilità di emergenza
|
||||
- nomi/tag sono supportati per `users`, ma gli ID sono più sicuri; `openclaw security audit` avvisa quando vengono usate voci nome/tag
|
||||
- se un server ha `channels` configurato, i canali non elencati vengono negati
|
||||
- se un server non ha un blocco `channels`, tutti i canali in quel server in allowlist sono consentiti
|
||||
- se una guild ha `channels` configurato, i canali non elencati vengono negati
|
||||
- se una guild non ha un blocco `channels`, tutti i canali in quella guild in allowlist sono consentiti
|
||||
|
||||
Esempio:
|
||||
|
||||
@ -457,7 +457,7 @@ Esempio:
|
||||
</Tab>
|
||||
|
||||
<Tab title="Menzioni e DM di gruppo">
|
||||
I messaggi del server sono vincolati alle menzioni per impostazione predefinita.
|
||||
I messaggi guild sono vincolati alle menzioni per impostazione predefinita.
|
||||
|
||||
Il rilevamento delle menzioni include:
|
||||
|
||||
@ -465,7 +465,7 @@ Esempio:
|
||||
- pattern di menzione configurati (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
|
||||
- comportamento implicito di risposta al bot nei casi supportati
|
||||
|
||||
`requireMention` viene configurato per server/canale (`channels.discord.guilds...`).
|
||||
`requireMention` è configurato per guild/canale (`channels.discord.guilds...`).
|
||||
`ignoreOtherMentions` scarta facoltativamente i messaggi che menzionano un altro utente/ruolo ma non il bot (escludendo @everyone/@here).
|
||||
|
||||
DM di gruppo:
|
||||
@ -478,7 +478,7 @@ Esempio:
|
||||
|
||||
### Instradamento dell'agente basato sui ruoli
|
||||
|
||||
Usa `bindings[].match.roles` per instradare i membri dei server Discord verso agenti diversi in base all'ID del ruolo. I binding basati sui ruoli accettano solo ID di ruolo e vengono valutati dopo i binding peer o peer padre e prima dei binding solo-server. Se un binding imposta anche altri campi di corrispondenza (ad esempio `peer` + `guildId` + `roles`), tutti i campi configurati devono corrispondere.
|
||||
Usa `bindings[].match.roles` per instradare i membri delle guild Discord a diversi agenti in base all'ID del ruolo. I binding basati sui ruoli accettano solo ID di ruolo e vengono valutati dopo i binding peer o parent-peer e prima dei binding solo-guild. Se un binding imposta anche altri campi di corrispondenza (ad esempio `peer` + `guildId` + `roles`), tutti i campi configurati devono corrispondere.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -519,16 +519,16 @@ Usa `bindings[].match.roles` per instradare i membri dei server Discord verso ag
|
||||
- Message Content Intent
|
||||
- Server Members Intent (consigliato)
|
||||
|
||||
Presence intent è facoltativo ed è richiesto solo se vuoi ricevere aggiornamenti di presenza. L'impostazione della presenza del bot (`setPresence`) non richiede l'abilitazione degli aggiornamenti di presenza per i membri.
|
||||
Presence Intent è facoltativo ed è richiesto solo se vuoi ricevere aggiornamenti di presenza. L'impostazione della presenza del bot (`setPresence`) non richiede l'abilitazione degli aggiornamenti di presenza per i membri.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Scope OAuth e permessi di base">
|
||||
<Accordion title="Scope OAuth e autorizzazioni di base">
|
||||
Generatore URL OAuth:
|
||||
|
||||
- scope: `bot`, `applications.commands`
|
||||
|
||||
Permessi di base tipici:
|
||||
Autorizzazioni di base tipiche:
|
||||
|
||||
**General Permissions**
|
||||
- View Channels
|
||||
@ -539,32 +539,32 @@ Usa `bindings[].match.roles` per instradare i membri dei server Discord verso ag
|
||||
- Attach Files
|
||||
- Add Reactions (facoltativo)
|
||||
|
||||
Questo è l'insieme minimo di base per i normali canali di testo. Se prevedi di pubblicare nei thread di Discord, inclusi i flussi di lavoro dei canali forum o multimediali che creano o continuano un thread, abilita anche **Send Messages in Threads**.
|
||||
Questo è l'insieme di base per i normali canali di testo. Se prevedi di pubblicare nei thread Discord, inclusi i flussi di lavoro dei canali forum o media che creano o continuano un thread, abilita anche **Send Messages in Threads**.
|
||||
Evita `Administrator` a meno che non sia esplicitamente necessario.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Copia ID">
|
||||
Abilita la Discord Developer Mode, quindi copia:
|
||||
<Accordion title="Copia gli ID">
|
||||
Abilita la modalità sviluppatore di Discord, quindi copia:
|
||||
|
||||
- ID server
|
||||
- ID canale
|
||||
- ID utente
|
||||
|
||||
Preferisci ID numerici nella config di OpenClaw per audit e probe affidabili.
|
||||
Preferisci gli ID numerici nella configurazione OpenClaw per audit e probe affidabili.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Comandi nativi e autenticazione dei comandi
|
||||
|
||||
- `commands.native` ha come valore predefinito `"auto"` ed è abilitato per Discord.
|
||||
- `commands.native` è predefinito su `"auto"` ed è abilitato per Discord.
|
||||
- Override per canale: `channels.discord.commands.native`.
|
||||
- `commands.native=false` cancella esplicitamente i comandi nativi Discord registrati in precedenza.
|
||||
- L'autenticazione dei comandi nativi usa le stesse allowlist/policy di Discord della normale gestione dei messaggi.
|
||||
- I comandi possono comunque essere visibili nell'interfaccia di Discord per utenti non autorizzati; l'esecuzione applica comunque l'autorizzazione OpenClaw e restituisce "non autorizzato".
|
||||
- L'autenticazione dei comandi nativi usa le stesse allowlist/policy Discord della normale gestione dei messaggi.
|
||||
- I comandi possono comunque essere visibili nell'interfaccia Discord agli utenti non autorizzati; l'esecuzione continua comunque ad applicare l'autorizzazione OpenClaw e restituisce "non autorizzato".
|
||||
|
||||
Vedi [Comandi slash](/it/tools/slash-commands) per il catalogo e il comportamento dei comandi.
|
||||
Vedi [Slash commands](/it/tools/slash-commands) per il catalogo dei comandi e il comportamento.
|
||||
|
||||
Impostazioni predefinite dei comandi slash:
|
||||
|
||||
@ -574,7 +574,7 @@ Impostazioni predefinite dei comandi slash:
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Tag di risposta e risposte native">
|
||||
Discord supporta tag di risposta nell'output dell'agente:
|
||||
Discord supporta i tag di risposta nell'output dell'agente:
|
||||
|
||||
- `[[reply_to_current]]`
|
||||
- `[[reply_to:<id>]]`
|
||||
@ -588,40 +588,16 @@ Impostazioni predefinite dei comandi slash:
|
||||
|
||||
Nota: `off` disabilita il threading implicito delle risposte. I tag espliciti `[[reply_to_*]]` vengono comunque rispettati.
|
||||
`first` allega sempre il riferimento implicito di risposta nativa al primo messaggio Discord in uscita del turno.
|
||||
`batched` allega il riferimento implicito di risposta nativa di Discord solo quando il
|
||||
turno in ingresso era un batch con debounce di più messaggi. Questo è utile
|
||||
quando vuoi risposte native soprattutto per chat ambigue e intense, non per ogni
|
||||
singolo turno con un solo messaggio.
|
||||
`batched` allega il riferimento implicito di risposta nativa di Discord solo quando il turno in ingresso era un batch con debounce di più messaggi. Questo è utile quando vuoi risposte native soprattutto per chat ambigue e concitate, non per ogni singolo turno con un solo messaggio.
|
||||
|
||||
Gli ID messaggio sono esposti in contesto/cronologia così che gli agenti possano puntare a messaggi specifici.
|
||||
Gli ID dei messaggi vengono esposti nel contesto/nella cronologia così che gli agenti possano indirizzare messaggi specifici.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Anteprima dello streaming live">
|
||||
OpenClaw può trasmettere bozze di risposta inviando un messaggio temporaneo e modificandolo man mano che arriva il testo.
|
||||
<Accordion title="Anteprima dello stream live">
|
||||
OpenClaw può trasmettere bozze di risposta inviando un messaggio temporaneo e modificandolo man mano che arriva il testo. `channels.discord.streaming` accetta `off` (predefinito) | `partial` | `block` | `progress`. `progress` viene mappato a `partial` su Discord; `streamMode` è un alias legacy e viene migrato automaticamente.
|
||||
|
||||
- `channels.discord.streaming` controlla lo streaming di anteprima (`off` | `partial` | `block` | `progress`, predefinito: `off`).
|
||||
- Il valore predefinito resta `off` perché le modifiche di anteprima di Discord possono raggiungere rapidamente i limiti di frequenza, soprattutto quando più bot o gateway condividono lo stesso account o il traffico del server.
|
||||
- `progress` è accettato per coerenza tra canali e viene mappato a `partial` su Discord.
|
||||
- `channels.discord.streamMode` è un alias legacy e viene migrato automaticamente.
|
||||
- `partial` modifica un singolo messaggio di anteprima man mano che arrivano i token.
|
||||
- `block` emette blocchi della dimensione di una bozza (usa `draftChunk` per regolare dimensione e punti di interruzione).
|
||||
- Le risposte con media, errore e risposta esplicita annullano le modifiche di anteprima in sospeso senza svuotare una bozza temporanea prima della consegna normale.
|
||||
- `streaming.preview.toolProgress` controlla se gli aggiornamenti di strumento/progresso riutilizzano lo stesso messaggio di anteprima della bozza (predefinito: `true`). Imposta `false` per mantenere separati i messaggi di strumento/progresso.
|
||||
|
||||
Esempio:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
discord: {
|
||||
streaming: "partial",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Valori predefiniti di suddivisione in blocchi per la modalità `block` (limitati da `channels.discord.textChunkLimit`):
|
||||
Il valore predefinito resta `off` perché le modifiche di anteprima su Discord raggiungono rapidamente i limiti di velocità quando più bot o gateway condividono un account.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -638,15 +614,17 @@ Impostazioni predefinite dei comandi slash:
|
||||
}
|
||||
```
|
||||
|
||||
Lo streaming di anteprima è solo testuale; le risposte multimediali usano la consegna normale come fallback.
|
||||
- `partial` modifica un singolo messaggio di anteprima man mano che arrivano i token.
|
||||
- `block` emette blocchi grandi quanto una bozza (usa `draftChunk` per regolare dimensione e punti di interruzione, limitati a `textChunkLimit`).
|
||||
- Media, errori e finali con risposta esplicita annullano le modifiche di anteprima in sospeso.
|
||||
- `streaming.preview.toolProgress` (predefinito `true`) controlla se gli aggiornamenti di strumenti/progresso riutilizzano il messaggio di anteprima.
|
||||
|
||||
Nota: lo streaming di anteprima è separato dallo streaming a blocchi. Quando lo streaming a blocchi è esplicitamente
|
||||
abilitato per Discord, OpenClaw salta il flusso di anteprima per evitare un doppio streaming.
|
||||
Lo streaming di anteprima è solo testuale; le risposte media tornano alla consegna normale. Quando lo streaming `block` è esplicitamente abilitato, OpenClaw salta lo stream di anteprima per evitare un doppio streaming.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Cronologia, contesto e comportamento dei thread">
|
||||
Contesto della cronologia del server:
|
||||
Contesto della cronologia guild:
|
||||
|
||||
- `channels.discord.historyLimit` predefinito `20`
|
||||
- fallback: `messages.groupChat.historyLimit`
|
||||
@ -659,32 +637,27 @@ Impostazioni predefinite dei comandi slash:
|
||||
|
||||
Comportamento dei thread:
|
||||
|
||||
- i thread Discord vengono instradati come sessioni di canale
|
||||
- i metadati del thread padre possono essere usati per il collegamento alla sessione padre
|
||||
- la configurazione del thread eredita la configurazione del canale padre, a meno che non esista una voce specifica per il thread
|
||||
- l'ereditarietà della trascrizione del padre nei nuovi thread automatici è opt-in tramite `channels.discord.thread.inheritParent` (predefinito `false`). Quando è `false`, le nuove sessioni thread Discord iniziano isolate dalla trascrizione del canale padre; quando è `true`, la cronologia del canale padre inizializza la nuova sessione thread
|
||||
- gli override per account si trovano in `channels.discord.accounts.<id>.thread.inheritParent`
|
||||
- le reazioni dello strumento message possono risolvere target DM `user:<id>` oltre ai target di canale
|
||||
- `channels.discord.guilds.<guild>.channels.<channel>.requireMention: false` viene preservato durante il fallback di attivazione nella fase di risposta, quindi i canali configurati come sempre attivi restano sempre attivi anche quando viene eseguito il fallback nella fase di risposta
|
||||
- I thread Discord vengono instradati come sessioni di canale ed ereditano la configurazione del canale padre se non sovrascritta.
|
||||
- `channels.discord.thread.inheritParent` (predefinito `false`) fa sì che i nuovi thread automatici ereditino il transcript del padre. Gli override per account si trovano sotto `channels.discord.accounts.<id>.thread.inheritParent`.
|
||||
- Le reazioni dello strumento messaggi possono risolvere target DM `user:<id>`.
|
||||
- `guilds.<guild>.channels.<channel>.requireMention: false` viene preservato durante il fallback di attivazione nella fase di risposta.
|
||||
|
||||
Gli argomenti del canale vengono iniettati come contesto **non attendibile** (non come prompt di sistema).
|
||||
Il contesto di risposta e dei messaggi citati attualmente rimane così come ricevuto.
|
||||
Le allowlist Discord limitano principalmente chi può attivare l'agente, non costituiscono un confine completo di redazione del contesto supplementare.
|
||||
Gli argomenti del canale vengono iniettati come contesto **non attendibile**. Le allowlist regolano chi può attivare l'agente, non un confine completo di redazione del contesto supplementare.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Sessioni vincolate al thread per i subagenti">
|
||||
Discord può associare un thread a un target di sessione in modo che i messaggi successivi in quel thread continuino a essere instradati verso la stessa sessione (incluse le sessioni dei subagenti).
|
||||
<Accordion title="Sessioni vincolate al thread per i sottoagenti">
|
||||
Discord può associare un thread a un target di sessione in modo che i messaggi successivi in quel thread continuino a essere instradati verso la stessa sessione (incluse le sessioni di sottoagenti).
|
||||
|
||||
Comandi:
|
||||
|
||||
- `/focus <target>` associa il thread corrente/nuovo a un target di subagente/sessione
|
||||
- `/focus <target>` associa il thread corrente/nuovo a un target di sottoagente/sessione
|
||||
- `/unfocus` rimuove l'associazione del thread corrente
|
||||
- `/agents` mostra le esecuzioni attive e lo stato delle associazioni
|
||||
- `/session idle <duration|off>` ispeziona/aggiorna la rimozione automatica del focus per inattività per le associazioni focalizzate
|
||||
- `/session max-age <duration|off>` ispeziona/aggiorna l'età massima rigida per le associazioni focalizzate
|
||||
- `/agents` mostra le esecuzioni attive e lo stato dell'associazione
|
||||
- `/session idle <duration|off>` controlla/aggiorna la rimozione automatica dell'associazione per inattività per i binding focalizzati
|
||||
- `/session max-age <duration|off>` controlla/aggiorna l'età massima rigida per i binding focalizzati
|
||||
|
||||
Config:
|
||||
Configurazione:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -712,16 +685,16 @@ Impostazioni predefinite dei comandi slash:
|
||||
|
||||
- `session.threadBindings.*` imposta i valori predefiniti globali.
|
||||
- `channels.discord.threadBindings.*` sovrascrive il comportamento di Discord.
|
||||
- `spawnSubagentSessions` deve essere true per creare/associare automaticamente thread per `sessions_spawn({ thread: true })`.
|
||||
- `spawnAcpSessions` deve essere true per creare/associare automaticamente thread per ACP (`/acp spawn ... --thread ...` o `sessions_spawn({ runtime: "acp", thread: true })`).
|
||||
- Se le associazioni dei thread sono disabilitate per un account, `/focus` e le operazioni correlate di associazione del thread non sono disponibili.
|
||||
- `spawnSubagentSessions` deve essere `true` per creare/associare automaticamente thread per `sessions_spawn({ thread: true })`.
|
||||
- `spawnAcpSessions` deve essere `true` per creare/associare automaticamente thread per ACP (`/acp spawn ... --thread ...` o `sessions_spawn({ runtime: "acp", thread: true })`).
|
||||
- Se i thread binding sono disabilitati per un account, `/focus` e le relative operazioni di thread binding non sono disponibili.
|
||||
|
||||
Vedi [Sub-agents](/it/tools/subagents), [ACP Agents](/it/tools/acp-agents) e [Configuration Reference](/it/gateway/configuration-reference).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Associazioni persistenti dei canali ACP">
|
||||
Per aree di lavoro ACP stabili "sempre attive", configura associazioni ACP tipizzate di livello superiore che puntano a conversazioni Discord.
|
||||
<Accordion title="Binding persistenti dei canali ACP">
|
||||
Per workspace ACP stabili “sempre attivi”, configura binding ACP tipizzati di livello superiore indirizzati alle conversazioni Discord.
|
||||
|
||||
Percorso config:
|
||||
|
||||
@ -777,20 +750,16 @@ Impostazioni predefinite dei comandi slash:
|
||||
|
||||
Note:
|
||||
|
||||
- `/acp spawn codex --bind here` associa il canale o thread Discord corrente sul posto e mantiene i messaggi futuri instradati alla stessa sessione ACP.
|
||||
- Questo può comunque significare "avvia una nuova sessione ACP Codex", ma non crea da solo un nuovo thread Discord. Il canale esistente resta la superficie di chat.
|
||||
- Codex può comunque essere eseguito nel proprio `cwd` o nello spazio di lavoro backend su disco. Quello spazio di lavoro è stato di runtime, non un thread Discord.
|
||||
- I messaggi del thread possono ereditare l'associazione ACP del canale padre.
|
||||
- In un canale o thread associato, `/new` e `/reset` reimpostano sul posto la stessa sessione ACP.
|
||||
- Le associazioni temporanee del thread funzionano comunque e possono sovrascrivere la risoluzione del target mentre sono attive.
|
||||
- `spawnAcpSessions` è richiesto solo quando OpenClaw deve creare/associare un thread figlio tramite `--thread auto|here`. Non è richiesto per `/acp spawn ... --bind here` nel canale corrente.
|
||||
- `/acp spawn codex --bind here` associa il canale o thread corrente sul posto e mantiene i messaggi futuri sulla stessa sessione ACP. I messaggi del thread ereditano il binding del canale padre.
|
||||
- In un canale o thread associato, `/new` e `/reset` reimpostano la stessa sessione ACP sul posto. I binding temporanei del thread possono sovrascrivere la risoluzione del target mentre sono attivi.
|
||||
- `spawnAcpSessions` è richiesto solo quando OpenClaw deve creare/associare un thread figlio tramite `--thread auto|here`.
|
||||
|
||||
Vedi [ACP Agents](/it/tools/acp-agents) per i dettagli sul comportamento delle associazioni.
|
||||
Vedi [ACP Agents](/it/tools/acp-agents) per i dettagli sul comportamento dei binding.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Notifiche di reazione">
|
||||
Modalità di notifica delle reazioni per server:
|
||||
<Accordion title="Notifiche delle reazioni">
|
||||
Modalità di notifica delle reazioni per guild:
|
||||
|
||||
- `off`
|
||||
- `own` (predefinito)
|
||||
@ -802,24 +771,24 @@ Impostazioni predefinite dei comandi slash:
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reazioni di conferma">
|
||||
`ackReaction` invia un emoji di conferma mentre OpenClaw sta elaborando un messaggio in ingresso.
|
||||
`ackReaction` invia un'emoji di conferma mentre OpenClaw sta elaborando un messaggio in ingresso.
|
||||
|
||||
Ordine di risoluzione:
|
||||
|
||||
- `channels.discord.accounts.<accountId>.ackReaction`
|
||||
- `channels.discord.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- fallback emoji dell'identità dell'agente (`agents.list[].identity.emoji`, altrimenti "👀")
|
||||
- fallback emoji identità agente (`agents.list[].identity.emoji`, altrimenti "👀")
|
||||
|
||||
Note:
|
||||
|
||||
- Discord accetta emoji Unicode o nomi di emoji personalizzate.
|
||||
- Discord accetta emoji unicode o nomi di emoji personalizzate.
|
||||
- Usa `""` per disabilitare la reazione per un canale o account.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Scritture di config">
|
||||
Le scritture di config avviate dal canale sono abilitate per impostazione predefinita.
|
||||
<Accordion title="Scritture di configurazione">
|
||||
Le scritture di configurazione avviate dal canale sono abilitate per impostazione predefinita.
|
||||
|
||||
Questo influisce sui flussi `/config set|unset` (quando le funzionalità dei comandi sono abilitate).
|
||||
|
||||
@ -838,7 +807,7 @@ Impostazioni predefinite dei comandi slash:
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Proxy Gateway">
|
||||
Instrada il traffico WebSocket del gateway Discord e le lookup REST di avvio (ID applicazione + risoluzione allowlist) tramite un proxy HTTP(S) con `channels.discord.proxy`.
|
||||
Instrada il traffico WebSocket del gateway Discord e le ricerche REST all'avvio (ID applicazione + risoluzione allowlist) tramite un proxy HTTP(S) con `channels.discord.proxy`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -869,7 +838,7 @@ Impostazioni predefinite dei comandi slash:
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Supporto PluralKit">
|
||||
Abilita la risoluzione PluralKit per mappare i messaggi inoltrati all'identità del membro del sistema:
|
||||
Abilita la risoluzione PluralKit per mappare i messaggi proxy all'identità del membro del sistema:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -887,14 +856,14 @@ Impostazioni predefinite dei comandi slash:
|
||||
Note:
|
||||
|
||||
- le allowlist possono usare `pk:<memberId>`
|
||||
- i nomi visualizzati dei membri vengono associati per nome/slug solo quando `channels.discord.dangerouslyAllowNameMatching: true`
|
||||
- le lookup usano l'ID messaggio originale e sono vincolate da una finestra temporale
|
||||
- se la lookup fallisce, i messaggi inoltrati vengono trattati come messaggi del bot e scartati, a meno che `allowBots=true`
|
||||
- i nomi visualizzati dei membri vengono confrontati per nome/slug solo quando `channels.discord.dangerouslyAllowNameMatching: true`
|
||||
- le ricerche usano l'ID messaggio originale e sono vincolate a una finestra temporale
|
||||
- se la ricerca fallisce, i messaggi proxy vengono trattati come messaggi del bot e scartati a meno che `allowBots=true`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Configurazione della presenza">
|
||||
Gli aggiornamenti della presenza vengono applicati quando imposti un campo di stato o attività, oppure quando abiliti la presenza automatica.
|
||||
Gli aggiornamenti di presenza vengono applicati quando imposti un campo di stato o attività, oppure quando abiliti la presenza automatica.
|
||||
|
||||
Esempio solo stato:
|
||||
|
||||
@ -914,7 +883,7 @@ Impostazioni predefinite dei comandi slash:
|
||||
{
|
||||
channels: {
|
||||
discord: {
|
||||
activity: "Momento di concentrazione",
|
||||
activity: "Tempo di concentrazione",
|
||||
activityType: 4,
|
||||
},
|
||||
},
|
||||
@ -927,7 +896,7 @@ Impostazioni predefinite dei comandi slash:
|
||||
{
|
||||
channels: {
|
||||
discord: {
|
||||
activity: "Coding dal vivo",
|
||||
activity: "Coding live",
|
||||
activityType: 1,
|
||||
activityUrl: "https://twitch.tv/openclaw",
|
||||
},
|
||||
@ -937,14 +906,14 @@ Impostazioni predefinite dei comandi slash:
|
||||
|
||||
Mappa dei tipi di attività:
|
||||
|
||||
- 0: Playing
|
||||
- 1: Streaming (richiede `activityUrl`)
|
||||
- 2: Listening
|
||||
- 3: Watching
|
||||
- 4: Custom (usa il testo dell'attività come stato; l'emoji è facoltativa)
|
||||
- 5: Competing
|
||||
- 0: Giocando
|
||||
- 1: In streaming (richiede `activityUrl`)
|
||||
- 2: In ascolto
|
||||
- 3: Guardando
|
||||
- 4: Personalizzata (usa il testo dell'attività come stato; l'emoji è facoltativa)
|
||||
- 5: Competendo
|
||||
|
||||
Esempio presenza automatica (segnale di integrità del runtime):
|
||||
Esempio di presenza automatica (segnale di salute del runtime):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -961,7 +930,7 @@ Impostazioni predefinite dei comandi slash:
|
||||
}
|
||||
```
|
||||
|
||||
La presenza automatica mappa la disponibilità del runtime allo stato Discord: healthy => online, degraded o unknown => idle, exhausted o unavailable => dnd. Override di testo facoltativi:
|
||||
La presenza automatica mappa la disponibilità del runtime allo stato Discord: sano => online, degradato o sconosciuto => idle, esaurito o non disponibile => dnd. Override testuali facoltativi:
|
||||
|
||||
- `autoPresence.healthyText`
|
||||
- `autoPresence.degradedText`
|
||||
@ -970,43 +939,25 @@ Impostazioni predefinite dei comandi slash:
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Approvazioni in Discord">
|
||||
Discord supporta la gestione delle approvazioni basata su pulsanti nelle DM e può facoltativamente pubblicare prompt di approvazione nel canale di origine.
|
||||
Discord supporta la gestione delle approvazioni basata su pulsanti nei DM e può facoltativamente pubblicare i prompt di approvazione nel canale di origine.
|
||||
|
||||
Percorso config:
|
||||
|
||||
- `channels.discord.execApprovals.enabled`
|
||||
- `channels.discord.execApprovals.approvers` (facoltativo; fallback a `commands.ownerAllowFrom` quando possibile)
|
||||
- `channels.discord.execApprovals.approvers` (facoltativo; usa `commands.ownerAllowFrom` come fallback quando possibile)
|
||||
- `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, predefinito: `dm`)
|
||||
- `agentFilter`, `sessionFilter`, `cleanupAfterResolve`
|
||||
|
||||
Discord abilita automaticamente le approvazioni exec native quando `enabled` non è impostato oppure è `"auto"` e può essere risolto almeno un approvatore, da `execApprovals.approvers` o da `commands.ownerAllowFrom`. Discord non deduce gli approvatori exec da `allowFrom` del canale, dal legacy `dm.allowFrom` o da `defaultTo` dei messaggi diretti. Imposta `enabled: false` per disabilitare esplicitamente Discord come client di approvazione nativo.
|
||||
Discord abilita automaticamente le approvazioni exec native quando `enabled` non è impostato o è `"auto"` e può essere risolto almeno un approvatore, da `execApprovals.approvers` oppure da `commands.ownerAllowFrom`. Discord non deduce gli approvatori exec da `allowFrom` del canale, da `dm.allowFrom` legacy o da `defaultTo` dei messaggi diretti. Imposta `enabled: false` per disabilitare esplicitamente Discord come client di approvazione nativo.
|
||||
|
||||
Quando `target` è `channel` o `both`, il prompt di approvazione è visibile nel canale. Solo gli approvatori risolti possono usare i pulsanti; gli altri utenti ricevono un rifiuto effimero. I prompt di approvazione includono il testo del comando, quindi abilita la consegna nel canale solo in canali affidabili. Se l'ID del canale non può essere derivato dalla chiave di sessione, OpenClaw usa come fallback la consegna via DM.
|
||||
Quando `target` è `channel` o `both`, il prompt di approvazione è visibile nel canale. Solo gli approvatori risolti possono usare i pulsanti; gli altri utenti ricevono un rifiuto effimero. I prompt di approvazione includono il testo del comando, quindi abilita la consegna nel canale solo nei canali attendibili. Se l'ID del canale non può essere derivato dalla chiave di sessione, OpenClaw torna alla consegna tramite DM.
|
||||
|
||||
Discord renderizza anche i pulsanti di approvazione condivisi usati da altri canali di chat. L'adapter Discord nativo aggiunge principalmente l'instradamento DM degli approvatori e il fanout sul canale.
|
||||
Quando questi pulsanti sono presenti, rappresentano l'esperienza utente di approvazione principale; 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.
|
||||
Discord renderizza anche i pulsanti di approvazione condivisi usati da altri canali di chat. L'adapter nativo Discord aggiunge principalmente l'instradamento DM degli approvatori e il fanout del canale.
|
||||
Quando questi pulsanti sono presenti, rappresentano l'esperienza utente di approvazione principale; 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.
|
||||
|
||||
L'autenticazione Gateway per questo gestore usa lo stesso contratto condiviso di risoluzione delle credenziali degli altri client Gateway:
|
||||
L'autenticazione Gateway e la risoluzione delle approvazioni seguono il contratto client Gateway condiviso (`plugin:` IDs vengono risolti tramite `plugin.approval.resolve`; gli altri ID tramite `exec.approval.resolve`). Le approvazioni scadono dopo 30 minuti per impostazione predefinita.
|
||||
|
||||
- autenticazione locale env-first (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` poi `gateway.auth.*`)
|
||||
- in modalità locale, `gateway.remote.*` può essere usato come fallback solo quando `gateway.auth.*` non è impostato; SecretRef locali configurati ma non risolti falliscono in modo chiuso
|
||||
- supporto in modalità remota tramite `gateway.remote.*` quando applicabile
|
||||
- gli override URL sono sicuri rispetto agli override: gli override CLI non riutilizzano credenziali implicite e gli override env usano solo credenziali env
|
||||
|
||||
Comportamento della risoluzione delle approvazioni:
|
||||
|
||||
- Gli ID con prefisso `plugin:` vengono risolti tramite `plugin.approval.resolve`.
|
||||
- Gli altri ID vengono risolti tramite `exec.approval.resolve`.
|
||||
- Discord non esegue qui un ulteriore fallback exec-to-plugin; il
|
||||
prefisso dell'id decide quale metodo gateway chiamare.
|
||||
|
||||
Le approvazioni exec scadono dopo 30 minuti per impostazione predefinita. Se le approvazioni falliscono con
|
||||
ID di approvazione sconosciuti, verifica la risoluzione degli approvatori, l'abilitazione della funzionalità e
|
||||
che il tipo di id di approvazione consegnato corrisponda alla richiesta in sospeso.
|
||||
|
||||
Documentazione correlata: [Exec approvals](/it/tools/exec-approvals)
|
||||
Vedi [Exec approvals](/it/tools/exec-approvals).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -1022,9 +973,9 @@ Esempi principali:
|
||||
- moderazione: `timeout`, `kick`, `ban`
|
||||
- presenza: `setPresence`
|
||||
|
||||
L'azione `event-create` accetta un parametro facoltativo `image` (URL o percorso di file locale) per impostare l'immagine di copertina dell'evento programmato.
|
||||
L'azione `event-create` accetta un parametro `image` facoltativo (URL o percorso di file locale) per impostare l'immagine di copertina dell'evento pianificato.
|
||||
|
||||
I gate delle azioni si trovano in `channels.discord.actions.*`.
|
||||
I gate delle azioni si trovano sotto `channels.discord.actions.*`.
|
||||
|
||||
Comportamento predefinito dei gate:
|
||||
|
||||
@ -1037,11 +988,11 @@ Comportamento predefinito dei gate:
|
||||
|
||||
## UI Components v2
|
||||
|
||||
OpenClaw usa i componenti Discord v2 per exec approvals e marcatori cross-context. Le azioni dei messaggi Discord possono anche accettare `components` per un'interfaccia utente personalizzata (avanzato; richiede la costruzione di un payload componente tramite lo strumento discord), mentre i `embeds` legacy restano disponibili ma non sono consigliati.
|
||||
OpenClaw usa i components v2 di Discord per le approvazioni exec e i marcatori cross-context. Le azioni dei messaggi Discord possono anche accettare `components` per UI personalizzate (avanzato; richiede la costruzione di un payload di componenti tramite lo strumento Discord), mentre i `embeds` legacy restano disponibili ma non sono consigliati.
|
||||
|
||||
- `channels.discord.ui.components.accentColor` imposta il colore di accento usato dai contenitori dei componenti Discord (hex).
|
||||
- Impostalo per account con `channels.discord.accounts.<id>.ui.components.accentColor`.
|
||||
- `embeds` vengono ignorati quando sono presenti componenti v2.
|
||||
- Imposta per account con `channels.discord.accounts.<id>.ui.components.accentColor`.
|
||||
- `embeds` vengono ignorati quando sono presenti components v2.
|
||||
|
||||
Esempio:
|
||||
|
||||
@ -1059,17 +1010,19 @@ Esempio:
|
||||
}
|
||||
```
|
||||
|
||||
## Canali vocali
|
||||
## Voce
|
||||
|
||||
OpenClaw può entrare nei canali vocali Discord per conversazioni continue in tempo reale. Questa funzionalità è separata dagli allegati di messaggi vocali.
|
||||
Discord ha due superfici vocali distinte: i **canali vocali** realtime (conversazioni continue) e gli **allegati di messaggi vocali** (il formato con anteprima waveform). Il gateway supporta entrambi.
|
||||
|
||||
### Canali vocali
|
||||
|
||||
Requisiti:
|
||||
|
||||
- Abilita i comandi nativi (`commands.native` o `channels.discord.commands.native`).
|
||||
- Configura `channels.discord.voice`.
|
||||
- Il bot deve avere i permessi Connect + Speak nel canale vocale di destinazione.
|
||||
- Il bot necessita dei permessi Connect + Speak nel canale vocale di destinazione.
|
||||
|
||||
Usa il comando nativo solo Discord `/vc join|leave|status` per controllare le sessioni. Il comando usa l'agente predefinito dell'account e segue le stesse regole di allowlist e group policy degli altri comandi Discord.
|
||||
Usa `/vc join|leave|status` per controllare le sessioni. Il comando usa l'agente predefinito dell'account e segue le stesse regole di allowlist e group policy degli altri comandi Discord.
|
||||
|
||||
Esempio di join automatico:
|
||||
|
||||
@ -1100,24 +1053,20 @@ Esempio di join automatico:
|
||||
Note:
|
||||
|
||||
- `voice.tts` sovrascrive `messages.tts` solo per la riproduzione vocale.
|
||||
- I turni di trascrizione vocale derivano lo stato del proprietario da Discord `allowFrom` (o `dm.allowFrom`); gli speaker non proprietari non possono accedere agli strumenti riservati al proprietario (ad esempio `gateway` e `cron`).
|
||||
- I turni di trascrizione vocale derivano lo stato di owner da Discord `allowFrom` (o `dm.allowFrom`); gli speaker non owner non possono accedere agli strumenti riservati all'owner (ad esempio `gateway` e `cron`).
|
||||
- La voce è abilitata per impostazione predefinita; imposta `channels.discord.voice.enabled=false` per disabilitarla.
|
||||
- `voice.daveEncryption` e `voice.decryptionFailureTolerance` vengono passati alle opzioni di join di `@discordjs/voice`.
|
||||
- I valori predefiniti di `@discordjs/voice` sono `daveEncryption=true` e `decryptionFailureTolerance=24` se non impostati.
|
||||
- OpenClaw monitora anche gli errori di decifratura in ricezione e si ripristina automaticamente uscendo e rientrando nel canale vocale dopo errori ripetuti in una breve finestra temporale.
|
||||
- OpenClaw monitora anche gli errori di decrittazione in ricezione e si ripristina automaticamente uscendo/rientrando nel canale vocale dopo errori ripetuti in una breve finestra temporale.
|
||||
- Se i log di ricezione mostrano ripetutamente `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, potrebbe trattarsi del bug di ricezione upstream di `@discordjs/voice` tracciato in [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419).
|
||||
|
||||
## Messaggi vocali
|
||||
### Messaggi vocali
|
||||
|
||||
I messaggi vocali Discord mostrano un'anteprima della forma d'onda e richiedono audio OGG/Opus più metadati. OpenClaw genera automaticamente la forma d'onda, ma richiede che `ffmpeg` e `ffprobe` siano disponibili sull'host del gateway per ispezionare e convertire i file audio.
|
||||
|
||||
Requisiti e vincoli:
|
||||
I messaggi vocali Discord mostrano un'anteprima waveform e richiedono audio OGG/Opus. OpenClaw genera automaticamente la waveform, ma richiede `ffmpeg` e `ffprobe` sull'host del gateway per ispezionare e convertire.
|
||||
|
||||
- Fornisci un **percorso di file locale** (gli URL vengono rifiutati).
|
||||
- Ometti il contenuto testuale (Discord non consente testo + messaggio vocale nello stesso payload).
|
||||
- Qualsiasi formato audio è accettato; OpenClaw lo converte in OGG/Opus quando necessario.
|
||||
|
||||
Esempio:
|
||||
- Ometti il contenuto di testo (Discord rifiuta testo + messaggio vocale nello stesso payload).
|
||||
- Qualsiasi formato audio è accettato; OpenClaw converte in OGG/Opus se necessario.
|
||||
|
||||
```bash
|
||||
message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)
|
||||
@ -1126,19 +1075,19 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a
|
||||
## Risoluzione dei problemi
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Intent non consentiti usati o il bot non vede messaggi del server">
|
||||
<Accordion title="Usati intent non consentiti oppure il bot non vede messaggi guild">
|
||||
|
||||
- abilita Message Content Intent
|
||||
- abilita Server Members Intent quando dipendi dalla risoluzione utente/membro
|
||||
- riavvia il gateway dopo aver cambiato gli intent
|
||||
- riavvia il gateway dopo aver modificato gli intent
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Messaggi del server bloccati in modo imprevisto">
|
||||
<Accordion title="Messaggi guild bloccati in modo imprevisto">
|
||||
|
||||
- verifica `groupPolicy`
|
||||
- verifica l'allowlist del server in `channels.discord.guilds`
|
||||
- se esiste la mappa `channels` del server, sono consentiti solo i canali elencati
|
||||
- verifica la allowlist della guild sotto `channels.discord.guilds`
|
||||
- se esiste la mappa `channels` della guild, sono consentiti solo i canali elencati
|
||||
- verifica il comportamento di `requireMention` e i pattern di menzione
|
||||
|
||||
Controlli utili:
|
||||
@ -1151,16 +1100,16 @@ openclaw logs --follow
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Require mention false ma ancora bloccato">
|
||||
<Accordion title="Require mention impostato su false ma ancora bloccato">
|
||||
Cause comuni:
|
||||
|
||||
- `groupPolicy="allowlist"` senza allowlist corrispondente di server/canale
|
||||
- `requireMention` configurato nel posto sbagliato (deve trovarsi in `channels.discord.guilds` o nella voce del canale)
|
||||
- mittente bloccato dall'allowlist `users` del server/canale
|
||||
- `groupPolicy="allowlist"` senza una allowlist guild/canale corrispondente
|
||||
- `requireMention` configurato nel posto sbagliato (deve essere sotto `channels.discord.guilds` o nella voce del canale)
|
||||
- mittente bloccato dalla allowlist `users` della guild/del canale
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Gli handler di lunga durata vanno in timeout o duplicano le risposte">
|
||||
<Accordion title="Gli handler a lunga esecuzione vanno in timeout o duplicano le risposte">
|
||||
|
||||
Log tipici:
|
||||
|
||||
@ -1168,12 +1117,12 @@ openclaw logs --follow
|
||||
- `Slow listener detected ...`
|
||||
- `discord inbound worker timed out after ...`
|
||||
|
||||
Impostazione del budget del listener:
|
||||
Parametro del budget del listener:
|
||||
|
||||
- account singolo: `channels.discord.eventQueue.listenerTimeout`
|
||||
- multi-account: `channels.discord.accounts.<accountId>.eventQueue.listenerTimeout`
|
||||
|
||||
Impostazione del timeout di esecuzione del worker:
|
||||
Parametro del timeout di esecuzione del worker:
|
||||
|
||||
- account singolo: `channels.discord.inboundWorker.runTimeoutMs`
|
||||
- multi-account: `channels.discord.accounts.<accountId>.inboundWorker.runTimeoutMs`
|
||||
@ -1200,12 +1149,12 @@ openclaw logs --follow
|
||||
}
|
||||
```
|
||||
|
||||
Usa `eventQueue.listenerTimeout` per la configurazione lenta del listener e `inboundWorker.runTimeoutMs`
|
||||
Usa `eventQueue.listenerTimeout` per setup lenti del listener e `inboundWorker.runTimeoutMs`
|
||||
solo se vuoi una valvola di sicurezza separata per i turni agente in coda.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Incongruenze nell'audit dei permessi">
|
||||
<Accordion title="Mancate corrispondenze nell'audit dei permessi">
|
||||
I controlli dei permessi di `channels status --probe` funzionano solo per ID canale numerici.
|
||||
|
||||
Se usi chiavi slug, la corrispondenza a runtime può comunque funzionare, ma il probe non può verificare completamente i permessi.
|
||||
@ -1215,28 +1164,28 @@ openclaw logs --follow
|
||||
<Accordion title="Problemi con DM e abbinamento">
|
||||
|
||||
- DM disabilitati: `channels.discord.dm.enabled=false`
|
||||
- criterio DM disabilitato: `channels.discord.dmPolicy="disabled"` (legacy: `channels.discord.dm.policy`)
|
||||
- policy DM disabilitata: `channels.discord.dmPolicy="disabled"` (legacy: `channels.discord.dm.policy`)
|
||||
- in attesa di approvazione dell'abbinamento in modalità `pairing`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Loop bot a bot">
|
||||
Per impostazione predefinita i messaggi creati dai bot vengono ignorati.
|
||||
<Accordion title="Loop bot-to-bot">
|
||||
Per impostazione predefinita, i messaggi creati dai bot vengono ignorati.
|
||||
|
||||
Se imposti `channels.discord.allowBots=true`, usa regole rigorose di menzione e allowlist per evitare comportamenti a loop.
|
||||
Preferisci `channels.discord.allowBots="mentions"` per accettare solo messaggi di bot che menzionano il bot.
|
||||
Se imposti `channels.discord.allowBots=true`, usa regole rigide di menzione e allowlist per evitare comportamenti a loop.
|
||||
Preferisci `channels.discord.allowBots="mentions"` per accettare solo i messaggi dei bot che menzionano il bot.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="La STT vocale perde con DecryptionFailed(...)">
|
||||
<Accordion title="La STT vocale perde dati con DecryptionFailed(...)">
|
||||
|
||||
- mantieni OpenClaw aggiornato (`openclaw update`) così che la logica di recupero della ricezione vocale Discord sia presente
|
||||
- mantieni OpenClaw aggiornato (`openclaw update`) così che sia presente la logica di recupero della ricezione vocale Discord
|
||||
- conferma `channels.discord.voice.daveEncryption=true` (predefinito)
|
||||
- parti da `channels.discord.voice.decryptionFailureTolerance=24` (valore predefinito upstream) e regolalo solo se necessario
|
||||
- monitora i log per:
|
||||
- parti da `channels.discord.voice.decryptionFailureTolerance=24` (predefinito upstream) e regola solo se necessario
|
||||
- osserva i log per:
|
||||
- `discord voice: DAVE decrypt failures detected`
|
||||
- `discord voice: repeated decrypt failures; attempting rejoin`
|
||||
- se gli errori continuano dopo il rientro automatico, raccogli i log e confrontali con [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)
|
||||
- se i problemi continuano dopo il rejoin automatico, raccogli i log e confrontali con [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -1245,15 +1194,15 @@ openclaw logs --follow
|
||||
|
||||
Riferimento principale:
|
||||
|
||||
- [Riferimento alla configurazione - Discord](/it/gateway/configuration-reference#discord)
|
||||
- [Configuration reference - Discord](/it/gateway/configuration-reference#discord)
|
||||
|
||||
Campi Discord ad alto segnale:
|
||||
|
||||
- avvio/autenticazione: `enabled`, `token`, `accounts.*`, `allowBots`
|
||||
- criteri: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*`
|
||||
- comandi: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*`
|
||||
- policy: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*`
|
||||
- comando: `commands.native`, `commands.useAccessGroups`, `configWrites`, `slashCommand.*`
|
||||
- coda eventi: `eventQueue.listenerTimeout` (budget del listener), `eventQueue.maxQueueSize`, `eventQueue.maxConcurrency`
|
||||
- worker in ingresso: `inboundWorker.runTimeoutMs`
|
||||
- worker inbound: `inboundWorker.runTimeoutMs`
|
||||
- risposta/cronologia: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
|
||||
- consegna: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage`
|
||||
- streaming: `streaming` (alias legacy: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce`
|
||||
@ -1266,16 +1215,16 @@ Campi Discord ad alto segnale:
|
||||
|
||||
## Sicurezza e operazioni
|
||||
|
||||
- Tratta i token del bot come segreti (`DISCORD_BOT_TOKEN` preferito in ambienti supervisionati).
|
||||
- Tratta i token bot come segreti (`DISCORD_BOT_TOKEN` preferito negli ambienti supervisionati).
|
||||
- Concedi i permessi Discord minimi necessari.
|
||||
- Se il deployment/stato dei comandi è obsoleto, riavvia il gateway e ricontrolla con `openclaw channels status --probe`.
|
||||
- Se il deploy/stato dei comandi è obsoleto, riavvia il gateway e ricontrolla con `openclaw channels status --probe`.
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Abbinamento](/it/channels/pairing)
|
||||
- [Gruppi](/it/channels/groups)
|
||||
- [Instradamento dei canali](/it/channels/channel-routing)
|
||||
- [Sicurezza](/it/gateway/security)
|
||||
- [Instradamento multi-agente](/it/concepts/multi-agent)
|
||||
- [Risoluzione dei problemi](/it/channels/troubleshooting)
|
||||
- [Comandi slash](/it/tools/slash-commands)
|
||||
- [Pairing](/it/channels/pairing)
|
||||
- [Groups](/it/channels/groups)
|
||||
- [Channel routing](/it/channels/channel-routing)
|
||||
- [Security](/it/gateway/security)
|
||||
- [Multi-agent routing](/it/concepts/multi-agent)
|
||||
- [Troubleshooting](/it/channels/troubleshooting)
|
||||
- [Slash commands](/it/tools/slash-commands)
|
||||
|
||||
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- Lavorare su funzionalità Telegram o webhook
|
||||
- Lavorare sulle funzionalità di Telegram o sui Webhook
|
||||
summary: Stato del supporto del bot Telegram, capacità e configurazione
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T08:24:15Z"
|
||||
generated_at: "2026-04-23T13:57:56Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e2073245079eb48b599c4274cc620eb29211a64c5d396ffb355f7022fecec9a6
|
||||
source_hash: 024b76c3c71537995fc4efc26887eae516846d3f845d135b263d4d7f270afbb7
|
||||
source_path: channels/telegram.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Telegram (Bot API)
|
||||
# Telegram (API Bot)
|
||||
|
||||
Stato: pronto per la produzione per DM bot + gruppi tramite grammY. Il long polling è la modalità predefinita; la modalità webhook è facoltativa.
|
||||
Stato: pronto per la produzione per DM bot + gruppi tramite grammY. Il long polling è la modalità predefinita; la modalità webhook è opzionale.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Abbinamento" icon="link" href="/it/channels/pairing">
|
||||
La policy DM predefinita per Telegram è pairing.
|
||||
La policy DM predefinita per Telegram è l'abbinamento.
|
||||
</Card>
|
||||
<Card title="Risoluzione dei problemi del canale" icon="wrench" href="/it/channels/troubleshooting">
|
||||
Diagnostica cross-channel e playbook di riparazione.
|
||||
</Card>
|
||||
<Card title="Configurazione del Gateway" icon="settings" href="/it/gateway/configuration">
|
||||
Pattern ed esempi completi di configurazione del canale.
|
||||
Modelli ed esempi completi di configurazione del canale.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -32,13 +32,13 @@ Stato: pronto per la produzione per DM bot + gruppi tramite grammY. Il long poll
|
||||
|
||||
<Steps>
|
||||
<Step title="Crea il token del bot in BotFather">
|
||||
Apri Telegram e avvia una chat con **@BotFather** (controlla che l'handle sia esattamente `@BotFather`).
|
||||
Apri Telegram e avvia una chat con **@BotFather** (verifica che l'handle sia esattamente `@BotFather`).
|
||||
|
||||
Esegui `/newbot`, segui le istruzioni e salva il token.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configura token e policy DM">
|
||||
<Step title="Configura il token e la policy DM">
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -66,42 +66,42 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
I codici di pairing scadono dopo 1 ora.
|
||||
I codici di abbinamento scadono dopo 1 ora.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Aggiungi il bot a un gruppo">
|
||||
Aggiungi il bot al tuo gruppo, poi imposta `channels.telegram.groups` e `groupPolicy` in modo che corrispondano al tuo modello di accesso.
|
||||
Aggiungi il bot al tuo gruppo, quindi imposta `channels.telegram.groups` e `groupPolicy` in modo che corrispondano al tuo modello di accesso.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
L'ordine di risoluzione del token tiene conto dell'account. In pratica, i valori in config hanno la precedenza sul fallback env, e `TELEGRAM_BOT_TOKEN` si applica solo all'account predefinito.
|
||||
L'ordine di risoluzione del token è consapevole dell'account. In pratica, i valori di configurazione hanno priorità sul fallback env e `TELEGRAM_BOT_TOKEN` si applica solo all'account predefinito.
|
||||
</Note>
|
||||
|
||||
## Impostazioni lato Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Modalità privacy e visibilità nei gruppi">
|
||||
<Accordion title="Modalità privacy e visibilità del gruppo">
|
||||
I bot Telegram usano per impostazione predefinita la **Privacy Mode**, che limita i messaggi di gruppo che ricevono.
|
||||
|
||||
Se il bot deve vedere tutti i messaggi del gruppo, puoi:
|
||||
|
||||
- disabilitare la privacy mode tramite `/setprivacy`, oppure
|
||||
- disattivare la modalità privacy tramite `/setprivacy`, oppure
|
||||
- rendere il bot amministratore del gruppo.
|
||||
|
||||
Quando cambi la privacy mode, rimuovi e aggiungi di nuovo il bot in ogni gruppo, così Telegram applica la modifica.
|
||||
Quando cambi la modalità privacy, rimuovi e poi aggiungi di nuovo il bot in ciascun gruppo in modo che Telegram applichi la modifica.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Permessi del gruppo">
|
||||
Lo stato di amministratore è controllato nelle impostazioni del gruppo Telegram.
|
||||
|
||||
I bot amministratori ricevono tutti i messaggi del gruppo, il che è utile per un comportamento del gruppo sempre attivo.
|
||||
I bot amministratori ricevono tutti i messaggi del gruppo, il che è utile per un comportamento di gruppo sempre attivo.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Comandi utili di BotFather">
|
||||
<Accordion title="Comandi BotFather utili">
|
||||
|
||||
- `/setjoingroups` per consentire/negare l'aggiunta ai gruppi
|
||||
- `/setprivacy` per il comportamento di visibilità nei gruppi
|
||||
@ -121,20 +121,20 @@ L'ordine di risoluzione del token tiene conto dell'account. In pratica, i valori
|
||||
- `disabled`
|
||||
|
||||
`channels.telegram.allowFrom` accetta ID utente Telegram numerici. I prefissi `telegram:` / `tg:` sono accettati e normalizzati.
|
||||
`dmPolicy: "allowlist"` con `allowFrom` vuoto blocca tutti i DM e viene rifiutato dalla validazione della configurazione.
|
||||
`dmPolicy: "allowlist"` con `allowFrom` vuoto blocca tutti i DM ed è rifiutato dalla validazione della configurazione.
|
||||
La configurazione richiede solo ID utente numerici.
|
||||
Se hai eseguito un upgrade e la tua configurazione contiene voci allowlist `@username`, esegui `openclaw doctor --fix` per risolverle (best-effort; richiede un token bot Telegram).
|
||||
Se hai eseguito un aggiornamento e la tua configurazione contiene voci allowlist `@username`, esegui `openclaw doctor --fix` per risolverle (best-effort; richiede un token bot Telegram).
|
||||
Se in precedenza ti affidavi ai file allowlist del pairing-store, `openclaw doctor --fix` può recuperare le voci in `channels.telegram.allowFrom` nei flussi allowlist (per esempio quando `dmPolicy: "allowlist"` non ha ancora ID espliciti).
|
||||
|
||||
Per bot con un solo proprietario, preferisci `dmPolicy: "allowlist"` con ID `allowFrom` numerici espliciti per mantenere la policy di accesso stabile in configurazione (invece di dipendere da precedenti approvazioni pairing).
|
||||
Per bot con un solo proprietario, preferisci `dmPolicy: "allowlist"` con ID `allowFrom` numerici espliciti per mantenere la policy di accesso durevole nella configurazione (invece di dipendere da approvazioni di abbinamento precedenti).
|
||||
|
||||
Confusione comune: l'approvazione del pairing DM non significa "questo mittente è autorizzato ovunque".
|
||||
Il pairing concede solo l'accesso DM. L'autorizzazione dei mittenti nei gruppi continua invece a provenire da allowlist esplicite in configurazione.
|
||||
Se vuoi ottenere "sono autorizzato una volta e funzionano sia i DM sia i comandi nei gruppi", inserisci il tuo ID utente Telegram numerico in `channels.telegram.allowFrom`.
|
||||
Equivoco comune: l'approvazione dell'abbinamento DM non significa "questo mittente è autorizzato ovunque".
|
||||
L'abbinamento concede solo l'accesso DM. L'autorizzazione del mittente nei gruppi deriva comunque da allowlist esplicite nella configurazione.
|
||||
Se vuoi che "io sia autorizzato una volta e funzionino sia i DM sia i comandi di gruppo", inserisci il tuo ID utente Telegram numerico in `channels.telegram.allowFrom`.
|
||||
|
||||
### Trovare il tuo ID utente Telegram
|
||||
|
||||
Più sicuro (nessun bot di terze parti):
|
||||
Metodo più sicuro (senza bot di terze parti):
|
||||
|
||||
1. Invia un DM al tuo bot.
|
||||
2. Esegui `openclaw logs --follow`.
|
||||
@ -155,8 +155,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
1. **Quali gruppi sono consentiti** (`channels.telegram.groups`)
|
||||
- nessuna configurazione `groups`:
|
||||
- con `groupPolicy: "open"`: qualsiasi gruppo può superare i controlli sull'ID gruppo
|
||||
- con `groupPolicy: "allowlist"` (predefinito): i gruppi sono bloccati finché non aggiungi voci in `groups` (o `"*"`)
|
||||
- con `groupPolicy: "open"`: qualsiasi gruppo può superare i controlli dell'ID gruppo
|
||||
- con `groupPolicy: "allowlist"` (predefinito): i gruppi sono bloccati finché non aggiungi voci a `groups` (o `"*"`)
|
||||
- `groups` configurato: agisce come allowlist (ID espliciti o `"*"`)
|
||||
|
||||
2. **Quali mittenti sono consentiti nei gruppi** (`channels.telegram.groupPolicy`)
|
||||
@ -164,17 +164,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `allowlist` (predefinito)
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` viene usato per il filtro dei mittenti nei gruppi. Se non è impostato, Telegram usa `allowFrom` come fallback.
|
||||
Le voci di `groupAllowFrom` devono essere ID utente Telegram numerici (i prefissi `telegram:` / `tg:` vengono normalizzati).
|
||||
`groupAllowFrom` è usato per il filtro dei mittenti nei gruppi. Se non è impostato, Telegram usa `allowFrom` come fallback.
|
||||
Le voci di `groupAllowFrom` devono essere ID utente Telegram numerici (i prefissi `telegram:` / `tg:` sono normalizzati).
|
||||
Non inserire ID chat di gruppo o supergruppo Telegram in `groupAllowFrom`. Gli ID chat negativi appartengono a `channels.telegram.groups`.
|
||||
Le voci non numeriche vengono ignorate per l'autorizzazione del mittente.
|
||||
Limite di sicurezza (`2026.2.25+`): l'autorizzazione dei mittenti nei gruppi **non** eredita le approvazioni del pairing-store DM.
|
||||
Il pairing resta solo DM. Per i gruppi, imposta `groupAllowFrom` oppure `allowFrom` per gruppo/per topic.
|
||||
Confine di sicurezza (`2026.2.25+`): l'autorizzazione dei mittenti nei gruppi **non** eredita le approvazioni del pairing-store DM.
|
||||
L'abbinamento resta solo per i DM. Per i gruppi, imposta `groupAllowFrom` oppure `allowFrom` per gruppo/per topic.
|
||||
Se `groupAllowFrom` non è impostato, Telegram usa `allowFrom` della configurazione come fallback, non il pairing store.
|
||||
Pattern pratico per bot con un solo proprietario: imposta il tuo ID utente in `channels.telegram.allowFrom`, lascia `groupAllowFrom` non impostato e consenti i gruppi di destinazione in `channels.telegram.groups`.
|
||||
Nota runtime: se `channels.telegram` manca completamente, il runtime usa per impostazione predefinita `groupPolicy="allowlist"` fail-closed, a meno che `channels.defaults.groupPolicy` non sia impostato esplicitamente.
|
||||
Modello pratico per bot con un solo proprietario: imposta il tuo ID utente in `channels.telegram.allowFrom`, lascia `groupAllowFrom` non impostato e consenti i gruppi di destinazione in `channels.telegram.groups`.
|
||||
Nota di runtime: se `channels.telegram` è completamente assente, i valori predefiniti di runtime applicano fail-closed `groupPolicy="allowlist"` a meno che `channels.defaults.groupPolicy` non sia impostato esplicitamente.
|
||||
|
||||
Esempio: consentire a qualsiasi membro in uno specifico gruppo:
|
||||
Esempio: consentire qualsiasi membro in uno specifico gruppo:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -191,7 +191,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Esempio: consentire solo a utenti specifici all'interno di uno specifico gruppo:
|
||||
Esempio: consentire solo utenti specifici in uno specifico gruppo:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -209,17 +209,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Errore comune: `groupAllowFrom` non è una allowlist dei gruppi Telegram.
|
||||
Errore comune: `groupAllowFrom` non è una allowlist di gruppi Telegram.
|
||||
|
||||
- Inserisci gli ID negativi di gruppi o supergruppi Telegram come `-1001234567890` in `channels.telegram.groups`.
|
||||
- Inserisci gli ID utente Telegram come `8734062810` in `groupAllowFrom` quando vuoi limitare quali persone all'interno di un gruppo consentito possono attivare il bot.
|
||||
- Inserisci ID utente Telegram come `8734062810` in `groupAllowFrom` quando vuoi limitare quali persone all'interno di un gruppo consentito possono attivare il bot.
|
||||
- Usa `groupAllowFrom: ["*"]` solo quando vuoi che qualsiasi membro di un gruppo consentito possa parlare con il bot.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Comportamento delle menzioni">
|
||||
Le risposte nei gruppi richiedono una menzione per impostazione predefinita.
|
||||
Per impostazione predefinita, le risposte nei gruppi richiedono una menzione.
|
||||
|
||||
La menzione può provenire da:
|
||||
|
||||
@ -228,7 +228,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
Attivazioni/disattivazioni dei comandi a livello sessione:
|
||||
Attivazioni di comando a livello di sessione:
|
||||
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
@ -253,26 +253,26 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- inoltra un messaggio del gruppo a `@userinfobot` / `@getidsbot`
|
||||
- oppure leggi `chat.id` da `openclaw logs --follow`
|
||||
- oppure ispeziona `getUpdates` della Bot API
|
||||
- oppure controlla `getUpdates` della Bot API
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Comportamento runtime
|
||||
## Comportamento di runtime
|
||||
|
||||
- Telegram è gestito dal processo gateway.
|
||||
- Il routing è deterministico: le risposte in ingresso da Telegram tornano a Telegram (il modello non sceglie i canali).
|
||||
- I messaggi in ingresso vengono normalizzati nell'envelope canale condivisa con metadati di risposta e segnaposto media.
|
||||
- Telegram è gestito dal processo Gateway.
|
||||
- Il routing è deterministico: le risposte in ingresso di Telegram tornano a Telegram (il modello non sceglie i canali).
|
||||
- I messaggi in ingresso vengono normalizzati nell'envelope di canale condivisa con metadati di risposta e segnaposto multimediali.
|
||||
- Le sessioni di gruppo sono isolate per ID gruppo. I topic del forum aggiungono `:topic:<threadId>` per mantenere i topic isolati.
|
||||
- I messaggi DM possono includere `message_thread_id`; OpenClaw li instrada con chiavi di sessione thread-aware e conserva l'ID thread per le risposte.
|
||||
- Il long polling usa grammY runner con sequenziamento per chat/per thread. La concorrenza complessiva del sink runner usa `agents.defaults.maxConcurrent`.
|
||||
- I riavvii del watchdog del long polling si attivano per impostazione predefinita dopo 120 secondi senza liveness `getUpdates` completata. Aumenta `channels.telegram.pollingStallThresholdMs` solo se il tuo deployment continua a vedere falsi riavvii per stallo del polling durante lavori di lunga durata. Il valore è in millisecondi ed è consentito da `30000` a `600000`; sono supportati override per account.
|
||||
- Telegram Bot API non supporta le conferme di lettura (`sendReadReceipts` non si applica).
|
||||
- I messaggi DM possono includere `message_thread_id`; OpenClaw li instrada con chiavi di sessione consapevoli del thread e preserva l'ID thread per le risposte.
|
||||
- Il long polling usa grammY runner con sequenziamento per chat/per thread. La concorrenza complessiva del sink del runner usa `agents.defaults.maxConcurrent`.
|
||||
- I riavvii del watchdog per long polling si attivano per impostazione predefinita dopo 120 secondi senza liveness `getUpdates` completata. Aumenta `channels.telegram.pollingStallThresholdMs` solo se il tuo deployment continua a vedere falsi riavvii per stallo del polling durante lavoro di lunga durata. Il valore è in millisecondi ed è consentito da `30000` a `600000`; sono supportate le sostituzioni per account.
|
||||
- La Telegram Bot API non supporta le conferme di lettura (`sendReadReceipts` non si applica).
|
||||
|
||||
## Riferimento funzionalità
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Anteprima streaming live (modifiche del messaggio)">
|
||||
<Accordion title="Anteprima streaming live (modifiche ai messaggi)">
|
||||
OpenClaw può trasmettere risposte parziali in tempo reale:
|
||||
|
||||
- chat dirette: messaggio di anteprima + `editMessageText`
|
||||
@ -282,24 +282,24 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `channels.telegram.streaming` è `off | partial | block | progress` (predefinito: `partial`)
|
||||
- `progress` viene mappato a `partial` su Telegram (compatibilità con la denominazione cross-channel)
|
||||
- `streaming.preview.toolProgress` controlla se gli aggiornamenti strumento/progresso riusano lo stesso messaggio di anteprima modificato (predefinito: `true`). Imposta `false` per mantenere messaggi separati per strumento/progresso.
|
||||
- i valori legacy `channels.telegram.streamMode` e `streaming` booleani vengono mappati automaticamente
|
||||
- `streaming.preview.toolProgress` controlla se gli aggiornamenti di strumento/progresso riutilizzano lo stesso messaggio di anteprima modificato (predefinito: `true`). Imposta `false` per mantenere messaggi separati per strumento/progresso.
|
||||
- i valori booleani legacy `channels.telegram.streamMode` e `streaming` vengono mappati automaticamente
|
||||
|
||||
Per risposte solo testo:
|
||||
|
||||
- DM: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale in place (nessun secondo messaggio)
|
||||
- gruppo/topic: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale in place (nessun secondo messaggio)
|
||||
- DM: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale sul posto (nessun secondo messaggio)
|
||||
- gruppo/topic: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale sul posto (nessun secondo messaggio)
|
||||
|
||||
Per risposte complesse (per esempio payload media), OpenClaw torna alla normale consegna finale e poi ripulisce il messaggio di anteprima.
|
||||
Per risposte complesse (per esempio payload multimediali), OpenClaw torna alla normale consegna finale e poi pulisce il messaggio di anteprima.
|
||||
|
||||
Lo streaming di anteprima è separato dallo streaming a blocchi. Quando lo streaming a blocchi è esplicitamente abilitato per Telegram, OpenClaw salta il flusso di anteprima per evitare uno streaming doppio.
|
||||
Lo streaming di anteprima è separato dallo streaming a blocchi. Quando lo streaming a blocchi è esplicitamente abilitato per Telegram, OpenClaw salta lo stream di anteprima per evitare il doppio streaming.
|
||||
|
||||
Se il trasporto bozza nativo non è disponibile/viene rifiutato, OpenClaw torna automaticamente a `sendMessage` + `editMessageText`.
|
||||
Se il trasporto bozza nativo non è disponibile/viene rifiutato, OpenClaw usa automaticamente `sendMessage` + `editMessageText` come fallback.
|
||||
|
||||
Stream di ragionamento solo Telegram:
|
||||
Stream di reasoning solo Telegram:
|
||||
|
||||
- `/reasoning stream` invia il ragionamento all'anteprima live durante la generazione
|
||||
- la risposta finale viene inviata senza testo di ragionamento
|
||||
- `/reasoning stream` invia il reasoning all'anteprima live durante la generazione
|
||||
- la risposta finale viene inviata senza testo di reasoning
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -307,8 +307,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Il testo in uscita usa Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Il testo in stile Markdown viene renderizzato in HTML sicuro per Telegram.
|
||||
- L'HTML grezzo del modello viene escaped per ridurre gli errori di parsing di Telegram.
|
||||
- Se Telegram rifiuta l'HTML analizzato, OpenClaw riprova come testo semplice.
|
||||
- L'HTML grezzo del modello viene sottoposto a escape per ridurre i fallimenti di parsing di Telegram.
|
||||
- Se Telegram rifiuta l'HTML analizzato, OpenClaw ritenta come testo semplice.
|
||||
|
||||
Le anteprime dei link sono abilitate per impostazione predefinita e possono essere disabilitate con `channels.telegram.linkPreview: false`.
|
||||
|
||||
@ -321,7 +321,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `commands.native: "auto"` abilita i comandi nativi per Telegram
|
||||
|
||||
Aggiungi voci personalizzate nel menu comandi:
|
||||
Aggiungi voci personalizzate al menu comandi:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -338,28 +338,28 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Regole:
|
||||
|
||||
- i nomi vengono normalizzati (rimozione della `/` iniziale, minuscolo)
|
||||
- i nomi vengono normalizzati (rimuove `/` iniziale, minuscolo)
|
||||
- pattern valido: `a-z`, `0-9`, `_`, lunghezza `1..32`
|
||||
- i comandi personalizzati non possono sovrascrivere i comandi nativi
|
||||
- conflitti/duplicati vengono saltati e registrati nei log
|
||||
|
||||
Note:
|
||||
|
||||
- i comandi personalizzati sono solo voci di menu; non implementano automaticamente un comportamento
|
||||
- i comandi di plugin/Skills possono comunque funzionare se digitati anche se non sono mostrati nel menu Telegram
|
||||
- i comandi personalizzati sono solo voci di menu; non implementano automaticamente il comportamento
|
||||
- i comandi di plugin/Skills possono comunque funzionare se digitati, anche se non sono mostrati nel menu Telegram
|
||||
|
||||
Se i comandi nativi sono disabilitati, quelli integrati vengono rimossi. I comandi personalizzati/plugin possono comunque essere registrati se configurati.
|
||||
Se i comandi nativi sono disabilitati, quelli integrati vengono rimossi. I comandi personalizzati/plugin possono comunque registrarsi se configurati.
|
||||
|
||||
Errori comuni di configurazione:
|
||||
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu Telegram è ancora in overflow dopo il trimming; riduci i comandi personalizzati/plugin/Skills oppure disabilita `channels.telegram.commands.native`.
|
||||
- `setMyCommands failed` con errori di rete/fetch di solito significa che il DNS/HTTPS in uscita verso `api.telegram.org` è bloccato.
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu Telegram è ancora in overflow dopo il trimming; riduci i comandi di plugin/Skills/personalizzati oppure disabilita `channels.telegram.commands.native`.
|
||||
- `setMyCommands failed` con errori di rete/fetch di solito significa che DNS/HTTPS in uscita verso `api.telegram.org` è bloccato.
|
||||
|
||||
### Comandi di pairing del dispositivo (plugin `device-pair`)
|
||||
### Comandi di abbinamento dispositivo (plugin `device-pair`)
|
||||
|
||||
Quando il plugin `device-pair` è installato:
|
||||
|
||||
1. `/pair` genera il codice di configurazione
|
||||
1. `/pair` genera un codice di configurazione
|
||||
2. incolla il codice nell'app iOS
|
||||
3. `/pair pending` elenca le richieste in sospeso (inclusi ruolo/ambiti)
|
||||
4. approva la richiesta:
|
||||
@ -367,11 +367,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `/pair approve` quando c'è una sola richiesta in sospeso
|
||||
- `/pair approve latest` per la più recente
|
||||
|
||||
Il codice di configurazione contiene un token bootstrap a breve durata. L'handoff bootstrap integrato mantiene il token primario del Node su `scopes: []`; qualsiasi token operatore passato in handoff resta limitato a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. I controlli di ambito bootstrap sono con prefisso del ruolo, quindi quella allowlist dell'operatore soddisfa solo le richieste dell'operatore; i ruoli non operatore richiedono comunque ambiti sotto il proprio prefisso di ruolo.
|
||||
Il codice di configurazione contiene un bootstrap token a breve durata. Il passaggio bootstrap integrato mantiene il token del Node primario con `scopes: []`; qualsiasi token operatore passato resta limitato a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. I controlli di ambito bootstrap sono prefissati dal ruolo, quindi tale allowlist operatore soddisfa solo richieste operatore; i ruoli non operatore richiedono comunque ambiti sotto il proprio prefisso di ruolo.
|
||||
|
||||
Se un dispositivo ritenta con dettagli di autenticazione modificati (per esempio ruolo/ambiti/chiave pubblica), la precedente richiesta in sospeso viene sostituita e la nuova richiesta usa un `requestId` diverso. Esegui di nuovo `/pair pending` prima di approvare.
|
||||
Se un dispositivo riprova con dettagli auth modificati (per esempio ruolo/ambiti/chiave pubblica), la precedente richiesta in sospeso viene sostituita e la nuova richiesta usa un `requestId` diverso. Esegui di nuovo `/pair pending` prima di approvare.
|
||||
|
||||
Maggiori dettagli: [Pairing](/it/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
Maggiori dettagli: [Abbinamento](/it/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -425,13 +425,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
action: "send",
|
||||
channel: "telegram",
|
||||
to: "123456789",
|
||||
message: "Choose an option:",
|
||||
message: "Scegli un'opzione:",
|
||||
buttons: [
|
||||
[
|
||||
{ text: "Yes", callback_data: "yes" },
|
||||
{ text: "Sì", callback_data: "yes" },
|
||||
{ text: "No", callback_data: "no" },
|
||||
],
|
||||
[{ text: "Cancel", callback_data: "cancel" }],
|
||||
[{ text: "Annulla", callback_data: "cancel" }],
|
||||
],
|
||||
}
|
||||
```
|
||||
@ -441,16 +441,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Azioni dei messaggi Telegram per agenti e automazione">
|
||||
Le azioni dello strumento Telegram includono:
|
||||
<Accordion title="Azioni messaggio Telegram per agenti e automazione">
|
||||
Le azioni strumento Telegram includono:
|
||||
|
||||
- `sendMessage` (`to`, `content`, facoltativi `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `sendMessage` (`to`, `content`, `mediaUrl` opzionale, `replyToMessageId`, `messageThreadId`)
|
||||
- `react` (`chatId`, `messageId`, `emoji`)
|
||||
- `deleteMessage` (`chatId`, `messageId`)
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, facoltativi `iconColor`, `iconCustomEmojiId`)
|
||||
- `createForumTopic` (`chatId`, `name`, `iconColor` opzionale, `iconCustomEmojiId`)
|
||||
|
||||
Le azioni dei messaggi del canale espongono alias ergonomici (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
Le azioni messaggio del canale espongono alias ergonomici (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Controlli di gating:
|
||||
|
||||
@ -459,10 +459,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.actions.reactions`
|
||||
- `channels.telegram.actions.sticker` (predefinito: disabilitato)
|
||||
|
||||
Nota: `edit` e `topic-create` sono attualmente abilitati per impostazione predefinita e non hanno toggle separati `channels.telegram.actions.*`.
|
||||
Gli invii runtime usano lo snapshot attivo di config/segreti (avvio/ricarica), quindi i percorsi azione non eseguono una nuova risoluzione ad hoc di SecretRef per ogni invio.
|
||||
Nota: `edit` e `topic-create` sono attualmente abilitati per impostazione predefinita e non hanno toggle `channels.telegram.actions.*` separati.
|
||||
Gli invii a runtime usano lo snapshot attivo di config/secrets (avvio/ricarica), quindi i percorsi delle azioni non eseguono una nuova risoluzione ad hoc di SecretRef a ogni invio.
|
||||
|
||||
Semantica di rimozione delle reazioni: [/tools/reactions](/it/tools/reactions)
|
||||
Semantica della rimozione delle reazioni: [/tools/reactions](/it/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -470,7 +470,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Telegram supporta tag espliciti di threading delle risposte nell'output generato:
|
||||
|
||||
- `[[reply_to_current]]` risponde al messaggio che ha attivato l'azione
|
||||
- `[[reply_to:<id>]]` risponde a un ID messaggio Telegram specifico
|
||||
- `[[reply_to:<id>]]` risponde a uno specifico ID messaggio Telegram
|
||||
|
||||
`channels.telegram.replyToMode` controlla la gestione:
|
||||
|
||||
@ -486,19 +486,19 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Supergruppi forum:
|
||||
|
||||
- le chiavi di sessione del topic aggiungono `:topic:<threadId>`
|
||||
- risposte e digitazione puntano al thread del topic
|
||||
- percorso di configurazione del topic:
|
||||
- risposte e digitazione sono indirizzate al thread del topic
|
||||
- percorso config del topic:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Caso speciale del topic generale (`threadId=1`):
|
||||
Caso speciale topic generale (`threadId=1`):
|
||||
|
||||
- gli invii dei messaggi omettono `message_thread_id` (Telegram rifiuta `sendMessage(...thread_id=1)`)
|
||||
- gli invii di messaggi omettono `message_thread_id` (Telegram rifiuta `sendMessage(...thread_id=1)`)
|
||||
- le azioni di digitazione includono comunque `message_thread_id`
|
||||
|
||||
Ereditarietà dei topic: le voci topic ereditano le impostazioni del gruppo salvo override (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` è solo per topic e non eredita dai valori predefiniti del gruppo.
|
||||
`agentId` è solo del topic e non viene ereditato dai valori predefiniti del gruppo.
|
||||
|
||||
**Routing agente per topic**: ogni topic può instradare a un agente diverso impostando `agentId` nella configurazione del topic. Questo assegna a ogni topic il proprio workspace, memoria e sessione isolati. Esempio:
|
||||
**Routing agente per topic**: ogni topic può instradare verso un agente diverso impostando `agentId` nella config del topic. Questo fornisce a ciascun topic il proprio workspace, memoria e sessione isolati. Esempio:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -520,74 +520,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Ogni topic ha quindi la propria chiave di sessione: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**Binding persistente del topic ACP**: i topic forum possono fissare sessioni harness ACP tramite binding ACP tipizzati di livello superiore:
|
||||
**Binding persistente del topic ACP**: i topic del forum possono fissare sessioni harness ACP tramite binding ACP tipizzati di primo livello (`bindings[]` con `type: "acp"` e `match.channel: "telegram"`, `peer.kind: "group"` e un id qualificato col topic come `-1001234567890:topic:42`). Attualmente limitato ai topic forum in gruppi/supergruppi. Vedi [Agenti ACP](/it/tools/acp-agents).
|
||||
|
||||
- `bindings[]` con `type: "acp"` e `match.channel: "telegram"`
|
||||
**Spawn ACP legato al thread dalla chat**: `/acp spawn <agent> --thread here|auto` collega il topic corrente a una nuova sessione ACP; i messaggi successivi vengono instradati lì direttamente. OpenClaw fissa la conferma di spawn nel topic. Richiede `channels.telegram.threadBindings.spawnAcpSessions=true`.
|
||||
|
||||
Esempio:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
list: [
|
||||
{
|
||||
id: "codex",
|
||||
runtime: {
|
||||
type: "acp",
|
||||
acp: {
|
||||
agent: "codex",
|
||||
backend: "acpx",
|
||||
mode: "persistent",
|
||||
cwd: "/workspace/openclaw",
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
bindings: [
|
||||
{
|
||||
type: "acp",
|
||||
agentId: "codex",
|
||||
match: {
|
||||
channel: "telegram",
|
||||
accountId: "default",
|
||||
peer: { kind: "group", id: "-1001234567890:topic:42" },
|
||||
},
|
||||
},
|
||||
],
|
||||
channels: {
|
||||
telegram: {
|
||||
groups: {
|
||||
"-1001234567890": {
|
||||
topics: {
|
||||
"42": {
|
||||
requireMention: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Questo è attualmente limitato ai topic forum in gruppi e supergruppi.
|
||||
|
||||
**Avvio ACP vincolato al thread dalla chat**:
|
||||
|
||||
- `/acp spawn <agent> --thread here|auto` può associare il topic Telegram corrente a una nuova sessione ACP.
|
||||
- I successivi messaggi nel topic vengono instradati direttamente alla sessione ACP associata (non serve `/acp steer`).
|
||||
- OpenClaw fissa il messaggio di conferma dell'avvio nel topic dopo un binding riuscito.
|
||||
- Richiede `channels.telegram.threadBindings.spawnAcpSessions=true`.
|
||||
|
||||
Il contesto del template include:
|
||||
|
||||
- `MessageThreadId`
|
||||
- `IsForum`
|
||||
|
||||
Comportamento dei thread DM:
|
||||
|
||||
- le chat private con `message_thread_id` mantengono il routing DM ma usano chiavi di sessione e destinazioni di risposta consapevoli del thread.
|
||||
Il contesto del template espone `MessageThreadId` e `IsForum`. Le chat DM con `message_thread_id` mantengono il routing DM ma usano chiavi di sessione consapevoli del thread.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -596,7 +533,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Telegram distingue tra note vocali e file audio.
|
||||
|
||||
- predefinito: comportamento file audio
|
||||
- predefinito: comportamento da file audio
|
||||
- tag `[[audio_as_voice]]` nella risposta dell'agente per forzare l'invio come nota vocale
|
||||
|
||||
Esempio di azione messaggio:
|
||||
@ -613,7 +550,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
### Messaggi video
|
||||
|
||||
Telegram distingue tra file video e note video.
|
||||
Telegram distingue tra file video e video note.
|
||||
|
||||
Esempio di azione messaggio:
|
||||
|
||||
@ -627,17 +564,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Le note video non supportano didascalie; l'eventuale testo del messaggio viene inviato separatamente.
|
||||
Le video note non supportano didascalie; il testo del messaggio fornito viene inviato separatamente.
|
||||
|
||||
### Sticker
|
||||
|
||||
Gestione degli sticker in ingresso:
|
||||
|
||||
- WEBP statico: scaricato ed elaborato (segnaposto `<media:sticker>`)
|
||||
- TGS animato: saltato
|
||||
- WEBM video: saltato
|
||||
- TGS animato: ignorato
|
||||
- WEBM video: ignorato
|
||||
|
||||
Campi di contesto sticker:
|
||||
Campi di contesto dello sticker:
|
||||
|
||||
- `Sticker.emoji`
|
||||
- `Sticker.setName`
|
||||
@ -649,7 +586,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Gli sticker vengono descritti una sola volta (quando possibile) e messi in cache per ridurre le chiamate vision ripetute.
|
||||
Gli sticker vengono descritti una volta (quando possibile) e memorizzati in cache per ridurre chiamate vision ripetute.
|
||||
|
||||
Abilita le azioni sticker:
|
||||
|
||||
@ -676,13 +613,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Cerca negli sticker in cache:
|
||||
Cerca sticker in cache:
|
||||
|
||||
```json5
|
||||
{
|
||||
action: "sticker-search",
|
||||
channel: "telegram",
|
||||
query: "cat waving",
|
||||
query: "gatto che saluta",
|
||||
limit: 5,
|
||||
}
|
||||
```
|
||||
@ -694,7 +631,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Quando abilitate, OpenClaw accoda eventi di sistema come:
|
||||
|
||||
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
|
||||
- `Reazione Telegram aggiunta: 👍 da Alice (@alice) al msg 42`
|
||||
|
||||
Configurazione:
|
||||
|
||||
@ -704,16 +641,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Note:
|
||||
|
||||
- `own` significa solo reazioni degli utenti ai messaggi inviati dal bot (best-effort tramite cache dei messaggi inviati).
|
||||
- Gli eventi di reazione continuano a rispettare i controlli di accesso Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); i mittenti non autorizzati vengono scartati.
|
||||
- Telegram non fornisce ID thread negli aggiornamenti di reazione.
|
||||
- Gli eventi di reazione rispettano comunque i controlli di accesso Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); i mittenti non autorizzati vengono scartati.
|
||||
- Telegram non fornisce ID thread negli aggiornamenti delle reazioni.
|
||||
- i gruppi non forum vengono instradati alla sessione chat di gruppo
|
||||
- i gruppi forum vengono instradati alla sessione del topic generale del gruppo (`:topic:1`), non al topic di origine esatto
|
||||
- i gruppi forum vengono instradati alla sessione del topic generale del gruppo (`:topic:1`), non al topic esatto di origine
|
||||
|
||||
`allowed_updates` per polling/webhook include automaticamente `message_reaction`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reazioni di ack">
|
||||
<Accordion title="Reazioni ack">
|
||||
`ackReaction` invia un'emoji di conferma mentre OpenClaw sta elaborando un messaggio in ingresso.
|
||||
|
||||
Ordine di risoluzione:
|
||||
@ -735,10 +672,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Le scritture attivate da Telegram includono:
|
||||
|
||||
- eventi di migrazione del gruppo (`migrate_to_chat_id`) per aggiornare `channels.telegram.groups`
|
||||
- `/config set` e `/config unset` (richiede l'abilitazione dei comandi)
|
||||
- eventi di migrazione gruppo (`migrate_to_chat_id`) per aggiornare `channels.telegram.groups`
|
||||
- `/config set` e `/config unset` (richiede abilitazione dei comandi)
|
||||
|
||||
Disabilitare:
|
||||
Disabilita:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -752,45 +689,28 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Autorizzazione del selettore modello nei gruppi">
|
||||
I pulsanti inline del selettore modello nei gruppi richiedono la stessa autorizzazione di `/models`. I partecipanti non autorizzati possono sfogliare e toccare i pulsanti, ma OpenClaw rifiuta il callback prima di cambiare il modello della sessione.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Long polling vs webhook">
|
||||
Predefinito: long polling.
|
||||
Il valore predefinito è long polling. Per la modalità webhook imposta `channels.telegram.webhookUrl` e `channels.telegram.webhookSecret`; opzionali `webhookPath`, `webhookHost`, `webhookPort` (predefiniti `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
|
||||
Modalità webhook:
|
||||
|
||||
- imposta `channels.telegram.webhookUrl`
|
||||
- imposta `channels.telegram.webhookSecret` (obbligatorio quando è impostato un URL webhook)
|
||||
- facoltativo `channels.telegram.webhookPath` (predefinito `/telegram-webhook`)
|
||||
- facoltativo `channels.telegram.webhookHost` (predefinito `127.0.0.1`)
|
||||
- facoltativo `channels.telegram.webhookPort` (predefinito `8787`)
|
||||
|
||||
Il listener locale predefinito per la modalità webhook si associa a `127.0.0.1:8787`.
|
||||
|
||||
Se il tuo endpoint pubblico è diverso, inserisci un reverse proxy davanti e punta `webhookUrl` all'URL pubblico.
|
||||
Imposta `webhookHost` (per esempio `0.0.0.0`) quando hai intenzionalmente bisogno di ingress esterno.
|
||||
|
||||
Il callback webhook di grammY restituisce un 200 entro 5 secondi così Telegram non ritenta gli aggiornamenti di lunga durata come timeout di lettura; il lavoro più lungo continua in background. Il polling ricostruisce il trasporto HTTP dopo conflitti `getUpdates` 409, così i tentativi usano una connessione TCP nuova invece di continuare in loop su un socket keep-alive terminato da Telegram.
|
||||
Il listener locale si collega a `127.0.0.1:8787`. Per ingress pubblico, metti un reverse proxy davanti alla porta locale oppure imposta intenzionalmente `webhookHost: "0.0.0.0"`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Limiti, retry e destinazioni CLI">
|
||||
<Accordion title="Limiti, retry e target CLI">
|
||||
- il valore predefinito di `channels.telegram.textChunkLimit` è 4000.
|
||||
- `channels.telegram.chunkMode="newline"` privilegia i confini dei paragrafi (righe vuote) prima della suddivisione per lunghezza.
|
||||
- `channels.telegram.chunkMode="newline"` preferisce i confini dei paragrafi (righe vuote) prima della suddivisione per lunghezza.
|
||||
- `channels.telegram.mediaMaxMb` (predefinito 100) limita la dimensione dei media Telegram in ingresso e in uscita.
|
||||
- `channels.telegram.timeoutSeconds` sovrascrive il timeout del client API Telegram (se non impostato, si applica il valore predefinito di grammY).
|
||||
- `channels.telegram.pollingStallThresholdMs` ha come valore predefinito `120000`; regolalo tra `30000` e `600000` solo per falsi positivi di riavvii per stallo del polling.
|
||||
- `channels.telegram.pollingStallThresholdMs` ha come valore predefinito `120000`; regolalo tra `30000` e `600000` solo per falsi positivi di riavvio per polling bloccato.
|
||||
- la cronologia del contesto di gruppo usa `channels.telegram.historyLimit` oppure `messages.groupChat.historyLimit` (predefinito 50); `0` disabilita.
|
||||
- il contesto supplementare di risposta/citazione/inoltro viene attualmente passato così come ricevuto.
|
||||
- le allowlist Telegram limitano principalmente chi può attivare l'agente, non sono un limite completo di redazione del contesto supplementare.
|
||||
- le allowlist Telegram controllano principalmente chi può attivare l'agente, non costituiscono un confine completo di redazione del contesto supplementare.
|
||||
- controlli della cronologia DM:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- la configurazione `channels.telegram.retry` si applica agli helper di invio Telegram (CLI/strumenti/azioni) per errori API in uscita recuperabili.
|
||||
- la configurazione `channels.telegram.retry` si applica agli helper di invio Telegram (CLI/tools/actions) per errori API in uscita recuperabili.
|
||||
|
||||
La destinazione di invio CLI può essere un ID chat numerico o un username:
|
||||
Il target di invio CLI può essere un ID chat numerico o un username:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
@ -812,75 +732,50 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- `--thread-id` per i topic del forum (oppure usa una destinazione `:topic:`)
|
||||
- `--thread-id` per i topic del forum (oppure usa un target `:topic:`)
|
||||
|
||||
L'invio Telegram supporta anche:
|
||||
|
||||
- `--presentation` con blocchi `buttons` per tastiere inline quando `channels.telegram.capabilities.inlineButtons` lo consente
|
||||
- `--pin` oppure `--delivery '{"pin":true}'` per richiedere la consegna fissata quando il bot può fissare in quella chat
|
||||
- `--pin` oppure `--delivery '{"pin":true}'` per richiedere la consegna fissata quando il bot può fissare messaggi in quella chat
|
||||
- `--force-document` per inviare immagini e GIF in uscita come documenti invece che come foto compresse o upload di media animati
|
||||
|
||||
Gating delle azioni:
|
||||
Controllo delle azioni:
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` disabilita i messaggi Telegram in uscita, inclusi i poll
|
||||
- `channels.telegram.actions.poll=false` disabilita la creazione di poll Telegram lasciando abilitati gli invii regolari
|
||||
- `channels.telegram.actions.poll=false` disabilita la creazione di poll Telegram lasciando abilitati i normali invii
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Approvazioni exec in Telegram">
|
||||
Telegram supporta le approvazioni exec nei DM degli approvatori e può facoltativamente pubblicare richieste di approvazione nella chat o nel topic di origine.
|
||||
Telegram supporta le approvazioni exec nei DM degli approvatori e può facoltativamente pubblicare i prompt nella chat o nel topic di origine. Gli approvatori devono essere ID utente Telegram numerici.
|
||||
|
||||
Percorso di configurazione:
|
||||
Percorso config:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled`
|
||||
- `channels.telegram.execApprovals.approvers` (facoltativo; usa come fallback gli ID proprietario numerici dedotti da `allowFrom` e `defaultTo` diretto quando possibile)
|
||||
- `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, predefinito: `dm`)
|
||||
- `channels.telegram.execApprovals.enabled` (si abilita automaticamente quando almeno un approvatore è risolvibile)
|
||||
- `channels.telegram.execApprovals.approvers` (usa come fallback gli ID proprietario numerici da `allowFrom` / `defaultTo`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (predefinito) | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
Gli approvatori devono essere ID utente Telegram numerici. Telegram abilita automaticamente le approvazioni exec native quando `enabled` non è impostato o è `"auto"` e può essere risolto almeno un approvatore, da `execApprovals.approvers` oppure dalla configurazione numerica del proprietario dell'account (`allowFrom` e `defaultTo` del messaggio diretto). Imposta `enabled: false` per disabilitare esplicitamente Telegram come client di approvazione nativo. In caso contrario, le richieste di approvazione tornano su altre route di approvazione configurate o sulla policy di fallback delle approvazioni exec.
|
||||
La consegna nel canale mostra il testo del comando nella chat; abilita `channel` o `both` solo in gruppi/topic fidati. Quando il prompt arriva in un topic del forum, OpenClaw preserva il topic per il prompt di approvazione e per il follow-up. Le approvazioni exec scadono dopo 30 minuti per impostazione predefinita.
|
||||
|
||||
Telegram renderizza anche i pulsanti di approvazione condivisi usati da altri canali chat. L'adapter Telegram nativo aggiunge soprattutto routing DM degli approvatori, fanout del canale/topic e suggerimenti di digitazione prima della consegna.
|
||||
Quando questi pulsanti sono presenti, rappresentano la UX 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.
|
||||
I pulsanti di approvazione inline richiedono anche che `channels.telegram.capabilities.inlineButtons` consenta la superficie di destinazione (`dm`, `group` o `all`). Gli ID di approvazione con prefisso `plugin:` vengono risolti tramite le approvazioni del plugin; gli altri vengono risolti prima tramite le approvazioni exec.
|
||||
|
||||
Regole di consegna:
|
||||
|
||||
- `target: "dm"` invia le richieste di approvazione solo ai DM degli approvatori risolti
|
||||
- `target: "channel"` reinvia la richiesta alla chat/topic Telegram di origine
|
||||
- `target: "both"` invia sia ai DM degli approvatori sia alla chat/topic di origine
|
||||
|
||||
Solo gli approvatori risolti possono approvare o negare. I non approvatori non possono usare `/approve` e non possono usare i pulsanti di approvazione Telegram.
|
||||
|
||||
Comportamento di risoluzione delle approvazioni:
|
||||
|
||||
- gli ID con prefisso `plugin:` vengono sempre risolti tramite approvazioni del plugin.
|
||||
- altri ID provano prima `exec.approval.resolve`.
|
||||
- se Telegram è autorizzato anche per le approvazioni del plugin e il gateway dice
|
||||
che l'approvazione exec è sconosciuta/scaduta, Telegram ritenta una volta tramite
|
||||
`plugin.approval.resolve`.
|
||||
- i rifiuti/errori reali delle approvazioni exec non ricadono in modo silenzioso nella risoluzione
|
||||
delle approvazioni del plugin.
|
||||
|
||||
La consegna al canale mostra il testo del comando nella chat, quindi abilita `channel` o `both` solo in gruppi/topic attendibili. Quando la richiesta arriva in un topic del forum, OpenClaw conserva il topic sia per la richiesta di approvazione sia per il follow-up successivo all'approvazione. Le approvazioni exec scadono dopo 30 minuti per impostazione predefinita.
|
||||
|
||||
I pulsanti di approvazione inline dipendono anche dal fatto che `channels.telegram.capabilities.inlineButtons` consenta la superficie di destinazione (`dm`, `group` o `all`).
|
||||
|
||||
Documentazione correlata: [Approvazioni exec](/it/tools/exec-approvals)
|
||||
Vedi [Approvazioni exec](/it/tools/exec-approvals).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Controlli delle risposte di errore
|
||||
## Controlli delle risposte agli errori
|
||||
|
||||
Quando l'agente incontra un errore di consegna o del provider, Telegram può rispondere con il testo dell'errore oppure sopprimerlo. Due chiavi di configurazione controllano questo comportamento:
|
||||
|
||||
| Chiave | Valori | Predefinito | Descrizione |
|
||||
| ----------------------------------- | ----------------- | ----------- | ----------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` invia un messaggio di errore comprensibile alla chat. `silent` sopprime completamente le risposte di errore. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Tempo minimo tra risposte di errore alla stessa chat. Previene spam di errori durante le interruzioni. |
|
||||
| ----------------------------------- | ----------------- | ----------- | ------------------------------------------------------------------------------------------------ |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` invia un messaggio di errore amichevole alla chat. `silent` sopprime completamente le risposte di errore. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Tempo minimo tra risposte di errore alla stessa chat. Previene spam di errori durante interruzioni. |
|
||||
|
||||
Sono supportati override per account, gruppo e topic (stessa ereditarietà delle altre chiavi di configurazione Telegram).
|
||||
Sono supportati override per account, per gruppo e per topic (stessa ereditarietà delle altre chiavi di configurazione Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -903,39 +798,39 @@ Sono supportati override per account, gruppo e topic (stessa ereditarietà delle
|
||||
<AccordionGroup>
|
||||
<Accordion title="Il bot non risponde ai messaggi di gruppo senza menzione">
|
||||
|
||||
- Se `requireMention=false`, la privacy mode di Telegram deve consentire visibilità completa.
|
||||
- BotFather: `/setprivacy` -> Disabilita
|
||||
- poi rimuovi + aggiungi di nuovo il bot al gruppo
|
||||
- `openclaw channels status` avverte quando la configurazione prevede messaggi di gruppo senza menzione.
|
||||
- `openclaw channels status --probe` può controllare ID gruppo numerici espliciti; la wildcard `"*"` non può essere verificata per membership.
|
||||
- test rapido di sessione: `/activation always`.
|
||||
- Se `requireMention=false`, la modalità privacy di Telegram deve consentire piena visibilità.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- poi rimuovi e aggiungi di nuovo il bot al gruppo
|
||||
- `openclaw channels status` avvisa quando la configurazione prevede messaggi di gruppo senza menzione.
|
||||
- `openclaw channels status --probe` può controllare ID gruppo numerici espliciti; il wildcard `"*"` non può essere verificato per appartenenza.
|
||||
- test rapido della sessione: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Il bot non vede affatto i messaggi di gruppo">
|
||||
|
||||
- quando esiste `channels.telegram.groups`, il gruppo deve essere elencato (oppure includere `"*"`)
|
||||
- verifica la presenza del bot nel gruppo
|
||||
- controlla i log: `openclaw logs --follow` per i motivi di salto
|
||||
- quando esiste `channels.telegram.groups`, il gruppo deve essere elencato (o includere `"*"`)
|
||||
- verifica l'appartenenza del bot al gruppo
|
||||
- controlla i log: `openclaw logs --follow` per i motivi di esclusione
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="I comandi funzionano parzialmente o non funzionano affatto">
|
||||
|
||||
- autorizza la tua identità mittente (pairing e/o `allowFrom` numerico)
|
||||
- l'autorizzazione dei comandi continua ad applicarsi anche quando la policy di gruppo è `open`
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu nativo ha troppe voci; riduci i comandi personalizzati/plugin/Skills oppure disabilita i menu nativi
|
||||
- autorizza la tua identità mittente (abbinamento e/o `allowFrom` numerico)
|
||||
- l'autorizzazione dei comandi si applica comunque anche quando la policy di gruppo è `open`
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu nativo ha troppe voci; riduci i comandi di plugin/Skills/personalizzati o disabilita i menu nativi
|
||||
- `setMyCommands failed` con errori di rete/fetch di solito indica problemi di raggiungibilità DNS/HTTPS verso `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Instabilità del polling o della rete">
|
||||
|
||||
- Node 22+ + fetch/proxy personalizzato possono attivare un comportamento di interruzione immediata se i tipi AbortSignal non corrispondono.
|
||||
- Alcuni host risolvono `api.telegram.org` prima su IPv6; un'uscita IPv6 non funzionante può causare errori intermittenti delle API Telegram.
|
||||
- Node 22+ + fetch/proxy personalizzato può attivare un comportamento di abort immediato se i tipi AbortSignal non corrispondono.
|
||||
- Alcuni host risolvono `api.telegram.org` prima in IPv6; un'uscita IPv6 guasta può causare errori intermittenti dell'API Telegram.
|
||||
- Se i log includono `TypeError: fetch failed` o `Network request for 'getUpdates' failed!`, OpenClaw ora li ritenta come errori di rete recuperabili.
|
||||
- Se i log includono `Polling stall detected`, OpenClaw riavvia il polling e ricostruisce il trasporto Telegram dopo 120 secondi senza liveness long-poll completata, per impostazione predefinita.
|
||||
- Aumenta `channels.telegram.pollingStallThresholdMs` solo quando le chiamate `getUpdates` di lunga durata sono sane ma il tuo host continua comunque a segnalare falsi riavvii per stallo del polling. Gli stalli persistenti di solito indicano problemi di proxy, DNS, IPv6 o uscita TLS tra l'host e `api.telegram.org`.
|
||||
- Se i log includono `Polling stall detected`, OpenClaw riavvia il polling e ricostruisce il trasporto Telegram dopo 120 secondi senza liveness long-poll completata per impostazione predefinita.
|
||||
- Aumenta `channels.telegram.pollingStallThresholdMs` solo quando le chiamate `getUpdates` di lunga durata sono sane ma il tuo host continua a segnalare falsi riavvii per polling bloccato. Blocchi persistenti di solito indicano problemi di proxy, DNS, IPv6 o uscita TLS tra l'host e `api.telegram.org`.
|
||||
- Su host VPS con uscita diretta/TLS instabile, instrada le chiamate API Telegram tramite `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
@ -944,8 +839,8 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ usa per impostazione predefinita `autoSelectFamily=true` (eccetto WSL2) e `dnsResultOrder=ipv4first`.
|
||||
- Se il tuo host è WSL2 o funziona esplicitamente meglio con comportamento solo IPv4, forza la selezione della famiglia:
|
||||
- Node 22+ usa per impostazione predefinita `autoSelectFamily=true` (tranne WSL2) e `dnsResultOrder=ipv4first`.
|
||||
- Se il tuo host è WSL2 o funziona esplicitamente meglio con un comportamento solo IPv4, forza la selezione della famiglia:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -955,10 +850,10 @@ channels:
|
||||
```
|
||||
|
||||
- Le risposte nell'intervallo benchmark RFC 2544 (`198.18.0.0/15`) sono già consentite
|
||||
per impostazione predefinita per i download di media Telegram. Se un fake-IP attendibile o
|
||||
un proxy trasparente riscrive `api.telegram.org` in un altro
|
||||
indirizzo privato/interno/special-use durante i download dei media, puoi aderire
|
||||
al bypass solo Telegram:
|
||||
per i download dei media Telegram per impostazione predefinita. Se un fake-IP fidato o
|
||||
un proxy trasparente riscrive `api.telegram.org` in qualche altro
|
||||
indirizzo privato/interno/special-use durante i download dei media, puoi scegliere
|
||||
il bypass solo Telegram:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -970,11 +865,14 @@ channels:
|
||||
- Lo stesso opt-in è disponibile per account in
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Se il tuo proxy risolve gli host media Telegram in `198.18.x.x`, lascia
|
||||
inizialmente disattivato il flag dangerous. I media Telegram consentono già per impostazione predefinita l'intervallo
|
||||
benchmark RFC 2544.
|
||||
prima disattivato il flag dangerous. I media Telegram consentono già per impostazione predefinita l'intervallo benchmark RFC 2544.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` indebolisce le protezioni SSRF dei media Telegram. Usalo solo per ambienti proxy attendibili controllati dall'operatore come Clash, Mihomo o routing fake-IP di Surge quando sintetizzano risposte private o special-use fuori dall'intervallo benchmark RFC 2544. Lascialo disattivato per il normale accesso Telegram su internet pubblico.
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` indebolisce le protezioni SSRF dei
|
||||
media Telegram. Usalo solo per ambienti proxy fidati controllati dall'operatore
|
||||
come routing fake-IP di Clash, Mihomo o Surge quando
|
||||
sintetizzano risposte private o special-use fuori dall'intervallo benchmark RFC 2544.
|
||||
Lascialo disattivato per il normale accesso Telegram su Internet pubblico.
|
||||
</Warning>
|
||||
|
||||
- Override env (temporanei):
|
||||
@ -993,86 +891,86 @@ dig +short api.telegram.org AAAA
|
||||
|
||||
Ulteriore aiuto: [Risoluzione dei problemi del canale](/it/channels/troubleshooting).
|
||||
|
||||
## Puntatori al riferimento di configurazione Telegram
|
||||
## Puntatori al riferimento della configurazione Telegram
|
||||
|
||||
Riferimento principale:
|
||||
|
||||
- `channels.telegram.enabled`: abilita/disabilita l'avvio del canale.
|
||||
- `channels.telegram.botToken`: token del bot (BotFather).
|
||||
- `channels.telegram.tokenFile`: legge il token da un normale percorso file. I symlink vengono rifiutati.
|
||||
- `channels.telegram.tokenFile`: legge il token da un percorso file regolare. I symlink sono rifiutati.
|
||||
- `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (predefinito: pairing).
|
||||
- `channels.telegram.allowFrom`: allowlist DM (ID utente Telegram numerici). `allowlist` richiede almeno un ID mittente. `open` richiede `"*"`. `openclaw doctor --fix` può risolvere le voci legacy `@username` in ID e può recuperare voci allowlist dai file pairing-store nei flussi di migrazione allowlist.
|
||||
- `channels.telegram.allowFrom`: allowlist DM (ID utente Telegram numerici). `allowlist` richiede almeno un ID mittente. `open` richiede `"*"`. `openclaw doctor --fix` può risolvere voci legacy `@username` in ID e può recuperare voci allowlist da file pairing-store nei flussi di migrazione allowlist.
|
||||
- `channels.telegram.actions.poll`: abilita o disabilita la creazione di poll Telegram (predefinito: abilitato; richiede comunque `sendMessage`).
|
||||
- `channels.telegram.defaultTo`: destinazione Telegram predefinita usata dalla CLI `--deliver` quando non viene fornito alcun `--reply-to` esplicito.
|
||||
- `channels.telegram.defaultTo`: target Telegram predefinito usato dalla CLI `--deliver` quando non viene fornito un `--reply-to` esplicito.
|
||||
- `channels.telegram.groupPolicy`: `open | allowlist | disabled` (predefinito: allowlist).
|
||||
- `channels.telegram.groupAllowFrom`: allowlist dei mittenti di gruppo (ID utente Telegram numerici). `openclaw doctor --fix` può risolvere le voci legacy `@username` in ID. Le voci non numeriche vengono ignorate in fase di autenticazione. L'autenticazione di gruppo non usa il fallback del pairing-store DM (`2026.2.25+`).
|
||||
- `channels.telegram.groupAllowFrom`: allowlist dei mittenti di gruppo (ID utente Telegram numerici). `openclaw doctor --fix` può risolvere voci legacy `@username` in ID. Le voci non numeriche vengono ignorate al momento dell'autorizzazione. L'autorizzazione di gruppo non usa il fallback DM pairing-store (`2026.2.25+`).
|
||||
- Precedenza multi-account:
|
||||
- Quando sono configurati due o più ID account, imposta `channels.telegram.defaultAccount` (oppure includi `channels.telegram.accounts.default`) per rendere esplicito il routing predefinito.
|
||||
- Se nessuno dei due è impostato, OpenClaw usa come fallback il primo ID account normalizzato e `openclaw doctor` emette un avviso.
|
||||
- `channels.telegram.accounts.default.allowFrom` e `channels.telegram.accounts.default.groupAllowFrom` si applicano solo all'account `default`.
|
||||
- Gli account nominati ereditano `channels.telegram.allowFrom` e `channels.telegram.groupAllowFrom` quando i valori a livello account non sono impostati.
|
||||
- Gli account nominati non ereditano `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`.
|
||||
- Gli account con nome ereditano `channels.telegram.allowFrom` e `channels.telegram.groupAllowFrom` quando i valori a livello account non sono impostati.
|
||||
- Gli account con nome non ereditano `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`.
|
||||
- `channels.telegram.groups`: valori predefiniti per gruppo + allowlist (usa `"*"` per valori predefiniti globali).
|
||||
- `channels.telegram.groups.<id>.groupPolicy`: override per gruppo di groupPolicy (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.requireMention`: valore predefinito del gating delle menzioni.
|
||||
- `channels.telegram.groups.<id>.requireMention`: valore predefinito del gating per menzione.
|
||||
- `channels.telegram.groups.<id>.skills`: filtro Skills (omesso = tutte le Skills, vuoto = nessuna).
|
||||
- `channels.telegram.groups.<id>.allowFrom`: override per gruppo dell'allowlist dei mittenti.
|
||||
- `channels.telegram.groups.<id>.allowFrom`: override della allowlist mittenti per gruppo.
|
||||
- `channels.telegram.groups.<id>.systemPrompt`: prompt di sistema aggiuntivo per il gruppo.
|
||||
- `channels.telegram.groups.<id>.enabled`: disabilita il gruppo quando è `false`.
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.*`: override per topic (campi di gruppo + `agentId` solo per topic).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.agentId`: instrada questo topic a un agente specifico (ha la precedenza sul routing a livello gruppo e binding).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.*`: override per topic (campi di gruppo + `agentId` solo topic).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.agentId`: instrada questo topic a un agente specifico (sovrascrive il routing a livello gruppo e binding).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.groupPolicy`: override per topic di groupPolicy (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention`: override per topic del gating delle menzioni.
|
||||
- `bindings[]` di livello superiore con `type: "acp"` e ID topic canonico `chatId:topic:topicId` in `match.peer.id`: campi di binding persistente del topic ACP (vedi [ACP Agents](/it/tools/acp-agents#channel-specific-settings)).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention`: override per topic del gating per menzione.
|
||||
- `bindings[]` di primo livello con `type: "acp"` e id topic canonico `chatId:topic:topicId` in `match.peer.id`: campi di binding persistente del topic ACP (vedi [Agenti ACP](/it/tools/acp-agents#channel-specific-settings)).
|
||||
- `channels.telegram.direct.<id>.topics.<threadId>.agentId`: instrada i topic DM a un agente specifico (stesso comportamento dei topic forum).
|
||||
- `channels.telegram.execApprovals.enabled`: abilita Telegram come client di approvazione exec basato su chat per questo account.
|
||||
- `channels.telegram.execApprovals.approvers`: ID utente Telegram autorizzati ad approvare o negare richieste exec. Facoltativo quando `channels.telegram.allowFrom` o un `channels.telegram.defaultTo` diretto identifica già il proprietario.
|
||||
- `channels.telegram.execApprovals.approvers`: ID utente Telegram autorizzati ad approvare o negare richieste exec. Opzionale quando `channels.telegram.allowFrom` o un `channels.telegram.defaultTo` diretto identifica già il proprietario.
|
||||
- `channels.telegram.execApprovals.target`: `dm | channel | both` (predefinito: `dm`). `channel` e `both` preservano il topic Telegram di origine quando presente.
|
||||
- `channels.telegram.execApprovals.agentFilter`: filtro facoltativo per ID agente per le richieste di approvazione inoltrate.
|
||||
- `channels.telegram.execApprovals.sessionFilter`: filtro facoltativo per chiave di sessione (sottostringa o regex) per le richieste di approvazione inoltrate.
|
||||
- `channels.telegram.accounts.<account>.execApprovals`: override per account del routing delle approvazioni exec Telegram e dell'autorizzazione degli approvatori.
|
||||
- `channels.telegram.execApprovals.agentFilter`: filtro opzionale per ID agente per i prompt di approvazione inoltrati.
|
||||
- `channels.telegram.execApprovals.sessionFilter`: filtro opzionale per chiave sessione (sottostringa o regex) per i prompt di approvazione inoltrati.
|
||||
- `channels.telegram.accounts.<account>.execApprovals`: override per account del routing di approvazione exec Telegram e dell'autorizzazione degli approvatori.
|
||||
- `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (predefinito: allowlist).
|
||||
- `channels.telegram.accounts.<account>.capabilities.inlineButtons`: override per account.
|
||||
- `channels.telegram.commands.nativeSkills`: abilita/disabilita i comandi nativi Skills di Telegram.
|
||||
- `channels.telegram.replyToMode`: `off | first | all` (predefinito: `off`).
|
||||
- `channels.telegram.textChunkLimit`: dimensione dei chunk in uscita (caratteri).
|
||||
- `channels.telegram.textChunkLimit`: dimensione chunk in uscita (caratteri).
|
||||
- `channels.telegram.chunkMode`: `length` (predefinito) oppure `newline` per dividere sulle righe vuote (confini dei paragrafi) prima del chunking per lunghezza.
|
||||
- `channels.telegram.linkPreview`: attiva/disattiva le anteprime dei link per i messaggi in uscita (predefinito: true).
|
||||
- `channels.telegram.streaming`: `off | partial | block | progress` (anteprima streaming live; predefinito: `partial`; `progress` viene mappato a `partial`; `block` è compatibilità legacy per la modalità anteprima). L'anteprima streaming Telegram usa un singolo messaggio di anteprima che viene modificato in place.
|
||||
- `channels.telegram.streaming.preview.toolProgress`: riusa il messaggio di anteprima live per aggiornamenti strumento/progresso quando l'anteprima streaming è attiva (predefinito: `true`). Imposta `false` per mantenere messaggi separati di strumento/progresso.
|
||||
- `channels.telegram.mediaMaxMb`: limite dei media Telegram in ingresso/uscita (MB, predefinito: 100).
|
||||
- `channels.telegram.retry`: policy di retry per gli helper di invio Telegram (CLI/strumenti/azioni) su errori API in uscita recuperabili (tentativi, minDelayMs, maxDelayMs, jitter).
|
||||
- `channels.telegram.network.autoSelectFamily`: override di Node autoSelectFamily (true=abilita, false=disabilita). Per impostazione predefinita è abilitato su Node 22+, con WSL2 impostato come predefinito su disabilitato.
|
||||
- `channels.telegram.network.dnsResultOrder`: override dell'ordine dei risultati DNS (`ipv4first` o `verbatim`). Il valore predefinito su Node 22+ è `ipv4first`.
|
||||
- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: opt-in pericoloso per ambienti attendibili fake-IP o con proxy trasparente in cui i download dei media Telegram risolvono `api.telegram.org` in indirizzi privati/interni/special-use fuori dall'intervallo benchmark RFC 2544 consentito per impostazione predefinita.
|
||||
- `channels.telegram.proxy`: URL proxy per le chiamate Bot API (SOCKS/HTTP).
|
||||
- `channels.telegram.webhookUrl`: abilita la modalità webhook (richiede `channels.telegram.webhookSecret`).
|
||||
- `channels.telegram.webhookSecret`: secret del webhook (obbligatorio quando è impostato `webhookUrl`).
|
||||
- `channels.telegram.webhookPath`: percorso webhook locale (predefinito `/telegram-webhook`).
|
||||
- `channels.telegram.webhookHost`: host di bind del webhook locale (predefinito `127.0.0.1`).
|
||||
- `channels.telegram.webhookPort`: porta di bind del webhook locale (predefinito `8787`).
|
||||
- `channels.telegram.actions.reactions`: gating delle reazioni dello strumento Telegram.
|
||||
- `channels.telegram.actions.sendMessage`: gating degli invii di messaggi dello strumento Telegram.
|
||||
- `channels.telegram.actions.deleteMessage`: gating delle eliminazioni di messaggi dello strumento Telegram.
|
||||
- `channels.telegram.actions.sticker`: gating delle azioni sticker Telegram — invio e ricerca (predefinito: false).
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` — controlla quali reazioni attivano eventi di sistema (predefinito: `own` se non impostato).
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — controlla la capacità di reazione dell'agente (predefinito: `minimal` se non impostato).
|
||||
- `channels.telegram.streaming`: `off | partial | block | progress` (anteprima streaming live; predefinito: `partial`; `progress` viene mappato a `partial`; `block` è compatibilità legacy della modalità anteprima). L'anteprima streaming Telegram usa un singolo messaggio di anteprima modificato sul posto.
|
||||
- `channels.telegram.streaming.preview.toolProgress`: riusa il messaggio di anteprima live per aggiornamenti di strumento/progresso quando l'anteprima streaming è attiva (predefinito: `true`). Imposta `false` per mantenere messaggi separati per strumento/progresso.
|
||||
- `channels.telegram.mediaMaxMb`: limite media Telegram in ingresso/uscita (MB, predefinito: 100).
|
||||
- `channels.telegram.retry`: policy di retry per gli helper di invio Telegram (CLI/tools/actions) su errori API in uscita recuperabili (tentativi, `minDelayMs`, `maxDelayMs`, jitter).
|
||||
- `channels.telegram.network.autoSelectFamily`: sovrascrive Node autoSelectFamily (true=abilita, false=disabilita). Predefinito abilitato su Node 22+, con WSL2 che per impostazione predefinita è disabilitato.
|
||||
- `channels.telegram.network.dnsResultOrder`: sovrascrive l'ordine dei risultati DNS (`ipv4first` o `verbatim`). Predefinito `ipv4first` su Node 22+.
|
||||
- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: opt-in pericoloso per ambienti fidati fake-IP o transparent-proxy in cui i download media Telegram risolvono `api.telegram.org` in indirizzi privati/interni/special-use fuori dall'allowance predefinita dell'intervallo benchmark RFC 2544.
|
||||
- `channels.telegram.proxy`: URL proxy per chiamate Bot API (SOCKS/HTTP).
|
||||
- `channels.telegram.webhookUrl`: abilita la modalità Webhook (richiede `channels.telegram.webhookSecret`).
|
||||
- `channels.telegram.webhookSecret`: segreto Webhook (richiesto quando è impostato webhookUrl).
|
||||
- `channels.telegram.webhookPath`: percorso Webhook locale (predefinito `/telegram-webhook`).
|
||||
- `channels.telegram.webhookHost`: host bind Webhook locale (predefinito `127.0.0.1`).
|
||||
- `channels.telegram.webhookPort`: porta bind Webhook locale (predefinito `8787`).
|
||||
- `channels.telegram.actions.reactions`: controllo delle reazioni degli strumenti Telegram.
|
||||
- `channels.telegram.actions.sendMessage`: controllo degli invii di messaggi degli strumenti Telegram.
|
||||
- `channels.telegram.actions.deleteMessage`: controllo delle eliminazioni di messaggi degli strumenti Telegram.
|
||||
- `channels.telegram.actions.sticker`: controllo delle azioni sticker Telegram — invio e ricerca (predefinito: false).
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` — controlla quali reazioni attivano eventi di sistema (predefinito: `own` quando non impostato).
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — controlla la capacità di reazione dell'agente (predefinito: `minimal` quando non impostato).
|
||||
- `channels.telegram.errorPolicy`: `reply | silent` — controlla il comportamento delle risposte di errore (predefinito: `reply`). Supporta override per account/gruppo/topic.
|
||||
- `channels.telegram.errorCooldownMs`: ms minimi tra risposte di errore alla stessa chat (predefinito: `60000`). Previene spam di errori durante le interruzioni.
|
||||
- `channels.telegram.errorCooldownMs`: ms minimi tra risposte di errore alla stessa chat (predefinito: `60000`). Previene spam di errori durante interruzioni.
|
||||
|
||||
- [Riferimento configurazione - Telegram](/it/gateway/configuration-reference#telegram)
|
||||
|
||||
Campi Telegram specifici ad alto segnale:
|
||||
|
||||
- avvio/autenticazione: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve puntare a un file normale; i symlink vengono rifiutati)
|
||||
- controllo accessi: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` di livello superiore (`type: "acp"`)
|
||||
- avvio/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve puntare a un file regolare; i symlink sono rifiutati)
|
||||
- controllo accessi: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` di primo livello (`type: "acp"`)
|
||||
- approvazioni exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- comando/menu: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- threading/risposte: `replyToMode`
|
||||
- streaming: `streaming` (anteprima), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- formattazione/consegna: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- media/rete: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- azioni/capacità: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- reazioni: `reactionNotifications`, `reactionLevel`
|
||||
- errori: `errorPolicy`, `errorCooldownMs`
|
||||
@ -1080,9 +978,9 @@ Campi Telegram specifici ad alto segnale:
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Pairing](/it/channels/pairing)
|
||||
- [Abbinamento](/it/channels/pairing)
|
||||
- [Gruppi](/it/channels/groups)
|
||||
- [Sicurezza](/it/gateway/security)
|
||||
- [Instradamento dei canali](/it/channels/channel-routing)
|
||||
- [Routing multi-agent](/it/concepts/multi-agent)
|
||||
- [Instradamento del canale](/it/channels/channel-routing)
|
||||
- [Instradamento multi-agente](/it/concepts/multi-agent)
|
||||
- [Risoluzione dei problemi](/it/channels/troubleshooting)
|
||||
|
||||
110
docs/it/ci.md
110
docs/it/ci.md
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Devi capire perché un job CI è stato o non è stato eseguito
|
||||
- Stai eseguendo il debug di controlli GitHub Actions non riusciti
|
||||
summary: Grafo dei job CI, gate di ambito ed equivalenti dei comandi locali
|
||||
- Devi capire perché un job CI è stato eseguito o non è stato eseguito.
|
||||
- Stai eseguendo il debug di controlli GitHub Actions non riusciti.
|
||||
summary: Grafico dei job CI, gate di ambito e comandi locali equivalenti
|
||||
title: Pipeline CI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T08:25:01Z"
|
||||
generated_at: "2026-04-23T13:57:58Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 5c89c66204b203a39435cfc19de7b437867f2792bbfa2c3948371abde9f80e11
|
||||
source_hash: c5a8ea0d8e428826169b0e6aced1caeb993106fe79904002125ace86b48cae1f
|
||||
source_path: ci.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Pipeline CI
|
||||
|
||||
La CI viene eseguita a ogni push su `main` e a ogni pull request. Usa uno scope intelligente per saltare i job costosi quando sono cambiate solo aree non correlate.
|
||||
La CI viene eseguita a ogni push su `main` e a ogni pull request. Usa uno scoping intelligente per saltare i job costosi quando sono cambiate solo aree non correlate.
|
||||
|
||||
QA Lab ha lane CI dedicate al di fuori del workflow principale con scope intelligente. Il
|
||||
workflow `Parity gate` viene eseguito su modifiche PR corrispondenti e tramite avvio manuale; crea
|
||||
il runtime QA privato e confronta i pack agentici mock GPT-5.4 e Opus 4.6.
|
||||
QA Lab ha lane CI dedicate al di fuori del workflow principale con smart scope. Il
|
||||
workflow `Parity gate` viene eseguito su modifiche PR corrispondenti e tramite invio manuale; esso
|
||||
compila il runtime QA privato e confronta i pacchetti agentici mock GPT-5.4 e Opus 4.6.
|
||||
Il workflow `QA-Lab - All Lanes` viene eseguito ogni notte su `main` e tramite
|
||||
avvio manuale; distribuisce in parallelo il parity gate mock, la lane Matrix live e la lane
|
||||
Telegram live. I job live usano l'ambiente `qa-live-shared`,
|
||||
invio manuale; distribuisce in parallelo il mock parity gate, la lane live Matrix e la lane live
|
||||
Telegram come job paralleli. I job live usano l'ambiente `qa-live-shared`,
|
||||
e la lane Telegram usa lease Convex. Anche `OpenClaw Release
|
||||
Checks` esegue le stesse lane QA Lab prima dell'approvazione della release.
|
||||
|
||||
@ -30,24 +30,24 @@ Checks` esegue le stesse lane QA Lab prima dell'approvazione della release.
|
||||
|
||||
| Job | Scopo | Quando viene eseguito |
|
||||
| -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ |
|
||||
| `preflight` | Rileva modifiche solo documentazione, scope modificati, estensioni modificate e costruisce il manifest CI | Sempre su push e PR non draft |
|
||||
| `security-scm-fast` | Rilevamento chiavi private e audit dei workflow tramite `zizmor` | Sempre su push e PR non draft |
|
||||
| `preflight` | Rileva modifiche solo-docs, scope modificati, extension modificate e costruisce il manifest CI | Sempre su push e PR non draft |
|
||||
| `security-scm-fast` | Rilevamento di chiavi private e audit del workflow tramite `zizmor` | Sempre su push e PR non draft |
|
||||
| `security-dependency-audit` | Audit del lockfile di produzione senza dipendenze rispetto agli advisory npm | Sempre su push e PR non draft |
|
||||
| `security-fast` | Aggregato obbligatorio per i job di sicurezza rapidi | Sempre su push e PR non draft |
|
||||
| `build-artifacts` | Build di `dist/`, Control UI, controlli degli artifact buildati e artifact riutilizzabili downstream | Modifiche rilevanti per Node |
|
||||
| `security-fast` | Aggregato richiesto per i job di sicurezza rapidi | Sempre su push e PR non draft |
|
||||
| `build-artifacts` | Compila `dist/`, Control UI, controlli degli artifact compilati e artifact riutilizzabili downstream | Modifiche rilevanti per Node |
|
||||
| `checks-fast-core` | Lane rapide di correttezza Linux come controlli bundled/plugin-contract/protocol | Modifiche rilevanti per Node |
|
||||
| `checks-fast-contracts-channels` | Controlli shardati dei contratti dei canali con un risultato di controllo aggregato stabile | Modifiche rilevanti per Node |
|
||||
| `checks-node-extensions` | Shard completi di test dei plugin inclusi in tutta la suite delle estensioni | Modifiche rilevanti per Node |
|
||||
| `checks-node-core-test` | Shard di test core Node, escluse lane di canale, bundled, contratto ed estensione | Modifiche rilevanti per Node |
|
||||
| `extension-fast` | Test mirati solo per i plugin inclusi modificati | Pull request con modifiche alle estensioni |
|
||||
| `check` | Equivalente shardato del gate locale principale: tipi prod, lint, guard, tipi test e smoke rigoroso | Modifiche rilevanti per Node |
|
||||
| `check-additional` | Shard di architettura, boundary, guard delle superfici delle estensioni, boundary di pacchetto e gateway-watch | Modifiche rilevanti per Node |
|
||||
| `build-smoke` | Smoke test della CLI buildata e smoke della memoria all'avvio | Modifiche rilevanti per Node |
|
||||
| `checks` | Verificatore per i test di canale su artifact buildati più compatibilità Node 22 solo push | Modifiche rilevanti per Node |
|
||||
| `check-docs` | Formattazione documentazione, lint e controlli dei link rotti | Documentazione modificata |
|
||||
| `skills-python` | Ruff + pytest per Skills supportate da Python | Modifiche rilevanti per Skills Python |
|
||||
| `checks-fast-contracts-channels` | Controlli sharded dei contratti dei canali con un risultato di check aggregato stabile | Modifiche rilevanti per Node |
|
||||
| `checks-node-extensions` | Shard completi di test dei bundled plugin sull'intera suite extension | Modifiche rilevanti per Node |
|
||||
| `checks-node-core-test` | Shard di test core Node, escluse le lane di canale, bundled, contratti ed extension | Modifiche rilevanti per Node |
|
||||
| `extension-fast` | Test mirati solo per i bundled plugin modificati | Pull request con modifiche alle extension |
|
||||
| `check` | Equivalente locale principale sharded del gate: tipi prod, lint, guard, tipi di test e smoke rigoroso | Modifiche rilevanti per Node |
|
||||
| `check-additional` | Guard di architettura, boundary, superficie extension, package-boundary e shard gateway-watch | Modifiche rilevanti per Node |
|
||||
| `build-smoke` | Smoke test della CLI compilata e smoke sulla memoria di avvio | Modifiche rilevanti per Node |
|
||||
| `checks` | Verificatore per test dei canali sugli artifact compilati più compatibilità Node 22 solo push | Modifiche rilevanti per Node |
|
||||
| `check-docs` | Controlli di formattazione docs, lint e link non validi | Docs modificate |
|
||||
| `skills-python` | Ruff + pytest per Skills basate su Python | Modifiche rilevanti per Skills Python |
|
||||
| `checks-windows` | Lane di test specifiche per Windows | Modifiche rilevanti per Windows |
|
||||
| `macos-node` | Lane di test TypeScript su macOS usando artifact buildati condivisi | Modifiche rilevanti per macOS |
|
||||
| `macos-node` | Lane di test TypeScript macOS che usa gli artifact compilati condivisi | Modifiche rilevanti per macOS |
|
||||
| `macos-swift` | Lint, build e test Swift per l'app macOS | Modifiche rilevanti per macOS |
|
||||
| `android` | Test unitari Android per entrambe le varianti più una build APK debug | Modifiche rilevanti per Android |
|
||||
|
||||
@ -55,53 +55,53 @@ Checks` esegue le stesse lane QA Lab prima dell'approvazione della release.
|
||||
|
||||
I job sono ordinati in modo che i controlli economici falliscano prima che vengano eseguiti quelli costosi:
|
||||
|
||||
1. `preflight` decide quali lane esistono del tutto. La logica `docs-scope` e `changed-scope` sono step interni a questo job, non job autonomi.
|
||||
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falliscono rapidamente senza attendere i job più pesanti della matrice di artifact e piattaforme.
|
||||
3. `build-artifacts` si sovrappone alle lane Linux rapide in modo che i consumer downstream possano iniziare non appena la build condivisa è pronta.
|
||||
4. Dopo questo si diramano le lane più pesanti di piattaforma e runtime: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast` solo PR, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`.
|
||||
1. `preflight` decide quali lane esistono effettivamente. La logica `docs-scope` e `changed-scope` è composta da step interni a questo job, non da job autonomi.
|
||||
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` e `skills-python` falliscono rapidamente senza attendere i job più pesanti della matrice artifact e piattaforme.
|
||||
3. `build-artifacts` si sovrappone alle lane Linux rapide così i consumer downstream possono iniziare non appena la build condivisa è pronta.
|
||||
4. Successivamente si distribuiscono le lane più pesanti di piattaforma e runtime: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast` solo PR, `checks`, `checks-windows`, `macos-node`, `macos-swift` e `android`.
|
||||
|
||||
La logica di scope vive in `scripts/ci-changed-scope.mjs` ed è coperta da unit test in `src/scripts/ci-changed-scope.test.ts`.
|
||||
Le modifiche ai workflow CI validano il grafo CI Node più il lint dei workflow, ma da sole non forzano build native Windows, Android o macOS; quelle lane di piattaforma restano limitate alle modifiche del codice sorgente della piattaforma.
|
||||
I controlli Node Windows sono limitati a wrapper di processo/percorso specifici di Windows, helper del runner npm/pnpm/UI, configurazione del package manager e superfici del workflow CI che eseguono quella lane; modifiche non correlate a sorgente, plugin, install-smoke e solo test restano sulle lane Linux Node così non riservano un worker Windows da 16 vCPU per copertura già esercitata dagli shard di test normali.
|
||||
Il workflow separato `install-smoke` riusa lo stesso script di scope tramite il proprio job `preflight`. Calcola `run_install_smoke` dal segnale changed-smoke più ristretto, quindi lo smoke Docker/install viene eseguito per modifiche rilevanti per installazione, packaging, container, modifiche di produzione alle estensioni incluse e superfici core plugin/canale/Gateway/Plugin SDK che i job smoke Docker esercitano. Le modifiche solo test e solo documentazione non riservano worker Docker. Il suo smoke del pacchetto QR forza il layer Docker `pnpm install` a essere rieseguito preservando la cache BuildKit dello store pnpm, quindi continua a esercitare l'installazione senza riscaricare le dipendenze a ogni esecuzione. Il suo e2e gateway-network riusa l'immagine runtime buildata in precedenza nel job, quindi aggiunge copertura WebSocket reale da container a container senza aggiungere un'altra build Docker. Il comando locale `test:docker:all` precompila un'unica immagine built-app condivisa di `scripts/e2e/Dockerfile` e la riusa nei runner smoke E2E in container; il workflow live/E2E riutilizzabile rispecchia questo schema creando e pubblicando un'unica immagine Docker E2E GHCR taggata SHA prima della matrice Docker, poi eseguendo la matrice con `OPENCLAW_SKIP_DOCKER_BUILD=1`. I test Docker QR e installer mantengono i propri Dockerfile focalizzati sull'installazione. Un job separato `docker-e2e-fast` esegue il profilo Docker bounded bundled-plugin con un timeout comando di 120 secondi: riparazione delle dipendenze setup-entry più isolamento sintetico dei fallimenti bundled-loader. La matrice completa di aggiornamento bundled/canale resta manuale/full-suite perché esegue passaggi ripetuti reali di aggiornamento npm e riparazione doctor.
|
||||
La logica di scope si trova in `scripts/ci-changed-scope.mjs` ed è coperta da unit test in `src/scripts/ci-changed-scope.test.ts`.
|
||||
Le modifiche ai workflow CI convalidano il grafo CI Node più il lint dei workflow, ma non forzano da sole build native Windows, Android o macOS; quelle lane di piattaforma restano limitate alle modifiche del codice sorgente della piattaforma.
|
||||
I controlli Node Windows sono limitati a wrapper specifici di processo/percorso Windows, helper npm/pnpm/UI runner, configurazione del package manager e superfici del workflow CI che eseguono quella lane; modifiche non correlate a sorgente, plugin, install-smoke e solo test restano sulle lane Linux Node, così non riservano un worker Windows da 16 vCPU per copertura già esercitata dai normali shard di test.
|
||||
Il workflow separato `install-smoke` riusa lo stesso script di scope tramite il proprio job `preflight`. Calcola `run_install_smoke` a partire dal segnale changed-smoke più ristretto, quindi lo smoke Docker/install viene eseguito per modifiche rilevanti a installazione, packaging, container, produzione delle bundled extension e alle superfici core plugin/channel/gateway/Plugin SDK che i job Docker smoke esercitano. Le modifiche solo test e solo docs non riservano worker Docker. Il suo QR package smoke forza il layer Docker `pnpm install` a essere rieseguito preservando la cache BuildKit dello store pnpm, così esercita comunque l'installazione senza riscaricare le dipendenze a ogni esecuzione. Il suo gateway-network e2e riusa l'immagine runtime compilata in precedenza nel job, quindi aggiunge copertura WebSocket reale da container a container senza aggiungere un'altra build Docker. L'aggregato locale `test:docker:all` precompila un'unica immagine live-test condivisa e un'unica immagine built-app condivisa `scripts/e2e/Dockerfile`, poi esegue in parallelo le lane smoke live/E2E con `OPENCLAW_SKIP_DOCKER_BUILD=1`; regola la concorrenza predefinita di 4 con `OPENCLAW_DOCKER_ALL_PARALLELISM`. L'aggregato locale, per impostazione predefinita, smette di pianificare nuove lane nel pool dopo il primo errore e ogni lane ha un timeout di 120 minuti, modificabile con `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Le lane sensibili all'avvio o al provider vengono eseguite in esclusiva dopo il pool parallelo. Il workflow live/E2E riutilizzabile rispecchia il pattern a immagine condivisa compilando e pubblicando una singola immagine Docker E2E GHCR con tag SHA prima della matrice Docker, quindi eseguendo la matrice con `OPENCLAW_SKIP_DOCKER_BUILD=1`. Il workflow live/E2E pianificato esegue quotidianamente l'intera suite Docker del percorso di release. I test Docker di QR e installer mantengono i propri Dockerfile focalizzati sull'installazione. Un job separato `docker-e2e-fast` esegue il profilo Docker bounded bundled-plugin con un timeout del comando di 120 secondi: riparazione delle dipendenze setup-entry più isolamento sintetico dei guasti del bundled-loader. La matrice completa bundled update/channel resta manuale/full-suite perché esegue ripetuti passaggi reali di npm update e doctor repair.
|
||||
|
||||
La logica locale changed-lane vive in `scripts/changed-lanes.mjs` ed è eseguita da `scripts/check-changed.mjs`. Quel gate locale è più rigoroso sui boundary architetturali rispetto all'ampio scope CI di piattaforma: le modifiche di produzione core eseguono typecheck prod core più test core, le modifiche solo test core eseguono solo typecheck/test core, le modifiche di produzione alle estensioni eseguono typecheck prod delle estensioni più test delle estensioni, e le modifiche solo test delle estensioni eseguono solo typecheck/test delle estensioni. Le modifiche al Plugin SDK pubblico o ai plugin-contract espandono la validazione alle estensioni perché le estensioni dipendono da quei contratti core. I version bump solo metadati di release eseguono controlli mirati di versione/configurazione/dipendenze root. Le modifiche sconosciute a root/configurazione falliscono in modo sicuro su tutte le lane.
|
||||
La logica locale delle lane modificate si trova in `scripts/changed-lanes.mjs` ed è eseguita da `scripts/check-changed.mjs`. Quel gate locale è più rigoroso sui boundary architetturali rispetto all'ampio scope CI di piattaforma: le modifiche di produzione core eseguono typecheck prod core più test core, le modifiche solo test core eseguono solo typecheck/test core di test, le modifiche di produzione extension eseguono typecheck prod extension più test extension, e le modifiche solo test extension eseguono solo typecheck/test extension di test. Le modifiche al Plugin SDK pubblico o al plugin-contract estendono la validazione alle extension perché le extension dipendono da quei contratti core. I version bump solo metadata di release eseguono controlli mirati di versione/config/dipendenze root. Le modifiche root/config sconosciute fanno fail safe su tutte le lane.
|
||||
|
||||
Sui push, la matrice `checks` aggiunge la lane `compat-node22` solo push. Sulle pull request, quella lane viene saltata e la matrice resta focalizzata sulle normali lane test/canale.
|
||||
Sui push, la matrice `checks` aggiunge la lane `compat-node22` solo push. Sulle pull request, quella lane viene saltata e la matrice resta focalizzata sulle normali lane di test/canale.
|
||||
|
||||
Le famiglie di test Node più lente sono suddivise o bilanciate in modo che ogni job resti contenuto: i contratti dei canali dividono la copertura registry e core in sei shard pesati totali, i test dei plugin inclusi sono bilanciati su sei worker delle estensioni, auto-reply gira come tre worker bilanciati invece di sei piccoli worker, e le configurazioni agentiche gateway/plugin sono distribuite sui job agentici Node esistenti solo-sorgente invece di attendere gli artifact buildati. I test ampi di browser, QA, media e plugin vari usano le proprie configurazioni Vitest dedicate invece del catch-all condiviso dei plugin. L'ampia lane agents usa lo scheduler file-parallel condiviso di Vitest perché è dominata da import/scheduling invece che da un singolo file di test lento. `runtime-config` gira con lo shard infra core-runtime per evitare che lo shard runtime condiviso possieda la coda finale. `check-additional` tiene insieme il lavoro di compile/canary del package-boundary e separa l'architettura della topologia runtime dalla copertura gateway watch; lo shard boundary guard esegue in concorrenza i suoi piccoli guard indipendenti all'interno di un job. Gateway watch, test dei canali e shard core support-boundary girano in concorrenza dentro `build-artifacts` dopo che `dist/` e `dist-runtime/` sono già stati buildati, mantenendo i loro vecchi nomi di check come job verificatori leggeri ed evitando due worker Blacksmith aggiuntivi e una seconda coda di consumer di artifact.
|
||||
La CI Android esegue sia `testPlayDebugUnitTest` sia `testThirdPartyDebugUnitTest`, poi crea la build dell'APK debug Play. La variante third-party non ha un source set o un manifest separato; la sua lane di test unitari continua comunque a compilare quella variante con i flag BuildConfig SMS/call-log, evitando al contempo un job duplicato di packaging APK debug a ogni push rilevante per Android.
|
||||
`extension-fast` è solo PR perché le esecuzioni push eseguono già gli shard completi dei plugin inclusi. Questo mantiene il feedback sui plugin modificati per le review senza riservare un worker Blacksmith aggiuntivo su `main` per copertura già presente in `checks-node-extensions`.
|
||||
Le famiglie di test Node più lente sono divise o bilanciate in modo che ogni job resti piccolo: i contratti dei canali dividono la copertura registry e core in sei shard pesati totali, i test dei bundled plugin sono bilanciati su sei worker extension, auto-reply viene eseguito come tre worker bilanciati invece di sei piccoli worker, e le configurazioni agentic gateway/plugin sono distribuite sui job Node agentic esistenti solo-sorgente invece di attendere gli artifact compilati. I test ampi browser, QA, media e plugin vari usano le loro configurazioni Vitest dedicate invece del catch-all condiviso per i plugin. La lane agents ampia usa lo scheduler condiviso di parallelismo per file di Vitest perché è dominata da import/scheduling piuttosto che da un singolo file di test lento. `runtime-config` viene eseguito con lo shard infra core-runtime per evitare che lo shard runtime condiviso possieda la coda finale. `check-additional` tiene insieme il lavoro compile/canary di package-boundary e separa l'architettura della topologia runtime dalla copertura gateway watch; lo shard boundary guard esegue i suoi piccoli guard indipendenti in parallelo all'interno di un unico job. Gateway watch, test dei canali e lo shard core support-boundary vengono eseguiti in parallelo all'interno di `build-artifacts` dopo che `dist/` e `dist-runtime/` sono già stati compilati, mantenendo i loro vecchi nomi di check come job verificatori leggeri ed evitando due worker Blacksmith aggiuntivi e una seconda coda di consumer degli artifact.
|
||||
La CI Android esegue sia `testPlayDebugUnitTest` sia `testThirdPartyDebugUnitTest`, quindi compila l'APK debug Play. La variante third-party non ha un source set o manifest separato; la sua lane di unit test compila comunque quella variante con i flag BuildConfig SMS/call-log, evitando però un job duplicato di packaging APK debug a ogni push rilevante per Android.
|
||||
`extension-fast` è solo PR perché le esecuzioni push eseguono già gli shard completi dei bundled plugin. Questo mantiene il feedback sui plugin modificati per le review senza riservare un worker Blacksmith aggiuntivo su `main` per una copertura già presente in `checks-node-extensions`.
|
||||
|
||||
GitHub può contrassegnare i job sostituiti come `cancelled` quando un push più recente arriva sulla stessa PR o sul ref `main`. Consideralo rumore CI a meno che anche l'esecuzione più recente per lo stesso ref non stia fallendo. I check aggregati degli shard usano `!cancelled() && always()` così riportano comunque i normali fallimenti degli shard ma non si accodano dopo che l'intero workflow è già stato sostituito.
|
||||
La chiave di concorrenza CI è versionata (`CI-v7-*`) così un processo zombie lato GitHub in un vecchio gruppo di coda non può bloccare indefinitamente le nuove esecuzioni su main.
|
||||
GitHub può contrassegnare come `cancelled` i job superati quando arriva un push più recente sullo stesso ref PR o `main`. Consideralo rumore della CI, a meno che anche l'esecuzione più recente per lo stesso ref non stia fallendo. I check shard aggregati usano `!cancelled() && always()` così riportano comunque i normali errori degli shard, ma non si mettono in coda dopo che l'intero workflow è già stato superato.
|
||||
La chiave di concorrenza CI è versionata (`CI-v7-*`) così uno zombie lato GitHub in un vecchio gruppo di coda non può bloccare indefinitamente le esecuzioni più recenti su main.
|
||||
|
||||
## Runner
|
||||
|
||||
| Runner | Job |
|
||||
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ubuntu-24.04` | `preflight`, job di sicurezza rapidi e aggregati (`security-scm-fast`, `security-dependency-audit`, `security-fast`), controlli rapidi di protocollo/contratti/bundled, controlli shardati dei contratti dei canali, shard di `check` tranne lint, shard e aggregati di `check-additional`, verificatori aggregati dei test Node, controlli documentazione, Skills Python, workflow-sanity, labeler, auto-response; anche il preflight di install-smoke usa Ubuntu ospitato da GitHub così la matrice Blacksmith può mettersi in coda prima |
|
||||
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard di test Linux Node, shard di test dei plugin inclusi, `android` |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, che resta abbastanza sensibile alla CPU da far costare 8 vCPU più di quanto facessero risparmiare; build Docker di install-smoke, dove il costo del tempo di coda a 32 vCPU era superiore al risparmio ottenuto |
|
||||
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
|
||||
| `blacksmith-6vcpu-macos-latest` | `macos-node` su `openclaw/openclaw`; i fork usano come fallback `macos-latest` |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-swift` su `openclaw/openclaw`; i fork usano come fallback `macos-latest` |
|
||||
| Runner | Job |
|
||||
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `ubuntu-24.04` | `preflight`, job e aggregati di sicurezza rapidi (`security-scm-fast`, `security-dependency-audit`, `security-fast`), controlli rapidi protocol/contract/bundled, controlli sharded dei contratti dei canali, shard `check` tranne lint, shard e aggregati `check-additional`, verificatori aggregati dei test Node, controlli docs, Skills Python, workflow-sanity, labeler, auto-response; anche il preflight install-smoke usa Ubuntu ospitato da GitHub così la matrice Blacksmith può mettersi in coda prima |
|
||||
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard di test Linux Node, shard di test dei bundled plugin, `android` |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, che resta abbastanza sensibile alla CPU da far costare di più 8 vCPU rispetto a quanto facesse risparmiare; build Docker install-smoke, dove il tempo di coda a 32 vCPU costava più di quanto facesse risparmiare |
|
||||
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
|
||||
| `blacksmith-6vcpu-macos-latest` | `macos-node` su `openclaw/openclaw`; i fork fanno fallback a `macos-latest` |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-swift` su `openclaw/openclaw`; i fork fanno fallback a `macos-latest` |
|
||||
|
||||
## Equivalenti locali
|
||||
|
||||
```bash
|
||||
pnpm changed:lanes # ispeziona il classificatore locale delle changed-lane per origin/main...HEAD
|
||||
pnpm changed:lanes # ispeziona il classificatore locale delle lane modificate per origin/main...HEAD
|
||||
pnpm check:changed # gate locale intelligente: typecheck/lint/test modificati per lane di boundary
|
||||
pnpm check # gate locale rapido: tsgo di produzione + lint shardato + guard rapidi in parallelo
|
||||
pnpm check # gate locale rapido: tsgo di produzione + lint sharded + guard rapidi in parallelo
|
||||
pnpm check:test-types
|
||||
pnpm check:timed # stesso gate con timing per fase
|
||||
pnpm check:timed # stesso gate con tempistiche per fase
|
||||
pnpm build:strict-smoke
|
||||
pnpm check:architecture
|
||||
pnpm test:gateway:watch-regression
|
||||
pnpm test # test vitest
|
||||
pnpm test:channels
|
||||
pnpm test:contracts:channels
|
||||
pnpm check:docs # formato documentazione + lint + link rotti
|
||||
pnpm build # build di dist quando contano le lane CI artifact/build-smoke
|
||||
node scripts/ci-run-timings.mjs <run-id> # riepiloga wall time, tempo di coda e job più lenti
|
||||
pnpm check:docs # formato docs + lint + link interrotti
|
||||
pnpm build # compila dist quando le lane CI artifact/build-smoke sono rilevanti
|
||||
node scripts/ci-run-timings.mjs <run-id> # riassume il tempo totale, il tempo di coda e i job più lenti
|
||||
```
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Vuoi una diagnosi rapida dello stato dei canali + dei destinatari delle sessioni recenti
|
||||
- Vuoi una diagnosi rapida dello stato del canale + i destinatari recenti della sessione
|
||||
- Vuoi uno stato “all” copiabile per il debug
|
||||
summary: Riferimento CLI per `openclaw status` (diagnostica, probe, istantanee di utilizzo)
|
||||
title: status
|
||||
summary: Riferimento della CLI per `openclaw status` (diagnostica, probe, istantanee di utilizzo)
|
||||
title: stato
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:48:59Z"
|
||||
generated_at: "2026-04-23T13:57:57Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fbe9d94fbe9938cd946ee6f293b5bd3b464b75e1ade2eacdd851788c3bffe94e
|
||||
source_hash: 015614e329ec172a62c625581897fa64589f12dfe28edefe8a2764b5b5367b2a
|
||||
source_path: cli/status.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -27,16 +27,17 @@ openclaw status --usage
|
||||
Note:
|
||||
|
||||
- `--deep` esegue probe live (WhatsApp Web + Telegram + Discord + Slack + Signal).
|
||||
- `--usage` stampa finestre di utilizzo normalizzate del provider come `X% left`.
|
||||
- I campi grezzi `usage_percent` / `usagePercent` di MiniMax rappresentano la quota rimanente, quindi OpenClaw li inverte prima della visualizzazione; i campi basati sul conteggio hanno la precedenza quando presenti. Le risposte `model_remains` preferiscono la voce del modello chat, ricavano l'etichetta della finestra temporale dai timestamp quando necessario e includono il nome del modello nell'etichetta del piano.
|
||||
- Quando l'istantanea della sessione corrente è scarsa, `/status` può riempire i contatori di token e cache dal log di utilizzo della trascrizione più recente. I valori live esistenti diversi da zero continuano comunque ad avere la precedenza rispetto ai valori di fallback della trascrizione.
|
||||
- Il fallback della trascrizione può anche recuperare l'etichetta del modello di runtime attivo quando manca nella voce della sessione live. Se quel modello della trascrizione differisce dal modello selezionato, status risolve la finestra di contesto rispetto al modello di runtime recuperato invece che a quello selezionato.
|
||||
- Per il conteggio della dimensione del prompt, il fallback della trascrizione preferisce il totale orientato al prompt più grande quando i metadati della sessione mancano o sono inferiori, in modo che le sessioni con provider personalizzati non vengano ridotte a visualizzazioni di `0` token.
|
||||
- `--usage` stampa finestre di utilizzo del provider normalizzate come `X% left`.
|
||||
- L'output dello stato della sessione ora separa `Runtime:` da `Runner:`. `Runtime` è il percorso di esecuzione e lo stato della sandbox (`direct`, `docker/*`), mentre `Runner` indica se la sessione sta usando Pi incorporato, un provider supportato da CLI o un backend harness ACP come `codex (acp/acpx)`.
|
||||
- I campi grezzi `usage_percent` / `usagePercent` di MiniMax rappresentano la quota rimanente, quindi OpenClaw li inverte prima della visualizzazione; i campi basati sul conteggio hanno la precedenza quando presenti. Le risposte `model_remains` privilegiano la voce del modello di chat, ricavano l'etichetta della finestra temporale dai timestamp quando necessario e includono il nome del modello nell'etichetta del piano.
|
||||
- Quando l'istantanea della sessione corrente è scarsa di dati, `/status` può completare i contatori di token e cache dal log di utilizzo della trascrizione più recente. I valori live esistenti e non nulli continuano ad avere la precedenza sui valori di fallback della trascrizione.
|
||||
- Il fallback della trascrizione può anche recuperare l'etichetta del modello runtime attivo quando manca nella voce della sessione live. Se quel modello della trascrizione differisce dal modello selezionato, status risolve la finestra di contesto rispetto al modello runtime recuperato invece che a quello selezionato.
|
||||
- Per il conteggio della dimensione del prompt, il fallback della trascrizione privilegia il totale orientato al prompt più grande quando i metadati della sessione mancano o sono inferiori, così le sessioni con provider personalizzati non vengono ridotte a visualizzazioni di `0` token.
|
||||
- L'output include archivi di sessione per agente quando sono configurati più agenti.
|
||||
- La panoramica include lo stato di installazione/runtime del servizio host Gateway + nodo quando disponibile.
|
||||
- La panoramica include il canale di aggiornamento + il git SHA (per i checkout dal sorgente).
|
||||
- Le informazioni sugli aggiornamenti vengono mostrate nella Panoramica; se è disponibile un aggiornamento, status stampa un suggerimento per eseguire `openclaw update` (vedi [Updating](/install/updating)).
|
||||
- Le superfici di stato in sola lettura (`status`, `status --json`, `status --all`) risolvono i SecretRef supportati per i percorsi di configurazione mirati quando possibile.
|
||||
- Se è configurato un SecretRef di canale supportato ma non è disponibile nel percorso del comando corrente, status resta in sola lettura e segnala un output degradato invece di bloccarsi. L'output per gli esseri umani mostra avvisi come “token configurato non disponibile in questo percorso del comando”, e l'output JSON include `secretDiagnostics`.
|
||||
- Quando la risoluzione locale del SecretRef del comando ha successo, status preferisce l'istantanea risolta e rimuove i marker temporanei di canale “secret unavailable” dall'output finale.
|
||||
- `status --all` include una riga di panoramica dei Secrets e una sezione di diagnosi che riepiloga la diagnostica dei secret (troncata per leggibilità) senza interrompere la generazione del report.
|
||||
- La panoramica include lo stato di installazione/runtime del servizio host di Gateway + node quando disponibile.
|
||||
- La panoramica include il canale di aggiornamento + SHA git (per i checkout dal sorgente).
|
||||
- Le informazioni sugli aggiornamenti compaiono nella panoramica; se è disponibile un aggiornamento, status stampa un suggerimento per eseguire `openclaw update` (vedi [Aggiornamento](/it/install/updating)).
|
||||
- Le superfici di stato in sola lettura (`status`, `status --json`, `status --all`) risolvono i SecretRef supportati per i percorsi di configurazione di destinazione quando possibile.
|
||||
- Se un SecretRef di un canale supportato è configurato ma non disponibile nel percorso del comando corrente, status rimane in sola lettura e segnala un output degradato invece di arrestarsi in modo anomalo. L'output leggibile mostra avvisi come “token configurato non disponibile in questo percorso del comando”, e l'output JSON include `secretDiagnostics`.
|
||||
- Quando la risoluzione locale al comando di SecretRef riesce, status privilegia l'istantanea risolta e rimuove dall'output finale i marker transitori del canale “secret unavailable”.
|
||||
- `status --all` include una riga di panoramica Secrets e una sezione di diagnosi che riassume la diagnostica dei secret (troncata per leggibilità) senza interrompere la generazione del report.
|
||||
|
||||
@ -2,35 +2,35 @@
|
||||
read_when:
|
||||
- Estendere qa-lab o qa-channel
|
||||
- Aggiunta di scenari QA supportati dal repository
|
||||
- Creazione di automazione QA a maggiore realismo attorno alla dashboard del Gateway
|
||||
summary: Forma dell'automazione QA privata per qa-lab, qa-channel, scenari con seed e report di protocollo
|
||||
title: Automazione QA end-to-end
|
||||
- Creazione di un'automazione QA con maggiore realismo attorno alla dashboard del Gateway
|
||||
summary: Forma dell'automazione QA privata per qa-lab, qa-channel, scenari con seed e report del protocollo
|
||||
title: Automazione QA E2E
|
||||
x-i18n:
|
||||
generated_at: "2026-04-20T08:30:54Z"
|
||||
generated_at: "2026-04-23T13:58:00Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 34245ce871356caeab0d9e0eeeaa9fb4e408920a4a97ad27567fa365d8db17c7
|
||||
source_hash: a967a74d2e70b042e9443c5ec954902b820d2e5a22cbecd9be74af13b9085553
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Automazione QA end-to-end
|
||||
# Automazione QA E2E
|
||||
|
||||
Lo stack QA privato è pensato per esercitare OpenClaw in un modo più realistico,
|
||||
con una forma simile ai canali, rispetto a quanto possa fare un singolo test unitario.
|
||||
con una forma simile a quella dei canali, rispetto a quanto possa fare un singolo test unitario.
|
||||
|
||||
Componenti attuali:
|
||||
|
||||
- `extensions/qa-channel`: canale di messaggistica sintetico con superfici per messaggi diretti, canale, thread,
|
||||
reazioni, modifiche ed eliminazioni.
|
||||
- `extensions/qa-lab`: interfaccia debugger e bus QA per osservare la trascrizione,
|
||||
iniettare messaggi in ingresso ed esportare un report Markdown.
|
||||
- `qa/`: risorse seed supportate dal repository per il task iniziale e gli scenari QA
|
||||
- `extensions/qa-channel`: canale di messaggi sintetico con superfici DM, canale, thread,
|
||||
reazione, modifica ed eliminazione.
|
||||
- `extensions/qa-lab`: interfaccia utente di debug e bus QA per osservare la trascrizione,
|
||||
iniettare messaggi in entrata ed esportare un report in Markdown.
|
||||
- `qa/`: asset seed supportati dal repository per il task iniziale e gli scenari QA
|
||||
di base.
|
||||
|
||||
L'attuale flusso operativo QA è un sito QA a due pannelli:
|
||||
L'attuale flusso dell'operatore QA è un sito QA a due pannelli:
|
||||
|
||||
- Sinistra: dashboard del Gateway (Control UI) con l'agente.
|
||||
- Sinistra: dashboard del Gateway (interfaccia di controllo) con l'agente.
|
||||
- Destra: QA Lab, che mostra la trascrizione in stile Slack e il piano dello scenario.
|
||||
|
||||
Eseguilo con:
|
||||
@ -39,13 +39,13 @@ Eseguilo con:
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
Questo compila il sito QA, avvia la corsia gateway supportata da Docker ed espone la
|
||||
pagina QA Lab dove un operatore o un ciclo di automazione può assegnare all'agente una
|
||||
missione QA, osservare il comportamento reale del canale e registrare cosa ha funzionato, cosa è fallito o
|
||||
Questo compila il sito QA, avvia la corsia Gateway supportata da Docker ed espone la
|
||||
pagina QA Lab dove un operatore o un loop di automazione può assegnare all'agente una missione QA,
|
||||
osservare il comportamento reale del canale e registrare cosa ha funzionato, cosa è fallito o
|
||||
cosa è rimasto bloccato.
|
||||
|
||||
Per iterazioni più rapide dell'interfaccia di QA Lab senza ricompilare ogni volta l'immagine Docker,
|
||||
avvia lo stack con un bundle QA Lab montato tramite bind:
|
||||
Per un'iterazione più rapida dell'interfaccia di QA Lab senza ricompilare ogni volta l'immagine Docker,
|
||||
avvia lo stack con un bundle di QA Lab montato tramite bind mount:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa docker-build-image
|
||||
@ -56,8 +56,8 @@ pnpm qa:lab:watch
|
||||
|
||||
`qa:lab:up:fast` mantiene i servizi Docker su un'immagine precompilata e monta tramite bind
|
||||
`extensions/qa-lab/web/dist` nel container `qa-lab`. `qa:lab:watch`
|
||||
ricompila quel bundle a ogni modifica e il browser si ricarica automaticamente quando cambia l'hash
|
||||
delle risorse di QA Lab.
|
||||
ricompila quel bundle a ogni modifica e il browser si ricarica automaticamente quando l'hash
|
||||
degli asset di QA Lab cambia.
|
||||
|
||||
Per una corsia smoke Matrix con trasporto reale, esegui:
|
||||
|
||||
@ -65,11 +65,11 @@ Per una corsia smoke Matrix con trasporto reale, esegui:
|
||||
pnpm openclaw qa matrix
|
||||
```
|
||||
|
||||
Questa corsia effettua il provisioning di un homeserver Tuwunel usa e getta in Docker, registra
|
||||
utenti temporanei driver, SUT e observer, crea una stanza privata, quindi esegue
|
||||
il vero plugin Matrix all'interno di un processo figlio QA del gateway. La corsia con trasporto live mantiene
|
||||
la configurazione figlia limitata al trasporto in test, così Matrix viene eseguito senza
|
||||
`qa-channel` nella configurazione figlia. Scrive gli artefatti di report strutturati e
|
||||
Questa corsia esegue il provisioning di un homeserver Tuwunel usa e getta in Docker, registra
|
||||
utenti temporanei driver, SUT e osservatore, crea una stanza privata, quindi esegue
|
||||
il Plugin Matrix reale all'interno di un processo figlio del gateway QA. La corsia di trasporto live mantiene
|
||||
la configurazione del processo figlio limitata al trasporto in test, quindi Matrix viene eseguito senza
|
||||
`qa-channel` nella configurazione del processo figlio. Scrive gli artifact del report strutturato e
|
||||
un log combinato stdout/stderr nella directory di output Matrix QA selezionata. Per
|
||||
acquisire anche l'output esterno di build/launcher di `scripts/run-node.mjs`, imposta
|
||||
`OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` su un file di log locale al repository.
|
||||
@ -80,89 +80,91 @@ Per una corsia smoke Telegram con trasporto reale, esegui:
|
||||
pnpm openclaw qa telegram
|
||||
```
|
||||
|
||||
Questa corsia punta a un gruppo privato Telegram reale invece di effettuare il provisioning di un
|
||||
server usa e getta. Richiede `OPENCLAW_QA_TELEGRAM_GROUP_ID`,
|
||||
Questa corsia usa come target un gruppo privato Telegram reale invece di eseguire il provisioning di
|
||||
un server usa e getta. Richiede `OPENCLAW_QA_TELEGRAM_GROUP_ID`,
|
||||
`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e
|
||||
`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, oltre a due bot distinti nello stesso
|
||||
gruppo privato. Il bot SUT deve avere un nome utente Telegram, e l'osservazione tra bot
|
||||
funziona al meglio quando entrambi i bot hanno la modalità di comunicazione Bot-to-Bot
|
||||
gruppo privato. Il bot SUT deve avere un nome utente Telegram, e l'osservazione bot-to-bot
|
||||
funziona al meglio quando entrambi i bot hanno la Bot-to-Bot Communication Mode
|
||||
abilitata in `@BotFather`.
|
||||
Il comando termina con codice diverso da zero quando uno scenario fallisce. Usa `--allow-failures` quando
|
||||
vuoi ottenere gli artefatti senza un codice di uscita di errore.
|
||||
Il comando termina con un codice diverso da zero quando uno scenario fallisce. Usa `--allow-failures` quando
|
||||
vuoi ottenere gli artifact senza un codice di uscita di errore.
|
||||
Il report e il riepilogo Telegram includono il RTT per risposta dal momento della richiesta di invio
|
||||
del messaggio del driver fino alla risposta osservata del SUT, a partire dal canary.
|
||||
|
||||
Le corsie live di trasporto ora condividono un contratto più piccolo invece di inventare
|
||||
ognuna una propria forma per l'elenco degli scenari:
|
||||
Le corsie di trasporto live ora condividono un unico contratto più piccolo invece di inventare
|
||||
ognuna una propria forma dell'elenco degli scenari:
|
||||
|
||||
`qa-channel` rimane la suite ampia di comportamento di prodotto sintetico e non fa parte
|
||||
della matrice di copertura del trasporto live.
|
||||
`qa-channel` rimane la suite ampia di comportamento sintetico del prodotto e non fa parte della matrice
|
||||
di copertura del trasporto live.
|
||||
|
||||
| Corsia | Canary | Blocco menzioni | Blocco allowlist | Risposta di primo livello | Ripresa dopo riavvio | Follow-up del thread | Isolamento del thread | Osservazione reazioni | Comando help |
|
||||
| -------- | ------ | --------------- | ---------------- | ------------------------- | -------------------- | ------------------- | --------------------- | --------------------- | ------------ |
|
||||
| Matrix | x | x | x | x | x | x | x | x | |
|
||||
| Telegram | x | | | | | | | | x |
|
||||
| Corsia | Canary | Gating delle mention | Blocco allowlist | Risposta di primo livello | Ripresa dopo riavvio | Follow-up nel thread | Isolamento del thread | Osservazione delle reazioni | Comando help |
|
||||
| -------- | ------ | -------------------- | ---------------- | ------------------------- | -------------------- | -------------------- | --------------------- | --------------------------- | ------------ |
|
||||
| Matrix | x | x | x | x | x | x | x | x | |
|
||||
| Telegram | x | | | | | | | | x |
|
||||
|
||||
Questo mantiene `qa-channel` come suite ampia di comportamento del prodotto, mentre Matrix,
|
||||
Telegram e i futuri trasporti live condividono una checklist esplicita di contratto di trasporto.
|
||||
Telegram e i futuri trasporti live condividono un'unica checklist esplicita di contratto di trasporto.
|
||||
|
||||
Per una corsia VM Linux usa e getta senza portare Docker nel percorso QA, esegui:
|
||||
Per una corsia VM Linux usa e getta senza introdurre Docker nel percorso QA, esegui:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
```
|
||||
|
||||
Questo avvia un guest Multipass pulito, installa le dipendenze, compila OpenClaw
|
||||
Questo avvia un guest Multipass nuovo, installa le dipendenze, compila OpenClaw
|
||||
all'interno del guest, esegue `qa suite`, quindi copia il normale report QA e il
|
||||
riepilogo di nuovo in `.artifacts/qa-e2e/...` sull'host.
|
||||
Riutilizza lo stesso comportamento di selezione degli scenari di `qa suite` sull'host.
|
||||
Le esecuzioni host e Multipass della suite eseguono in parallelo per impostazione predefinita
|
||||
più scenari selezionati con worker gateway isolati. `qa-channel` usa come valore predefinito la concorrenza
|
||||
Le esecuzioni suite su host e Multipass eseguono per impostazione predefinita più scenari selezionati in parallelo
|
||||
con worker gateway isolati. `qa-channel` usa per impostazione predefinita una concorrenza di
|
||||
4, limitata dal numero di scenari selezionati. Usa `--concurrency <count>` per regolare
|
||||
il numero di worker, oppure `--concurrency 1` per l'esecuzione seriale.
|
||||
Il comando termina con codice diverso da zero quando uno scenario fallisce. Usa `--allow-failures` quando
|
||||
vuoi ottenere gli artefatti senza un codice di uscita di errore.
|
||||
il numero di worker, oppure `--concurrency 1` per un'esecuzione seriale.
|
||||
Il comando termina con un codice diverso da zero quando uno scenario fallisce. Usa `--allow-failures` quando
|
||||
vuoi ottenere gli artifact senza un codice di uscita di errore.
|
||||
Le esecuzioni live inoltrano gli input di autenticazione QA supportati che sono pratici per il
|
||||
guest: chiavi provider basate su variabili d'ambiente, il percorso di configurazione del provider live QA e
|
||||
`CODEX_HOME` quando presente. Mantieni `--output-dir` sotto la root del repository in modo che il guest
|
||||
possa scrivere di ritorno attraverso il workspace montato.
|
||||
guest: chiavi provider basate su env, il percorso di configurazione del provider live QA e
|
||||
`CODEX_HOME` quando presente. Mantieni `--output-dir` sotto la root del repository così il guest
|
||||
può scrivere indietro attraverso il workspace montato.
|
||||
|
||||
## Seed supportati dal repository
|
||||
|
||||
Le risorse seed si trovano in `qa/`:
|
||||
Gli asset seed si trovano in `qa/`:
|
||||
|
||||
- `qa/scenarios/index.md`
|
||||
- `qa/scenarios/<theme>/*.md`
|
||||
|
||||
Queste sono intenzionalmente in git così che il piano QA sia visibile sia agli esseri umani sia
|
||||
Questi sono intenzionalmente in git così il piano QA è visibile sia agli umani sia
|
||||
all'agente.
|
||||
|
||||
`qa-lab` dovrebbe rimanere un runner Markdown generico. Ogni file Markdown di scenario è
|
||||
la fonte di verità per una singola esecuzione di test e dovrebbe definire:
|
||||
|
||||
- metadati dello scenario
|
||||
- metadati facoltativi di categoria, capacità, corsia e rischio
|
||||
- metadati opzionali di categoria, capacità, corsia e rischio
|
||||
- riferimenti a documentazione e codice
|
||||
- requisiti facoltativi dei plugin
|
||||
- patch facoltativa della configurazione Gateway
|
||||
- requisiti opzionali dei plugin
|
||||
- patch opzionale della configurazione Gateway
|
||||
- il `qa-flow` eseguibile
|
||||
|
||||
La superficie runtime riutilizzabile che supporta `qa-flow` può rimanere generica
|
||||
e trasversale. Ad esempio, gli scenari Markdown possono combinare helper lato trasporto
|
||||
con helper lato browser che guidano la Control UI incorporata tramite la seam
|
||||
Gateway `browser.request` senza aggiungere un runner con casi speciali.
|
||||
La superficie di runtime riutilizzabile che supporta `qa-flow` può rimanere generica
|
||||
e trasversale. Per esempio, gli scenari Markdown possono combinare helper lato trasporto
|
||||
con helper lato browser che guidano l'interfaccia di controllo incorporata tramite la seam
|
||||
Gateway `browser.request` senza aggiungere un runner speciale.
|
||||
|
||||
I file di scenario dovrebbero essere raggruppati per capacità del prodotto invece che per cartella
|
||||
dell'albero sorgente. Mantieni stabili gli ID degli scenari quando i file vengono spostati; usa `docsRefs` e `codeRefs`
|
||||
per la tracciabilità dell'implementazione.
|
||||
I file di scenario dovrebbero essere raggruppati per capacità del prodotto anziché per cartella
|
||||
dell'albero sorgente. Mantieni stabili gli ID degli scenari quando i file vengono spostati; usa
|
||||
`docsRefs` e `codeRefs` per la tracciabilità dell'implementazione.
|
||||
|
||||
L'elenco di base dovrebbe rimanere abbastanza ampio da coprire:
|
||||
|
||||
- chat in DM e canale
|
||||
- chat DM e di canale
|
||||
- comportamento dei thread
|
||||
- ciclo di vita delle azioni sui messaggi
|
||||
- callback Cron
|
||||
- richiamo della memoria
|
||||
- cambio modello
|
||||
- handoff ai subagenti
|
||||
- cambio di modello
|
||||
- handoff a subagent
|
||||
- lettura del repository e della documentazione
|
||||
- un piccolo task di build come Lobster Invaders
|
||||
|
||||
@ -171,34 +173,36 @@ L'elenco di base dovrebbe rimanere abbastanza ampio da coprire:
|
||||
`qa suite` ha due corsie mock locali del provider:
|
||||
|
||||
- `mock-openai` è il mock OpenClaw consapevole dello scenario. Rimane la corsia mock deterministica
|
||||
predefinita per la QA supportata dal repository e per i gate di parità.
|
||||
- `aimock` avvia un server provider basato su AIMock per copertura sperimentale di protocollo,
|
||||
fixture, record/replay e chaos. È aggiuntivo e non sostituisce il dispatcher
|
||||
di scenari `mock-openai`.
|
||||
predefinita per il QA supportato dal repository e i gate di parità.
|
||||
- `aimock` avvia un server provider supportato da AIMock per copertura sperimentale di protocollo,
|
||||
fixture, record/replay e chaos. È aggiuntivo e non sostituisce il dispatcher di scenari
|
||||
`mock-openai`.
|
||||
|
||||
L'implementazione della corsia provider si trova in `extensions/qa-lab/src/providers/`.
|
||||
Ogni provider possiede i propri valori predefiniti, l'avvio del server locale, la configurazione
|
||||
del modello gateway, le esigenze di staging del profilo auth e i flag di capacità live/mock. Il codice condiviso della suite e del gateway dovrebbe instradare attraverso il registro dei provider invece di ramificare sui nomi dei provider.
|
||||
del modello Gateway, le esigenze di staging del profilo di autenticazione e i flag di capacità
|
||||
live/mock. Il codice condiviso della suite e del gateway dovrebbe instradare tramite il registro
|
||||
dei provider invece di fare branching sui nomi dei provider.
|
||||
|
||||
## Adattatori di trasporto
|
||||
|
||||
`qa-lab` possiede una seam di trasporto generica per gli scenari QA Markdown.
|
||||
`qa-channel` è il primo adattatore su quella seam, ma l'obiettivo di progettazione è più ampio:
|
||||
i futuri canali reali o sintetici dovrebbero collegarsi allo stesso runner di suite
|
||||
invece di aggiungere un runner QA specifico per il trasporto.
|
||||
futuri canali reali o sintetici dovrebbero collegarsi allo stesso runner di suite invece di
|
||||
aggiungere un runner QA specifico per trasporto.
|
||||
|
||||
A livello di architettura, la suddivisione è:
|
||||
|
||||
- `qa-lab` possiede l'esecuzione generica degli scenari, la concorrenza dei worker, la scrittura degli artefatti e la reportistica.
|
||||
- l'adattatore di trasporto possiede la configurazione gateway, la readiness, l'osservazione in ingresso e in uscita, le azioni di trasporto e lo stato di trasporto normalizzato.
|
||||
- i file di scenario Markdown sotto `qa/scenarios/` definiscono l'esecuzione di test; `qa-lab` fornisce la superficie runtime riutilizzabile che li esegue.
|
||||
- `qa-lab` possiede l'esecuzione generica degli scenari, la concorrenza dei worker, la scrittura degli artifact e il reporting.
|
||||
- l'adattatore di trasporto possiede la configurazione Gateway, la readiness, l'osservazione in entrata e in uscita, le azioni di trasporto e lo stato di trasporto normalizzato.
|
||||
- i file di scenario Markdown sotto `qa/scenarios/` definiscono l'esecuzione del test; `qa-lab` fornisce la superficie di runtime riutilizzabile che li esegue.
|
||||
|
||||
Le linee guida di adozione rivolte ai maintainer per i nuovi adattatori di canale si trovano in
|
||||
[Testing](/it/help/testing#adding-a-channel-to-qa).
|
||||
|
||||
## Reportistica
|
||||
## Reporting
|
||||
|
||||
`qa-lab` esporta un report di protocollo Markdown dalla timeline del bus osservata.
|
||||
`qa-lab` esporta un report del protocollo in Markdown dalla timeline osservata del bus.
|
||||
Il report dovrebbe rispondere a:
|
||||
|
||||
- Cosa ha funzionato
|
||||
@ -206,8 +210,8 @@ Il report dovrebbe rispondere a:
|
||||
- Cosa è rimasto bloccato
|
||||
- Quali scenari di follow-up vale la pena aggiungere
|
||||
|
||||
Per i controlli di carattere e stile, esegui lo stesso scenario su più riferimenti di modelli live
|
||||
e scrivi un report Markdown valutato:
|
||||
Per verifiche di carattere e stile, esegui lo stesso scenario su più
|
||||
ref di modelli live e scrivi un report Markdown valutato:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa character-eval \
|
||||
@ -226,31 +230,31 @@ pnpm openclaw qa character-eval \
|
||||
--judge-concurrency 16
|
||||
```
|
||||
|
||||
Il comando esegue processi figli locali del gateway QA, non Docker. Gli scenari di valutazione del carattere
|
||||
Il comando esegue processi figlio del gateway QA locali, non Docker. Gli scenari di character eval
|
||||
dovrebbero impostare la persona tramite `SOUL.md`, quindi eseguire normali turni utente
|
||||
come chat, aiuto nel workspace e piccoli task sui file. Al modello candidato
|
||||
non dovrebbe essere detto che sta venendo valutato. Il comando conserva ogni trascrizione
|
||||
completa, registra statistiche di base dell'esecuzione, quindi chiede ai modelli giudici in modalità fast con
|
||||
ragionamento `xhigh` di classificare le esecuzioni per naturalezza, atmosfera e umorismo.
|
||||
come chat, aiuto nell'workspace e piccoli task sui file. Al modello candidato
|
||||
non dovrebbe essere detto che è in valutazione. Il comando conserva ogni trascrizione
|
||||
completa, registra statistiche di base dell'esecuzione, quindi chiede ai modelli giudice in modalità fast con
|
||||
ragionamento `xhigh` di classificare le esecuzioni per naturalezza, vibe e umorismo.
|
||||
Usa `--blind-judge-models` quando confronti provider: il prompt del giudice riceve comunque
|
||||
ogni trascrizione e stato di esecuzione, ma i riferimenti candidati vengono sostituiti con etichette
|
||||
neutre come `candidate-01`; il report rimappa le classifiche ai riferimenti reali dopo
|
||||
il parsing.
|
||||
ogni trascrizione e stato di esecuzione, ma i ref candidati vengono sostituiti con etichette
|
||||
neutre come `candidate-01`; il report rimappa le classifiche ai ref reali dopo il
|
||||
parsing.
|
||||
Le esecuzioni dei candidati usano per impostazione predefinita il thinking `high`, con `xhigh` per i modelli OpenAI che
|
||||
lo supportano. Sostituisci un candidato specifico inline con
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` imposta comunque
|
||||
un fallback globale, e la vecchia forma `--model-thinking <provider/model=level>` viene
|
||||
lo supportano. Sovrascrivi un candidato specifico inline con
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` continua a impostare un
|
||||
fallback globale, e la forma precedente `--model-thinking <provider/model=level>` viene
|
||||
mantenuta per compatibilità.
|
||||
I riferimenti candidati OpenAI usano per impostazione predefinita la modalità fast così da usare l'elaborazione prioritaria dove
|
||||
il provider la supporta. Aggiungi `,fast`, `,no-fast` o `,fast=false` inline quando un
|
||||
singolo candidato o giudice necessita di un override. Passa `--fast` solo quando vuoi
|
||||
forzare la modalità fast per ogni modello candidato. Le durate di candidati e giudici vengono
|
||||
registrate nel report per l'analisi comparativa, ma i prompt dei giudici specificano esplicitamente
|
||||
I ref candidati OpenAI usano per impostazione predefinita la modalità fast così l'elaborazione prioritaria viene usata
|
||||
dove il provider la supporta. Aggiungi `,fast`, `,no-fast` o `,fast=false` inline quando un
|
||||
singolo candidato o giudice necessita di una sovrascrittura. Passa `--fast` solo quando vuoi
|
||||
forzare la modalità fast per ogni modello candidato. Le durate dei modelli candidati e giudici
|
||||
vengono registrate nel report per l'analisi comparativa, ma i prompt dei giudici dicono esplicitamente
|
||||
di non classificare in base alla velocità.
|
||||
Le esecuzioni sia dei modelli candidati sia di quelli giudici usano entrambe per impostazione predefinita la concorrenza 16. Riduci
|
||||
`--concurrency` o `--judge-concurrency` quando i limiti del provider o la pressione sul gateway locale
|
||||
Sia le esecuzioni dei modelli candidati sia quelle dei modelli giudici usano per impostazione predefinita una concorrenza di 16. Riduci
|
||||
`--concurrency` o `--judge-concurrency` quando i limiti del provider o la pressione locale sul gateway
|
||||
rendono un'esecuzione troppo rumorosa.
|
||||
Quando non viene passato alcun `--model` candidato, la valutazione del carattere usa per impostazione predefinita
|
||||
Quando non viene passato alcun candidato `--model`, la character eval usa per impostazione predefinita
|
||||
`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
|
||||
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
|
||||
`moonshot/kimi-k2.5` e
|
||||
@ -263,4 +267,4 @@ Quando non viene passato alcun `--judge-model`, i giudici usano per impostazione
|
||||
|
||||
- [Testing](/it/help/testing)
|
||||
- [QA Channel](/it/channels/qa-channel)
|
||||
- [Dashboard](/web/dashboard)
|
||||
- [Dashboard](/it/web/dashboard)
|
||||
|
||||
@ -1,37 +1,37 @@
|
||||
---
|
||||
read_when:
|
||||
- Configurare OpenClaw per la prima volta
|
||||
- Cerchi pattern di configurazione comuni
|
||||
- Passare a sezioni specifiche della configurazione
|
||||
- Configurazione iniziale di OpenClaw
|
||||
- Cerchi modelli di configurazione comuni
|
||||
- Passaggio a sezioni di configurazione specifiche
|
||||
summary: 'Panoramica della configurazione: attività comuni, configurazione rapida e link al riferimento completo'
|
||||
title: Configurazione
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T08:28:28Z"
|
||||
generated_at: "2026-04-23T13:58:00Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a674bbc73f3a501ffd47ef9396d55d6087806921cfb24ef576398022dd0248c3
|
||||
source_hash: d76b40c25f98de791e0d8012b2bc5b80e3e38dde99bb9105539e800ddac3f362
|
||||
source_path: gateway/configuration.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Configurazione
|
||||
|
||||
OpenClaw legge una configurazione <Tooltip tip="JSON5 supports comments and trailing commas">**JSON5**</Tooltip> opzionale da `~/.openclaw/openclaw.json`.
|
||||
Il percorso della configurazione attiva deve essere un file regolare. Layout
|
||||
OpenClaw legge una configurazione <Tooltip tip="JSON5 supporta commenti e virgole finali">**JSON5**</Tooltip> facoltativa da `~/.openclaw/openclaw.json`.
|
||||
Il percorso della configurazione attiva deve essere un file regolare. I layout di
|
||||
`openclaw.json` con symlink non sono supportati per le scritture gestite da OpenClaw; una scrittura atomica può sostituire
|
||||
il percorso invece di preservare il symlink. Se mantieni la configurazione fuori dalla
|
||||
directory di stato predefinita, punta `OPENCLAW_CONFIG_PATH` direttamente al file reale.
|
||||
|
||||
Se il file manca, OpenClaw usa impostazioni predefinite sicure. Motivi comuni per aggiungere una configurazione:
|
||||
|
||||
- Connettere i canali e controllare chi può inviare messaggi al bot
|
||||
- Impostare modelli, strumenti, sandboxing o automazione (Cron, hook)
|
||||
- Connettere canali e controllare chi può inviare messaggi al bot
|
||||
- Impostare modelli, strumenti, sandboxing o automazione (cron, hook)
|
||||
- Regolare sessioni, contenuti multimediali, rete o UI
|
||||
|
||||
Vedi il [riferimento completo](/it/gateway/configuration-reference) per ogni campo disponibile.
|
||||
Consulta il [riferimento completo](/it/gateway/configuration-reference) per ogni campo disponibile.
|
||||
|
||||
<Tip>
|
||||
**Nuovo alla configurazione?** Inizia con `openclaw onboard` per la configurazione interattiva, oppure consulta la guida [Esempi di configurazione](/it/gateway/configuration-examples) per configurazioni complete da copiare e incollare.
|
||||
**Sei nuovo alla configurazione?** Inizia con `openclaw onboard` per una configurazione interattiva, oppure consulta la guida [Esempi di configurazione](/it/gateway/configuration-examples) per configurazioni complete da copiare e incollare.
|
||||
</Tip>
|
||||
|
||||
## Configurazione minima
|
||||
@ -49,11 +49,11 @@ Vedi il [riferimento completo](/it/gateway/configuration-reference) per ogni cam
|
||||
<Tabs>
|
||||
<Tab title="Procedura guidata interattiva">
|
||||
```bash
|
||||
openclaw onboard # flusso completo di onboarding
|
||||
openclaw onboard # flusso di onboarding completo
|
||||
openclaw configure # procedura guidata di configurazione
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="CLI (one-liner)">
|
||||
<Tab title="CLI (comandi in una riga)">
|
||||
```bash
|
||||
openclaw config get agents.defaults.workspace
|
||||
openclaw config set agents.defaults.heartbeat.every "2h"
|
||||
@ -62,29 +62,29 @@ Vedi il [riferimento completo](/it/gateway/configuration-reference) per ogni cam
|
||||
</Tab>
|
||||
<Tab title="Control UI">
|
||||
Apri [http://127.0.0.1:18789](http://127.0.0.1:18789) e usa la scheda **Config**.
|
||||
La Control UI renderizza un modulo a partire dallo schema di configurazione live, includendo i metadati documentali
|
||||
dei campi `title` / `description` oltre agli schemi di plugin e canali quando
|
||||
disponibili, con un editor **Raw JSON** come via di fuga. Per
|
||||
UI di drill-down e altri strumenti, il gateway espone anche `config.schema.lookup` per
|
||||
recuperare un nodo dello schema limitato a un percorso più riepiloghi immediati dei figli.
|
||||
Il Control UI genera un modulo dallo schema di configurazione live, inclusi i metadati di documentazione dei campi
|
||||
`title` / `description` più gli schemi di plugin e canali quando
|
||||
disponibili, con un editor **Raw JSON** come via di fuga. Per UI
|
||||
di navigazione dettagliata e altri strumenti, il gateway espone anche `config.schema.lookup` per
|
||||
recuperare un singolo nodo di schema con ambito di percorso più i riepiloghi immediati dei figli.
|
||||
</Tab>
|
||||
<Tab title="Modifica diretta">
|
||||
Modifica direttamente `~/.openclaw/openclaw.json`. Il Gateway osserva il file e applica automaticamente le modifiche (vedi [hot reload](#config-hot-reload)).
|
||||
Modifica direttamente `~/.openclaw/openclaw.json`. Il Gateway osserva il file e applica automaticamente le modifiche (vedi [ricaricamento a caldo](#config-hot-reload)).
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Validazione rigorosa
|
||||
|
||||
<Warning>
|
||||
OpenClaw accetta solo configurazioni che corrispondono completamente allo schema. Chiavi sconosciute, tipi non validi o valori non validi fanno sì che il Gateway **si rifiuti di avviarsi**. L'unica eccezione a livello root è `$schema` (stringa), così gli editor possono collegare metadati JSON Schema.
|
||||
OpenClaw accetta solo configurazioni che corrispondono completamente allo schema. Chiavi sconosciute, tipi malformati o valori non validi fanno sì che il Gateway **rifiuti di avviarsi**. L'unica eccezione a livello root è `$schema` (stringa), così gli editor possono associare i metadati JSON Schema.
|
||||
</Warning>
|
||||
|
||||
`openclaw config schema` stampa il JSON Schema canonico usato da Control UI
|
||||
e dalla validazione. `config.schema.lookup` recupera un singolo nodo limitato a un percorso più
|
||||
riepiloghi dei figli per strumenti drill-down. I metadati documentali `title`/`description`
|
||||
dei campi vengono mantenuti in oggetti annidati, wildcard (`*`), elementi di array (`[]`) e rami `anyOf`/
|
||||
e dalla validazione. `config.schema.lookup` recupera un singolo nodo con ambito di percorso più
|
||||
i riepiloghi dei figli per strumenti di navigazione dettagliata. I metadati di documentazione dei campi `title`/`description`
|
||||
si propagano attraverso oggetti annidati, wildcard (`*`), elementi di array (`[]`) e rami `anyOf`/
|
||||
`oneOf`/`allOf`. Gli schemi runtime di plugin e canali vengono uniti quando il
|
||||
registro dei manifest viene caricato.
|
||||
registro dei manifest è caricato.
|
||||
|
||||
Quando la validazione fallisce:
|
||||
|
||||
@ -93,19 +93,19 @@ Quando la validazione fallisce:
|
||||
- Esegui `openclaw doctor` per vedere i problemi esatti
|
||||
- Esegui `openclaw doctor --fix` (o `--yes`) per applicare le riparazioni
|
||||
|
||||
Il Gateway mantiene una copia trusted last-known-good dopo ogni avvio riuscito.
|
||||
Se successivamente `openclaw.json` fallisce la validazione (o perde `gateway.mode`, si riduce
|
||||
bruscamente o ha una riga di log estranea anteposta), OpenClaw preserva il file danneggiato
|
||||
come `.clobbered.*`, ripristina la copia last-known-good e registra la ragione del
|
||||
Il Gateway mantiene una copia attendibile dell'ultimo stato valido dopo ogni avvio riuscito.
|
||||
Se `openclaw.json` in seguito non supera la validazione (o perde `gateway.mode`, si riduce
|
||||
bruscamente o presenta una riga di log estranea anteposta), OpenClaw conserva il file non valido
|
||||
come `.clobbered.*`, ripristina la copia dell'ultimo stato valido e registra il motivo del
|
||||
ripristino. Anche il turno successivo dell'agente riceve un avviso di evento di sistema, così l'agente principale
|
||||
non riscrive ciecamente la configurazione ripristinata. La promozione a last-known-good
|
||||
viene saltata quando un candidato contiene segnaposto di segreti redatti come `***`.
|
||||
non riscrive alla cieca la configurazione ripristinata. La promozione a ultimo stato valido
|
||||
viene saltata quando un candidato contiene segnaposto di segreti oscurati come `***`.
|
||||
|
||||
## Attività comuni
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Configurare un canale (WhatsApp, Telegram, Discord, ecc.)">
|
||||
Ogni canale ha la propria sezione di configurazione sotto `channels.<provider>`. Vedi la pagina dedicata del canale per i passaggi di configurazione:
|
||||
Ogni canale ha una propria sezione di configurazione sotto `channels.<provider>`. Consulta la pagina dedicata al canale per i passaggi di configurazione:
|
||||
|
||||
- [WhatsApp](/it/channels/whatsapp) — `channels.whatsapp`
|
||||
- [Telegram](/it/channels/telegram) — `channels.telegram`
|
||||
@ -118,7 +118,7 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
- [iMessage](/it/channels/imessage) — `channels.imessage`
|
||||
- [Mattermost](/it/channels/mattermost) — `channels.mattermost`
|
||||
|
||||
Tutti i canali condividono lo stesso pattern di policy DM:
|
||||
Tutti i canali condividono lo stesso schema di policy per i DM:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -127,7 +127,7 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
enabled: true,
|
||||
botToken: "123:abc",
|
||||
dmPolicy: "pairing", // pairing | allowlist | open | disabled
|
||||
allowFrom: ["tg:123"], // only for allowlist/open
|
||||
allowFrom: ["tg:123"], // solo per allowlist/open
|
||||
},
|
||||
},
|
||||
}
|
||||
@ -155,31 +155,31 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
}
|
||||
```
|
||||
|
||||
- `agents.defaults.models` definisce il catalogo dei modelli e agisce come allowlist per `/model`.
|
||||
- Usa `openclaw config set agents.defaults.models '<json>' --strict-json --merge` per aggiungere voci alla allowlist senza rimuovere i modelli esistenti. Le sostituzioni semplici che rimuoverebbero voci vengono rifiutate a meno che tu non passi `--replace`.
|
||||
- `agents.defaults.models` definisce il catalogo dei modelli e funge da allowlist per `/model`.
|
||||
- Usa `openclaw config set agents.defaults.models '<json>' --strict-json --merge` per aggiungere voci all'allowlist senza rimuovere i modelli esistenti. Le sostituzioni semplici che rimuoverebbero voci vengono rifiutate a meno che tu non passi `--replace`.
|
||||
- I riferimenti ai modelli usano il formato `provider/model` (ad esempio `anthropic/claude-opus-4-6`).
|
||||
- `agents.defaults.imageMaxDimensionPx` controlla il downscaling delle immagini di trascrizione/strumenti (predefinito `1200`); valori più bassi di solito riducono l'uso di vision token nelle esecuzioni ricche di screenshot.
|
||||
- Vedi [Models CLI](/it/concepts/models) per cambiare modello in chat e [Model Failover](/it/concepts/model-failover) per il comportamento di rotazione auth e fallback.
|
||||
- Per provider personalizzati/self-hosted, vedi [provider personalizzati](/it/gateway/configuration-reference#custom-providers-and-base-urls) nel riferimento.
|
||||
- `agents.defaults.imageMaxDimensionPx` controlla il ridimensionamento delle immagini nel transcript/negli strumenti (predefinito `1200`); valori più bassi di solito riducono l'uso di vision token nelle esecuzioni con molti screenshot.
|
||||
- Consulta [Models CLI](/it/concepts/models) per cambiare modello in chat e [Model Failover](/it/concepts/model-failover) per la rotazione dell'autenticazione e il comportamento di fallback.
|
||||
- Per provider personalizzati/self-hosted, consulta [Provider personalizzati](/it/gateway/configuration-reference#custom-providers-and-base-urls) nel riferimento.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Controllare chi può inviare messaggi al bot">
|
||||
L'accesso DM è controllato per canale tramite `dmPolicy`:
|
||||
L'accesso ai DM è controllato per canale tramite `dmPolicy`:
|
||||
|
||||
- `"pairing"` (predefinito): i mittenti sconosciuti ricevono un codice di pairing monouso da approvare
|
||||
- `"allowlist"`: solo i mittenti in `allowFrom` (o nell'archivio paired allow)
|
||||
- `"pairing"` (predefinito): i mittenti sconosciuti ricevono un codice di associazione monouso da approvare
|
||||
- `"allowlist"`: solo i mittenti in `allowFrom` (o nell'archivio degli abbinamenti approvati)
|
||||
- `"open"`: consente tutti i DM in ingresso (richiede `allowFrom: ["*"]`)
|
||||
- `"disabled"`: ignora tutti i DM
|
||||
|
||||
Per i gruppi, usa `groupPolicy` + `groupAllowFrom` o allowlist specifiche del canale.
|
||||
Per i gruppi, usa `groupPolicy` + `groupAllowFrom` o le allowlist specifiche del canale.
|
||||
|
||||
Vedi il [riferimento completo](/it/gateway/configuration-reference#dm-and-group-access) per i dettagli per canale.
|
||||
Consulta il [riferimento completo](/it/gateway/configuration-reference#dm-and-group-access) per i dettagli per canale.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Configurare il gating delle menzioni nella chat di gruppo">
|
||||
I messaggi di gruppo richiedono per impostazione predefinita una **menzione**. Configura i pattern per agente:
|
||||
<Accordion title="Impostare il filtro per menzioni nelle chat di gruppo">
|
||||
Per impostazione predefinita, i messaggi di gruppo **richiedono una menzione**. Configura i pattern per agente:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -201,14 +201,15 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
}
|
||||
```
|
||||
|
||||
- **Menzioni dei metadati**: @-mention native (@ di WhatsApp tap-to-mention, @bot di Telegram, ecc.)
|
||||
- **Menzioni nei metadati**: @-mention native (WhatsApp tocca-per-menzionare, Telegram @bot, ecc.)
|
||||
- **Pattern di testo**: pattern regex sicuri in `mentionPatterns`
|
||||
- Vedi il [riferimento completo](/it/gateway/configuration-reference#group-chat-mention-gating) per override per canale e modalità self-chat.
|
||||
- Consulta il [riferimento completo](/it/gateway/configuration-reference#group-chat-mention-gating) per override per canale e modalità self-chat.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Limitare le Skills per agente">
|
||||
Usa `agents.defaults.skills` per una base condivisa, poi sovrascrivi gli agenti specifici con `agents.list[].skills`:
|
||||
Usa `agents.defaults.skills` per una base condivisa, poi sovrascrivi gli
|
||||
agenti specifici con `agents.list[].skills`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -217,24 +218,24 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
skills: ["github", "weather"],
|
||||
},
|
||||
list: [
|
||||
{ id: "writer" }, // inherits github, weather
|
||||
{ id: "docs", skills: ["docs-search"] }, // replaces defaults
|
||||
{ id: "locked-down", skills: [] }, // no skills
|
||||
{ id: "writer" }, // eredita github, weather
|
||||
{ id: "docs", skills: ["docs-search"] }, // sostituisce i valori predefiniti
|
||||
{ id: "locked-down", skills: [] }, // nessuna Skills
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- Ometti `agents.defaults.skills` per Skills senza restrizioni per impostazione predefinita.
|
||||
- Ometti `agents.defaults.skills` per avere Skills senza restrizioni per impostazione predefinita.
|
||||
- Ometti `agents.list[].skills` per ereditare i valori predefiniti.
|
||||
- Imposta `agents.list[].skills: []` per nessuna Skills.
|
||||
- Vedi [Skills](/it/tools/skills), [Configurazione Skills](/it/tools/skills-config) e
|
||||
- Imposta `agents.list[].skills: []` per non avere Skills.
|
||||
- Consulta [Skills](/it/tools/skills), [Configurazione di Skills](/it/tools/skills-config) e
|
||||
il [Riferimento configurazione](/it/gateway/configuration-reference#agents-defaults-skills).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Regolare il monitoraggio dello stato di salute dei canali del gateway">
|
||||
Controlla quanto aggressivamente il gateway riavvia i canali che sembrano obsoleti:
|
||||
<Accordion title="Regolare il monitoraggio dello stato dei canali del gateway">
|
||||
Controlla quanto aggressivamente il gateway riavvia i canali che sembrano inattivi:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -256,10 +257,10 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
}
|
||||
```
|
||||
|
||||
- Imposta `gateway.channelHealthCheckMinutes: 0` per disabilitare globalmente i riavvii del monitoraggio dello stato di salute.
|
||||
- `channelStaleEventThresholdMinutes` deve essere maggiore o uguale all'intervallo di controllo.
|
||||
- Imposta `gateway.channelHealthCheckMinutes: 0` per disabilitare globalmente i riavvii del monitoraggio dello stato.
|
||||
- `channelStaleEventThresholdMinutes` dovrebbe essere maggiore o uguale all'intervallo di controllo.
|
||||
- Usa `channels.<provider>.healthMonitor.enabled` o `channels.<provider>.accounts.<id>.healthMonitor.enabled` per disabilitare i riavvii automatici per un canale o account senza disabilitare il monitor globale.
|
||||
- Vedi [Controlli di salute](/it/gateway/health) per il debug operativo e il [riferimento completo](/it/gateway/configuration-reference#gateway) per tutti i campi.
|
||||
- Consulta [Health Checks](/it/gateway/health) per il debug operativo e il [riferimento completo](/it/gateway/configuration-reference#gateway) per tutti i campi.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -269,7 +270,7 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
```json5
|
||||
{
|
||||
session: {
|
||||
dmScope: "per-channel-peer", // recommended for multi-user
|
||||
dmScope: "per-channel-peer", // consigliato per multiutente
|
||||
threadBindings: {
|
||||
enabled: true,
|
||||
idleHours: 24,
|
||||
@ -285,14 +286,14 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
```
|
||||
|
||||
- `dmScope`: `main` (condiviso) | `per-peer` | `per-channel-peer` | `per-account-channel-peer`
|
||||
- `threadBindings`: valori predefiniti globali per l'instradamento delle sessioni associate ai thread (Discord supporta `/focus`, `/unfocus`, `/agents`, `/session idle` e `/session max-age`).
|
||||
- Vedi [Gestione delle sessioni](/it/concepts/session) per ambito, collegamenti di identità e policy di invio.
|
||||
- Vedi il [riferimento completo](/it/gateway/configuration-reference#session) per tutti i campi.
|
||||
- `threadBindings`: valori predefiniti globali per il routing delle sessioni legate ai thread (Discord supporta `/focus`, `/unfocus`, `/agents`, `/session idle` e `/session max-age`).
|
||||
- Consulta [Gestione delle sessioni](/it/concepts/session) per ambito, collegamenti di identità e policy di invio.
|
||||
- Consulta il [riferimento completo](/it/gateway/configuration-reference#session) per tutti i campi.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Abilitare il sandboxing">
|
||||
Esegui le sessioni agente in runtime sandbox isolati:
|
||||
Esegui le sessioni degli agenti in runtime sandbox isolati:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -309,12 +310,12 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
|
||||
Costruisci prima l'immagine: `scripts/sandbox-setup.sh`
|
||||
|
||||
Vedi [Sandboxing](/it/gateway/sandboxing) per la guida completa e il [riferimento completo](/it/gateway/configuration-reference#agentsdefaultssandbox) per tutte le opzioni.
|
||||
Consulta [Sandboxing](/it/gateway/sandboxing) per la guida completa e il [riferimento completo](/it/gateway/configuration-reference#agentsdefaultssandbox) per tutte le opzioni.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Abilitare il push basato su relay per le build iOS ufficiali">
|
||||
Il push basato su relay viene configurato in `openclaw.json`.
|
||||
<Accordion title="Abilitare le notifiche push tramite relay per le build iOS ufficiali">
|
||||
Le notifiche push tramite relay sono configurate in `openclaw.json`.
|
||||
|
||||
Imposta questo nella configurazione del gateway:
|
||||
|
||||
@ -325,7 +326,7 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
apns: {
|
||||
relay: {
|
||||
baseUrl: "https://relay.example.com",
|
||||
// Optional. Default: 10000
|
||||
// Facoltativo. Predefinito: 10000
|
||||
timeoutMs: 10000,
|
||||
},
|
||||
},
|
||||
@ -342,35 +343,35 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
|
||||
Cosa fa:
|
||||
|
||||
- Consente al gateway di inviare `push.test`, wake nudges e reconnect wakes tramite il relay esterno.
|
||||
- Usa un send grant con ambito registrazione inoltrato dall'app iOS associata. Il gateway non ha bisogno di un token relay valido per l'intero deployment.
|
||||
- Associa ogni registrazione supportata da relay all'identità gateway con cui l'app iOS è stata associata, così un altro gateway non può riutilizzare la registrazione archiviata.
|
||||
- Consente al gateway di inviare `push.test`, segnali di risveglio e risvegli di riconnessione tramite il relay esterno.
|
||||
- Usa un permesso di invio con ambito di registrazione inoltrato dall'app iOS associata. Il gateway non ha bisogno di un token relay valido per l'intera distribuzione.
|
||||
- Collega ogni registrazione supportata da relay all'identità del gateway con cui l'app iOS è stata associata, così un altro gateway non può riutilizzare la registrazione memorizzata.
|
||||
- Mantiene le build iOS locali/manuali su APNs diretto. Gli invii supportati da relay si applicano solo alle build ufficiali distribuite che si sono registrate tramite il relay.
|
||||
- Deve corrispondere all'URL base del relay incorporato nella build iOS ufficiale/TestFlight, così traffico di registrazione e di invio raggiungono lo stesso deployment relay.
|
||||
- Deve corrispondere al base URL del relay incorporato nella build iOS ufficiale/TestFlight, in modo che il traffico di registrazione e invio raggiunga la stessa distribuzione relay.
|
||||
|
||||
Flusso end-to-end:
|
||||
|
||||
1. Installa una build iOS ufficiale/TestFlight compilata con lo stesso URL base del relay.
|
||||
1. Installa una build iOS ufficiale/TestFlight compilata con lo stesso base URL del relay.
|
||||
2. Configura `gateway.push.apns.relay.baseUrl` sul gateway.
|
||||
3. Associa l'app iOS al gateway e lascia connettere sia le sessioni node sia quelle operatore.
|
||||
4. L'app iOS recupera l'identità del gateway, si registra presso il relay usando App Attest più la ricevuta dell'app, quindi pubblica il payload `push.apns.register` supportato da relay sul gateway associato.
|
||||
5. Il gateway memorizza l'handle relay e il send grant, poi li usa per `push.test`, wake nudges e reconnect wakes.
|
||||
3. Associa l'app iOS al gateway e lascia che si connettano sia le sessioni del nodo sia quelle dell'operatore.
|
||||
4. L'app iOS recupera l'identità del gateway, si registra con il relay usando App Attest insieme alla ricevuta dell'app, quindi pubblica il payload `push.apns.register` supportato da relay sul gateway associato.
|
||||
5. Il gateway memorizza l'handle relay e il permesso di invio, quindi li usa per `push.test`, segnali di risveglio e risvegli di riconnessione.
|
||||
|
||||
Note operative:
|
||||
|
||||
- Se passi l'app iOS a un gateway diverso, ricollega l'app così può pubblicare una nuova registrazione relay associata a quel gateway.
|
||||
- Se distribuisci una nuova build iOS che punta a un deployment relay differente, l'app aggiorna la registrazione relay in cache invece di riutilizzare la vecchia origine relay.
|
||||
- Se sposti l'app iOS su un gateway diverso, riconnetti l'app così potrà pubblicare una nuova registrazione relay associata a quel gateway.
|
||||
- Se distribuisci una nuova build iOS che punta a una distribuzione relay diversa, l'app aggiorna la registrazione relay memorizzata in cache invece di riutilizzare la vecchia origine relay.
|
||||
|
||||
Nota di compatibilità:
|
||||
Nota sulla compatibilità:
|
||||
|
||||
- `OPENCLAW_APNS_RELAY_BASE_URL` e `OPENCLAW_APNS_RELAY_TIMEOUT_MS` funzionano ancora come override env temporanei.
|
||||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` resta una via di fuga di sviluppo solo loopback; non rendere persistenti URL relay HTTP nella configurazione.
|
||||
- `OPENCLAW_APNS_RELAY_BASE_URL` e `OPENCLAW_APNS_RELAY_TIMEOUT_MS` continuano a funzionare come override temporanei tramite env.
|
||||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` rimane una via di fuga di sviluppo solo loopback; non persistere URL relay HTTP nella configurazione.
|
||||
|
||||
Vedi [App iOS](/it/platforms/ios#relay-backed-push-for-official-builds) per il flusso end-to-end e [Flusso di autenticazione e trust](/it/platforms/ios#authentication-and-trust-flow) per il modello di sicurezza del relay.
|
||||
Consulta [App iOS](/it/platforms/ios#relay-backed-push-for-official-builds) per il flusso end-to-end e [Flusso di autenticazione e attendibilità](/it/platforms/ios#authentication-and-trust-flow) per il modello di sicurezza del relay.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Configurare Heartbeat (check-in periodici)">
|
||||
<Accordion title="Impostare Heartbeat (check-in periodici)">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -384,14 +385,14 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
}
|
||||
```
|
||||
|
||||
- `every`: stringa durata (`30m`, `2h`). Imposta `0m` per disabilitare.
|
||||
- `target`: `last` | `none` | `<channel-id>` (per esempio `discord`, `matrix`, `telegram` o `whatsapp`)
|
||||
- `directPolicy`: `allow` (predefinito) oppure `block` per destinazioni Heartbeat in stile DM
|
||||
- Vedi [Heartbeat](/it/gateway/heartbeat) per la guida completa.
|
||||
- `every`: stringa di durata (`30m`, `2h`). Imposta `0m` per disabilitare.
|
||||
- `target`: `last` | `none` | `<channel-id>` (ad esempio `discord`, `matrix`, `telegram` o `whatsapp`)
|
||||
- `directPolicy`: `allow` (predefinito) o `block` per target Heartbeat in stile DM
|
||||
- Consulta [Heartbeat](/it/gateway/heartbeat) per la guida completa.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Configurare job Cron">
|
||||
<Accordion title="Configurare processi Cron">
|
||||
```json5
|
||||
{
|
||||
cron: {
|
||||
@ -407,13 +408,13 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
```
|
||||
|
||||
- `sessionRetention`: elimina da `sessions.json` le sessioni di esecuzione isolate completate (predefinito `24h`; imposta `false` per disabilitare).
|
||||
- `runLog`: pota `cron/runs/<jobId>.jsonl` per dimensione e righe mantenute.
|
||||
- Vedi [Job Cron](/it/automation/cron-jobs) per la panoramica delle funzionalità e gli esempi CLI.
|
||||
- `runLog`: elimina in `cron/runs/<jobId>.jsonl` in base alla dimensione e alle righe conservate.
|
||||
- Consulta [Processi Cron](/it/automation/cron-jobs) per una panoramica della funzionalità ed esempi CLI.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Configurare Webhook (hook)">
|
||||
Abilita endpoint HTTP Webhook sul Gateway:
|
||||
<Accordion title="Impostare Webhook (hook)">
|
||||
Abilita endpoint Webhook HTTP sul Gateway:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -436,20 +437,20 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
}
|
||||
```
|
||||
|
||||
Nota di sicurezza:
|
||||
- Tratta tutto il contenuto dei payload hook/Webhook come input non fidato.
|
||||
- Usa un `hooks.token` dedicato; non riutilizzare il token condiviso del Gateway.
|
||||
- L'autenticazione hook è solo header (`Authorization: Bearer ...` oppure `x-openclaw-token`); i token nella query string vengono rifiutati.
|
||||
- `hooks.path` non può essere `/`; mantieni l'ingresso Webhook su un sottopercorso dedicato come `/hooks`.
|
||||
- Mantieni disabilitati i flag di bypass del contenuto non sicuro (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`) a meno che tu non stia facendo debug strettamente limitato.
|
||||
- Se abiliti `hooks.allowRequestSessionKey`, imposta anche `hooks.allowedSessionKeyPrefixes` per limitare le chiavi di sessione selezionabili dal chiamante.
|
||||
- Per agenti guidati da hook, preferisci tier di modello moderni e robusti e una policy strumenti rigorosa (per esempio solo messaggistica più sandboxing quando possibile).
|
||||
Nota sulla sicurezza:
|
||||
- Tratta tutto il contenuto dei payload hook/webhook come input non attendibile.
|
||||
- Usa un `hooks.token` dedicato; non riutilizzare il token Gateway condiviso.
|
||||
- L'autenticazione hook è solo tramite header (`Authorization: Bearer ...` o `x-openclaw-token`); i token nella query string vengono rifiutati.
|
||||
- `hooks.path` non può essere `/`; mantieni l'ingresso webhook su un sottopercorso dedicato come `/hooks`.
|
||||
- Mantieni disabilitati i flag di bypass del contenuto non sicuro (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`) a meno che tu non stia eseguendo debug strettamente circoscritti.
|
||||
- Se abiliti `hooks.allowRequestSessionKey`, imposta anche `hooks.allowedSessionKeyPrefixes` per limitare le chiavi di sessione selezionate dal chiamante.
|
||||
- Per gli agenti guidati da hook, preferisci tier di modelli moderni e robusti e una policy degli strumenti rigorosa (ad esempio solo messaggistica più sandboxing quando possibile).
|
||||
|
||||
Vedi il [riferimento completo](/it/gateway/configuration-reference#hooks) per tutte le opzioni di mapping e l'integrazione Gmail.
|
||||
Consulta il [riferimento completo](/it/gateway/configuration-reference#hooks) per tutte le opzioni di mapping e l'integrazione Gmail.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Configurare instradamento multi-agent">
|
||||
<Accordion title="Configurare il routing multi-agent">
|
||||
Esegui più agenti isolati con workspace e sessioni separate:
|
||||
|
||||
```json5
|
||||
@ -467,7 +468,7 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
}
|
||||
```
|
||||
|
||||
Vedi [Multi-Agent](/it/concepts/multi-agent) e il [riferimento completo](/it/gateway/configuration-reference#multi-agent-routing) per le regole di binding e i profili di accesso per agente.
|
||||
Consulta [Multi-Agent](/it/concepts/multi-agent) e il [riferimento completo](/it/gateway/configuration-reference#multi-agent-routing) per le regole di binding e i profili di accesso per agente.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -486,46 +487,46 @@ viene saltata quando un candidato contiene segnaposto di segreti redatti come `*
|
||||
```
|
||||
|
||||
- **File singolo**: sostituisce l'oggetto contenitore
|
||||
- **Array di file**: deep-merge in ordine (vince l'ultimo)
|
||||
- **Array di file**: unione profonda in ordine (i successivi hanno la precedenza)
|
||||
- **Chiavi sibling**: unite dopo gli include (sovrascrivono i valori inclusi)
|
||||
- **Include annidati**: supportati fino a 10 livelli di profondità
|
||||
- **Percorsi relativi**: risolti relativamente al file includente
|
||||
- **Percorsi relativi**: risolti relativamente al file che include
|
||||
- **Scritture gestite da OpenClaw**: quando una scrittura modifica solo una sezione di primo livello
|
||||
supportata da un include a file singolo come `plugins: { $include: "./plugins.json5" }`,
|
||||
OpenClaw aggiorna quel file incluso e lascia intatto `openclaw.json`
|
||||
- **Write-through non supportato**: include root, array di include e include
|
||||
con override sibling falliscono in modo chiuso per le scritture gestite da OpenClaw invece
|
||||
di appiattire la configurazione
|
||||
- **Gestione errori**: errori chiari per file mancanti, errori di parsing e include circolari
|
||||
con override sibling falliscono in modo sicuro per le scritture gestite da OpenClaw invece di
|
||||
appiattire la configurazione
|
||||
- **Gestione degli errori**: errori chiari per file mancanti, errori di parsing e include circolari
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Hot reload della configurazione
|
||||
## Ricaricamento a caldo della configurazione
|
||||
|
||||
Il Gateway osserva `~/.openclaw/openclaw.json` e applica automaticamente le modifiche — nella maggior parte dei casi non serve un riavvio manuale.
|
||||
Il Gateway osserva `~/.openclaw/openclaw.json` e applica automaticamente le modifiche — per la maggior parte delle impostazioni non è necessario alcun riavvio manuale.
|
||||
|
||||
Le modifiche dirette al file vengono trattate come non fidate finché non vengono validate. Il watcher attende
|
||||
che il churn di scrittura/rinomina temporanea dell'editor si stabilizzi, legge il file finale e rifiuta
|
||||
le modifiche esterne non valide ripristinando la configurazione last-known-good. Le scritture di configurazione
|
||||
gestite da OpenClaw usano lo stesso gate di schema prima di scrivere; clobber distruttivi come
|
||||
la rimozione di `gateway.mode` o la riduzione del file a meno della metà vengono rifiutati
|
||||
Le modifiche dirette al file vengono trattate come non attendibili finché non superano la validazione. Il watcher attende
|
||||
che il churn di scrittura temporanea/rinomina dell'editor si stabilizzi, legge il file finale e rifiuta
|
||||
le modifiche esterne non valide ripristinando la configurazione dell'ultimo stato valido. Le scritture di configurazione
|
||||
gestite da OpenClaw usano lo stesso controllo di schema prima della scrittura; clobber distruttivi come
|
||||
la rimozione di `gateway.mode` o la riduzione del file di oltre la metà vengono rifiutati
|
||||
e salvati come `.rejected.*` per l'ispezione.
|
||||
|
||||
Se nei log vedi `Config auto-restored from last-known-good` oppure
|
||||
`config reload restored last-known-good config`, ispeziona il file
|
||||
`.clobbered.*` corrispondente accanto a `openclaw.json`, correggi il payload rifiutato, poi esegui
|
||||
`openclaw config validate`. Vedi [Risoluzione dei problemi del Gateway](/it/gateway/troubleshooting#gateway-restored-last-known-good-config)
|
||||
Se vedi `Config auto-restored from last-known-good` o
|
||||
`config reload restored last-known-good config` nei log, esamina il file
|
||||
`.clobbered.*` corrispondente accanto a `openclaw.json`, correggi il payload rifiutato, quindi esegui
|
||||
`openclaw config validate`. Consulta [Risoluzione dei problemi del Gateway](/it/gateway/troubleshooting#gateway-restored-last-known-good-config)
|
||||
per la checklist di ripristino.
|
||||
|
||||
### Modalità di reload
|
||||
### Modalità di ricaricamento
|
||||
|
||||
| Modalità | Comportamento |
|
||||
| ---------------------- | -------------------------------------------------------------------------------------- |
|
||||
| **`hybrid`** (predefinita) | Applica a caldo subito le modifiche sicure. Riavvia automaticamente per quelle critiche. |
|
||||
| **`hot`** | Applica a caldo solo le modifiche sicure. Registra un avviso quando serve un riavvio — lo gestisci tu. |
|
||||
| **`hybrid`** (predefinita) | Applica a caldo immediatamente le modifiche sicure. Riavvia automaticamente per quelle critiche. |
|
||||
| **`hot`** | Applica a caldo solo le modifiche sicure. Registra un avviso quando è necessario un riavvio — lo gestisci tu. |
|
||||
| **`restart`** | Riavvia il Gateway a ogni modifica della configurazione, sicura o meno. |
|
||||
| **`off`** | Disabilita l'osservazione del file. Le modifiche hanno effetto al successivo riavvio manuale. |
|
||||
| **`off`** | Disabilita l'osservazione dei file. Le modifiche hanno effetto al successivo riavvio manuale. |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -535,56 +536,56 @@ per la checklist di ripristino.
|
||||
}
|
||||
```
|
||||
|
||||
### Cosa viene applicato a caldo e cosa richiede un riavvio
|
||||
### Cosa si applica a caldo e cosa richiede un riavvio
|
||||
|
||||
La maggior parte dei campi viene applicata a caldo senza downtime. In modalità `hybrid`, le modifiche che richiedono riavvio vengono gestite automaticamente.
|
||||
La maggior parte dei campi si applica a caldo senza downtime. In modalità `hybrid`, le modifiche che richiedono il riavvio vengono gestite automaticamente.
|
||||
|
||||
| Categoria | Campi | Riavvio necessario? |
|
||||
| ------------------- | ----------------------------------------------------------------- | --------------- |
|
||||
| Canali | `channels.*`, `web` (WhatsApp) — tutti i canali integrati e plugin | No |
|
||||
| Agente e modelli | `agent`, `agents`, `models`, `routing` | No |
|
||||
| Automazione | `hooks`, `cron`, `agent.heartbeat` | No |
|
||||
| Sessioni e messaggi | `session`, `messages` | No |
|
||||
| Strumenti e contenuti multimediali | `tools`, `browser`, `skills`, `audio`, `talk` | No |
|
||||
| UI e varie | `ui`, `logging`, `identity`, `bindings` | No |
|
||||
| Server Gateway | `gateway.*` (porta, bind, auth, tailscale, TLS, HTTP) | **Sì** |
|
||||
| Infrastruttura | `discovery`, `canvasHost`, `plugins` | **Sì** |
|
||||
| ------------------- | ----------------------------------------------------------------- | ------------------- |
|
||||
| Canali | `channels.*`, `web` (WhatsApp) — tutti i canali integrati e plugin | No |
|
||||
| Agente e modelli | `agent`, `agents`, `models`, `routing` | No |
|
||||
| Automazione | `hooks`, `cron`, `agent.heartbeat` | No |
|
||||
| Sessioni e messaggi | `session`, `messages` | No |
|
||||
| Strumenti e media | `tools`, `browser`, `skills`, `audio`, `talk` | No |
|
||||
| UI e varie | `ui`, `logging`, `identity`, `bindings` | No |
|
||||
| Server Gateway | `gateway.*` (porta, bind, auth, tailscale, TLS, HTTP) | **Sì** |
|
||||
| Infrastruttura | `discovery`, `canvasHost`, `plugins` | **Sì** |
|
||||
|
||||
<Note>
|
||||
`gateway.reload` e `gateway.remote` sono eccezioni — modificarli **non** attiva un riavvio.
|
||||
</Note>
|
||||
|
||||
### Pianificazione del reload
|
||||
### Pianificazione del ricaricamento
|
||||
|
||||
Quando modifichi un file sorgente referenziato tramite `$include`, OpenClaw pianifica
|
||||
il reload a partire dal layout scritto nei sorgenti, non dalla vista appiattita in memoria.
|
||||
il ricaricamento in base al layout creato nella sorgente, non alla vista in memoria appiattita.
|
||||
Questo mantiene prevedibili le decisioni di hot reload (applicazione a caldo vs riavvio) anche quando una
|
||||
singola sezione di primo livello vive nel proprio file incluso, come
|
||||
`plugins: { $include: "./plugins.json5" }`. La pianificazione del reload fallisce in modo chiuso se il
|
||||
singola sezione di primo livello si trova nel proprio file incluso, come
|
||||
`plugins: { $include: "./plugins.json5" }`. La pianificazione del ricaricamento fallisce in modo sicuro se il
|
||||
layout sorgente è ambiguo.
|
||||
|
||||
## RPC di configurazione (aggiornamenti programmatici)
|
||||
|
||||
Per gli strumenti che scrivono la configurazione tramite l'API gateway, preferisci questo flusso:
|
||||
Per gli strumenti che scrivono la configurazione tramite l'API del gateway, preferisci questo flusso:
|
||||
|
||||
- `config.schema.lookup` per ispezionare un sottoalbero (nodo di schema shallow + riepiloghi
|
||||
- `config.schema.lookup` per ispezionare un sottoalbero (nodo di schema superficiale + riepiloghi
|
||||
dei figli)
|
||||
- `config.get` per recuperare lo snapshot corrente più `hash`
|
||||
- `config.patch` per aggiornamenti parziali (JSON merge patch: gli oggetti si uniscono, `null`
|
||||
elimina, gli array sostituiscono)
|
||||
- `config.apply` solo quando intendi sostituire l'intera configurazione
|
||||
- `update.run` per self-update esplicito più riavvio
|
||||
- `update.run` per auto-aggiornamento esplicito più riavvio
|
||||
|
||||
<Note>
|
||||
Le scritture del control plane (`config.apply`, `config.patch`, `update.run`) sono
|
||||
rate-limited a 3 richieste per 60 secondi per `deviceId+clientIp`. Le richieste di riavvio
|
||||
soggette a rate limit di 3 richieste per 60 secondi per `deviceId+clientIp`. Le richieste di riavvio
|
||||
vengono accorpate e poi applicano un cooldown di 30 secondi tra i cicli di riavvio.
|
||||
</Note>
|
||||
|
||||
Esempio di patch parziale:
|
||||
|
||||
```bash
|
||||
openclaw gateway call config.get --params '{}' # capture payload.hash
|
||||
openclaw gateway call config.get --params '{}' # acquisisci payload.hash
|
||||
openclaw gateway call config.patch --params '{
|
||||
"raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
|
||||
"baseHash": "<hash>"
|
||||
@ -592,8 +593,8 @@ openclaw gateway call config.patch --params '{
|
||||
```
|
||||
|
||||
Sia `config.apply` sia `config.patch` accettano `raw`, `baseHash`, `sessionKey`,
|
||||
`note` e `restartDelayMs`. `baseHash` è obbligatorio per `config.patch` e
|
||||
consigliato per `config.apply` quando una configurazione esiste già.
|
||||
`note` e `restartDelayMs`. `baseHash` è richiesto per entrambi i metodi quando
|
||||
esiste già una configurazione.
|
||||
|
||||
## Variabili d'ambiente
|
||||
|
||||
@ -613,8 +614,8 @@ Nessuno dei due file sovrascrive variabili d'ambiente esistenti. Puoi anche impo
|
||||
}
|
||||
```
|
||||
|
||||
<Accordion title="Importazione env della shell (opzionale)">
|
||||
Se abilitato e le chiavi attese non sono impostate, OpenClaw esegue la tua login shell e importa solo le chiavi mancanti:
|
||||
<Accordion title="Importazione env della shell (facoltativa)">
|
||||
Se abilitato e le chiavi previste non sono impostate, OpenClaw esegue la tua shell di login e importa solo le chiavi mancanti:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -624,10 +625,10 @@ Nessuno dei due file sovrascrive variabili d'ambiente esistenti. Puoi anche impo
|
||||
}
|
||||
```
|
||||
|
||||
Equivalente come variabile d'ambiente: `OPENCLAW_LOAD_SHELL_ENV=1`
|
||||
Equivalente tramite variabile d'ambiente: `OPENCLAW_LOAD_SHELL_ENV=1`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Sostituzione delle variabili d'ambiente nei valori di configurazione">
|
||||
<Accordion title="Sostituzione di variabili d'ambiente nei valori di configurazione">
|
||||
Fai riferimento alle variabili d'ambiente in qualsiasi valore stringa della configurazione con `${VAR_NAME}`:
|
||||
|
||||
```json5
|
||||
@ -639,15 +640,15 @@ Equivalente come variabile d'ambiente: `OPENCLAW_LOAD_SHELL_ENV=1`
|
||||
|
||||
Regole:
|
||||
|
||||
- Vengono abbinati solo nomi in maiuscolo: `[A-Z_][A-Z0-9_]*`
|
||||
- Variabili mancanti/vuote generano un errore al caricamento
|
||||
- Esegui l'escape con `$${VAR}` per output letterale
|
||||
- Funziona dentro i file `$include`
|
||||
- Vengono corrisposti solo nomi in maiuscolo: `[A-Z_][A-Z0-9_]*`
|
||||
- Variabili mancanti/vuote generano un errore al momento del caricamento
|
||||
- Usa l'escape con `$${VAR}` per output letterale
|
||||
- Funziona all'interno dei file `$include`
|
||||
- Sostituzione inline: `"${BASE}/v1"` → `"https://api.example.com/v1"`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="SecretRef (env, file, exec)">
|
||||
<Accordion title="Riferimenti ai segreti (env, file, exec)">
|
||||
Per i campi che supportano oggetti SecretRef, puoi usare:
|
||||
|
||||
```json5
|
||||
@ -681,14 +682,14 @@ Regole:
|
||||
```
|
||||
|
||||
I dettagli di SecretRef (incluso `secrets.providers` per `env`/`file`/`exec`) sono in [Gestione dei segreti](/it/gateway/secrets).
|
||||
I percorsi delle credenziali supportati sono elencati in [Superficie credenziali SecretRef](/it/reference/secretref-credential-surface).
|
||||
I percorsi delle credenziali supportati sono elencati in [Superficie delle credenziali SecretRef](/it/reference/secretref-credential-surface).
|
||||
</Accordion>
|
||||
|
||||
Vedi [Ambiente](/it/help/environment) per la precedenza completa e le sorgenti.
|
||||
Consulta [Ambiente](/it/help/environment) per la precedenza completa e le fonti.
|
||||
|
||||
## Riferimento completo
|
||||
|
||||
Per il riferimento completo campo per campo, vedi **[Riferimento configurazione](/it/gateway/configuration-reference)**.
|
||||
Per il riferimento completo campo per campo, consulta **[Riferimento configurazione](/it/gateway/configuration-reference)**.
|
||||
|
||||
---
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Vuoi usare modelli OpenAI in OpenClaw
|
||||
- Vuoi usare l'autenticazione con abbonamento Codex invece delle API key
|
||||
- Vuoi usare i modelli OpenAI in OpenClaw
|
||||
- Vuoi l'autenticazione con abbonamento Codex invece delle chiavi API
|
||||
- Hai bisogno di un comportamento di esecuzione dell'agente GPT-5 più rigoroso
|
||||
summary: Usa OpenAI tramite API key o abbonamento Codex in OpenClaw
|
||||
summary: Usa OpenAI tramite chiavi API o abbonamento Codex in OpenClaw
|
||||
title: OpenAI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T08:35:24Z"
|
||||
generated_at: "2026-04-23T13:58:21Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c3d847e53c2faee5363071dfdcb1f4150b64577674161e000844f579482198d1
|
||||
source_hash: ac42660234e1971440f6de3b04adb1d3a1fddca20219fb68936c36e4c2f95265
|
||||
source_path: providers/openai.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -18,37 +18,37 @@ x-i18n:
|
||||
|
||||
OpenAI fornisce API per sviluppatori per i modelli GPT. OpenClaw supporta due percorsi di autenticazione:
|
||||
|
||||
- **API key** — accesso diretto alla OpenAI Platform con fatturazione a consumo (modelli `openai/*`)
|
||||
- **Abbonamento Codex** — accesso con sign-in ChatGPT/Codex e abbonamento (modelli `openai-codex/*`)
|
||||
- **Chiave API** — accesso diretto a OpenAI Platform con fatturazione basata sull'utilizzo (modelli `openai/*`)
|
||||
- **Abbonamento Codex** — accesso ChatGPT/Codex con sottoscrizione (modelli `openai-codex/*`)
|
||||
|
||||
OpenAI supporta esplicitamente l'uso di OAuth con abbonamento in strumenti e flussi di lavoro esterni come OpenClaw.
|
||||
OpenAI supporta esplicitamente l'uso dell'OAuth con abbonamento in strumenti e flussi di lavoro esterni come OpenClaw.
|
||||
|
||||
## Copertura delle funzionalità OpenClaw
|
||||
## Copertura delle funzionalità di OpenClaw
|
||||
|
||||
| Capacità OpenAI | Surface OpenClaw | Stato |
|
||||
| ------------------------ | ----------------------------------------- | ------------------------------------------------------ |
|
||||
| Chat / Responses | provider di modelli `openai/<model>` | Sì |
|
||||
| Modelli con abbonamento Codex | provider di modelli `openai-codex/<model>` | Sì |
|
||||
| Ricerca web lato server | strumento Native OpenAI Responses | Sì, quando la ricerca web è abilitata e nessun provider è fissato |
|
||||
| Immagini | `image_generate` | Sì |
|
||||
| Video | `video_generate` | Sì |
|
||||
| Sintesi vocale | `messages.tts.provider: "openai"` / `tts` | Sì |
|
||||
| Speech-to-text batch | `tools.media.audio` / comprensione dei media | Sì |
|
||||
| Speech-to-text in streaming | Voice Call `streaming.provider: "openai"` | Sì |
|
||||
| Voce realtime | Voice Call `realtime.provider: "openai"` | Sì |
|
||||
| Embedding | provider di embedding per la memoria | Sì |
|
||||
| Funzionalità OpenAI | Superficie OpenClaw | Stato |
|
||||
| ------------------------- | ----------------------------------------- | ------------------------------------------------------ |
|
||||
| Chat / Responses | provider di modelli `openai/<model>` | Sì |
|
||||
| Modelli con abbonamento Codex | provider di modelli `openai-codex/<model>` | Sì |
|
||||
| Ricerca web lato server | Strumento nativo OpenAI Responses | Sì, quando la ricerca web è abilitata e nessun provider è fissato |
|
||||
| Immagini | `image_generate` | Sì |
|
||||
| Video | `video_generate` | Sì |
|
||||
| Sintesi vocale | `messages.tts.provider: "openai"` / `tts` | Sì |
|
||||
| Speech-to-text batch | `tools.media.audio` / comprensione media | Sì |
|
||||
| Speech-to-text in streaming | Voice Call `streaming.provider: "openai"` | Sì |
|
||||
| Voce realtime | Voice Call `realtime.provider: "openai"` | Sì |
|
||||
| Embeddings | provider di embedding della memoria | Sì |
|
||||
|
||||
## Per iniziare
|
||||
|
||||
Scegli il tuo metodo di autenticazione preferito e segui i passaggi di configurazione.
|
||||
Scegli il metodo di autenticazione che preferisci e segui i passaggi di configurazione.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API key (OpenAI Platform)">
|
||||
**Ideale per:** accesso API diretto e fatturazione a consumo.
|
||||
<Tab title="Chiave API (OpenAI Platform)">
|
||||
**Ideale per:** accesso API diretto e fatturazione basata sull'utilizzo.
|
||||
|
||||
<Steps>
|
||||
<Step title="Ottieni la tua API key">
|
||||
Crea o copia una API key dalla [dashboard OpenAI Platform](https://platform.openai.com/api-keys).
|
||||
<Step title="Ottieni la tua chiave API">
|
||||
Crea o copia una chiave API dalla [dashboard di OpenAI Platform](https://platform.openai.com/api-keys).
|
||||
</Step>
|
||||
<Step title="Esegui l'onboarding">
|
||||
```bash
|
||||
@ -70,16 +70,16 @@ x-i18n:
|
||||
|
||||
### Riepilogo del percorso
|
||||
|
||||
| Riferimento modello | Percorso | Auth |
|
||||
| Model ref | Percorso | Auth |
|
||||
|-----------|-------|------|
|
||||
| `openai/gpt-5.4` | API OpenAI Platform diretta | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.4-pro` | API OpenAI Platform diretta | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.4` | API diretta di OpenAI Platform | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.4-pro` | API diretta di OpenAI Platform | `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
Il sign-in ChatGPT/Codex viene instradato tramite `openai-codex/*`, non `openai/*`.
|
||||
L'accesso ChatGPT/Codex è instradato tramite `openai-codex/*`, non `openai/*`.
|
||||
</Note>
|
||||
|
||||
### Esempio di config
|
||||
### Esempio di configurazione
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -89,16 +89,16 @@ x-i18n:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
OpenClaw **non** espone `openai/gpt-5.3-codex-spark` sul percorso API diretto. Le richieste live all'API OpenAI rifiutano quel modello. Spark è solo Codex.
|
||||
OpenClaw **non** espone `openai/gpt-5.3-codex-spark` sul percorso API diretto. Le richieste live alle API OpenAI rifiutano quel modello. Spark è solo Codex.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Abbonamento Codex">
|
||||
**Ideale per:** usare il tuo abbonamento ChatGPT/Codex invece di una API key separata. Codex cloud richiede il sign-in ChatGPT.
|
||||
**Ideale per:** usare il tuo abbonamento ChatGPT/Codex invece di una chiave API separata. Codex cloud richiede l'accesso con ChatGPT.
|
||||
|
||||
<Steps>
|
||||
<Step title="Esegui OAuth Codex">
|
||||
<Step title="Esegui l'OAuth di Codex">
|
||||
```bash
|
||||
openclaw onboard --auth-choice openai-codex
|
||||
```
|
||||
@ -109,7 +109,7 @@ x-i18n:
|
||||
openclaw models auth login --provider openai-codex
|
||||
```
|
||||
|
||||
Per configurazioni headless o ostili ai callback, aggiungi `--device-code` per accedere con un flusso device-code di ChatGPT invece del callback browser localhost:
|
||||
Per configurazioni headless o ostili al callback, aggiungi `--device-code` per accedere con un flusso device-code di ChatGPT invece del callback del browser localhost:
|
||||
|
||||
```bash
|
||||
openclaw models auth login --provider openai-codex --device-code
|
||||
@ -129,16 +129,16 @@ x-i18n:
|
||||
|
||||
### Riepilogo del percorso
|
||||
|
||||
| Riferimento modello | Percorso | Auth |
|
||||
| Model ref | Percorso | Auth |
|
||||
|-----------|-------|------|
|
||||
| `openai-codex/gpt-5.4` | OAuth ChatGPT/Codex | sign-in Codex |
|
||||
| `openai-codex/gpt-5.3-codex-spark` | OAuth ChatGPT/Codex | sign-in Codex (dipende dai diritti) |
|
||||
| `openai-codex/gpt-5.4` | OAuth ChatGPT/Codex | accesso Codex |
|
||||
| `openai-codex/gpt-5.3-codex-spark` | OAuth ChatGPT/Codex | accesso Codex (dipende dai diritti) |
|
||||
|
||||
<Note>
|
||||
Questo percorso è intenzionalmente separato da `openai/gpt-5.4`. Usa `openai/*` con una API key per l'accesso diretto alla Platform e `openai-codex/*` per l'accesso con abbonamento Codex.
|
||||
Questo percorso è intenzionalmente separato da `openai/gpt-5.4`. Usa `openai/*` con una chiave API per l'accesso diretto a Platform e `openai-codex/*` per l'accesso con abbonamento Codex.
|
||||
</Note>
|
||||
|
||||
### Esempio di config
|
||||
### Esempio di configurazione
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -147,17 +147,17 @@ x-i18n:
|
||||
```
|
||||
|
||||
<Note>
|
||||
L'onboarding non importa più materiale OAuth da `~/.codex`. Accedi con OAuth via browser (predefinito) o con il flusso device-code sopra — OpenClaw gestisce le credenziali risultanti nel proprio archivio auth dell'agente.
|
||||
L'onboarding non importa più materiale OAuth da `~/.codex`. Accedi con OAuth nel browser (predefinito) o con il flusso device-code sopra — OpenClaw gestisce le credenziali risultanti nel proprio archivio di autenticazione dell'agente.
|
||||
</Note>
|
||||
|
||||
### Limite della finestra di contesto
|
||||
|
||||
OpenClaw tratta i metadati del modello e il limite di contesto del runtime come valori separati.
|
||||
OpenClaw tratta i metadati del modello e il limite di contesto runtime come valori separati.
|
||||
|
||||
Per `openai-codex/gpt-5.4`:
|
||||
|
||||
- `contextWindow` nativo: `1050000`
|
||||
- limite `contextTokens` di runtime predefinito: `272000`
|
||||
- limite predefinito runtime `contextTokens`: `272000`
|
||||
|
||||
Il limite predefinito più piccolo offre in pratica caratteristiche migliori di latenza e qualità. Sostituiscilo con `contextTokens`:
|
||||
|
||||
@ -174,7 +174,7 @@ x-i18n:
|
||||
```
|
||||
|
||||
<Note>
|
||||
Usa `contextWindow` per dichiarare i metadati nativi del modello. Usa `contextTokens` per limitare il budget di contesto del runtime.
|
||||
Usa `contextWindow` per dichiarare i metadati nativi del modello. Usa `contextTokens` per limitare il budget di contesto runtime.
|
||||
</Note>
|
||||
|
||||
</Tab>
|
||||
@ -182,15 +182,15 @@ x-i18n:
|
||||
|
||||
## Generazione di immagini
|
||||
|
||||
Il Plugin incluso `openai` registra la generazione di immagini tramite lo strumento `image_generate`.
|
||||
Il Plugin `openai` incluso registra la generazione di immagini tramite lo strumento `image_generate`.
|
||||
|
||||
| Capacità | Valore |
|
||||
| ----------------------- | ---------------------------------- |
|
||||
| Modello predefinito | `openai/gpt-image-2` |
|
||||
| Numero massimo di immagini per richiesta | 4 |
|
||||
| Modalità modifica | Abilitata (fino a 5 immagini di riferimento) |
|
||||
| Override di dimensione | Supportati, incluse dimensioni 2K/4K |
|
||||
| Rapporto d'aspetto / risoluzione | Non inoltrati all'API OpenAI Images |
|
||||
| Capacità | Valore |
|
||||
| ------------------------ | ---------------------------------- |
|
||||
| Modello predefinito | `openai/gpt-image-2` |
|
||||
| Numero massimo di immagini per richiesta | 4 |
|
||||
| Modalità modifica | Abilitata (fino a 5 immagini di riferimento) |
|
||||
| Override delle dimensioni | Supportati, incluse dimensioni 2K/4K |
|
||||
| Rapporto d'aspetto / risoluzione | Non inoltrati alla OpenAI Images API |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -203,36 +203,36 @@ Il Plugin incluso `openai` registra la generazione di immagini tramite lo strume
|
||||
```
|
||||
|
||||
<Note>
|
||||
Vedi [Image Generation](/it/tools/image-generation) per parametri condivisi dello strumento, selezione del provider e comportamento di failover.
|
||||
Vedi [Generazione di immagini](/it/tools/image-generation) per parametri condivisi dello strumento, selezione del provider e comportamento di failover.
|
||||
</Note>
|
||||
|
||||
`gpt-image-2` è il valore predefinito sia per la generazione text-to-image di OpenAI sia per il
|
||||
modifica di immagini. `gpt-image-1` resta utilizzabile come override esplicito del modello, ma i nuovi
|
||||
flussi di lavoro di immagini OpenAI dovrebbero usare `openai/gpt-image-2`.
|
||||
ritocco delle immagini. `gpt-image-1` resta utilizzabile come override esplicito del modello, ma i nuovi
|
||||
flussi di lavoro per immagini OpenAI dovrebbero usare `openai/gpt-image-2`.
|
||||
|
||||
Genera:
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="Un poster di lancio raffinato per OpenClaw su macOS" size=3840x2160 count=1
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="Un raffinato poster di lancio per OpenClaw su macOS" size=3840x2160 count=1
|
||||
```
|
||||
|
||||
Modifica:
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="Preserva la forma dell'oggetto, cambia il materiale in vetro traslucido" image=/path/to/reference.png size=1024x1536
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="Mantieni la forma dell'oggetto, cambia il materiale in vetro traslucido" image=/path/to/reference.png size=1024x1536
|
||||
```
|
||||
|
||||
## Generazione video
|
||||
|
||||
Il Plugin incluso `openai` registra la generazione video tramite lo strumento `video_generate`.
|
||||
Il Plugin `openai` incluso registra la generazione video tramite lo strumento `video_generate`.
|
||||
|
||||
| Capacità | Valore |
|
||||
| -------------- | --------------------------------------------------------------------------------- |
|
||||
| Modello predefinito | `openai/sora-2` |
|
||||
| Modalità | Text-to-video, image-to-video, modifica di singolo video |
|
||||
| Input di riferimento | 1 immagine o 1 video |
|
||||
| Override di dimensione | Supportati |
|
||||
| Altri override | `aspectRatio`, `resolution`, `audio`, `watermark` vengono ignorati con un avviso dello strumento |
|
||||
| Capacità | Valore |
|
||||
| --------------- | --------------------------------------------------------------------------------- |
|
||||
| Modello predefinito | `openai/sora-2` |
|
||||
| Modalità | Text-to-video, image-to-video, modifica di un singolo video |
|
||||
| Input di riferimento | 1 immagine o 1 video |
|
||||
| Override delle dimensioni | Supportati |
|
||||
| Altri override | `aspectRatio`, `resolution`, `audio`, `watermark` vengono ignorati con un avviso dello strumento |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -245,21 +245,21 @@ Il Plugin incluso `openai` registra la generazione video tramite lo strumento `v
|
||||
```
|
||||
|
||||
<Note>
|
||||
Vedi [Video Generation](/it/tools/video-generation) per parametri condivisi dello strumento, selezione del provider e comportamento di failover.
|
||||
Vedi [Generazione video](/it/tools/video-generation) per parametri condivisi dello strumento, selezione del provider e comportamento di failover.
|
||||
</Note>
|
||||
|
||||
## Contributo al prompt GPT-5
|
||||
|
||||
OpenClaw aggiunge un contributo condiviso al prompt GPT-5 per le esecuzioni della famiglia GPT-5 tra i provider. Si applica per ID modello, quindi `openai/gpt-5.4`, `openai-codex/gpt-5.4`, `openrouter/openai/gpt-5.4`, `opencode/gpt-5.4` e altri riferimenti GPT-5 compatibili ricevono lo stesso overlay. I vecchi modelli GPT-4.x non lo ricevono.
|
||||
OpenClaw aggiunge un contributo condiviso al prompt GPT-5 per le esecuzioni della famiglia GPT-5 tra provider. Si applica per ID modello, quindi `openai/gpt-5.4`, `openai-codex/gpt-5.4`, `openrouter/openai/gpt-5.4`, `opencode/gpt-5.4` e altri riferimenti GPT-5 compatibili ricevono lo stesso overlay. I modelli GPT-4.x meno recenti no.
|
||||
|
||||
Il provider incluso dell'harness Codex nativo (`codex/*`) usa lo stesso comportamento GPT-5 e lo stesso overlay Heartbeat tramite le istruzioni sviluppatore dell'app-server Codex, quindi le sessioni `codex/gpt-5.x` mantengono la stessa continuità di esecuzione e le stesse indicazioni proattive Heartbeat anche se Codex gestisce il resto del prompt dell'harness.
|
||||
Il provider harness Codex nativo incluso (`codex/*`) usa lo stesso comportamento GPT-5 e l'overlay Heartbeat tramite istruzioni developer dell'app-server Codex, quindi le sessioni `codex/gpt-5.x` mantengono la stessa continuità di esecuzione e la stessa guida Heartbeat proattiva anche se Codex gestisce il resto del prompt harness.
|
||||
|
||||
Il contributo GPT-5 aggiunge un contratto di comportamento con tag per persistenza della persona, sicurezza di esecuzione, disciplina degli strumenti, forma dell'output, controlli di completamento e verifica. Il comportamento specifico del canale per risposta e messaggi silenziosi resta nel prompt di sistema condiviso di OpenClaw e nella policy di consegna in uscita. La guida GPT-5 è sempre abilitata per i modelli corrispondenti. Il livello separato dello stile di interazione amichevole è configurabile.
|
||||
Il contributo GPT-5 aggiunge un contratto di comportamento con tag per persistenza della persona, sicurezza di esecuzione, disciplina degli strumenti, forma dell'output, controlli di completamento e verifica. Il comportamento specifico del canale per risposte e messaggi silenziosi resta nel prompt di sistema condiviso di OpenClaw e nella policy di consegna in uscita. La guida GPT-5 è sempre abilitata per i modelli corrispondenti. Il livello di stile di interazione amichevole è separato e configurabile.
|
||||
|
||||
| Valore | Effetto |
|
||||
| ---------------------- | ------------------------------------------- |
|
||||
| `"friendly"` (predefinito) | Abilita il livello dello stile di interazione amichevole |
|
||||
| `"on"` | Alias di `"friendly"` |
|
||||
| `"friendly"` (predefinito) | Abilita il livello di stile di interazione amichevole |
|
||||
| `"on"` | Alias per `"friendly"` |
|
||||
| `"off"` | Disabilita solo il livello di stile amichevole |
|
||||
|
||||
<Tabs>
|
||||
@ -284,18 +284,18 @@ Il contributo GPT-5 aggiunge un contratto di comportamento con tag per persisten
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
I valori non distinguono tra maiuscole e minuscole a runtime, quindi sia `"Off"` sia `"off"` disabilitano il livello di stile amichevole.
|
||||
I valori non distinguono tra maiuscole e minuscole a runtime, quindi `"Off"` e `"off"` disabilitano entrambi il livello di stile amichevole.
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fallback di compatibilità quando l'impostazione condivisa `agents.defaults.promptOverlays.gpt5.personality` non è impostata.
|
||||
Il valore legacy `plugins.entries.openai.config.personality` viene ancora letto come fallback di compatibilità quando l'impostazione condivisa `agents.defaults.promptOverlays.gpt5.personality` non è configurata.
|
||||
</Note>
|
||||
|
||||
## Voce e parlato
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Sintesi vocale (TTS)">
|
||||
Il Plugin incluso `openai` registra la sintesi vocale per la surface `messages.tts`.
|
||||
Il Plugin `openai` incluso registra la sintesi vocale per la superficie `messages.tts`.
|
||||
|
||||
| Impostazione | Percorso config | Predefinito |
|
||||
|---------|------------|---------|
|
||||
@ -304,8 +304,8 @@ Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fa
|
||||
| Velocità | `messages.tts.providers.openai.speed` | (non impostato) |
|
||||
| Istruzioni | `messages.tts.providers.openai.instructions` | (non impostato, solo `gpt-4o-mini-tts`) |
|
||||
| Formato | `messages.tts.providers.openai.responseFormat` | `opus` per note vocali, `mp3` per file |
|
||||
| API key | `messages.tts.providers.openai.apiKey` | Fallback a `OPENAI_API_KEY` |
|
||||
| Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
|
||||
| Chiave API | `messages.tts.providers.openai.apiKey` | Usa `OPENAI_API_KEY` come fallback |
|
||||
| URL base | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
|
||||
|
||||
Modelli disponibili: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Voci disponibili: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`.
|
||||
|
||||
@ -322,20 +322,20 @@ Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fa
|
||||
```
|
||||
|
||||
<Note>
|
||||
Imposta `OPENAI_TTS_BASE_URL` per sovrascrivere il base URL TTS senza influire sull'endpoint API della chat.
|
||||
Imposta `OPENAI_TTS_BASE_URL` per sostituire l'URL base TTS senza influire sull'endpoint API della chat.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Speech-to-text">
|
||||
Il Plugin incluso `openai` registra lo speech-to-text batch tramite
|
||||
la surface di trascrizione della comprensione dei media di OpenClaw.
|
||||
Il Plugin `openai` incluso registra lo speech-to-text batch tramite
|
||||
la superficie di trascrizione per la comprensione dei media di OpenClaw.
|
||||
|
||||
- Modello predefinito: `gpt-4o-transcribe`
|
||||
- Endpoint: REST OpenAI `/v1/audio/transcriptions`
|
||||
- Percorso di input: upload file audio multipart
|
||||
- Endpoint: OpenAI REST `/v1/audio/transcriptions`
|
||||
- Percorso di input: caricamento file audio multipart
|
||||
- Supportato da OpenClaw ovunque la trascrizione audio in ingresso usi
|
||||
`tools.media.audio`, inclusi segmenti dei canali vocali Discord e
|
||||
`tools.media.audio`, inclusi i segmenti dei canali vocali Discord e gli
|
||||
allegati audio dei canali
|
||||
|
||||
Per forzare OpenAI per la trascrizione audio in ingresso:
|
||||
@ -359,12 +359,12 @@ Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fa
|
||||
```
|
||||
|
||||
Gli hint di lingua e prompt vengono inoltrati a OpenAI quando forniti dalla
|
||||
config audio media condivisa o dalla richiesta di trascrizione per chiamata.
|
||||
configurazione audio condivisa dei media o dalla richiesta di trascrizione per chiamata.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Trascrizione realtime">
|
||||
Il Plugin incluso `openai` registra la trascrizione realtime per il Plugin Voice Call.
|
||||
Il Plugin `openai` incluso registra la trascrizione realtime per il Plugin Voice Call.
|
||||
|
||||
| Impostazione | Percorso config | Predefinito |
|
||||
|---------|------------|---------|
|
||||
@ -373,16 +373,16 @@ Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fa
|
||||
| Prompt | `...openai.prompt` | (non impostato) |
|
||||
| Durata del silenzio | `...openai.silenceDurationMs` | `800` |
|
||||
| Soglia VAD | `...openai.vadThreshold` | `0.5` |
|
||||
| API key | `...openai.apiKey` | Fallback a `OPENAI_API_KEY` |
|
||||
| Chiave API | `...openai.apiKey` | Usa `OPENAI_API_KEY` come fallback |
|
||||
|
||||
<Note>
|
||||
Usa una connessione WebSocket a `wss://api.openai.com/v1/realtime` con audio G.711 u-law (`g711_ulaw` / `audio/pcmu`). Questo provider di streaming è per il percorso di trascrizione realtime di Voice Call; la voce Discord attualmente registra segmenti brevi e usa invece il percorso batch di trascrizione `tools.media.audio`.
|
||||
Usa una connessione WebSocket a `wss://api.openai.com/v1/realtime` con audio G.711 u-law (`g711_ulaw` / `audio/pcmu`). Questo provider di streaming è per il percorso di trascrizione realtime di Voice Call; attualmente la voce Discord registra brevi segmenti e usa invece il percorso di trascrizione batch `tools.media.audio`.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Voce realtime">
|
||||
Il Plugin incluso `openai` registra la voce realtime per il Plugin Voice Call.
|
||||
Il Plugin `openai` incluso registra la voce realtime per il Plugin Voice Call.
|
||||
|
||||
| Impostazione | Percorso config | Predefinito |
|
||||
|---------|------------|---------|
|
||||
@ -391,30 +391,158 @@ Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fa
|
||||
| Temperatura | `...openai.temperature` | `0.8` |
|
||||
| Soglia VAD | `...openai.vadThreshold` | `0.5` |
|
||||
| Durata del silenzio | `...openai.silenceDurationMs` | `500` |
|
||||
| API key | `...openai.apiKey` | Fallback a `OPENAI_API_KEY` |
|
||||
| Chiave API | `...openai.apiKey` | Usa `OPENAI_API_KEY` come fallback |
|
||||
|
||||
<Note>
|
||||
Supporta Azure OpenAI tramite le chiavi di config `azureEndpoint` e `azureDeployment`. Supporta la chiamata di strumenti bidirezionale. Usa il formato audio G.711 u-law.
|
||||
Supporta Azure OpenAI tramite le chiavi di configurazione `azureEndpoint` e `azureDeployment`. Supporta il tool calling bidirezionale. Usa il formato audio G.711 u-law.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Endpoint Azure OpenAI
|
||||
|
||||
Il provider `openai` incluso può indirizzare una risorsa Azure OpenAI per la
|
||||
generazione di immagini sovrascrivendo l'URL base. Sul percorso di generazione
|
||||
di immagini, OpenClaw rileva gli hostname Azure in `models.providers.openai.baseUrl` e passa
|
||||
automaticamente alla forma di richiesta di Azure.
|
||||
|
||||
<Note>
|
||||
La voce realtime usa un percorso di configurazione separato
|
||||
(`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`)
|
||||
e non è influenzata da `models.providers.openai.baseUrl`. Vedi l'accordion **Voce
|
||||
realtime** in [Voce e parlato](#voice-and-speech) per le relative
|
||||
impostazioni Azure.
|
||||
</Note>
|
||||
|
||||
Usa Azure OpenAI quando:
|
||||
|
||||
- Hai già una sottoscrizione, quota o contratto enterprise Azure OpenAI
|
||||
- Hai bisogno della residenza regionale dei dati o dei controlli di conformità offerti da Azure
|
||||
- Vuoi mantenere il traffico all'interno di una tenancy Azure esistente
|
||||
|
||||
### Configurazione
|
||||
|
||||
Per la generazione di immagini Azure tramite il provider `openai` incluso, punta
|
||||
`models.providers.openai.baseUrl` alla tua risorsa Azure e imposta `apiKey` sulla
|
||||
chiave Azure OpenAI (non una chiave OpenAI Platform):
|
||||
|
||||
```json5
|
||||
{
|
||||
models: {
|
||||
providers: {
|
||||
openai: {
|
||||
baseUrl: "https://<your-resource>.openai.azure.com",
|
||||
apiKey: "<azure-openai-api-key>",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw riconosce questi suffissi host Azure per il percorso Azure di
|
||||
generazione di immagini:
|
||||
|
||||
- `*.openai.azure.com`
|
||||
- `*.services.ai.azure.com`
|
||||
- `*.cognitiveservices.azure.com`
|
||||
|
||||
Per le richieste di generazione di immagini su un host Azure riconosciuto, OpenClaw:
|
||||
|
||||
- Invia l'header `api-key` invece di `Authorization: Bearer`
|
||||
- Usa percorsi con ambito deployment (`/openai/deployments/{deployment}/...`)
|
||||
- Aggiunge `?api-version=...` a ogni richiesta
|
||||
|
||||
Gli altri URL base (OpenAI pubblico, proxy compatibili con OpenAI) mantengono la
|
||||
forma standard delle richieste immagine OpenAI.
|
||||
|
||||
<Note>
|
||||
Il routing Azure per il percorso di generazione di immagini del provider `openai` richiede
|
||||
OpenClaw 2026.4.22 o successivo. Le versioni precedenti trattano qualsiasi
|
||||
`openai.baseUrl` personalizzato come l'endpoint OpenAI pubblico e falliscono sui deployment
|
||||
immagine Azure.
|
||||
</Note>
|
||||
|
||||
### Versione API
|
||||
|
||||
Imposta `AZURE_OPENAI_API_VERSION` per fissare una specifica versione preview o GA di Azure
|
||||
per il percorso di generazione di immagini Azure:
|
||||
|
||||
```bash
|
||||
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
```
|
||||
|
||||
Il valore predefinito è `2024-12-01-preview` quando la variabile non è impostata.
|
||||
|
||||
### I nomi dei modelli sono nomi di deployment
|
||||
|
||||
Azure OpenAI associa i modelli ai deployment. Per le richieste di generazione di immagini Azure
|
||||
instradate tramite il provider `openai` incluso, il campo `model` in OpenClaw
|
||||
deve essere il **nome del deployment Azure** configurato nel portale Azure, non
|
||||
l'ID del modello OpenAI pubblico.
|
||||
|
||||
Se crei un deployment chiamato `gpt-image-2-prod` che serve `gpt-image-2`:
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2-prod prompt="Un poster pulito" size=1024x1024 count=1
|
||||
```
|
||||
|
||||
La stessa regola del nome del deployment si applica alle chiamate di generazione di immagini
|
||||
instradate tramite il provider `openai` incluso.
|
||||
|
||||
### Disponibilità regionale
|
||||
|
||||
La generazione di immagini Azure è attualmente disponibile solo in un sottoinsieme di regioni
|
||||
(ad esempio `eastus2`, `swedencentral`, `polandcentral`, `westus3`,
|
||||
`uaenorth`). Controlla l'elenco aggiornato delle regioni Microsoft prima di creare un
|
||||
deployment e conferma che il modello specifico sia offerto nella tua regione.
|
||||
|
||||
### Differenze dei parametri
|
||||
|
||||
Azure OpenAI e OpenAI pubblico non accettano sempre gli stessi parametri immagine.
|
||||
Azure può rifiutare opzioni consentite da OpenAI pubblico (per esempio alcuni
|
||||
valori `background` su `gpt-image-2`) o esporle solo su specifiche versioni del modello.
|
||||
Queste differenze dipendono da Azure e dal modello sottostante, non da
|
||||
OpenClaw. Se una richiesta Azure fallisce con un errore di validazione, controlla
|
||||
l'insieme di parametri supportato dal tuo specifico deployment e dalla versione API nel
|
||||
portale Azure.
|
||||
|
||||
<Note>
|
||||
Azure OpenAI usa trasporto e comportamento compat nativi ma non riceve
|
||||
gli header di attribuzione nascosti di OpenClaw. Vedi l'accordion **Percorsi
|
||||
nativi vs compatibili con OpenAI** in [Configurazione avanzata](#advanced-configuration)
|
||||
per i dettagli.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
Per un provider Azure OpenAI Responses separato (distinto dal provider `openai`),
|
||||
vedi i riferimenti di modello `azure-openai-responses/*` nell'accordion
|
||||
[Compaction lato server](#server-side-compaction-responses-api).
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
Il traffico Azure chat e Responses richiede configurazione provider/API specifica per Azure
|
||||
oltre alla sovrascrittura dell'URL base. Se vuoi chiamate ai modelli Azure oltre alla generazione
|
||||
di immagini, usa il flusso di onboarding o una configurazione provider che imposti la
|
||||
forma API/autenticazione Azure appropriata invece di presumere che `openai.baseUrl` da solo
|
||||
sia sufficiente.
|
||||
</Note>
|
||||
|
||||
## Configurazione avanzata
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Trasporto (WebSocket vs SSE)">
|
||||
OpenClaw usa WebSocket-first con fallback SSE (`"auto"`) sia per `openai/*` sia per `openai-codex/*`.
|
||||
OpenClaw usa prima WebSocket con fallback SSE (`"auto"`) sia per `openai/*` sia per `openai-codex/*`.
|
||||
|
||||
In modalità `"auto"`, OpenClaw:
|
||||
- Riprova un errore WebSocket iniziale prima di ripiegare su SSE
|
||||
- Dopo un errore, contrassegna WebSocket come degradato per ~60 secondi e usa SSE durante il cool-down
|
||||
- Collega header stabili di identità della sessione e del turno per retry e riconnessioni
|
||||
- Normalizza i contatori di utilizzo (`input_tokens` / `prompt_tokens`) tra varianti di trasporto
|
||||
- Riprova un errore iniziale WebSocket una volta prima di passare a SSE
|
||||
- Dopo un errore, contrassegna WebSocket come degradato per ~60 secondi e usa SSE durante il periodo di raffreddamento
|
||||
- Collega header stabili di identità di sessione e turno per retry e riconnessioni
|
||||
- Normalizza i contatori di utilizzo (`input_tokens` / `prompt_tokens`) tra le varianti di trasporto
|
||||
|
||||
| Valore | Comportamento |
|
||||
|-------|----------|
|
||||
| `"auto"` (predefinito) | WebSocket prima, fallback SSE |
|
||||
| `"auto"` (predefinito) | Prima WebSocket, fallback SSE |
|
||||
| `"sse"` | Forza solo SSE |
|
||||
| `"websocket"` | Forza solo WebSocket |
|
||||
|
||||
@ -433,13 +561,13 @@ Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fa
|
||||
```
|
||||
|
||||
Documentazione OpenAI correlata:
|
||||
- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
|
||||
- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
|
||||
- [Realtime API con WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
|
||||
- [Risposte API in streaming (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Warm-up WebSocket">
|
||||
OpenClaw abilita per impostazione predefinita il warm-up WebSocket per `openai/*` per ridurre la latenza del primo turno.
|
||||
OpenClaw abilita il warm-up WebSocket per impostazione predefinita per `openai/*` per ridurre la latenza del primo turno.
|
||||
|
||||
```json5
|
||||
// Disabilita warm-up
|
||||
@ -461,12 +589,12 @@ Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fa
|
||||
<a id="openai-fast-mode"></a>
|
||||
|
||||
<Accordion title="Modalità veloce">
|
||||
OpenClaw espone un toggle condiviso della modalità veloce sia per `openai/*` sia per `openai-codex/*`:
|
||||
OpenClaw espone un interruttore condiviso della modalità veloce sia per `openai/*` sia per `openai-codex/*`:
|
||||
|
||||
- **Chat/UI:** `/fast status|on|off`
|
||||
- **Config:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
|
||||
Quando abilitata, OpenClaw mappa la modalità veloce all'elaborazione prioritaria OpenAI (`service_tier = "priority"`). I valori `service_tier` esistenti vengono preservati e la modalità veloce non riscrive `reasoning` o `text.verbosity`.
|
||||
Quando è abilitata, OpenClaw mappa la modalità veloce all'elaborazione prioritaria di OpenAI (`service_tier = "priority"`). I valori `service_tier` esistenti vengono conservati e la modalità veloce non riscrive `reasoning` o `text.verbosity`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -482,7 +610,7 @@ Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fa
|
||||
```
|
||||
|
||||
<Note>
|
||||
Gli override di sessione hanno priorità sulla config. Cancellare l'override di sessione nella UI Sessions riporta la sessione al valore predefinito configurato.
|
||||
Gli override di sessione hanno la precedenza sulla configurazione. Rimuovere l'override di sessione nell'interfaccia Sessions riporta la sessione al valore predefinito configurato.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -506,17 +634,17 @@ Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fa
|
||||
Valori supportati: `auto`, `default`, `flex`, `priority`.
|
||||
|
||||
<Warning>
|
||||
`serviceTier` viene inoltrato solo agli endpoint OpenAI nativi (`api.openai.com`) e agli endpoint Codex nativi (`chatgpt.com/backend-api`). Se instradi uno dei due provider tramite un proxy, OpenClaw lascia `service_tier` invariato.
|
||||
`serviceTier` viene inoltrato solo agli endpoint nativi OpenAI (`api.openai.com`) e agli endpoint Codex nativi (`chatgpt.com/backend-api`). Se instradi uno dei due provider tramite un proxy, OpenClaw lascia `service_tier` invariato.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Compaction lato server (Responses API)">
|
||||
Per i modelli diretti OpenAI Responses (`openai/*` su `api.openai.com`), OpenClaw abilita automaticamente la Compaction lato server:
|
||||
Per i modelli OpenAI Responses diretti (`openai/*` su `api.openai.com`), OpenClaw abilita automaticamente Compaction lato server:
|
||||
|
||||
- Forza `store: true` (a meno che la compat del modello imposti `supportsStore: false`)
|
||||
- Forza `store: true` (a meno che la compatibilità del modello imposti `supportsStore: false`)
|
||||
- Inietta `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- `compact_threshold` predefinito: 70% di `contextWindow` (oppure `80000` quando non disponibile)
|
||||
- `compact_threshold` predefinito: 70% di `contextWindow` (o `80000` quando non disponibile)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Abilita esplicitamente">
|
||||
@ -572,7 +700,7 @@ Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fa
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
`responsesServerCompaction` controlla solo l'iniezione di `context_management`. I modelli diretti OpenAI Responses continuano comunque a forzare `store: true` a meno che la compat non imposti `supportsStore: false`.
|
||||
`responsesServerCompaction` controlla solo l'iniezione di `context_management`. I modelli OpenAI Responses diretti continuano a forzare `store: true` a meno che la compatibilità non imposti `supportsStore: false`.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -591,13 +719,13 @@ Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fa
|
||||
```
|
||||
|
||||
Con `strict-agentic`, OpenClaw:
|
||||
- Non considera più un turno con solo piano come progresso riuscito quando è disponibile un'azione strumento
|
||||
- Riprova il turno con uno steer ad agire subito
|
||||
- Abilita automaticamente `update_plan` per lavori sostanziali
|
||||
- Espone uno stato esplicito di blocco se il modello continua a pianificare senza agire
|
||||
- Non considera più un turno solo di pianificazione come progresso riuscito quando è disponibile un'azione tramite strumento
|
||||
- Riprova il turno con un indirizzamento act-now
|
||||
- Abilita automaticamente `update_plan` per lavoro sostanziale
|
||||
- Mostra uno stato di blocco esplicito se il modello continua a pianificare senza agire
|
||||
|
||||
<Note>
|
||||
Limitato solo alle esecuzioni OpenAI e Codex della famiglia GPT-5. Gli altri provider e le famiglie di modelli più vecchie mantengono il comportamento predefinito.
|
||||
Limitato solo alle esecuzioni della famiglia GPT-5 di OpenAI e Codex. Gli altri provider e le famiglie di modelli meno recenti mantengono il comportamento predefinito.
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -606,17 +734,17 @@ Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fa
|
||||
OpenClaw tratta gli endpoint diretti OpenAI, Codex e Azure OpenAI in modo diverso dai proxy generici compatibili con OpenAI `/v1`:
|
||||
|
||||
**Percorsi nativi** (`openai/*`, `openai-codex/*`, Azure OpenAI):
|
||||
- Mantengono `reasoning: { effort: "none" }` solo per i modelli che supportano l'effort OpenAI `none`
|
||||
- Mantengono `reasoning: { effort: "none" }` solo per i modelli che supportano l'effort `none` di OpenAI
|
||||
- Omettono il reasoning disabilitato per modelli o proxy che rifiutano `reasoning.effort: "none"`
|
||||
- Impostano per default gli schemi degli strumenti in modalità strict
|
||||
- Impostano gli schemi degli strumenti in modalità rigorosa per impostazione predefinita
|
||||
- Allegano header di attribuzione nascosti solo su host nativi verificati
|
||||
- Mantengono la modellazione di richieste solo OpenAI (`service_tier`, `store`, reasoning-compat, hint della cache del prompt)
|
||||
- Mantengono la forma delle richieste specifica di OpenAI (`service_tier`, `store`, compatibilità reasoning, hint della cache del prompt)
|
||||
|
||||
**Percorsi proxy/compatibili:**
|
||||
- Usano un comportamento di compatibilità più permissivo
|
||||
- Non forzano schemi di strumenti strict né header solo nativi
|
||||
- Usano un comportamento compat più permissivo
|
||||
- Non forzano schemi degli strumenti rigorosi né header solo nativi
|
||||
|
||||
Azure OpenAI usa trasporto nativo e comportamento di compatibilità nativo ma non riceve gli header di attribuzione nascosti.
|
||||
Azure OpenAI usa trasporto e comportamento compat nativi ma non riceve gli header di attribuzione nascosti.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -625,7 +753,7 @@ Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fa
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Selezione del modello" href="/it/concepts/model-providers" icon="layers">
|
||||
Scelta di provider, riferimenti modello e comportamento di failover.
|
||||
Scelta dei provider, dei riferimenti di modello e del comportamento di failover.
|
||||
</Card>
|
||||
<Card title="Generazione di immagini" href="/it/tools/image-generation" icon="image">
|
||||
Parametri condivisi dello strumento immagine e selezione del provider.
|
||||
@ -634,6 +762,6 @@ Il legacy `plugins.entries.openai.config.personality` viene ancora letto come fa
|
||||
Parametri condivisi dello strumento video e selezione del provider.
|
||||
</Card>
|
||||
<Card title="OAuth e autenticazione" href="/it/gateway/authentication" icon="key">
|
||||
Dettagli di autenticazione e regole di riutilizzo delle credenziali.
|
||||
Dettagli dell'autenticazione e regole di riutilizzo delle credenziali.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
---
|
||||
read_when:
|
||||
- Esecuzione o correzione dei test
|
||||
summary: Come eseguire i test localmente (vitest) e quando usare le modalità force/coverage
|
||||
- Eseguire o correggere i test
|
||||
summary: Come eseguire i test in locale (vitest) e quando usare le modalità force/coverage
|
||||
title: Test
|
||||
x-i18n:
|
||||
generated_at: "2026-04-22T04:27:46Z"
|
||||
generated_at: "2026-04-23T13:58:55Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: ed665840ef2c7728da8ec923eb3ea2878d9b20a841cb2fe4116a7f6334567b8e
|
||||
source_hash: e0bcecb0868b3b68361e5ef78afc3170f2a481771bda8f7d54200b1d778d044a
|
||||
source_path: reference/test.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -16,35 +16,36 @@ x-i18n:
|
||||
|
||||
- Kit di test completo (suite, live, Docker): [Testing](/it/help/testing)
|
||||
|
||||
- `pnpm test:force`: termina qualsiasi processo gateway residuo che occupa la porta di controllo predefinita, quindi esegue l'intera suite Vitest con una porta gateway isolata così i test del server non entrano in conflitto con un'istanza in esecuzione. Usalo quando una precedente esecuzione del gateway ha lasciato occupata la porta 18789.
|
||||
- `pnpm test:coverage`: esegue la suite unit con coverage V8 (tramite `vitest.unit.config.ts`). Si tratta di un gate di coverage unit dei file caricati, non di coverage all-file dell'intero repository. Le soglie sono 70% per linee/funzioni/statement e 55% per i branch. Poiché `coverage.all` è false, il gate misura i file caricati dalla suite di coverage unit invece di trattare ogni file sorgente nelle lane suddivise come non coperto.
|
||||
- `pnpm test:coverage:changed`: esegue la coverage unit solo per i file modificati rispetto a `origin/main`.
|
||||
- `pnpm test:changed`: espande i percorsi git modificati in lane Vitest con ambito quando la diff tocca solo file sorgente/test instradabili. Le modifiche a config/setup usano comunque come fallback l'esecuzione nativa dei progetti root così le modifiche al wiring rieseguono in modo ampio quando necessario.
|
||||
- `pnpm changed:lanes`: mostra le lane architetturali attivate dalla diff rispetto a `origin/main`.
|
||||
- `pnpm check:changed`: esegue lo smart changed gate per la diff rispetto a `origin/main`. Esegue il lavoro core con lane di test core, il lavoro delle estensioni con lane di test delle estensioni, il lavoro solo test solo con typecheck/test dei test, espande le modifiche all'SDK Plugin pubblico o al contratto plugin verso la validazione delle estensioni e mantiene i version bump solo di metadati release su controlli mirati di versione/config/dipendenze root.
|
||||
- `pnpm test`: instrada target espliciti file/directory attraverso lane Vitest con ambito. Le esecuzioni senza target usano gruppi di shard fissi e si espandono in config leaf per l'esecuzione parallela locale; il gruppo extension si espande sempre nelle config shard per-estensione invece che in un unico gigantesco processo root-project.
|
||||
- Le esecuzioni complete e quelle shard delle estensioni aggiornano i dati locali di timing in `.artifacts/vitest-shard-timings.json`; le esecuzioni successive usano quei timing per bilanciare shard lenti e veloci. Imposta `OPENCLAW_TEST_PROJECTS_TIMINGS=0` per ignorare l'artifact di timing locale.
|
||||
- Alcuni file di test `plugin-sdk` e `commands` selezionati ora vengono instradati tramite lane leggere dedicate che mantengono solo `test/setup.ts`, lasciando i casi pesanti a runtime sulle lane esistenti.
|
||||
- Alcuni file sorgente helper `plugin-sdk` e `commands` selezionati mappano anche `pnpm test:changed` a test sibling espliciti in quelle lane leggere, così piccole modifiche agli helper evitano di rieseguire le suite pesanti supportate dal runtime.
|
||||
- `auto-reply` ora si divide anch'esso in tre config dedicate (`core`, `top-level`, `reply`) così l'harness reply non domina i test più leggeri top-level di stato/token/helper.
|
||||
- La config base Vitest ora usa per impostazione predefinita `pool: "threads"` e `isolate: false`, con il runner condiviso non isolato abilitato in tutte le config del repo.
|
||||
- `pnpm test:force`: termina qualsiasi processo gateway residuo che mantiene occupata la porta di controllo predefinita, quindi esegue l'intera suite Vitest con una porta gateway isolata così i test del server non entrano in collisione con un'istanza in esecuzione. Usalo quando una precedente esecuzione del gateway ha lasciato occupata la porta 18789.
|
||||
- `pnpm test:coverage`: esegue la suite unit con copertura V8 (tramite `vitest.unit.config.ts`). Questo è un gate di copertura unit dei file caricati, non una copertura di tutti i file dell'intero repository. Le soglie sono 70% righe/funzioni/statement e 55% branch. Poiché `coverage.all` è false, il gate misura i file caricati dalla suite di copertura unit invece di trattare ogni file sorgente delle corsie suddivise come non coperto.
|
||||
- `pnpm test:coverage:changed`: esegue la copertura unit solo per i file modificati rispetto a `origin/main`.
|
||||
- `pnpm test:changed`: espande i percorsi git modificati in corsie Vitest con scope quando la diff tocca solo file sorgente/test instradabili. Le modifiche a config/setup continuano invece a ripiegare sull'esecuzione nativa dei progetti root così le modifiche di wiring rilanciano in modo ampio quando necessario.
|
||||
- `pnpm changed:lanes`: mostra le corsie architetturali attivate dalla diff rispetto a `origin/main`.
|
||||
- `pnpm check:changed`: esegue il gate intelligente dei file modificati per la diff rispetto a `origin/main`. Esegue il lavoro core con le corsie di test core, il lavoro delle extension con le corsie di test delle extension, il lavoro solo test con solo typecheck/test dei test, estende le modifiche pubbliche al Plugin SDK o al contratto dei plugin alla validazione delle extension e mantiene i version bump che toccano solo i metadati di release su controlli mirati di versione/config/dipendenze root.
|
||||
- `pnpm test`: instrada target espliciti file/directory tramite corsie Vitest con scope. Le esecuzioni senza target usano gruppi di shard fissi ed espandono a config foglia per l'esecuzione parallela locale; il gruppo extension si espande sempre nelle config shard per-extension invece che in un unico enorme processo root-project.
|
||||
- Le esecuzioni complete e degli shard delle extension aggiornano i dati locali di timing in `.artifacts/vitest-shard-timings.json`; le esecuzioni successive usano quei timing per bilanciare shard lenti e veloci. Imposta `OPENCLAW_TEST_PROJECTS_TIMINGS=0` per ignorare l'artifact locale dei timing.
|
||||
- Alcuni file di test `plugin-sdk` e `commands` ora vengono instradati tramite corsie leggere dedicate che mantengono solo `test/setup.ts`, lasciando i casi con runtime pesante nelle loro corsie esistenti.
|
||||
- Anche alcuni file sorgente helper di `plugin-sdk` e `commands` mappano `pnpm test:changed` verso test sibling espliciti in quelle corsie leggere, così piccole modifiche agli helper evitano di rieseguire le suite pesanti supportate dal runtime.
|
||||
- `auto-reply` ora è suddiviso anche in tre config dedicate (`core`, `top-level`, `reply`) così l'harness delle reply non domina i test più leggeri di stato/token/helper di livello superiore.
|
||||
- La config base di Vitest ora usa per impostazione predefinita `pool: "threads"` e `isolate: false`, con il runner condiviso non isolato abilitato in tutte le config del repository.
|
||||
- `pnpm test:channels` esegue `vitest.channels.config.ts`.
|
||||
- `pnpm test:extensions` e `pnpm test extensions` eseguono tutti gli shard extension/plugin. Le estensioni di canale pesanti e OpenAI vengono eseguite come shard dedicati; gli altri gruppi di estensioni restano raggruppati. Usa `pnpm test extensions/<id>` per una singola lane di Plugin bundled.
|
||||
- `pnpm test:perf:imports`: abilita la reportistica Vitest sulla durata degli import + breakdown degli import, continuando però a usare il routing lane con ambito per target espliciti file/directory.
|
||||
- `pnpm test:extensions` e `pnpm test extensions` eseguono tutti gli shard delle extension/plugin. Le extension di canale pesanti e OpenAI vengono eseguite come shard dedicati; gli altri gruppi di extension restano batchati. Usa `pnpm test extensions/<id>` per una singola corsia di plugin incluso.
|
||||
- `pnpm test:perf:imports`: abilita il reporting della durata degli import + breakdown degli import di Vitest, continuando a usare l'instradamento per corsie con scope per target espliciti file/directory.
|
||||
- `pnpm test:perf:imports:changed`: stesso profiling degli import, ma solo per i file modificati rispetto a `origin/main`.
|
||||
- `pnpm test:perf:changed:bench -- --ref <git-ref>` misura il percorso changed-mode instradato rispetto all'esecuzione nativa root-project per la stessa diff git salvata.
|
||||
- `pnpm test:perf:changed:bench -- --worktree` misura l'insieme di modifiche del worktree corrente senza prima fare commit.
|
||||
- `pnpm test:perf:changed:bench -- --ref <git-ref>` misura il percorso instradato in modalità changed rispetto all'esecuzione nativa dei progetti root per la stessa diff git già commitata.
|
||||
- `pnpm test:perf:changed:bench -- --worktree` misura l'attuale insieme di modifiche del worktree senza fare prima commit.
|
||||
- `pnpm test:perf:profile:main`: scrive un profilo CPU per il thread principale di Vitest (`.artifacts/vitest-main-profile`).
|
||||
- `pnpm test:perf:profile:runner`: scrive profili CPU + heap per il runner unit (`.artifacts/vitest-runner-profile`).
|
||||
- Integrazione Gateway: opt-in tramite `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` oppure `pnpm test:gateway`.
|
||||
- `pnpm test:e2e`: esegue test smoke end-to-end del gateway (pairing multiistanza WS/HTTP/node). Per impostazione predefinita usa `threads` + `isolate: false` con worker adattivi in `vitest.e2e.config.ts`; regola con `OPENCLAW_E2E_WORKERS=<n>` e imposta `OPENCLAW_E2E_VERBOSE=1` per log verbosi.
|
||||
- `pnpm test:live`: esegue test live del provider (minimax/zai). Richiede API key e `LIVE=1` (o `*_LIVE_TEST=1` specifico del provider) per togliere lo skip.
|
||||
- `pnpm test:docker:openwebui`: avvia OpenClaw + Open WebUI in Docker, effettua l'accesso tramite Open WebUI, controlla `/api/models`, quindi esegue una vera chat proxied tramite `/api/chat/completions`. Richiede una chiave di modello live utilizzabile (per esempio OpenAI in `~/.profile`), scarica un'immagine esterna Open WebUI e non è previsto che sia stabile in CI come le normali suite unit/e2e.
|
||||
- `pnpm test:docker:mcp-channels`: avvia un container Gateway inizializzato e un secondo container client che avvia `openclaw mcp serve`, quindi verifica discovery della conversazione instradata, letture del transcript, metadati degli allegati, comportamento della coda eventi live, instradamento dell'invio outbound e notifiche stile Claude di canale + permessi sul vero bridge stdio. L'asserzione sulla notifica Claude legge direttamente i frame MCP stdio grezzi così lo smoke riflette ciò che il bridge emette realmente.
|
||||
- Integrazione Gateway: opt-in tramite `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` o `pnpm test:gateway`.
|
||||
- `pnpm test:e2e`: esegue smoke test end-to-end del gateway (pairing multiistanza WS/HTTP/node). Usa per impostazione predefinita `threads` + `isolate: false` con worker adattivi in `vitest.e2e.config.ts`; regola con `OPENCLAW_E2E_WORKERS=<n>` e imposta `OPENCLAW_E2E_VERBOSE=1` per log verbosi.
|
||||
- `pnpm test:live`: esegue test live del provider (minimax/zai). Richiede chiavi API e `LIVE=1` (o `*_LIVE_TEST=1` specifico del provider) per non saltarli.
|
||||
- `pnpm test:docker:all`: compila una sola volta l'immagine condivisa dei test live e l'immagine Docker E2E, quindi esegue le corsie smoke Docker con `OPENCLAW_SKIP_DOCKER_BUILD=1` e concorrenza 4 per impostazione predefinita. Regola con `OPENCLAW_DOCKER_ALL_PARALLELISM=<n>`. Il runner smette di pianificare nuove corsie nel pool dopo il primo errore, a meno che non sia impostato `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, e ogni corsia ha un timeout di 120 minuti sovrascrivibile con `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Le corsie sensibili all'avvio o al provider vengono eseguite in esclusiva dopo il pool parallelo. I log per corsia vengono scritti in `.artifacts/docker-tests/<run-id>/`.
|
||||
- `pnpm test:docker:openwebui`: avvia OpenClaw + Open WebUI in Docker, effettua il login tramite Open WebUI, controlla `/api/models`, quindi esegue una vera chat proxata tramite `/api/chat/completions`. Richiede una chiave di modello live utilizzabile (per esempio OpenAI in `~/.profile`), scarica un'immagine Open WebUI esterna e non è pensato per essere stabile in CI come le normali suite unit/e2e.
|
||||
- `pnpm test:docker:mcp-channels`: avvia un container Gateway inizializzato e un secondo container client che avvia `openclaw mcp serve`, quindi verifica discovery delle conversazioni instradate, letture della trascrizione, metadati degli allegati, comportamento live della coda eventi, instradamento dell'invio in uscita e notifiche in stile Claude di canale + permessi sul vero bridge stdio. L'asserzione sulle notifiche Claude legge direttamente i frame MCP stdio grezzi così lo smoke riflette ciò che il bridge emette davvero.
|
||||
|
||||
## Gate PR locale
|
||||
|
||||
Per controlli locali di land/gate della PR, esegui:
|
||||
Per i controlli locali di land/gate PR, esegui:
|
||||
|
||||
- `pnpm check:changed`
|
||||
- `pnpm check`
|
||||
@ -53,7 +54,7 @@ Per controlli locali di land/gate della PR, esegui:
|
||||
- `pnpm test`
|
||||
- `pnpm check:docs`
|
||||
|
||||
Se `pnpm test` flappa su un host carico, rieseguilo una volta prima di trattarlo come regressione, poi isola con `pnpm test <path/to/test>`. Per host con memoria limitata, usa:
|
||||
Se `pnpm test` è flaky su un host sotto carico, rieseguilo una volta prima di trattarlo come una regressione, poi isola con `pnpm test <path/to/test>`. Per host con memoria limitata, usa:
|
||||
|
||||
- `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test`
|
||||
- `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed`
|
||||
@ -65,15 +66,15 @@ Script: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/mai
|
||||
Uso:
|
||||
|
||||
- `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10`
|
||||
- Env facoltative: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
|
||||
- Prompt predefinito: “Reply with a single word: ok. No punctuation or extra text.”
|
||||
- Env opzionali: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY`
|
||||
- Prompt predefinito: “Rispondi con una sola parola: ok. Nessuna punteggiatura o testo aggiuntivo.”
|
||||
|
||||
Ultima esecuzione (2025-12-31, 20 esecuzioni):
|
||||
|
||||
- median minimax 1279ms (min 1114, max 2431)
|
||||
- median opus 2454ms (min 1224, max 3170)
|
||||
- minimax mediana 1279ms (min 1114, max 2431)
|
||||
- opus mediana 2454ms (min 1224, max 3170)
|
||||
|
||||
## Benchmark dell'avvio CLI
|
||||
## Benchmark di avvio CLI
|
||||
|
||||
Script: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts)
|
||||
|
||||
@ -100,35 +101,35 @@ Preset:
|
||||
- `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port`
|
||||
- `all`: entrambi i preset
|
||||
|
||||
L'output include `sampleCount`, avg, p50, p95, min/max, distribuzione di exit-code/signal e riepiloghi max RSS per ogni comando. `--cpu-prof-dir` / `--heap-prof-dir` facoltativi scrivono profili V8 per esecuzione così timing e acquisizione profili usano lo stesso harness.
|
||||
L'output include `sampleCount`, avg, p50, p95, min/max, distribuzione di exit-code/signal e riepiloghi max RSS per ogni comando. `--cpu-prof-dir` / `--heap-prof-dir` opzionali scrivono profili V8 per esecuzione così timing e acquisizione del profilo usano lo stesso harness.
|
||||
|
||||
Convenzioni per gli output salvati:
|
||||
Convenzioni per l'output salvato:
|
||||
|
||||
- `pnpm test:startup:bench:smoke` scrive l'artifact smoke mirato in `.artifacts/cli-startup-bench-smoke.json`
|
||||
- `pnpm test:startup:bench:save` scrive l'artifact della suite completa in `.artifacts/cli-startup-bench-all.json` usando `runs=5` e `warmup=1`
|
||||
- `pnpm test:startup:bench:update` aggiorna il fixture baseline versionato in `test/fixtures/cli-startup-bench.json` usando `runs=5` e `warmup=1`
|
||||
- `pnpm test:startup:bench:update` aggiorna la baseline fixture versionata in `test/fixtures/cli-startup-bench.json` usando `runs=5` e `warmup=1`
|
||||
|
||||
Fixture versionato:
|
||||
Fixture versionata:
|
||||
|
||||
- `test/fixtures/cli-startup-bench.json`
|
||||
- Aggiorna con `pnpm test:startup:bench:update`
|
||||
- Confronta i risultati correnti con il fixture tramite `pnpm test:startup:bench:check`
|
||||
- Confronta i risultati correnti con la fixture usando `pnpm test:startup:bench:check`
|
||||
|
||||
## Onboarding E2E (Docker)
|
||||
|
||||
Docker è facoltativo; serve solo per i test smoke di onboarding containerizzati.
|
||||
Docker è opzionale; questo serve solo per gli smoke test di onboarding containerizzati.
|
||||
|
||||
Flusso completo cold-start in un container Linux pulito:
|
||||
Flusso completo da avvio a freddo in un container Linux pulito:
|
||||
|
||||
```bash
|
||||
scripts/e2e/onboard-docker.sh
|
||||
```
|
||||
|
||||
Questo script guida la procedura guidata interattiva tramite pseudo-tty, verifica i file di config/workspace/sessione, quindi avvia il gateway ed esegue `openclaw health`.
|
||||
Questo script guida la procedura guidata interattiva tramite uno pseudo-tty, verifica i file di config/workspace/session, quindi avvia il gateway ed esegue `openclaw health`.
|
||||
|
||||
## Smoke di import QR (Docker)
|
||||
|
||||
Garantisce che `qrcode-terminal` venga caricato nei runtime Docker Node supportati (Node 24 predefinito, Node 22 compatibile):
|
||||
Garantisce che `qrcode-terminal` si carichi sotto i runtime Docker Node supportati (Node 24 predefinito, Node 22 compatibile):
|
||||
|
||||
```bash
|
||||
pnpm test:docker:qr
|
||||
|
||||
@ -1,31 +1,31 @@
|
||||
---
|
||||
read_when:
|
||||
- Generazione di immagini tramite l’agente
|
||||
- Configurazione di provider e modelli per la generazione di immagini
|
||||
- Generazione di immagini tramite l'agente
|
||||
- Configurazione dei provider e dei modelli per la generazione di immagini
|
||||
- Comprendere i parametri dello strumento `image_generate`
|
||||
summary: Genera e modifica immagini usando i provider configurati (OpenAI, Google Gemini, fal, MiniMax, ComfyUI, Vydra, xAI)
|
||||
title: Generazione immagini
|
||||
title: Generazione di immagini
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T08:36:58Z"
|
||||
generated_at: "2026-04-23T13:59:29Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 228049c74dd3437544cda6418da665aed375c0494ef36a6927d15c28d7783bbd
|
||||
source_hash: 0fbd8eda2cb0867d1426b9349f6778c231051d600ebe451534efbee0e215c871
|
||||
source_path: tools/image-generation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Generazione immagini
|
||||
# Generazione di immagini
|
||||
|
||||
Lo strumento `image_generate` consente all’agente di creare e modificare immagini usando i provider configurati. Le immagini generate vengono consegnate automaticamente come allegati media nella risposta dell’agente.
|
||||
Lo strumento `image_generate` consente all'agente di creare e modificare immagini usando i provider configurati. Le immagini generate vengono consegnate automaticamente come allegati multimediali nella risposta dell'agente.
|
||||
|
||||
<Note>
|
||||
Lo strumento compare solo quando è disponibile almeno un provider di generazione immagini. Se non vedi `image_generate` tra gli strumenti del tuo agente, configura `agents.defaults.imageGenerationModel` oppure imposta una chiave API provider.
|
||||
Lo strumento compare solo quando è disponibile almeno un provider di generazione di immagini. Se non vedi `image_generate` negli strumenti del tuo agente, configura `agents.defaults.imageGenerationModel` oppure imposta una chiave API del 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
|
||||
{
|
||||
@ -39,9 +39,9 @@ Lo strumento compare solo quando è disponibile almeno un provider di generazion
|
||||
}
|
||||
```
|
||||
|
||||
3. Chiedi all’agente: _"Genera un’immagine di una simpatica mascotte aragosta."_
|
||||
3. Chiedi all'agente: _"Genera un'immagine di una mascotte aragosta amichevole."_
|
||||
|
||||
L’agente chiama automaticamente `image_generate`. Non serve alcuna allowlist dello strumento: è abilitato per impostazione predefinita quando un provider è disponibile.
|
||||
L'agente chiama automaticamente `image_generate`. Non è necessario alcun elenco di autorizzazione degli strumenti: è abilitato per impostazione predefinita quando è disponibile un provider.
|
||||
|
||||
## Provider supportati
|
||||
|
||||
@ -50,12 +50,12 @@ L’agente chiama automaticamente `image_generate`. Non serve alcuna allowlist d
|
||||
| OpenAI | `gpt-image-2` | 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 MiniMax OAuth (`minimax-portal`) |
|
||||
| ComfyUI | `workflow` | Sì (1 immagine, configurata dal workflow) | `COMFY_API_KEY` o `COMFY_CLOUD_API_KEY` per il cloud |
|
||||
| MiniMax | `image-01` | Sì (riferimento del 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` |
|
||||
| xAI | `grok-imagine-image` | Sì (fino a 5 immagini) | `XAI_API_KEY` |
|
||||
|
||||
Usa `action: "list"` per ispezionare provider e modelli disponibili a runtime:
|
||||
Usa `action: "list"` per ispezionare i provider e i modelli disponibili in fase di esecuzione:
|
||||
|
||||
```
|
||||
/tool image_generate action=list
|
||||
@ -63,22 +63,22 @@ Usa `action: "list"` per ispezionare provider e modelli disponibili a runtime:
|
||||
|
||||
## Parametri dello strumento
|
||||
|
||||
| Parametro | Tipo | Descrizione |
|
||||
| ------------- | -------- | ----------------------------------------------------------------------------------- |
|
||||
| `prompt` | string | Prompt per la generazione dell’immagine (obbligatorio per `action: "generate"`) |
|
||||
| `action` | string | `"generate"` (predefinito) oppure `"list"` per ispezionare i provider |
|
||||
| `model` | string | Override provider/modello, ad esempio `openai/gpt-image-2` |
|
||||
| `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 | Hint di dimensione: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160` |
|
||||
| `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 | Hint di risoluzione: `1K`, `2K` o `4K` |
|
||||
| `count` | number | Numero di immagini da generare (1–4) |
|
||||
| `filename` | string | Hint del nome file in uscita |
|
||||
| Parametro | Tipo | Descrizione |
|
||||
| ------------- | -------- | ------------------------------------------------------------------------------------ |
|
||||
| `prompt` | string | Prompt per la generazione di immagini (obbligatorio per `action: "generate"`) |
|
||||
| `action` | string | `"generate"` (predefinito) oppure `"list"` per ispezionare i provider |
|
||||
| `model` | string | Override provider/modello, ad esempio `openai/gpt-image-2` |
|
||||
| `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 | Suggerimento dimensione: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160` |
|
||||
| `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 | Suggerimento risoluzione: `1K`, `2K` o `4K` |
|
||||
| `count` | number | Numero di immagini da generare (1–4) |
|
||||
| `filename` | string | Suggerimento per il nome del file di output |
|
||||
|
||||
Non tutti i provider supportano tutti i parametri. Quando un provider di fallback supporta un’opzione geometrica vicina invece di quella richiesta esatta, OpenClaw rimappa alla dimensione, al rapporto d’aspetto o alla risoluzione supportata più vicina prima dell’invio. Gli override realmente non supportati vengono comunque segnalati nel risultato dello strumento.
|
||||
Non tutti i provider supportano tutti i parametri. Quando un provider di fallback supporta un'opzione di geometria vicina invece di quella richiesta esatta, OpenClaw la rimappa alla dimensione, al rapporto d'aspetto o alla risoluzione supportati più vicini prima dell'invio. Gli override realmente non supportati vengono comunque riportati nel risultato dello strumento.
|
||||
|
||||
I risultati dello strumento riportano le impostazioni applicate. Quando OpenClaw rimappa la geometria durante il fallback del provider, i valori restituiti `size`, `aspectRatio` e `resolution` riflettono quanto è stato effettivamente inviato, e `details.normalization` cattura la traduzione da richiesto ad applicato.
|
||||
I risultati dello strumento riportano le impostazioni applicate. Quando OpenClaw rimappa la geometria durante il fallback del provider, i valori restituiti `size`, `aspectRatio` e `resolution` riflettono ciò che è stato effettivamente inviato, e `details.normalization` acquisisce la traduzione da richiesto ad applicato.
|
||||
|
||||
## Configurazione
|
||||
|
||||
@ -99,28 +99,26 @@ I risultati dello strumento riportano le impostazioni applicate. Quando OpenClaw
|
||||
|
||||
### Ordine di selezione del provider
|
||||
|
||||
Quando genera un’immagine, OpenClaw prova i provider in questo ordine:
|
||||
Quando genera un'immagine, OpenClaw prova i provider in questo ordine:
|
||||
|
||||
1. **Parametro `model`** dalla chiamata dello strumento (se l’agente ne specifica uno)
|
||||
1. Il parametro **`model`** della chiamata dello strumento (se l'agente ne specifica uno)
|
||||
2. **`imageGenerationModel.primary`** dalla configurazione
|
||||
3. **`imageGenerationModel.fallbacks`** in ordine
|
||||
4. **Rilevamento automatico** — usa solo i valori predefiniti del 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 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.), viene provato automaticamente il candidato successivo. Se falliscono tutti, l’errore include dettagli di ogni tentativo.
|
||||
Se un provider fallisce, ad esempio per errore di autenticazione o rate limit, il candidato successivo viene provato automaticamente. Se falliscono tutti, l'errore include i dettagli di ogni tentativo.
|
||||
|
||||
Note:
|
||||
|
||||
- Il rilevamento automatico è consapevole dell’autenticazione. Un valore predefinito del provider entra nell’elenco dei candidati solo quando OpenClaw può davvero autenticare quel provider.
|
||||
- Il rilevamento automatico è abilitato per impostazione predefinita. Imposta
|
||||
`agents.defaults.mediaGenerationAutoProviderFallback: false` se vuoi che la generazione immagini usi solo le voci esplicite `model`, `primary` e `fallbacks`.
|
||||
- Usa `action: "list"` per ispezionare i provider attualmente registrati, i loro
|
||||
modelli predefiniti e gli hint delle env var di autenticazione.
|
||||
- Il rilevamento automatico è consapevole dell'autenticazione. Un provider predefinito entra nell'elenco dei candidati solo quando OpenClaw può effettivamente autenticare quel provider.
|
||||
- Il rilevamento automatico è abilitato per impostazione predefinita. Imposta `agents.defaults.mediaGenerationAutoProviderFallback: false` se vuoi che la generazione di immagini usi solo le voci esplicite `model`, `primary` e `fallbacks`.
|
||||
- Usa `action: "list"` per ispezionare i provider attualmente registrati, i loro modelli predefiniti e i suggerimenti delle variabili d'ambiente per l'autenticazione.
|
||||
|
||||
### Modifica delle immagini
|
||||
|
||||
OpenAI, Google, fal, MiniMax, ComfyUI e xAI supportano la modifica di immagini di riferimento. Passa un percorso immagine di riferimento o un URL:
|
||||
OpenAI, Google, fal, MiniMax, ComfyUI e xAI supportano la modifica di immagini di riferimento. Passa un percorso o URL di immagine di riferimento:
|
||||
|
||||
```
|
||||
"Genera una versione ad acquerello di questa foto" + image: "/path/to/photo.jpg"
|
||||
@ -130,79 +128,84 @@ OpenAI, Google e xAI supportano fino a 5 immagini di riferimento tramite il para
|
||||
|
||||
### OpenAI `gpt-image-2`
|
||||
|
||||
La generazione immagini OpenAI usa per impostazione predefinita `openai/gpt-image-2`. Il vecchio
|
||||
La generazione di immagini OpenAI usa per impostazione predefinita `openai/gpt-image-2`. Il vecchio
|
||||
modello `openai/gpt-image-1` può ancora essere selezionato esplicitamente, ma le nuove richieste OpenAI
|
||||
di generazione e modifica immagini dovrebbero usare `gpt-image-2`.
|
||||
di generazione e modifica di immagini dovrebbero usare `gpt-image-2`.
|
||||
|
||||
`gpt-image-2` supporta sia la generazione da testo a immagine sia la modifica di immagini di riferimento tramite lo stesso strumento `image_generate`. OpenClaw inoltra a OpenAI `prompt`,
|
||||
`count`, `size` e immagini di riferimento. OpenAI non riceve
|
||||
direttamente `aspectRatio` o `resolution`; quando possibile OpenClaw li mappa in una
|
||||
`size` supportata, altrimenti lo strumento li segnala come override ignorati.
|
||||
`gpt-image-2` supporta sia la generazione text-to-image sia la
|
||||
modifica di immagini di riferimento tramite lo stesso strumento `image_generate`. OpenClaw inoltra `prompt`,
|
||||
`count`, `size` e le immagini di riferimento a OpenAI. OpenAI non riceve
|
||||
direttamente `aspectRatio` o `resolution`; quando possibile OpenClaw li mappa a una
|
||||
`size` supportata, altrimenti lo strumento li riporta come override ignorati.
|
||||
|
||||
Genera un’immagine panoramica 4K:
|
||||
Genera un'immagine orizzontale 4K:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Un poster editoriale pulito per la generazione di immagini di OpenClaw" size=3840x2160 count=1
|
||||
```
|
||||
|
||||
Genera due immagini quadrate:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Due direzioni visive per l'icona di un'app di produttività calma" size=1024x1024 count=2
|
||||
```
|
||||
|
||||
Modifica un’immagine di riferimento locale:
|
||||
Modifica un'immagine di riferimento locale:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Mantieni il soggetto, sostituisci lo sfondo con un set da studio luminoso" image=/path/to/reference.png size=1024x1536
|
||||
```
|
||||
|
||||
Modifica con più riferimenti:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combina l'identità del personaggio della prima immagine con la tavolozza colori della seconda" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024
|
||||
```
|
||||
|
||||
La generazione immagini MiniMax è disponibile tramite entrambi i percorsi di autenticazione MiniMax bundled:
|
||||
Per instradare la generazione di immagini OpenAI tramite una distribuzione Azure OpenAI
|
||||
invece di `api.openai.com`, vedi [Endpoint Azure OpenAI](/it/providers/openai#azure-openai-endpoints)
|
||||
nella documentazione del provider OpenAI.
|
||||
|
||||
- `minimax/image-01` per setup con chiave API
|
||||
- `minimax-portal/image-01` per setup OAuth
|
||||
La generazione di immagini MiniMax è disponibile tramite entrambi i percorsi di autenticazione MiniMax inclusi:
|
||||
|
||||
## Capability del provider
|
||||
- `minimax/image-01` per configurazioni con chiave API
|
||||
- `minimax-portal/image-01` per configurazioni OAuth
|
||||
|
||||
| Capability | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
|
||||
## Capacità dei provider
|
||||
|
||||
| Capacità | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
|
||||
| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- |
|
||||
| Generazione | Sì (fino a 4) | Sì (fino a 4) | Sì (fino a 4) | Sì (fino a 9) | Sì (output definiti dal workflow) | Sì (1) | Sì (fino a 4) |
|
||||
| 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 | Sì (fino a 5 immagini) |
|
||||
| Modifica/riferimento | Sì (fino a 5 immagini) | Sì (fino a 5 immagini) | Sì (1 immagine) | Sì (1 immagine, riferimento del soggetto) | Sì (1 immagine, configurata tramite workflow) | No | Sì (fino a 5 immagini) |
|
||||
| Controllo dimensione | Sì (fino a 4K) | Sì | Sì | No | No | No | No |
|
||||
| Rapporto d’aspetto | No | Sì | Sì (solo generazione) | Sì | No | No | Sì |
|
||||
| Rapporto d'aspetto | No | Sì | Sì (solo generazione) | Sì | No | No | Sì |
|
||||
| Risoluzione (1K/2K/4K) | No | Sì | Sì | No | No | No | Sì (1K/2K) |
|
||||
|
||||
### xAI `grok-imagine-image`
|
||||
|
||||
Il provider xAI bundled usa `/v1/images/generations` per richieste solo prompt
|
||||
Il provider xAI incluso usa `/v1/images/generations` per richieste solo prompt
|
||||
e `/v1/images/edits` quando è presente `image` o `images`.
|
||||
|
||||
- Modelli: `xai/grok-imagine-image`, `xai/grok-imagine-image-pro`
|
||||
- Count: fino a 4
|
||||
- Riferimenti: un `image` o fino a cinque `images`
|
||||
- Rapporti d’aspetto: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`
|
||||
- Quantità: fino a 4
|
||||
- Riferimenti: un `image` oppure fino a cinque `images`
|
||||
- Rapporti d'aspetto: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`
|
||||
- Risoluzioni: `1K`, `2K`
|
||||
- Output: restituiti come allegati immagine gestiti da OpenClaw
|
||||
|
||||
OpenClaw intenzionalmente non espone `quality`, `mask`, `user` nativi xAI o
|
||||
rapporti d’aspetto extra solo nativi finché questi controlli non esistono nel contratto condiviso
|
||||
cross-provider `image_generate`.
|
||||
OpenClaw intenzionalmente non espone `quality`, `mask`, `user` nativi di xAI o
|
||||
rapporti d'aspetto aggiuntivi disponibili solo nativamente finché tali controlli non esistono nel
|
||||
contratto condiviso cross-provider `image_generate`.
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Tools Overview](/it/tools) — tutti gli strumenti agent disponibili
|
||||
- [fal](/it/providers/fal) — configurazione del provider immagini e video fal
|
||||
- [ComfyUI](/it/providers/comfy) — configurazione del workflow ComfyUI locale e Comfy Cloud
|
||||
- [Panoramica degli strumenti](/it/tools) — tutti gli strumenti disponibili dell'agente
|
||||
- [fal](/it/providers/fal) — configurazione del provider fal per immagini e video
|
||||
- [ComfyUI](/it/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
|
||||
- [OpenAI](/it/providers/openai) — configurazione del provider OpenAI Images
|
||||
- [Vydra](/it/providers/vydra) — configurazione Vydra per immagini, video e speech
|
||||
- [xAI](/it/providers/xai) — configurazione Grok per immagini, video, search, esecuzione di codice e TTS
|
||||
- [Configuration Reference](/it/gateway/configuration-reference#agent-defaults) — configurazione `imageGenerationModel`
|
||||
- [Models](/it/concepts/models) — configurazione del modello e failover
|
||||
- [Vydra](/it/providers/vydra) — configurazione Vydra per immagini, video e voce
|
||||
- [xAI](/it/providers/xai) — configurazione Grok per immagini, video, ricerca, esecuzione di codice e TTS
|
||||
- [Riferimento della configurazione](/it/gateway/configuration-reference#agent-defaults) — configurazione `imageGenerationModel`
|
||||
- [Modelli](/it/concepts/models) — configurazione dei modelli e failover
|
||||
|
||||
@ -1,27 +1,27 @@
|
||||
---
|
||||
read_when:
|
||||
- Installazione o configurazione dei plugin
|
||||
- Comprendere le regole di discovery e caricamento dei plugin
|
||||
- Comprendere il rilevamento dei plugin e le regole di caricamento
|
||||
- Lavorare con bundle di plugin compatibili con Codex/Claude
|
||||
sidebarTitle: Install and Configure
|
||||
summary: Installa, configura e gestisci i plugin OpenClaw
|
||||
title: Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T08:37:41Z"
|
||||
generated_at: "2026-04-23T14:00:01Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: dc944b53654552ca5cf6132c6ef16c71745a7bffc249daccaee40c513e04209c
|
||||
source_hash: 63aa1b5ed9e3aaa2117b78137a457582b00ea47d94af7da3780ddae38e8e3665
|
||||
source_path: tools/plugin.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Plugin
|
||||
|
||||
I plugin estendono OpenClaw con nuove capability: canali, provider di modelli,
|
||||
strumenti, Skills, speech, trascrizione realtime, voce realtime,
|
||||
media-understanding, generazione immagini, generazione video, web fetch, web
|
||||
search e altro ancora. Alcuni plugin sono **core** (distribuiti con OpenClaw), altri
|
||||
sono **external** (pubblicati su npm dalla community).
|
||||
I plugin estendono OpenClaw con nuove capacità: canali, provider di modelli,
|
||||
strumenti, Skills, voce, trascrizione in tempo reale, voce in tempo reale,
|
||||
comprensione dei media, generazione di immagini, generazione di video, recupero web, ricerca sul web
|
||||
e altro ancora. Alcuni plugin sono **core** (forniti con OpenClaw), altri
|
||||
sono **esterni** (pubblicati su npm dalla community).
|
||||
|
||||
## Avvio rapido
|
||||
|
||||
@ -49,12 +49,12 @@ sono **external** (pubblicati su npm dalla community).
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Poi configura in `plugins.entries.\<id\>.config` nel tuo file di configurazione.
|
||||
Quindi configura in `plugins.entries.\<id\>.config` nel tuo file di configurazione.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Se preferisci il controllo nativo via chat, abilita `commands.plugins: true` e usa:
|
||||
Se preferisci il controllo nativo in chat, abilita `commands.plugins: true` e usa:
|
||||
|
||||
```text
|
||||
/plugin install clawhub:@openclaw/voice-call
|
||||
@ -62,48 +62,48 @@ Se preferisci il controllo nativo via chat, abilita `commands.plugins: true` e u
|
||||
/plugin enable voice-call
|
||||
```
|
||||
|
||||
Il percorso di installazione usa lo stesso resolver della CLI: percorso/archivio locale, `clawhub:<pkg>` esplicito oppure package spec bare (prima ClawHub, poi fallback npm).
|
||||
Il percorso di installazione usa lo stesso resolver della CLI: percorso/archivio locale, `clawhub:<pkg>` esplicito oppure specifica di pacchetto bare (prima ClawHub, poi fallback a npm).
|
||||
|
||||
Se la configurazione non è valida, normalmente l’installazione fallisce in fail-closed e ti indirizza a
|
||||
`openclaw doctor --fix`. L’unica eccezione di recupero è uno stretto percorso di reinstallazione di plugin bundled
|
||||
per i plugin che scelgono esplicitamente
|
||||
Se la configurazione non è valida, l'installazione normalmente fallisce in modo sicuro e ti indirizza a
|
||||
`openclaw doctor --fix`. L'unica eccezione di ripristino è un percorso ristretto di
|
||||
reinstallazione di plugin integrati per i plugin che aderiscono a
|
||||
`openclaw.install.allowInvalidConfigRecovery`.
|
||||
|
||||
Le installazioni pacchettizzate di OpenClaw non installano eager l’intero
|
||||
albero delle dipendenze runtime di ogni plugin bundled. Quando un plugin OpenClaw-owned bundled è attivo dalla
|
||||
configurazione del plugin, dalla configurazione legacy del canale o da un manifest abilitato per impostazione predefinita, l’avvio
|
||||
ripara solo le dipendenze runtime dichiarate di quel plugin prima di importarlo.
|
||||
I plugin external e i percorsi di caricamento personalizzati devono comunque essere installati tramite
|
||||
Le installazioni pacchettizzate di OpenClaw non installano in modo eager l'intero
|
||||
albero delle dipendenze runtime di ogni plugin integrato. Quando un plugin integrato di proprietà OpenClaw è attivo dalla
|
||||
configurazione plugin, dalla configurazione legacy del canale o da un manifest abilitato per impostazione predefinita, all'avvio
|
||||
vengono riparate solo le dipendenze runtime dichiarate di quel plugin prima di importarlo.
|
||||
I plugin esterni e i percorsi di caricamento personalizzati devono comunque essere installati tramite
|
||||
`openclaw plugins install`.
|
||||
|
||||
## Tipi di plugin
|
||||
|
||||
OpenClaw riconosce due formati di plugin:
|
||||
|
||||
| Formato | Come funziona | Esempi |
|
||||
| ---------- | --------------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| **Native** | `openclaw.plugin.json` + modulo runtime; esecuzione in-process | Plugin ufficiali, pacchetti npm della community |
|
||||
| **Bundle** | Layout compatibile Codex/Claude/Cursor; mappato alle capability di OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
| Formato | Come funziona | Esempi |
|
||||
| ---------- | -------------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| **Native** | `openclaw.plugin.json` + modulo runtime; esecuzione in-process | Plugin ufficiali, pacchetti npm della community |
|
||||
| **Bundle** | Layout compatibile con Codex/Claude/Cursor; mappato sulle funzionalità di OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
|
||||
|
||||
Entrambi compaiono in `openclaw plugins list`. Vedi [Plugin Bundles](/it/plugins/bundles) per i dettagli sui bundle.
|
||||
Entrambi compaiono in `openclaw plugins list`. Consulta [Bundle di plugin](/it/plugins/bundles) per i dettagli sui bundle.
|
||||
|
||||
Se stai scrivendo un plugin nativo, inizia da [Building Plugins](/it/plugins/building-plugins)
|
||||
e [Plugin SDK Overview](/it/plugins/sdk-overview).
|
||||
Se stai scrivendo un plugin nativo, inizia con [Creazione di plugin](/it/plugins/building-plugins)
|
||||
e la [Panoramica del Plugin SDK](/it/plugins/sdk-overview).
|
||||
|
||||
## Plugin ufficiali
|
||||
|
||||
### Installabili (npm)
|
||||
|
||||
| Plugin | Pacchetto | Documentazione |
|
||||
| --------------- | ---------------------- | ------------------------------------- |
|
||||
| Matrix | `@openclaw/matrix` | [Matrix](/it/channels/matrix) |
|
||||
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/it/channels/msteams) |
|
||||
| Nostr | `@openclaw/nostr` | [Nostr](/it/channels/nostr) |
|
||||
| Voice Call | `@openclaw/voice-call` | [Voice Call](/it/plugins/voice-call) |
|
||||
| Zalo | `@openclaw/zalo` | [Zalo](/it/channels/zalo) |
|
||||
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/it/plugins/zalouser) |
|
||||
| Plugin | Pacchetto | Documentazione |
|
||||
| --------------- | ---------------------- | ------------------------------------ |
|
||||
| Matrix | `@openclaw/matrix` | [Matrix](/it/channels/matrix) |
|
||||
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/it/channels/msteams) |
|
||||
| Nostr | `@openclaw/nostr` | [Nostr](/it/channels/nostr) |
|
||||
| Voice Call | `@openclaw/voice-call` | [Voice Call](/it/plugins/voice-call) |
|
||||
| Zalo | `@openclaw/zalo` | [Zalo](/it/channels/zalo) |
|
||||
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/it/plugins/zalouser) |
|
||||
|
||||
### Core (distribuiti con OpenClaw)
|
||||
### Core (forniti con OpenClaw)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Provider di modelli (abilitati per impostazione predefinita)">
|
||||
@ -115,21 +115,21 @@ e [Plugin SDK Overview](/it/plugins/sdk-overview).
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Plugin di memoria">
|
||||
- `memory-core` — ricerca memoria bundled (predefinito tramite `plugins.slots.memory`)
|
||||
- `memory-lancedb` — memoria a lungo termine install-on-demand con auto-recall/capture (imposta `plugins.slots.memory = "memory-lancedb"`)
|
||||
- `memory-core` — plugin di ricerca in memoria integrato (predefinito tramite `plugins.slots.memory`)
|
||||
- `memory-lancedb` — memoria a lungo termine installata su richiesta con richiamo/acquisizione automatica (imposta `plugins.slots.memory = "memory-lancedb"`)
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Provider speech (abilitati per impostazione predefinita)">
|
||||
<Accordion title="Provider vocali (abilitati per impostazione predefinita)">
|
||||
`elevenlabs`, `microsoft`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Altro">
|
||||
- `browser` — plugin browser bundled per lo strumento browser, CLI `openclaw browser`, metodo Gateway `browser.request`, runtime browser e servizio predefinito di controllo browser (abilitato per impostazione predefinita; disabilitalo prima di sostituirlo)
|
||||
- `browser` — plugin browser integrato per lo strumento browser, la CLI `openclaw browser`, il metodo gateway `browser.request`, il runtime browser e il servizio di controllo browser predefinito (abilitato per impostazione predefinita; disabilitalo prima di sostituirlo)
|
||||
- `copilot-proxy` — bridge VS Code Copilot Proxy (disabilitato per impostazione predefinita)
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Cerchi plugin di terze parti? Vedi [Community Plugins](/it/plugins/community).
|
||||
Cerchi plugin di terze parti? Consulta [Plugin della community](/it/plugins/community).
|
||||
|
||||
## Configurazione
|
||||
|
||||
@ -147,28 +147,28 @@ Cerchi plugin di terze parti? Vedi [Community Plugins](/it/plugins/community).
|
||||
}
|
||||
```
|
||||
|
||||
| Campo | Descrizione |
|
||||
| ---------------- | ---------------------------------------------------------- |
|
||||
| `enabled` | Toggle master (predefinito: `true`) |
|
||||
| `allow` | Allowlist dei plugin (facoltativa) |
|
||||
| `deny` | Denylist dei plugin (facoltativa; deny ha la precedenza) |
|
||||
| `load.paths` | File/directory plugin aggiuntivi |
|
||||
| Campo | Descrizione |
|
||||
| ---------------- | --------------------------------------------------------- |
|
||||
| `enabled` | Interruttore principale (predefinito: `true`) |
|
||||
| `allow` | Allowlist dei plugin (facoltativa) |
|
||||
| `deny` | Denylist dei plugin (facoltativa; deny ha la precedenza) |
|
||||
| `load.paths` | File/directory plugin aggiuntivi |
|
||||
| `slots` | Selettori di slot esclusivi (ad es. `memory`, `contextEngine`) |
|
||||
| `entries.\<id\>` | Toggle + configurazione per plugin |
|
||||
| `entries.\<id\>` | Interruttori + configurazione per plugin |
|
||||
|
||||
Le modifiche alla configurazione **richiedono un riavvio del Gateway**. Se il Gateway è in esecuzione con
|
||||
watch della configurazione + riavvio in-process abilitato (il percorso predefinito `openclaw gateway`), quel
|
||||
riavvio di solito viene eseguito automaticamente poco dopo che la scrittura della configurazione è stata applicata.
|
||||
Le modifiche alla configurazione **richiedono un riavvio del gateway**. Se il Gateway è in esecuzione con
|
||||
watch della configurazione + riavvio in-process abilitato (il percorso predefinito `openclaw gateway`),
|
||||
di solito quel riavvio viene eseguito automaticamente poco dopo che la scrittura della configurazione viene applicata.
|
||||
|
||||
<Accordion title="Stati del plugin: disabilitato vs mancante vs non valido">
|
||||
- **Disabilitato**: il plugin esiste ma le regole di abilitazione lo hanno disattivato. La configurazione viene preservata.
|
||||
- **Mancante**: la configurazione fa riferimento a un ID plugin che la discovery non ha trovato.
|
||||
- **Mancante**: la configurazione fa riferimento a un id plugin che il rilevamento non ha trovato.
|
||||
- **Non valido**: il plugin esiste ma la sua configurazione non corrisponde allo schema dichiarato.
|
||||
</Accordion>
|
||||
|
||||
## Discovery e precedenza
|
||||
## Rilevamento e precedenza
|
||||
|
||||
OpenClaw cerca i plugin in questo ordine (vince la prima corrispondenza):
|
||||
OpenClaw analizza i plugin in questo ordine (vince la prima corrispondenza):
|
||||
|
||||
<Steps>
|
||||
<Step title="Percorsi di configurazione">
|
||||
@ -183,9 +183,9 @@ OpenClaw cerca i plugin in questo ordine (vince la prima corrispondenza):
|
||||
`~/.openclaw/<plugin-root>/*.ts` e `~/.openclaw/<plugin-root>/*/index.ts`.
|
||||
</Step>
|
||||
|
||||
<Step title="Plugin bundled">
|
||||
Distribuiti con OpenClaw. Molti sono abilitati per impostazione predefinita (provider di modelli, speech).
|
||||
Altri richiedono un’abilitazione esplicita.
|
||||
<Step title="Plugin integrati">
|
||||
Forniti con OpenClaw. Molti sono abilitati per impostazione predefinita (provider di modelli, voce).
|
||||
Altri richiedono un'abilitazione esplicita.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@ -194,9 +194,9 @@ OpenClaw cerca i plugin in questo ordine (vince la prima corrispondenza):
|
||||
- `plugins.enabled: false` disabilita tutti i plugin
|
||||
- `plugins.deny` ha sempre la precedenza su allow
|
||||
- `plugins.entries.\<id\>.enabled: false` disabilita quel plugin
|
||||
- I plugin originati dal workspace sono **disabilitati per impostazione predefinita** (devono essere abilitati esplicitamente)
|
||||
- I plugin bundled seguono l’insieme built-in di quelli attivi per default salvo override
|
||||
- Gli slot esclusivi possono forzare l’abilitazione del plugin selezionato per quello slot
|
||||
- I plugin di origine workspace sono **disabilitati per impostazione predefinita** (devono essere esplicitamente abilitati)
|
||||
- I plugin integrati seguono l'insieme built-in di quelli attivi per impostazione predefinita, salvo override
|
||||
- Gli slot esclusivi possono forzare l'abilitazione del plugin selezionato per quello slot
|
||||
|
||||
## Slot dei plugin (categorie esclusive)
|
||||
|
||||
@ -206,17 +206,17 @@ Alcune categorie sono esclusive (solo una attiva alla volta):
|
||||
{
|
||||
plugins: {
|
||||
slots: {
|
||||
memory: "memory-core", // oppure "none" per disabilitare
|
||||
contextEngine: "legacy", // oppure un ID plugin
|
||||
memory: "memory-core", // o "none" per disabilitare
|
||||
contextEngine: "legacy", // o un id plugin
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
| Slot | Cosa controlla | Predefinito |
|
||||
| --------------- | ------------------------ | ------------------- |
|
||||
| `memory` | Plugin di memoria attivo | `memory-core` |
|
||||
| `contextEngine` | Motore di contesto attivo | `legacy` (integrato) |
|
||||
| Slot | Cosa controlla | Predefinito |
|
||||
| --------------- | ------------------------- | ------------------- |
|
||||
| `memory` | Plugin Active Memory | `memory-core` |
|
||||
| `contextEngine` | Motore di contesto attivo | `legacy` (built-in) |
|
||||
|
||||
## Riferimento CLI
|
||||
|
||||
@ -224,21 +224,21 @@ Alcune categorie sono esclusive (solo una attiva alla volta):
|
||||
openclaw plugins list # inventario compatto
|
||||
openclaw plugins list --enabled # solo plugin caricati
|
||||
openclaw plugins list --verbose # righe di dettaglio per plugin
|
||||
openclaw plugins list --json # inventario leggibile dalla macchina
|
||||
openclaw plugins list --json # inventario leggibile da macchina
|
||||
openclaw plugins inspect <id> # dettaglio approfondito
|
||||
openclaw plugins inspect <id> --json # leggibile dalla macchina
|
||||
openclaw plugins inspect --all # tabella completa
|
||||
openclaw plugins inspect <id> --json # leggibile da macchina
|
||||
openclaw plugins inspect --all # tabella estesa all'intera flotta
|
||||
openclaw plugins info <id> # alias di inspect
|
||||
openclaw plugins doctor # diagnostica
|
||||
|
||||
openclaw plugins install <package> # installa (prima ClawHub, poi npm)
|
||||
openclaw plugins install clawhub:<pkg> # installa solo da ClawHub
|
||||
openclaw plugins install <spec> --force # sovrascrive un’installazione esistente
|
||||
openclaw plugins install <spec> --force # sovrascrive un'installazione esistente
|
||||
openclaw plugins install <path> # installa da percorso locale
|
||||
openclaw plugins install -l <path> # link (senza copia) per sviluppo
|
||||
openclaw plugins install -l <path> # collega (senza copia) per sviluppo
|
||||
openclaw plugins install <plugin> --marketplace <source>
|
||||
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
|
||||
openclaw plugins install <spec> --pin # registra l’esatta npm spec risolta
|
||||
openclaw plugins install <spec> --pin # registra la specifica npm esatta risolta
|
||||
openclaw plugins install <spec> --dangerously-force-unsafe-install
|
||||
openclaw plugins update <id-or-npm-spec> # aggiorna un plugin
|
||||
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
|
||||
@ -252,48 +252,58 @@ openclaw plugins enable <id>
|
||||
openclaw plugins disable <id>
|
||||
```
|
||||
|
||||
I plugin bundled vengono distribuiti con OpenClaw. Molti sono abilitati per impostazione predefinita (per esempio
|
||||
provider di modelli bundled, provider speech bundled e il plugin browser bundled). Altri plugin bundled richiedono ancora `openclaw plugins enable <id>`.
|
||||
I plugin integrati vengono forniti con OpenClaw. Molti sono abilitati per impostazione predefinita (per esempio
|
||||
provider di modelli integrati, provider vocali integrati e il plugin browser
|
||||
integrato). Altri plugin integrati richiedono comunque `openclaw plugins enable <id>`.
|
||||
|
||||
`--force` sovrascrive un plugin o hook pack installato esistente sul posto. Usa
|
||||
`openclaw plugins update <id-or-npm-spec>` per gli aggiornamenti ordinari dei plugin npm tracciati. Non è supportato con `--link`, che riusa il percorso sorgente invece
|
||||
di copiare su una destinazione di installazione gestita.
|
||||
`--force` sovrascrive sul posto un plugin o hook pack già installato. Usa
|
||||
`openclaw plugins update <id-or-npm-spec>` per i normali aggiornamenti dei
|
||||
plugin npm tracciati. Non è supportato con `--link`, che riutilizza il percorso sorgente
|
||||
invece di copiare sopra una destinazione di installazione gestita.
|
||||
|
||||
Quando `plugins.allow` è già impostato, `openclaw plugins install` aggiunge
|
||||
l'id del plugin installato a quell'allowlist prima di abilitarlo, così le installazioni sono
|
||||
immediatamente caricabili dopo il riavvio.
|
||||
|
||||
`openclaw plugins update <id-or-npm-spec>` si applica alle installazioni tracciate. Passare
|
||||
una npm package spec con un dist-tag o una versione esatta risolve il nome del pacchetto
|
||||
di nuovo nel record del plugin tracciato e registra la nuova spec per aggiornamenti futuri.
|
||||
Passare il nome del pacchetto senza versione riporta un’installazione esattamente fissata alla
|
||||
linea di release predefinita del registry. Se il plugin npm installato corrisponde già
|
||||
alla versione risolta e all’identità dell’artefatto registrato, OpenClaw salta l’aggiornamento
|
||||
una specifica di pacchetto npm con un dist-tag o una versione esatta risolve il nome del pacchetto
|
||||
sul record del plugin tracciato e registra la nuova specifica per aggiornamenti futuri.
|
||||
Passare il nome del pacchetto senza una versione riporta un'installazione esatta fissata
|
||||
alla linea di release predefinita del registro. Se il plugin npm installato corrisponde già
|
||||
alla versione risolta e all'identità dell'artefatto registrata, OpenClaw salta l'aggiornamento
|
||||
senza scaricare, reinstallare o riscrivere la configurazione.
|
||||
|
||||
`--pin` è solo per npm. Non è supportato con `--marketplace`, perché le
|
||||
installazioni da marketplace persistono metadati della sorgente marketplace invece di una npm spec.
|
||||
`--pin` è solo per npm. Non è supportato con `--marketplace`, perché
|
||||
le installazioni da marketplace persistono i metadati della sorgente del marketplace invece di una specifica npm.
|
||||
|
||||
`--dangerously-force-unsafe-install` è un override break-glass per i falsi positivi
|
||||
dello scanner integrato di codice pericoloso. Consente a installazioni e aggiornamenti di plugin di proseguire oltre findings `critical` integrati, ma comunque
|
||||
non bypassa i blocchi di policy `before_install` del plugin né il blocco dovuto a errore della scansione.
|
||||
`--dangerously-force-unsafe-install` è un override di emergenza per i falsi
|
||||
positivi dello scanner integrato di codice pericoloso. Consente alle installazioni
|
||||
e agli aggiornamenti dei plugin di proseguire oltre i rilevamenti built-in `critical`, ma comunque
|
||||
non bypassa i blocchi di policy `before_install` del plugin né il blocco in caso di errore di scansione.
|
||||
|
||||
Questo flag CLI si applica solo ai flussi di installazione/aggiornamento dei plugin. Le installazioni di dipendenze delle Skills supportate dal Gateway usano invece il corrispondente override di richiesta `dangerouslyForceUnsafeInstall`, mentre `openclaw skills install` resta il flusso separato di download/installazione delle Skills da ClawHub.
|
||||
Questo flag CLI si applica solo ai flussi di installazione/aggiornamento dei plugin. Le installazioni di dipendenze
|
||||
delle Skills supportate dal Gateway usano invece l'override di richiesta corrispondente `dangerouslyForceUnsafeInstall`, mentre `openclaw skills install` rimane il flusso separato di download/installazione delle Skills da ClawHub.
|
||||
|
||||
I bundle compatibili partecipano allo stesso flusso di elenco/ispezione/abilitazione/disabilitazione dei plugin. Il supporto runtime attuale include bundle Skills, Claude command-Skills,
|
||||
valori predefiniti Claude `settings.json`, valori predefiniti Claude `.lsp.json` e `lspServers`
|
||||
dichiarati dal manifest, Cursor command-Skills e directory di hook Codex compatibili.
|
||||
I bundle compatibili partecipano allo stesso flusso di list/inspect/enable/disable
|
||||
dei plugin. Il supporto runtime attuale include bundle Skills, Claude command-skills,
|
||||
impostazioni predefinite di Claude `settings.json`, valori predefiniti di Claude `.lsp.json` e `lspServers`
|
||||
dichiarati nel manifest, Cursor command-skills e directory di hook Codex compatibili.
|
||||
|
||||
`openclaw plugins inspect <id>` riporta anche le capability bundle rilevate più
|
||||
le voci MCP e LSP server supportate o non supportate per i plugin basati su bundle.
|
||||
`openclaw plugins inspect <id>` riporta anche le capacità del bundle rilevate più
|
||||
le voci di server MCP e LSP supportate o non supportate per i plugin basati su bundle.
|
||||
|
||||
Le sorgenti marketplace possono essere un nome di marketplace noto di Claude da
|
||||
`~/.claude/plugins/known_marketplaces.json`, una root marketplace locale o un
|
||||
percorso `marketplace.json`, una forma abbreviata GitHub come `owner/repo`, un URL di repository GitHub oppure un URL git. Per i marketplace remoti, le voci dei plugin devono restare dentro il
|
||||
repository marketplace clonato e usare solo sorgenti di percorso relative.
|
||||
Le sorgenti del marketplace possono essere un nome di marketplace noto di Claude da
|
||||
`~/.claude/plugins/known_marketplaces.json`, una root di marketplace locale o
|
||||
un percorso `marketplace.json`, una forma abbreviata GitHub come `owner/repo`, un URL di repository GitHub
|
||||
oppure un URL git. Per i marketplace remoti, le voci dei plugin devono rimanere all'interno del
|
||||
repository del marketplace clonato e usare solo sorgenti con percorso relativo.
|
||||
|
||||
Vedi il [riferimento CLI `openclaw plugins`](/it/cli/plugins) per tutti i dettagli.
|
||||
Consulta il [riferimento CLI di `openclaw plugins`](/it/cli/plugins) per i dettagli completi.
|
||||
|
||||
## Panoramica dell’API dei plugin
|
||||
## Panoramica dell'API dei plugin
|
||||
|
||||
I plugin nativi esportano un oggetto entry che espone `register(api)`. I plugin più vecchi
|
||||
possono ancora usare `activate(api)` come alias legacy, ma i nuovi plugin dovrebbero
|
||||
I plugin Native esportano un oggetto entry che espone `register(api)`. I plugin
|
||||
più vecchi possono ancora usare `activate(api)` come alias legacy, ma i nuovi plugin dovrebbero
|
||||
usare `register`.
|
||||
|
||||
```typescript
|
||||
@ -314,48 +324,49 @@ export default definePluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
OpenClaw carica l’oggetto entry e chiama `register(api)` durante l’attivazione del plugin.
|
||||
Il loader continua a usare come fallback `activate(api)` per i plugin più vecchi,
|
||||
ma i plugin bundled e i nuovi plugin external dovrebbero trattare `register` come il contratto pubblico.
|
||||
OpenClaw carica l'oggetto entry e chiama `register(api)` durante l'attivazione
|
||||
del plugin. Il loader continua a usare `activate(api)` come fallback per i plugin
|
||||
più vecchi, ma i bundle di plugin e i nuovi plugin esterni dovrebbero trattare `register` come
|
||||
contratto pubblico.
|
||||
|
||||
Metodi comuni di registrazione:
|
||||
Metodi di registrazione comuni:
|
||||
|
||||
| Metodo | Cosa registra |
|
||||
| --------------------------------------- | ------------------------------ |
|
||||
| `registerProvider` | Provider di modelli (LLM) |
|
||||
| `registerChannel` | Canale chat |
|
||||
| `registerTool` | Strumento agent |
|
||||
| `registerHook` / `on(...)` | Hook del ciclo di vita |
|
||||
| `registerSpeechProvider` | Text-to-speech / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | STT in streaming |
|
||||
| `registerRealtimeVoiceProvider` | Voce realtime duplex |
|
||||
| `registerMediaUnderstandingProvider` | Analisi immagini/audio |
|
||||
| `registerImageGenerationProvider` | Generazione immagini |
|
||||
| `registerMusicGenerationProvider` | Generazione musica |
|
||||
| `registerVideoGenerationProvider` | Generazione video |
|
||||
| `registerWebFetchProvider` | Provider di web fetch / scrape |
|
||||
| `registerWebSearchProvider` | Web search |
|
||||
| `registerHttpRoute` | Endpoint HTTP |
|
||||
| `registerCommand` / `registerCli` | Comandi CLI |
|
||||
| `registerContextEngine` | Motore di contesto |
|
||||
| `registerService` | Servizio in background |
|
||||
| Metodo | Cosa registra |
|
||||
| --------------------------------------- | -------------------------- |
|
||||
| `registerProvider` | Provider di modelli (LLM) |
|
||||
| `registerChannel` | Canale chat |
|
||||
| `registerTool` | Strumento dell'agente |
|
||||
| `registerHook` / `on(...)` | Hook del ciclo di vita |
|
||||
| `registerSpeechProvider` | Sintesi vocale / STT |
|
||||
| `registerRealtimeTranscriptionProvider` | STT in streaming |
|
||||
| `registerRealtimeVoiceProvider` | Voce realtime duplex |
|
||||
| `registerMediaUnderstandingProvider` | Analisi di immagini/audio |
|
||||
| `registerImageGenerationProvider` | Generazione di immagini |
|
||||
| `registerMusicGenerationProvider` | Generazione di musica |
|
||||
| `registerVideoGenerationProvider` | Generazione di video |
|
||||
| `registerWebFetchProvider` | Provider di recupero / scraping web |
|
||||
| `registerWebSearchProvider` | Ricerca web |
|
||||
| `registerHttpRoute` | Endpoint HTTP |
|
||||
| `registerCommand` / `registerCli` | Comandi CLI |
|
||||
| `registerContextEngine` | Motore di contesto |
|
||||
| `registerService` | Servizio in background |
|
||||
|
||||
Comportamento delle guardie degli hook per gli hook di ciclo di vita tipizzati:
|
||||
Comportamento delle guardie hook per gli hook tipizzati del ciclo di vita:
|
||||
|
||||
- `before_tool_call`: `{ block: true }` è terminale; gli handler a priorità inferiore vengono saltati.
|
||||
- `before_tool_call`: `{ block: false }` non produce effetti e non annulla un block precedente.
|
||||
- `before_install`: `{ block: true }` è terminale; gli handler a priorità inferiore vengono saltati.
|
||||
- `before_install`: `{ block: false }` non produce effetti e non annulla un block precedente.
|
||||
- `message_sending`: `{ cancel: true }` è terminale; gli handler a priorità inferiore vengono saltati.
|
||||
- `message_sending`: `{ cancel: false }` non produce effetti e non annulla un cancel precedente.
|
||||
- `before_tool_call`: `{ block: true }` è terminale; gli handler con priorità inferiore vengono saltati.
|
||||
- `before_tool_call`: `{ block: false }` non ha effetto e non annulla un blocco precedente.
|
||||
- `before_install`: `{ block: true }` è terminale; gli handler con priorità inferiore vengono saltati.
|
||||
- `before_install`: `{ block: false }` non ha effetto e non annulla un blocco precedente.
|
||||
- `message_sending`: `{ cancel: true }` è terminale; gli handler con priorità inferiore vengono saltati.
|
||||
- `message_sending`: `{ cancel: false }` non ha effetto e non annulla una cancellazione precedente.
|
||||
|
||||
Per il comportamento completo degli hook tipizzati, vedi [SDK Overview](/it/plugins/sdk-overview#hook-decision-semantics).
|
||||
Per il comportamento completo degli hook tipizzati, consulta [Panoramica SDK](/it/plugins/sdk-overview#hook-decision-semantics).
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Building Plugins](/it/plugins/building-plugins) — crea il tuo plugin
|
||||
- [Plugin Bundles](/it/plugins/bundles) — compatibilità bundle Codex/Claude/Cursor
|
||||
- [Plugin Manifest](/it/plugins/manifest) — schema del manifest
|
||||
- [Registering Tools](/it/plugins/building-plugins#registering-agent-tools) — aggiungi strumenti agent in un plugin
|
||||
- [Plugin Internals](/it/plugins/architecture) — modello di capability e pipeline di caricamento
|
||||
- [Community Plugins](/it/plugins/community) — elenchi di terze parti
|
||||
- [Creazione di plugin](/it/plugins/building-plugins) — crea il tuo plugin
|
||||
- [Bundle di plugin](/it/plugins/bundles) — compatibilità dei bundle Codex/Claude/Cursor
|
||||
- [Manifest del plugin](/it/plugins/manifest) — schema del manifest
|
||||
- [Registrazione degli strumenti](/it/plugins/building-plugins#registering-agent-tools) — aggiungi strumenti dell'agente in un plugin
|
||||
- [Componenti interni dei plugin](/it/plugins/architecture) — modello di capacità e pipeline di caricamento
|
||||
- [Plugin della community](/it/plugins/community) — elenchi di terze parti
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Uso o configurazione dei comandi chat
|
||||
- Debug dei permessi o dell'instradamento dei comandi
|
||||
- Debug del routing dei comandi o dei permessi
|
||||
summary: 'Comandi slash: testo vs nativi, configurazione e comandi supportati'
|
||||
title: Comandi slash
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T08:37:47Z"
|
||||
generated_at: "2026-04-23T13:59:41Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0f6b454afa77cf02b2c307efcc99ef35d002cb560c427affaf03ac12b2b666e8
|
||||
source_hash: 13290dcdf649ae66603a92a0aca68460bb63ff476179cc2dded796aaa841d66c
|
||||
source_path: tools/slash-commands.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -20,17 +20,17 @@ Il comando chat bash solo host usa `! <cmd>` (con `/bash <cmd>` come alias).
|
||||
|
||||
Esistono due sistemi correlati:
|
||||
|
||||
- **Comandi**: messaggi autonomi `/...`.
|
||||
- **Comandi**: messaggi `/...` autonomi.
|
||||
- **Direttive**: `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
|
||||
- Le direttive vengono rimosse dal messaggio prima che il modello lo veda.
|
||||
- Nei normali messaggi chat (non solo direttive), vengono trattate come “hint inline” e **non** persistono le impostazioni di sessione.
|
||||
- Nei messaggi composti solo da direttive (il messaggio contiene solo direttive), persistono nella sessione e rispondono con una conferma.
|
||||
- Le direttive vengono applicate solo per **mittenti autorizzati**. Se `commands.allowFrom` è impostato, è l'unica
|
||||
- Nei normali messaggi chat (non composti solo da direttive), vengono trattate come “hint inline” e **non** rendono persistenti le impostazioni della sessione.
|
||||
- Nei messaggi composti solo da direttive (il messaggio contiene solo direttive), diventano persistenti per la sessione e rispondono con un acknowledgment.
|
||||
- Le direttive vengono applicate solo per i **mittenti autorizzati**. Se `commands.allowFrom` è impostato, è l'unica
|
||||
allowlist usata; altrimenti l'autorizzazione deriva dalle allowlist/pairing del canale più `commands.useAccessGroups`.
|
||||
I mittenti non autorizzati vedono le direttive trattate come testo normale.
|
||||
|
||||
Esistono anche alcune **scorciatoie inline** (solo mittenti in allowlist/autorizzati): `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
Vengono eseguite immediatamente, vengono rimosse prima che il modello veda il messaggio e il testo rimanente continua nel flusso normale.
|
||||
Esistono anche alcune **scorciatoie inline** (solo per mittenti autorizzati/in allowlist): `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
Vengono eseguite immediatamente, vengono rimosse prima che il modello veda il messaggio e il testo rimanente continua nel normale flusso.
|
||||
|
||||
## Configurazione
|
||||
|
||||
@ -60,94 +60,94 @@ Vengono eseguite immediatamente, vengono rimosse prima che il modello veda il me
|
||||
```
|
||||
|
||||
- `commands.text` (predefinito `true`) abilita il parsing di `/...` nei messaggi chat.
|
||||
- Sulle superfici senza comandi nativi (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), i comandi testuali continuano a funzionare anche se lo imposti su `false`.
|
||||
- Nelle superfici senza comandi nativi (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams), i comandi testuali continuano a funzionare anche se imposti questo valore su `false`.
|
||||
- `commands.native` (predefinito `"auto"`) registra i comandi nativi.
|
||||
- Auto: attivo per Discord/Telegram; disattivo per Slack (finché non aggiungi slash command); ignorato per i provider senza supporto nativo.
|
||||
- Imposta `channels.discord.commands.native`, `channels.telegram.commands.native` o `channels.slack.commands.native` per eseguire override per provider (bool o `"auto"`).
|
||||
- `false` rimuove all'avvio i comandi registrati in precedenza su Discord/Telegram. I comandi Slack sono gestiti nell'app Slack e non vengono rimossi automaticamente.
|
||||
- Imposta `channels.discord.commands.native`, `channels.telegram.commands.native` o `channels.slack.commands.native` per sovrascrivere per provider (bool o `"auto"`).
|
||||
- `false` cancella all'avvio i comandi registrati in precedenza su Discord/Telegram. I comandi Slack sono gestiti nell'app Slack e non vengono rimossi automaticamente.
|
||||
- `commands.nativeSkills` (predefinito `"auto"`) registra i comandi **Skill** in modo nativo quando supportato.
|
||||
- Auto: attivo per Discord/Telegram; disattivo per Slack (Slack richiede la creazione di uno slash command per ogni skill).
|
||||
- Imposta `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` o `channels.slack.commands.nativeSkills` per eseguire override per provider (bool o `"auto"`).
|
||||
- `commands.bash` (predefinito `false`) abilita `! <cmd>` per eseguire comandi shell dell'host (`/bash <cmd>` è un alias; richiede le allowlist `tools.elevated`).
|
||||
- `commands.bashForegroundMs` (predefinito `2000`) controlla per quanto tempo bash attende prima di passare alla modalità background (`0` manda subito in background).
|
||||
- `commands.config` (predefinito `false`) abilita `/config` (lettura/scrittura di `openclaw.json`).
|
||||
- `commands.mcp` (predefinito `false`) abilita `/mcp` (lettura/scrittura della configurazione MCP gestita da OpenClaw sotto `mcp.servers`).
|
||||
- `commands.plugins` (predefinito `false`) abilita `/plugins` (discovery/stato dei plugin più controlli di installazione e abilitazione/disabilitazione).
|
||||
- Imposta `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` o `channels.slack.commands.nativeSkills` per sovrascrivere per provider (bool o `"auto"`).
|
||||
- `commands.bash` (predefinito `false`) abilita `! <cmd>` per eseguire comandi shell host (`/bash <cmd>` è un alias; richiede le allowlist `tools.elevated`).
|
||||
- `commands.bashForegroundMs` (predefinito `2000`) controlla per quanto tempo bash attende prima di passare alla modalità in background (`0` lo manda subito in background).
|
||||
- `commands.config` (predefinito `false`) abilita `/config` (legge/scrive `openclaw.json`).
|
||||
- `commands.mcp` (predefinito `false`) abilita `/mcp` (legge/scrive la configurazione MCP gestita da OpenClaw sotto `mcp.servers`).
|
||||
- `commands.plugins` (predefinito `false`) abilita `/plugins` (discovery/stato dei plugin più controlli di installazione + abilitazione/disabilitazione).
|
||||
- `commands.debug` (predefinito `false`) abilita `/debug` (override solo runtime).
|
||||
- `commands.restart` (predefinito `true`) abilita `/restart` più le azioni degli strumenti di riavvio del gateway.
|
||||
- `commands.ownerAllowFrom` (facoltativo) imposta l'allowlist esplicita del proprietario per le superfici di comandi/strumenti solo proprietario. È separata da `commands.allowFrom`.
|
||||
- `channels.<channel>.commands.enforceOwnerForCommands` per canale (facoltativo, predefinito `false`) fa sì che i comandi solo proprietario richiedano **identità del proprietario** per essere eseguiti su quella superficie. Quando è `true`, il mittente deve corrispondere a un candidato proprietario risolto (per esempio una voce in `commands.ownerAllowFrom` o metadati di proprietario nativi del provider) oppure avere scope interno `operator.admin` su un canale messaggi interno. Una voce wildcard in `allowFrom` del canale, oppure un elenco di candidati proprietario vuoto/non risolto, **non** è sufficiente: i comandi solo proprietario falliscono in modalità fail-closed su quel canale. Lascia questa opzione disattivata se vuoi che i comandi solo proprietario siano controllati solo da `ownerAllowFrom` e dalle allowlist standard dei comandi.
|
||||
- `commands.ownerDisplay` controlla come gli id del proprietario appaiono nel system prompt: `raw` o `hash`.
|
||||
- `commands.restart` (predefinito `true`) abilita `/restart` più le azioni tool di riavvio del gateway.
|
||||
- `commands.ownerAllowFrom` (opzionale) imposta l'allowlist esplicita del proprietario per le superfici comando/tool riservate al proprietario. È separata da `commands.allowFrom`.
|
||||
- `channels.<channel>.commands.enforceOwnerForCommands` per canale (opzionale, predefinito `false`) fa sì che i comandi riservati al proprietario richiedano l'**identità del proprietario** per essere eseguiti su quella superficie. Quando è `true`, il mittente deve corrispondere a un candidato proprietario risolto (per esempio una voce in `commands.ownerAllowFrom` o metadati proprietario nativi del provider) oppure possedere lo scope interno `operator.admin` su un canale di messaggi interno. Una voce wildcard in `allowFrom` del canale, o un elenco di candidati proprietario vuoto/non risolto, **non** è sufficiente: i comandi riservati al proprietario falliscono in modo chiuso su quel canale. Lascia questa opzione disattivata se vuoi che i comandi riservati al proprietario siano regolati solo da `ownerAllowFrom` e dalle allowlist standard dei comandi.
|
||||
- `commands.ownerDisplay` controlla come gli ID del proprietario appaiono nel prompt di sistema: `raw` o `hash`.
|
||||
- `commands.ownerDisplaySecret` imposta facoltativamente il segreto HMAC usato quando `commands.ownerDisplay="hash"`.
|
||||
- `commands.allowFrom` (facoltativo) imposta un'allowlist per provider per l'autorizzazione dei comandi. Quando configurata, è l'unica fonte
|
||||
di autorizzazione per comandi e direttive (le allowlist/pairing del canale e `commands.useAccessGroups`
|
||||
vengono ignorati). Usa `"*"` per un valore predefinito globale; le chiavi specifiche del provider hanno la precedenza.
|
||||
- `commands.useAccessGroups` (predefinito `true`) applica allowlist/policy ai comandi quando `commands.allowFrom` non è impostato.
|
||||
- `commands.allowFrom` (opzionale) imposta un'allowlist per provider per l'autorizzazione dei comandi. Quando configurata, è
|
||||
l'unica fonte di autorizzazione per comandi e direttive (`commands.useAccessGroups` e le allowlist/pairing del canale
|
||||
vengono ignorati). Usa `"*"` per un valore predefinito globale; le chiavi specifiche del provider hanno priorità.
|
||||
- `commands.useAccessGroups` (predefinito `true`) applica allowlist/policy per i comandi quando `commands.allowFrom` non è impostato.
|
||||
|
||||
## Elenco dei comandi
|
||||
|
||||
Fonte di verità attuale:
|
||||
|
||||
- i built-in del core provengono da `src/auto-reply/commands-registry.shared.ts`
|
||||
- i dock command generati provengono da `src/auto-reply/commands-registry.data.ts`
|
||||
- i comandi dei plugin provengono dalle chiamate `registerCommand()` dei plugin
|
||||
- la disponibilità effettiva sul tuo gateway dipende comunque dai flag di configurazione, dalla surface del canale e dai plugin installati/abilitati
|
||||
- i built-in core provengono da `src/auto-reply/commands-registry.shared.ts`
|
||||
- i comandi dock generati provengono da `src/auto-reply/commands-registry.data.ts`
|
||||
- i comandi plugin provengono dalle chiamate `registerCommand()` dei plugin
|
||||
- la disponibilità effettiva sul tuo gateway dipende comunque da flag di configurazione, superficie del canale e plugin installati/abilitati
|
||||
|
||||
### Comandi built-in del core
|
||||
### Comandi built-in core
|
||||
|
||||
Comandi built-in disponibili oggi:
|
||||
|
||||
- `/new [model]` avvia una nuova sessione; `/reset` è l'alias di reset.
|
||||
- `/reset soft [message]` mantiene la transcript corrente, elimina gli id di sessione del backend CLI riutilizzati ed esegue di nuovo in-place il caricamento di startup/system-prompt.
|
||||
- `/compact [instructions]` esegue Compaction del contesto della sessione. Vedi [/concepts/compaction](/it/concepts/compaction).
|
||||
- `/reset soft [message]` mantiene la trascrizione corrente, elimina gli ID di sessione backend CLI riutilizzati e riesegue sul posto il caricamento di avvio/system prompt.
|
||||
- `/compact [instructions]` esegue la Compaction del contesto della sessione. Vedi [/concepts/compaction](/it/concepts/compaction).
|
||||
- `/stop` interrompe l'esecuzione corrente.
|
||||
- `/session idle <duration|off>` e `/session max-age <duration|off>` gestiscono la scadenza del thread-binding.
|
||||
- `/think <level>` imposta il livello di thinking. Le opzioni provengono dal profilo provider del modello attivo; i livelli comuni sono `off`, `minimal`, `low`, `medium` e `high`, con livelli personalizzati come `xhigh`, `adaptive`, `max` o il binario `on` solo dove supportati. Alias: `/thinking`, `/t`.
|
||||
- `/verbose on|off|full` attiva o disattiva l'output dettagliato. Alias: `/v`.
|
||||
- `/trace on|off` attiva o disattiva l'output trace del plugin per la sessione corrente.
|
||||
- `/fast [status|on|off]` mostra o imposta la modalità rapida.
|
||||
- `/session idle <duration|off>` e `/session max-age <duration|off>` gestiscono la scadenza del binding del thread.
|
||||
- `/think <level>` imposta il livello di thinking. Le opzioni provengono dal profilo provider del modello attivo; i livelli comuni sono `off`, `minimal`, `low`, `medium` e `high`, con livelli personalizzati come `xhigh`, `adaptive`, `max` o il binario `on` solo dove supportato. Alias: `/thinking`, `/t`.
|
||||
- `/verbose on|off|full` attiva o disattiva l'output verboso. Alias: `/v`.
|
||||
- `/trace on|off` attiva o disattiva l'output di trace del plugin per la sessione corrente.
|
||||
- `/fast [status|on|off]` mostra o imposta la modalità fast.
|
||||
- `/reasoning [on|off|stream]` attiva o disattiva la visibilità del reasoning. Alias: `/reason`.
|
||||
- `/elevated [on|off|ask|full]` attiva o disattiva la modalità elevated. Alias: `/elev`.
|
||||
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` mostra o imposta i valori predefiniti di exec.
|
||||
- `/model [name|#|status]` mostra o imposta il modello.
|
||||
- `/models [provider] [page] [limit=<n>|size=<n>|all]` elenca provider o modelli per un provider.
|
||||
- `/queue <mode>` gestisce il comportamento della coda (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) più opzioni come `debounce:2s cap:25 drop:summarize`.
|
||||
- `/help` mostra il riepilogo breve dell'help.
|
||||
- `/commands` mostra il catalogo dei comandi generato.
|
||||
- `/tools [compact|verbose]` mostra cosa può usare l'agente corrente in questo momento.
|
||||
- `/status` mostra lo stato runtime, incluso l'utilizzo/quota del provider quando disponibile.
|
||||
- `/models [provider] [page] [limit=<n>|size=<n>|all]` elenca i provider o i modelli di un provider.
|
||||
- `/queue <mode>` gestisce il comportamento della queue (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`) più opzioni come `debounce:2s cap:25 drop:summarize`.
|
||||
- `/help` mostra il riepilogo breve della guida.
|
||||
- `/commands` mostra il catalogo comandi generato.
|
||||
- `/tools [compact|verbose]` mostra ciò che l'agente corrente può usare in questo momento.
|
||||
- `/status` mostra lo stato del runtime, incluse le etichette `Runtime`/`Runner` e l'utilizzo/quota del provider quando disponibili.
|
||||
- `/tasks` elenca i task in background attivi/recenti per la sessione corrente.
|
||||
- `/context [list|detail|json]` spiega come viene assemblato il contesto.
|
||||
- `/export-session [path]` esporta la sessione corrente in HTML. Alias: `/export`.
|
||||
- `/export-trajectory [path]` esporta un [trajectory bundle](/it/tools/trajectory) JSONL per la sessione corrente. Alias: `/trajectory`.
|
||||
- `/whoami` mostra il tuo id mittente. Alias: `/id`.
|
||||
- `/skill <name> [input]` esegue una Skill per nome.
|
||||
- `/whoami` mostra il tuo ID mittente. Alias: `/id`.
|
||||
- `/skill <name> [input]` esegue una skill per nome.
|
||||
- `/allowlist [list|add|remove] ...` gestisce le voci dell'allowlist. Solo testo.
|
||||
- `/approve <id> <decision>` risolve i prompt di approvazione exec.
|
||||
- `/btw <question>` pone una domanda laterale senza modificare il contesto delle sessioni future. Vedi [/tools/btw](/it/tools/btw).
|
||||
- `/approve <id> <decision>` risolve le richieste di approvazione exec.
|
||||
- `/btw <question>` pone una domanda laterale senza modificare il contesto futuro della sessione. Vedi [/tools/btw](/it/tools/btw).
|
||||
- `/subagents list|kill|log|info|send|steer|spawn` gestisce le esecuzioni dei sub-agent per la sessione corrente.
|
||||
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` gestisce le sessioni ACP e le opzioni runtime.
|
||||
- `/focus <target>` collega il thread Discord o il topic/conversazione Telegram corrente a un target di sessione.
|
||||
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` gestisce le sessioni ACP e le opzioni di runtime.
|
||||
- `/focus <target>` associa il thread Discord corrente o il topic/conversation Telegram a un target di sessione.
|
||||
- `/unfocus` rimuove il binding corrente.
|
||||
- `/agents` elenca gli agenti collegati al thread per la sessione corrente.
|
||||
- `/agents` elenca gli agenti associati al thread per la sessione corrente.
|
||||
- `/kill <id|#|all>` interrompe uno o tutti i sub-agent in esecuzione.
|
||||
- `/steer <id|#> <message>` invia uno steering a un sub-agent in esecuzione. Alias: `/tell`.
|
||||
- `/steer <id|#> <message>` invia steering a un sub-agent in esecuzione. Alias: `/tell`.
|
||||
- `/config show|get|set|unset` legge o scrive `openclaw.json`. Solo proprietario. Richiede `commands.config: true`.
|
||||
- `/mcp show|get|set|unset` legge o scrive la configurazione del server MCP gestita da OpenClaw sotto `mcp.servers`. Solo proprietario. Richiede `commands.mcp: true`.
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` ispeziona o modifica lo stato dei plugin. `/plugin` è un alias. Le scritture sono solo proprietario. Richiede `commands.plugins: true`.
|
||||
- `/debug show|set|unset|reset` gestisce gli override di configurazione solo runtime. Solo proprietario. Richiede `commands.debug: true`.
|
||||
- `/usage off|tokens|full|cost` controlla il footer di utilizzo per risposta oppure stampa un riepilogo dei costi locale.
|
||||
- `/tts on|off|status|provider|limit|summary|audio|help` controlla TTS. Vedi [/tools/tts](/it/tools/tts).
|
||||
- `/mcp show|get|set|unset` legge o scrive la configurazione server MCP gestita da OpenClaw sotto `mcp.servers`. Solo proprietario. Richiede `commands.mcp: true`.
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` ispeziona o modifica lo stato dei plugin. `/plugin` è un alias. Solo proprietario per le operazioni di scrittura. Richiede `commands.plugins: true`.
|
||||
- `/debug show|set|unset|reset` gestisce override di configurazione solo runtime. Solo proprietario. Richiede `commands.debug: true`.
|
||||
- `/usage off|tokens|full|cost` controlla il footer di utilizzo per risposta o stampa un riepilogo locale dei costi.
|
||||
- `/tts on|off|status|provider|limit|summary|audio|help` controlla il TTS. Vedi [/tools/tts](/it/tools/tts).
|
||||
- `/restart` riavvia OpenClaw quando abilitato. Predefinito: abilitato; imposta `commands.restart: false` per disabilitarlo.
|
||||
- `/activation mention|always` imposta la modalità di attivazione del gruppo.
|
||||
- `/send on|off|inherit` imposta la policy di invio. Solo proprietario.
|
||||
- `/bash <command>` esegue un comando shell dell'host. Solo testo. Alias: `! <command>`. Richiede `commands.bash: true` più le allowlist `tools.elevated`.
|
||||
- `/bash <command>` esegue un comando shell host. Solo testo. Alias: `! <command>`. Richiede `commands.bash: true` più le allowlist `tools.elevated`.
|
||||
- `!poll [sessionId]` controlla un job bash in background.
|
||||
- `!stop [sessionId]` arresta un job bash in background.
|
||||
- `!stop [sessionId]` interrompe un job bash in background.
|
||||
|
||||
### Dock command generati
|
||||
### Comandi dock generati
|
||||
|
||||
I dock command vengono generati dai plugin canale con supporto ai comandi nativi. Set incluso attuale:
|
||||
I comandi dock vengono generati dai plugin di canale con supporto ai comandi nativi. Set incluso attuale:
|
||||
|
||||
- `/dock-discord` (alias: `/dock_discord`)
|
||||
- `/dock-mattermost` (alias: `/dock_mattermost`)
|
||||
@ -156,14 +156,14 @@ I dock command vengono generati dai plugin canale con supporto ai comandi nativi
|
||||
|
||||
### Comandi dei plugin inclusi
|
||||
|
||||
I plugin inclusi possono aggiungere altri comandi slash. Comandi inclusi attuali in questo repository:
|
||||
I plugin inclusi possono aggiungere altri slash command. Comandi inclusi attuali in questo repository:
|
||||
|
||||
- `/dreaming [on|off|status|help]` attiva o disattiva Dreaming della memoria. Vedi [Dreaming](/it/concepts/dreaming).
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` gestisce il flusso di pairing/setup del device. Vedi [Pairing](/it/channels/pairing).
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` abilita temporaneamente i comandi Node del telefono ad alto rischio.
|
||||
- `/dreaming [on|off|status|help]` attiva o disattiva il Dreaming della memoria. Vedi [Dreaming](/it/concepts/dreaming).
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` gestisce il flusso di pairing/setup del dispositivo. Vedi [Pairing](/it/channels/pairing).
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` arma temporaneamente i comandi del Node telefono ad alto rischio.
|
||||
- `/voice status|list [limit]|set <voiceId|name>` gestisce la configurazione della voce Talk. Su Discord, il nome del comando nativo è `/talkvoice`.
|
||||
- `/card ...` invia preset di rich card LINE. Vedi [LINE](/it/channels/line).
|
||||
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` ispeziona e controlla l'harness dell'app-server Codex incluso. Vedi [Codex Harness](/it/plugins/codex-harness).
|
||||
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` ispeziona e controlla l'harness app-server Codex incluso. Vedi [Codex Harness](/it/plugins/codex-harness).
|
||||
- Comandi solo QQBot:
|
||||
- `/bot-ping`
|
||||
- `/bot-version`
|
||||
@ -171,71 +171,72 @@ I plugin inclusi possono aggiungere altri comandi slash. Comandi inclusi attuali
|
||||
- `/bot-upgrade`
|
||||
- `/bot-logs`
|
||||
|
||||
### Comandi dinamici delle Skill
|
||||
### Comandi Skill dinamici
|
||||
|
||||
Le Skills invocabili dall'utente sono esposte anche come comandi slash:
|
||||
Le Skills invocabili dall'utente sono esposte anche come slash command:
|
||||
|
||||
- `/skill <name> [input]` funziona sempre come entrypoint generico.
|
||||
- le skills possono apparire anche come comandi diretti come `/prose` quando la skill/il plugin li registra.
|
||||
- la registrazione nativa dei comandi Skill è controllata da `commands.nativeSkills` e `channels.<provider>.commands.nativeSkills`.
|
||||
- le skill possono anche apparire come comandi diretti come `/prose` quando la skill/il plugin li registra.
|
||||
- la registrazione nativa dei comandi skill è controllata da `commands.nativeSkills` e `channels.<provider>.commands.nativeSkills`.
|
||||
|
||||
Note:
|
||||
|
||||
- I comandi accettano un `:` facoltativo tra il comando e gli argomenti (ad esempio `/think: high`, `/send: on`, `/help:`).
|
||||
- `/new <model>` accetta un alias del modello, `provider/model` oppure il nome di un provider (fuzzy match); se non c'è corrispondenza, il testo viene trattato come corpo del messaggio.
|
||||
- Per il dettaglio completo dell'utilizzo per provider, usa `openclaw status --usage`.
|
||||
- I comandi accettano facoltativamente `:` tra il comando e gli argomenti (per esempio `/think: high`, `/send: on`, `/help:`).
|
||||
- `/new <model>` accetta un alias di modello, `provider/model` o il nome di un provider (fuzzy match); se non c'è corrispondenza, il testo viene trattato come corpo del messaggio.
|
||||
- Per il dettaglio completo dell'utilizzo del provider, usa `openclaw status --usage`.
|
||||
- `/allowlist add|remove` richiede `commands.config=true` e rispetta `configWrites` del canale.
|
||||
- Nei canali multi-account, anche `/allowlist --account <id>` mirato alla configurazione e `/config set channels.<provider>.accounts.<id>...` rispettano `configWrites` dell'account di destinazione.
|
||||
- `/usage` controlla il footer di utilizzo per risposta; `/usage cost` stampa un riepilogo locale dei costi dai log di sessione di OpenClaw.
|
||||
- Nei canali multi-account, `/allowlist --account <id>` mirato alla config e `/config set channels.<provider>.accounts.<id>...` rispettano anche `configWrites` dell'account di destinazione.
|
||||
- `/usage` controlla il footer di utilizzo per risposta; `/usage cost` stampa un riepilogo locale dei costi dai log di sessione OpenClaw.
|
||||
- `/restart` è abilitato per impostazione predefinita; imposta `commands.restart: false` per disabilitarlo.
|
||||
- `/plugins install <spec>` accetta le stesse specifiche di plugin di `openclaw plugins install`: percorso/archivio locale, pacchetto npm o `clawhub:<pkg>`.
|
||||
- `/plugins enable|disable` aggiorna la configurazione del plugin e può richiedere un riavvio.
|
||||
- Comando nativo solo Discord: `/vc join|leave|status` controlla i canali vocali (richiede `channels.discord.voice` e comandi nativi; non disponibile come testo).
|
||||
- I comandi di thread-binding di Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) richiedono che i thread binding effettivi siano abilitati (`session.threadBindings.enabled` e/o `channels.discord.threadBindings.enabled`).
|
||||
- Riferimento dei comandi ACP e comportamento runtime: [Agenti ACP](/it/tools/acp-agents).
|
||||
- `/verbose` è pensato per debug e visibilità aggiuntiva; mantienilo **disattivato** nell'uso normale.
|
||||
- `/trace` è più ristretto di `/verbose`: rivela solo righe di trace/debug gestite dal plugin e mantiene disattivo il normale chatter verbose di strumenti/stato.
|
||||
- `/fast on|off` persiste un override di sessione. Usa l'opzione `inherit` nell'interfaccia Sessions per cancellarlo e tornare ai valori predefiniti della configurazione.
|
||||
- `/plugins install <spec>` accetta le stesse specifiche plugin di `openclaw plugins install`: percorso/archive locale, pacchetto npm o `clawhub:<pkg>`.
|
||||
- `/plugins enable|disable` aggiorna la configurazione dei plugin e può richiedere un riavvio.
|
||||
- Comando nativo solo Discord: `/vc join|leave|status` controlla i canali vocali (richiede `channels.discord.voice` e comandi nativi; non è disponibile come testo).
|
||||
- I comandi Discord di binding del thread (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) richiedono che i thread binding effettivi siano abilitati (`session.threadBindings.enabled` e/o `channels.discord.threadBindings.enabled`).
|
||||
- Riferimento comandi ACP e comportamento runtime: [ACP Agents](/it/tools/acp-agents).
|
||||
- `/verbose` è pensato per debug e visibilità aggiuntiva; in uso normale tienilo **off**.
|
||||
- `/trace` è più ristretto di `/verbose`: rivela solo le righe di trace/debug di proprietà dei plugin e mantiene disattivato il normale chatter verboso di tool.
|
||||
- `/fast on|off` rende persistente un override di sessione. Usa l'opzione `inherit` nell'interfaccia Sessions per cancellarlo e tornare ai valori predefiniti della configurazione.
|
||||
- `/fast` è specifico del provider: OpenAI/OpenAI Codex lo mappano a `service_tier=priority` sugli endpoint nativi Responses, mentre le richieste Anthropic pubbliche dirette, incluso il traffico autenticato OAuth inviato a `api.anthropic.com`, lo mappano a `service_tier=auto` o `standard_only`. Vedi [OpenAI](/it/providers/openai) e [Anthropic](/it/providers/anthropic).
|
||||
- I riepiloghi degli errori degli strumenti vengono comunque mostrati quando pertinenti, ma il testo dettagliato dell'errore è incluso solo quando `/verbose` è `on` o `full`.
|
||||
- `/reasoning`, `/verbose` e `/trace` sono rischiosi in contesti di gruppo: possono rivelare reasoning interno, output degli strumenti o diagnostica dei plugin che non intendevi esporre. Preferisci lasciarli disattivati, soprattutto nelle chat di gruppo.
|
||||
- `/model` persiste immediatamente il nuovo modello di sessione.
|
||||
- I riepiloghi dei guasti dei tool vengono comunque mostrati quando pertinenti, ma il testo dettagliato del guasto viene incluso solo quando `/verbose` è `on` o `full`.
|
||||
- `/reasoning`, `/verbose` e `/trace` sono rischiosi in contesti di gruppo: possono rivelare reasoning interni, output dei tool o diagnostica dei plugin che non intendevi esporre. È preferibile lasciarli disattivati, soprattutto nelle chat di gruppo.
|
||||
- `/model` rende persistente immediatamente il nuovo modello della sessione.
|
||||
- Se l'agente è inattivo, l'esecuzione successiva lo usa subito.
|
||||
- Se un'esecuzione è già attiva, OpenClaw contrassegna un cambio live come in sospeso e riavvia nel nuovo modello solo a un punto pulito di retry.
|
||||
- Se l'attività degli strumenti o l'output della risposta sono già iniziati, il cambio in sospeso può restare in coda fino a una successiva opportunità di retry o al turno utente successivo.
|
||||
- **Percorso rapido:** i messaggi composti solo da comandi provenienti da mittenti in allowlist vengono gestiti immediatamente (bypassano coda + modello).
|
||||
- **Gating delle menzioni nei gruppi:** i messaggi composti solo da comandi provenienti da mittenti in allowlist bypassano i requisiti di menzione.
|
||||
- Se è già attiva un'esecuzione, OpenClaw contrassegna un cambio live come in sospeso e riavvia nel nuovo modello solo in un punto di retry pulito.
|
||||
- Se l'attività dei tool o l'output della risposta sono già iniziati, il cambio in sospeso può restare in coda fino a un'opportunità di retry successiva o al prossimo turno utente.
|
||||
- **Percorso rapido:** i messaggi composti solo da comandi provenienti da mittenti in allowlist vengono gestiti immediatamente (bypass di queue + modello).
|
||||
- **Gating delle mention di gruppo:** i messaggi composti solo da comandi provenienti da mittenti in allowlist bypassano i requisiti delle mention.
|
||||
- **Scorciatoie inline (solo mittenti in allowlist):** alcuni comandi funzionano anche quando sono incorporati in un messaggio normale e vengono rimossi prima che il modello veda il testo rimanente.
|
||||
- Esempio: `hey /status` attiva una risposta di stato e il testo rimanente continua nel flusso normale.
|
||||
- Esempio: `hey /status` attiva una risposta di stato e il testo rimanente continua nel normale flusso.
|
||||
- Attualmente: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
|
||||
- I messaggi composti solo da comandi non autorizzati vengono ignorati silenziosamente e i token inline `/...` vengono trattati come testo normale.
|
||||
- **Comandi Skill:** le Skills `user-invocable` sono esposte come comandi slash. I nomi vengono sanitizzati in `a-z0-9_` (max 32 caratteri); in caso di collisione ricevono suffissi numerici (ad esempio `_2`).
|
||||
- `/skill <name> [input]` esegue una Skill per nome (utile quando i limiti dei comandi nativi impediscono comandi per singola Skill).
|
||||
- Per impostazione predefinita, i comandi Skill vengono inoltrati al modello come una richiesta normale.
|
||||
- Le Skills possono facoltativamente dichiarare `command-dispatch: tool` per instradare il comando direttamente a uno strumento (deterministico, senza modello).
|
||||
- **Comandi Skill:** le skill `user-invocable` sono esposte come slash command. I nomi vengono sanitizzati in `a-z0-9_` (max 32 caratteri); le collisioni ricevono suffissi numerici (per esempio `_2`).
|
||||
- `/skill <name> [input]` esegue una skill per nome (utile quando i limiti dei comandi nativi impediscono i comandi per-skill).
|
||||
- Per impostazione predefinita, i comandi skill vengono inoltrati al modello come richiesta normale.
|
||||
- Le skill possono facoltativamente dichiarare `command-dispatch: tool` per instradare il comando direttamente a un tool (deterministico, nessun modello).
|
||||
- Esempio: `/prose` (Plugin OpenProse) — vedi [OpenProse](/it/prose).
|
||||
- **Argomenti dei comandi nativi:** Discord usa autocomplete per opzioni dinamiche (e menu a pulsanti quando ometti argomenti obbligatori). Telegram e Slack mostrano un menu a pulsanti quando un comando supporta scelte e ometti l'argomento.
|
||||
- **Argomenti dei comandi nativi:** Discord usa l'autocomplete per le opzioni dinamiche (e menu a pulsanti quando ometti argomenti richiesti). Telegram e Slack mostrano un menu a pulsanti quando un comando supporta scelte e ometti l'argomento.
|
||||
|
||||
## `/tools`
|
||||
|
||||
`/tools` risponde a una domanda di runtime, non a una domanda di configurazione: **che cosa questo agente può usare in questo momento in
|
||||
questa conversazione**.
|
||||
|
||||
- Il valore predefinito di `/tools` è compatto e ottimizzato per una rapida scansione.
|
||||
- Il valore predefinito di `/tools` è compatto e ottimizzato per una scansione rapida.
|
||||
- `/tools verbose` aggiunge brevi descrizioni.
|
||||
- Le superfici con comandi nativi che supportano argomenti espongono lo stesso cambio di modalità `compact|verbose`.
|
||||
- Le superfici con comandi nativi che supportano argomenti espongono lo stesso selettore di modalità `compact|verbose`.
|
||||
- I risultati hanno scope di sessione, quindi cambiare agente, canale, thread, autorizzazione del mittente o modello può
|
||||
cambiare l'output.
|
||||
- `/tools` include gli strumenti effettivamente raggiungibili a runtime, inclusi strumenti core, strumenti
|
||||
dei plugin collegati e strumenti gestiti dal canale.
|
||||
modificare l'output.
|
||||
- `/tools` include i tool realmente raggiungibili a runtime, inclusi tool core, tool dei plugin
|
||||
connessi e tool di proprietà del canale.
|
||||
|
||||
Per modificare profili e override, usa il pannello Tools della Control UI o le superfici di configurazione/catalogo invece
|
||||
di trattare `/tools` come un catalogo statico.
|
||||
Per modificare profili e override, usa il pannello Tools dell'interfaccia di controllo o le superfici config/catalog
|
||||
invece di trattare `/tools` come un catalogo statico.
|
||||
|
||||
## Superfici di utilizzo (cosa appare dove)
|
||||
|
||||
- **Utilizzo/quota del provider** (esempio: “Claude 80% left”) appare in `/status` per il provider del modello corrente quando il tracciamento dell'utilizzo è abilitato. OpenClaw normalizza le finestre dei provider in `% left`; per MiniMax, i campi percentuali di solo residuo vengono invertiti prima della visualizzazione, e le risposte `model_remains` preferiscono la voce del modello chat più un'etichetta di piano associata al modello.
|
||||
- **Righe token/cache** in `/status` possono usare come fallback l'ultima voce di utilizzo della transcript quando lo snapshot live della sessione è scarso. I valori live esistenti non nulli hanno comunque la precedenza, e il fallback dalla transcript può anche recuperare l'etichetta del modello runtime attivo più un totale più ampio orientato al prompt quando i totali memorizzati mancano o sono inferiori.
|
||||
- **Utilizzo/quota del provider** (esempio: “Claude 80% left”) appare in `/status` per il provider del modello corrente quando il tracciamento dell'utilizzo è abilitato. OpenClaw normalizza le finestre del provider in `% left`; per MiniMax, i campi percentuali con solo residuo vengono invertiti prima della visualizzazione, e le risposte `model_remains` privilegiano la voce del modello chat più un'etichetta di piano con tag del modello.
|
||||
- Le righe **token/cache** in `/status` possono ripiegare sull'ultima voce di utilizzo della trascrizione quando lo snapshot live della sessione è scarso. I valori live non zero esistenti hanno comunque priorità, e il fallback dalla trascrizione può anche recuperare l'etichetta del modello runtime attivo più un totale più ampio orientato al prompt quando i totali memorizzati mancano o sono inferiori.
|
||||
- **Runtime vs runner:** `/status` riporta `Runtime` per il percorso di esecuzione effettivo e lo stato sandbox, e `Runner` per chi sta effettivamente eseguendo la sessione: Pi incorporato, provider supportato da CLI o harness/backend ACP.
|
||||
- **Token/costo per risposta** è controllato da `/usage off|tokens|full` (aggiunto alle normali risposte).
|
||||
- `/model status` riguarda **modelli/auth/endpoint**, non l'utilizzo.
|
||||
|
||||
@ -245,7 +246,7 @@ di trattare `/tools` come un catalogo statico.
|
||||
|
||||
Esempi:
|
||||
|
||||
```
|
||||
```text
|
||||
/model
|
||||
/model list
|
||||
/model 3
|
||||
@ -259,15 +260,15 @@ Note:
|
||||
- `/model` e `/model list` mostrano un selettore compatto numerato (famiglia di modelli + provider disponibili).
|
||||
- Su Discord, `/model` e `/models` aprono un selettore interattivo con menu a discesa per provider e modello più un passaggio Submit.
|
||||
- `/model <#>` seleziona da quel selettore (e preferisce il provider corrente quando possibile).
|
||||
- `/model status` mostra la vista dettagliata, inclusi endpoint del provider configurato (`baseUrl`) e modalità API (`api`) quando disponibili.
|
||||
- `/model status` mostra la vista dettagliata, incluso l'endpoint del provider configurato (`baseUrl`) e la modalità API (`api`) quando disponibili.
|
||||
|
||||
## Override di debug
|
||||
|
||||
`/debug` ti consente di impostare override di configurazione **solo runtime** (in memoria, non su disco). Solo proprietario. Disabilitato per impostazione predefinita; abilitalo con `commands.debug: true`.
|
||||
`/debug` permette di impostare override di configurazione **solo runtime** (in memoria, non su disco). Solo proprietario. Disabilitato per impostazione predefinita; abilitalo con `commands.debug: true`.
|
||||
|
||||
Esempi:
|
||||
|
||||
```
|
||||
```text
|
||||
/debug show
|
||||
/debug set messages.responsePrefix="[openclaw]"
|
||||
/debug set channels.whatsapp.allowFrom=["+1555","+4477"]
|
||||
@ -277,12 +278,12 @@ Esempi:
|
||||
|
||||
Note:
|
||||
|
||||
- Gli override si applicano immediatamente alle nuove letture della configurazione, ma **non** scrivono in `openclaw.json`.
|
||||
- Gli override si applicano immediatamente alle nuove letture di configurazione, ma **non** scrivono in `openclaw.json`.
|
||||
- Usa `/debug reset` per cancellare tutti gli override e tornare alla configurazione su disco.
|
||||
|
||||
## Output trace del plugin
|
||||
## Output di trace dei plugin
|
||||
|
||||
`/trace` ti consente di attivare o disattivare **righe di trace/debug del plugin con scope di sessione** senza attivare la modalità verbose completa.
|
||||
`/trace` permette di attivare o disattivare **righe di trace/debug dei plugin con scope di sessione** senza attivare la modalità verbosa completa.
|
||||
|
||||
Esempi:
|
||||
|
||||
@ -294,12 +295,12 @@ Esempi:
|
||||
|
||||
Note:
|
||||
|
||||
- `/trace` senza argomento mostra lo stato trace corrente della sessione.
|
||||
- `/trace on` abilita le righe trace del plugin per la sessione corrente.
|
||||
- `/trace` senza argomenti mostra lo stato trace corrente della sessione.
|
||||
- `/trace on` abilita le righe di trace dei plugin per la sessione corrente.
|
||||
- `/trace off` le disabilita di nuovo.
|
||||
- Le righe trace del plugin possono comparire in `/status` e come messaggio diagnostico di follow-up dopo la normale risposta dell'assistant.
|
||||
- Le righe di trace dei plugin possono apparire in `/status` e come messaggio diagnostico di follow-up dopo la normale risposta dell'assistente.
|
||||
- `/trace` non sostituisce `/debug`; `/debug` continua a gestire gli override di configurazione solo runtime.
|
||||
- `/trace` non sostituisce `/verbose`; il normale output verbose di strumenti/stato continua a dipendere da `/verbose`.
|
||||
- `/trace` non sostituisce `/verbose`; il normale output verboso di tool/stato continua a competere a `/verbose`.
|
||||
|
||||
## Aggiornamenti della configurazione
|
||||
|
||||
@ -307,7 +308,7 @@ Note:
|
||||
|
||||
Esempi:
|
||||
|
||||
```
|
||||
```text
|
||||
/config show
|
||||
/config show messages.responsePrefix
|
||||
/config get messages.responsePrefix
|
||||
@ -317,7 +318,7 @@ Esempi:
|
||||
|
||||
Note:
|
||||
|
||||
- La configurazione viene convalidata prima della scrittura; le modifiche non valide vengono rifiutate.
|
||||
- La configurazione viene validata prima della scrittura; le modifiche non valide vengono rifiutate.
|
||||
- Gli aggiornamenti di `/config` persistono dopo i riavvii.
|
||||
|
||||
## Aggiornamenti MCP
|
||||
@ -335,12 +336,12 @@ Esempi:
|
||||
|
||||
Note:
|
||||
|
||||
- `/mcp` memorizza la configurazione nella configurazione OpenClaw, non nelle impostazioni di progetto gestite da Pi.
|
||||
- Gli adapter runtime decidono quali transport sono effettivamente eseguibili.
|
||||
- `/mcp` memorizza la configurazione nella configurazione OpenClaw, non nelle impostazioni di progetto di proprietà di Pi.
|
||||
- Gli adattatori runtime decidono quali trasporti sono effettivamente eseguibili.
|
||||
|
||||
## Aggiornamenti dei plugin
|
||||
|
||||
`/plugins` consente agli operatori di ispezionare i plugin rilevati e attivarli/disattivarli nella configurazione. I flussi di sola lettura possono usare `/plugin` come alias. Disabilitato per impostazione predefinita; abilitalo con `commands.plugins: true`.
|
||||
`/plugins` consente agli operatori di ispezionare i plugin rilevati e attivare/disattivare l'abilitazione nella configurazione. I flussi in sola lettura possono usare `/plugin` come alias. Disabilitato per impostazione predefinita; abilitalo con `commands.plugins: true`.
|
||||
|
||||
Esempi:
|
||||
|
||||
@ -354,19 +355,19 @@ Esempi:
|
||||
|
||||
Note:
|
||||
|
||||
- `/plugins list` e `/plugins show` usano il rilevamento reale dei plugin rispetto al workspace corrente più la configurazione su disco.
|
||||
- `/plugins enable|disable` aggiorna solo la configurazione del plugin; non installa né disinstalla i plugin.
|
||||
- Dopo modifiche di enable/disable, riavvia il gateway per applicarle.
|
||||
- `/plugins list` e `/plugins show` usano il reale rilevamento dei plugin rispetto al workspace corrente più la configurazione su disco.
|
||||
- `/plugins enable|disable` aggiorna solo la configurazione dei plugin; non installa né disinstalla plugin.
|
||||
- Dopo modifiche di abilitazione/disabilitazione, riavvia il gateway per applicarle.
|
||||
|
||||
## Note sulla surface
|
||||
## Note sulle superfici
|
||||
|
||||
- **I comandi testuali** vengono eseguiti nella normale sessione chat (i DM condividono `main`, i gruppi hanno una loro sessione).
|
||||
- **I comandi nativi** usano sessioni isolate:
|
||||
- **Comandi testuali** vengono eseguiti nella normale sessione chat (i DM condividono `main`, i gruppi hanno una propria sessione).
|
||||
- **Comandi nativi** usano sessioni isolate:
|
||||
- Discord: `agent:<agentId>:discord:slash:<userId>`
|
||||
- Slack: `agent:<agentId>:slack:slash:<userId>` (prefisso configurabile tramite `channels.slack.slashCommand.sessionPrefix`)
|
||||
- Telegram: `telegram:slash:<userId>` (punta alla sessione chat tramite `CommandTargetSessionKey`)
|
||||
- **`/stop`** prende di mira la sessione chat attiva così può interrompere l'esecuzione corrente.
|
||||
- **Slack:** `channels.slack.slashCommand` è ancora supportato per un singolo comando in stile `/openclaw`. Se abiliti `commands.native`, devi creare uno slash command Slack per ogni comando built-in (con gli stessi nomi di `/help`). I menu degli argomenti dei comandi per Slack vengono forniti come pulsanti effimeri Block Kit.
|
||||
- Telegram: `telegram:slash:<userId>` (ha come target la sessione chat tramite `CommandTargetSessionKey`)
|
||||
- **`/stop`** ha come target la sessione chat attiva così può interrompere l'esecuzione corrente.
|
||||
- **Slack:** `channels.slack.slashCommand` è ancora supportato per un singolo comando in stile `/openclaw`. Se abiliti `commands.native`, devi creare uno slash command Slack per ogni comando built-in (stessi nomi di `/help`). I menu degli argomenti dei comandi per Slack vengono distribuiti come pulsanti Block Kit effimeri.
|
||||
- Eccezione nativa Slack: registra `/agentstatus` (non `/status`) perché Slack riserva `/status`. Il testo `/status` continua comunque a funzionare nei messaggi Slack.
|
||||
|
||||
## Domande laterali BTW
|
||||
@ -375,20 +376,20 @@ Note:
|
||||
|
||||
A differenza della normale chat:
|
||||
|
||||
- usa la sessione corrente come contesto di sfondo,
|
||||
- viene eseguito come chiamata one-shot separata **senza strumenti**,
|
||||
- non modifica il contesto delle sessioni future,
|
||||
- non viene scritto nella cronologia della transcript,
|
||||
- viene consegnato come risultato laterale live invece che come normale messaggio dell'assistant.
|
||||
- usa la sessione corrente come contesto di background,
|
||||
- viene eseguito come chiamata one-shot separata **senza tool**,
|
||||
- non modifica il contesto futuro della sessione,
|
||||
- non viene scritto nella cronologia della trascrizione,
|
||||
- viene consegnato come risultato laterale live invece che come normale messaggio dell'assistente.
|
||||
|
||||
Questo rende `/btw` utile quando vuoi un chiarimento temporaneo mentre l'attività principale
|
||||
continua.
|
||||
Questo rende `/btw` utile quando vuoi un chiarimento temporaneo mentre il task
|
||||
principale continua.
|
||||
|
||||
Esempio:
|
||||
|
||||
```text
|
||||
/btw what are we doing right now?
|
||||
/btw cosa stiamo facendo in questo momento?
|
||||
```
|
||||
|
||||
Vedi [Domande laterali BTW](/it/tools/btw) per il comportamento completo e i dettagli
|
||||
Vedi [BTW Side Questions](/it/tools/btw) per il comportamento completo e i dettagli
|
||||
dell'esperienza utente del client.
|
||||
|
||||
@ -1,18 +1,18 @@
|
||||
---
|
||||
read_when:
|
||||
- Regolazione del parsing o dei valori predefiniti delle direttive di thinking, fast-mode o verbose
|
||||
summary: Sintassi delle direttive per /think, /fast, /verbose, /trace e visibilità del ragionamento
|
||||
title: Livelli di pensiero
|
||||
- Regolazione dell'analisi o dei valori predefiniti delle direttive thinking, fast-mode o verbose
|
||||
summary: Sintassi delle direttive per /think, /fast, /verbose, /trace e visibilità del reasoning
|
||||
title: Livelli di thinking
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T08:37:46Z"
|
||||
generated_at: "2026-04-23T13:59:55Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 66033bb9272c9b9ea8fc85dc91e33e95ce4c469c56a8cd10c19632a5aa8a2338
|
||||
source_hash: 4efe899f7b47244745a105583b3239effa7975fadd06bd7bcad6327afcc91207
|
||||
source_path: tools/thinking.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Livelli di pensiero (/think directives)
|
||||
# Livelli di thinking (direttive /think)
|
||||
|
||||
## Cosa fa
|
||||
|
||||
@ -22,111 +22,111 @@ x-i18n:
|
||||
- low → “think hard”
|
||||
- medium → “think harder”
|
||||
- high → “ultrathink” (budget massimo)
|
||||
- xhigh → “ultrathink+” (modelli GPT-5.2 + Codex e livello di effort di Anthropic Claude Opus 4.7)
|
||||
- xhigh → “ultrathink+” (sforzo GPT-5.2 + modelli Codex e Anthropic Claude Opus 4.7)
|
||||
- adaptive → thinking adattivo gestito dal provider (supportato per Claude 4.6 su Anthropic/Bedrock e Anthropic Claude Opus 4.7)
|
||||
- max → reasoning massimo del provider (attualmente Anthropic Claude Opus 4.7)
|
||||
- `x-high`, `x_high`, `extra-high`, `extra high` e `extra_high` vengono mappati a `xhigh`.
|
||||
- `highest` viene mappato a `high`.
|
||||
- `x-high`, `x_high`, `extra-high`, `extra high` e `extra_high` corrispondono a `xhigh`.
|
||||
- `highest` corrisponde a `high`.
|
||||
- Note sui provider:
|
||||
- I menu e i selettori di thinking sono guidati dal profilo provider. I Plugin provider dichiarano l'esatto insieme di livelli per il modello selezionato, incluse etichette come il binario `on`.
|
||||
- `adaptive`, `xhigh` e `max` vengono pubblicizzati solo per i profili provider/modello che li supportano. Le direttive tipizzate per livelli non supportati vengono rifiutate con le opzioni valide di quel modello.
|
||||
- I livelli memorizzati esistenti ma non supportati vengono rimappati in base al rank del profilo provider. `adaptive` usa come fallback `medium` sui modelli non adattivi, mentre `xhigh` e `max` usano come fallback il più grande livello supportato diverso da off per il modello selezionato.
|
||||
- I modelli Anthropic Claude 4.6 usano come predefinito `adaptive` quando non è impostato alcun livello di thinking esplicito.
|
||||
- Anthropic Claude Opus 4.7 non usa il thinking adattivo come predefinito. Il valore predefinito dell'API per effort resta di proprietà del provider a meno che tu non imposti esplicitamente un livello di thinking.
|
||||
- Anthropic Claude Opus 4.7 mappa `/think xhigh` a thinking adattivo più `output_config.effort: "xhigh"`, perché `/think` è una direttiva di thinking e `xhigh` è l'impostazione di effort di Opus 4.7.
|
||||
- Anthropic Claude Opus 4.7 espone anche `/think max`; viene mappato allo stesso percorso max effort di proprietà del provider.
|
||||
- I modelli OpenAI GPT mappano `/think` tramite il supporto effort dell'API Responses specifico del modello. `/think off` invia `reasoning.effort: "none"` solo quando il modello di destinazione lo supporta; altrimenti OpenClaw omette il payload di reasoning disabilitato invece di inviare un valore non supportato.
|
||||
- MiniMax (`minimax/*`) sul percorso streaming compatibile con Anthropic usa come predefinito `thinking: { type: "disabled" }` a meno che tu non imposti esplicitamente il thinking nei parametri del modello o nei parametri della richiesta. Questo evita delta `reasoning_content` trapelati dal formato stream Anthropic non nativo di MiniMax.
|
||||
- Z.AI (`zai/*`) supporta solo thinking binario (`on`/`off`). Qualsiasi livello diverso da `off` viene trattato come `on` (mappato a `low`).
|
||||
- I menu e i selettori di thinking sono guidati dal profilo del provider. I plugin provider dichiarano l'insieme esatto di livelli per il modello selezionato, incluse etichette come il binario `on`.
|
||||
- `adaptive`, `xhigh` e `max` vengono pubblicizzati solo per i profili provider/modello che li supportano. Le direttive digitate per livelli non supportati vengono rifiutate con le opzioni valide di quel modello.
|
||||
- I livelli non supportati già memorizzati vengono rimappati in base al rango del profilo provider. `adaptive` ricade su `medium` nei modelli non adattivi, mentre `xhigh` e `max` ricadono sul livello non `off` più alto supportato per il modello selezionato.
|
||||
- I modelli Anthropic Claude 4.6 usano `adaptive` per impostazione predefinita quando non è impostato alcun livello di thinking esplicito.
|
||||
- Anthropic Claude Opus 4.7 non usa il thinking adattivo come predefinito. Il suo valore predefinito di effort API resta gestito dal provider a meno che tu non imposti esplicitamente un livello di thinking.
|
||||
- Anthropic Claude Opus 4.7 mappa `/think xhigh` al thinking adattivo più `output_config.effort: "xhigh"`, perché `/think` è una direttiva di thinking e `xhigh` è l'impostazione di effort di Opus 4.7.
|
||||
- Anthropic Claude Opus 4.7 espone anche `/think max`; viene mappato allo stesso percorso di effort massimo gestito dal provider.
|
||||
- I modelli OpenAI GPT mappano `/think` tramite il supporto `effort` specifico del modello nella Responses API. `/think off` invia `reasoning.effort: "none"` solo quando il modello di destinazione lo supporta; altrimenti OpenClaw omette il payload di reasoning disabilitato invece di inviare un valore non supportato.
|
||||
- MiniMax (`minimax/*`) sul percorso di streaming compatibile con Anthropic usa per impostazione predefinita `thinking: { type: "disabled" }` a meno che tu non imposti esplicitamente il thinking nei parametri del modello o della richiesta. Questo evita delta `reasoning_content` trapelati dal formato di stream Anthropic non nativo di MiniMax.
|
||||
- Z.AI (`zai/*`) supporta solo thinking binario (`on`/`off`). Qualsiasi livello diverso da `off` viene trattato come `on` (mappato su `low`).
|
||||
- Moonshot (`moonshot/*`) mappa `/think off` a `thinking: { type: "disabled" }` e qualsiasi livello diverso da `off` a `thinking: { type: "enabled" }`. Quando il thinking è abilitato, Moonshot accetta solo `tool_choice` `auto|none`; OpenClaw normalizza i valori incompatibili in `auto`.
|
||||
|
||||
## Ordine di risoluzione
|
||||
|
||||
1. Direttiva inline nel messaggio (si applica solo a quel messaggio).
|
||||
2. Override di sessione (impostato inviando un messaggio contenente solo la direttiva).
|
||||
3. Predefinito per agente (`agents.list[].thinkingDefault` nella configurazione).
|
||||
4. Predefinito globale (`agents.defaults.thinkingDefault` nella configurazione).
|
||||
5. Fallback: predefinito dichiarato dal provider quando disponibile, `low` per altri modelli del catalogo contrassegnati come capaci di reasoning, `off` altrimenti.
|
||||
3. Valore predefinito per agente (`agents.list[].thinkingDefault` nella config).
|
||||
4. Valore predefinito globale (`agents.defaults.thinkingDefault` nella config).
|
||||
5. Fallback: valore predefinito dichiarato dal provider quando disponibile; altrimenti i modelli con capacità di reasoning risolvono a `medium` o al livello non `off` supportato più vicino per quel modello, e i modelli senza reasoning restano `off`.
|
||||
|
||||
## Impostazione di un valore predefinito di sessione
|
||||
|
||||
- Invia un messaggio che contenga **solo** la direttiva (spazi consentiti), ad esempio `/think:medium` oppure `/t high`.
|
||||
- Questo resta attivo per la sessione corrente (per mittente per impostazione predefinita); viene cancellato da `/think:off` o dal reset per inattività della sessione.
|
||||
- Viene inviata una risposta di conferma (`Thinking level set to high.` / `Thinking disabled.`). Se il livello non è valido (ad esempio `/thinking big`), il comando viene rifiutato con un suggerimento e lo stato della sessione resta invariato.
|
||||
- Invia `/think` (oppure `/think:`) senza argomento per vedere il livello di thinking corrente.
|
||||
- Invia un messaggio che sia **solo** la direttiva (spazi consentiti), per esempio `/think:medium` o `/t high`.
|
||||
- Rimane per la sessione corrente (per mittente per impostazione predefinita); viene cancellato da `/think:off` o dal reset per inattività della sessione.
|
||||
- Viene inviata una risposta di conferma (`Thinking level set to high.` / `Thinking disabled.`). Se il livello non è valido (per esempio `/thinking big`), il comando viene rifiutato con un suggerimento e lo stato della sessione rimane invariato.
|
||||
- Invia `/think` (o `/think:`) senza argomento per vedere il livello di thinking corrente.
|
||||
|
||||
## Applicazione per agente
|
||||
|
||||
- **Pi incorporato**: il livello risolto viene passato al runtime dell'agente Pi in-process.
|
||||
|
||||
## Modalità fast (/fast)
|
||||
## Modalità veloce (/fast)
|
||||
|
||||
- Livelli: `on|off`.
|
||||
- Un messaggio contenente solo la direttiva attiva/disattiva un override di sessione della modalità fast e risponde con `Fast mode enabled.` / `Fast mode disabled.`.
|
||||
- Invia `/fast` (oppure `/fast status`) senza modalità per vedere lo stato effettivo corrente della modalità fast.
|
||||
- OpenClaw risolve la modalità fast in questo ordine:
|
||||
- Un messaggio contenente solo la direttiva attiva/disattiva un override di sessione della modalità veloce e risponde `Fast mode enabled.` / `Fast mode disabled.`.
|
||||
- Invia `/fast` (o `/fast status`) senza modalità per vedere lo stato effettivo corrente della modalità veloce.
|
||||
- OpenClaw risolve la modalità veloce in questo ordine:
|
||||
1. `/fast on|off` inline/con sola direttiva
|
||||
2. Override di sessione
|
||||
3. Predefinito per agente (`agents.list[].fastModeDefault`)
|
||||
4. Configurazione per modello: `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
3. Valore predefinito per agente (`agents.list[].fastModeDefault`)
|
||||
4. Config per modello: `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
5. Fallback: `off`
|
||||
- Per `openai/*`, la modalità fast si mappa all'elaborazione prioritaria OpenAI inviando `service_tier=priority` sulle richieste Responses supportate.
|
||||
- Per `openai-codex/*`, la modalità fast invia lo stesso flag `service_tier=priority` sulle Responses Codex. OpenClaw mantiene un unico toggle `/fast` condiviso su entrambi i percorsi auth.
|
||||
- Per richieste dirette pubbliche `anthropic/*`, incluso il traffico autenticato OAuth inviato a `api.anthropic.com`, la modalità fast si mappa ai service tier di Anthropic: `/fast on` imposta `service_tier=auto`, `/fast off` imposta `service_tier=standard_only`.
|
||||
- Per `minimax/*` sul percorso compatibile con Anthropic, `/fast on` (oppure `params.fastMode: true`) riscrive `MiniMax-M2.7` in `MiniMax-M2.7-highspeed`.
|
||||
- I parametri espliciti del modello Anthropic `serviceTier` / `service_tier` sovrascrivono il valore predefinito della modalità fast quando entrambi sono impostati. OpenClaw continua comunque a saltare l'iniezione del service tier Anthropic per URL base proxy non Anthropic.
|
||||
- `/status` mostra `Fast` solo quando la modalità fast è abilitata.
|
||||
- Per `openai/*`, la modalità veloce viene mappata all'elaborazione prioritaria di OpenAI inviando `service_tier=priority` nelle richieste Responses supportate.
|
||||
- Per `openai-codex/*`, la modalità veloce invia lo stesso flag `service_tier=priority` su Codex Responses. OpenClaw mantiene un unico interruttore condiviso `/fast` su entrambi i percorsi di autenticazione.
|
||||
- Per richieste `anthropic/*` pubbliche dirette, incluso il traffico autenticato via OAuth inviato a `api.anthropic.com`, la modalità veloce viene mappata ai service tier Anthropic: `/fast on` imposta `service_tier=auto`, `/fast off` imposta `service_tier=standard_only`.
|
||||
- Per `minimax/*` sul percorso compatibile con Anthropic, `/fast on` (o `params.fastMode: true`) riscrive `MiniMax-M2.7` in `MiniMax-M2.7-highspeed`.
|
||||
- I parametri di modello espliciti Anthropic `serviceTier` / `service_tier` sostituiscono il valore predefinito della modalità veloce quando entrambi sono impostati. OpenClaw continua comunque a saltare l'iniezione del service tier Anthropic per URL base proxy non Anthropic.
|
||||
- `/status` mostra `Fast` solo quando la modalità veloce è abilitata.
|
||||
|
||||
## Direttive verbose (/verbose oppure /v)
|
||||
## Direttive verbose (/verbose o /v)
|
||||
|
||||
- Livelli: `on` (minimal) | `full` | `off` (predefinito).
|
||||
- Un messaggio contenente solo la direttiva attiva/disattiva il verbose di sessione e risponde con `Verbose logging enabled.` / `Verbose logging disabled.`; livelli non validi restituiscono un suggerimento senza modificare lo stato.
|
||||
- Livelli: `on` (minimo) | `full` | `off` (predefinito).
|
||||
- Un messaggio contenente solo la direttiva attiva/disattiva il verbose di sessione e risponde `Verbose logging enabled.` / `Verbose logging disabled.`; i livelli non validi restituiscono un suggerimento senza cambiare lo stato.
|
||||
- `/verbose off` memorizza un override di sessione esplicito; cancellalo tramite l'interfaccia Sessions scegliendo `inherit`.
|
||||
- La direttiva inline influenza solo quel messaggio; altrimenti si applicano i valori predefiniti di sessione/globali.
|
||||
- Invia `/verbose` (oppure `/verbose:`) senza argomento per vedere il livello verbose corrente.
|
||||
- Quando verbose è attivo, gli agenti che emettono risultati strutturati dei tool (Pi, altri agenti JSON) rimandano ogni chiamata tool come proprio messaggio solo-metadati, con prefisso `<emoji> <tool-name>: <arg>` quando disponibile (percorso/comando). Questi riepiloghi dei tool vengono inviati non appena ogni tool inizia (bolle separate), non come delta in streaming.
|
||||
- I riepiloghi dei fallimenti dei tool restano visibili in modalità normale, ma i suffissi con i dettagli grezzi degli errori sono nascosti a meno che verbose non sia `on` o `full`.
|
||||
- Quando verbose è `full`, anche gli output dei tool vengono inoltrati dopo il completamento (bolla separata, troncata a una lunghezza sicura). Se cambi `/verbose on|full|off` mentre un'esecuzione è in corso, le bolle successive dei tool rispettano la nuova impostazione.
|
||||
- La direttiva inline si applica solo a quel messaggio; in caso contrario si applicano i valori predefiniti di sessione/globali.
|
||||
- Invia `/verbose` (o `/verbose:`) senza argomento per vedere il livello verbose corrente.
|
||||
- Quando verbose è attivo, gli agenti che emettono risultati strutturati degli strumenti (Pi, altri agenti JSON) rimandano ogni chiamata di strumento come proprio messaggio solo metadati, con prefisso `<emoji> <tool-name>: <arg>` quando disponibile (path/comando). Questi riepiloghi degli strumenti vengono inviati non appena ogni strumento si avvia (bolle separate), non come delta in streaming.
|
||||
- I riepiloghi dei fallimenti degli strumenti restano visibili in modalità normale, ma i suffissi dei dettagli di errore grezzi sono nascosti a meno che verbose non sia `on` o `full`.
|
||||
- Quando verbose è `full`, anche gli output degli strumenti vengono inoltrati dopo il completamento (bolla separata, troncata a una lunghezza sicura). Se attivi `/verbose on|full|off` mentre un'esecuzione è in corso, le bolle degli strumenti successive rispettano la nuova impostazione.
|
||||
|
||||
## Direttive di trace dei Plugin (/trace)
|
||||
## Direttive di trace del plugin (/trace)
|
||||
|
||||
- Livelli: `on` | `off` (predefinito).
|
||||
- Un messaggio contenente solo la direttiva attiva/disattiva l'output trace dei Plugin di sessione e risponde con `Plugin trace enabled.` / `Plugin trace disabled.`.
|
||||
- La direttiva inline influenza solo quel messaggio; altrimenti si applicano i valori predefiniti di sessione/globali.
|
||||
- Invia `/trace` (oppure `/trace:`) senza argomento per vedere il livello trace corrente.
|
||||
- `/trace` è più ristretto di `/verbose`: espone solo righe trace/debug di proprietà dei Plugin come i riepiloghi di debug di Active Memory.
|
||||
- Le righe trace possono comparire in `/status` e come messaggio diagnostico di follow-up dopo la normale risposta dell'assistente.
|
||||
- Un messaggio contenente solo la direttiva attiva/disattiva l'output di trace del plugin per la sessione e risponde `Plugin trace enabled.` / `Plugin trace disabled.`.
|
||||
- La direttiva inline si applica solo a quel messaggio; in caso contrario si applicano i valori predefiniti di sessione/globali.
|
||||
- Invia `/trace` (o `/trace:`) senza argomento per vedere il livello di trace corrente.
|
||||
- `/trace` è più ristretto di `/verbose`: espone solo righe di trace/debug possedute dal plugin, come i riepiloghi di debug di Active Memory.
|
||||
- Le righe di trace possono comparire in `/status` e come messaggio diagnostico di follow-up dopo la normale risposta dell'assistente.
|
||||
|
||||
## Visibilità del reasoning (/reasoning)
|
||||
|
||||
- Livelli: `on|off|stream`.
|
||||
- Un messaggio contenente solo la direttiva attiva/disattiva la visualizzazione dei blocchi di thinking nelle risposte.
|
||||
- Quando abilitato, il reasoning viene inviato come **messaggio separato** con prefisso `Reasoning:`.
|
||||
- `stream` (solo Telegram): trasmette il reasoning nella bolla draft di Telegram mentre la risposta viene generata, poi invia la risposta finale senza reasoning.
|
||||
- Quando è abilitata, il reasoning viene inviato come **messaggio separato** con prefisso `Reasoning:`.
|
||||
- `stream` (solo Telegram): trasmette il reasoning nella bolla bozza di Telegram mentre la risposta viene generata, poi invia la risposta finale senza reasoning.
|
||||
- Alias: `/reason`.
|
||||
- Invia `/reasoning` (oppure `/reasoning:`) senza argomento per vedere il livello di reasoning corrente.
|
||||
- Ordine di risoluzione: direttiva inline, poi override di sessione, poi predefinito per agente (`agents.list[].reasoningDefault`), poi fallback (`off`).
|
||||
- Invia `/reasoning` (o `/reasoning:`) senza argomento per vedere il livello di reasoning corrente.
|
||||
- Ordine di risoluzione: direttiva inline, poi override di sessione, poi valore predefinito per agente (`agents.list[].reasoningDefault`), poi fallback (`off`).
|
||||
|
||||
## Correlati
|
||||
|
||||
- La documentazione della modalità Elevated si trova in [Modalità Elevated](/it/tools/elevated).
|
||||
- La documentazione della modalità elevata si trova in [Modalità elevata](/it/tools/elevated).
|
||||
|
||||
## Heartbeat
|
||||
|
||||
- Il corpo del probe Heartbeat è il prompt Heartbeat configurato (predefinito: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Le direttive inline in un messaggio Heartbeat si applicano normalmente (ma evita di cambiare i valori predefiniti di sessione dagli Heartbeat).
|
||||
- La consegna Heartbeat usa come predefinito solo il payload finale. Per inviare anche il messaggio separato `Reasoning:` (quando disponibile), imposta `agents.defaults.heartbeat.includeReasoning: true` oppure `agents.list[].heartbeat.includeReasoning: true` per agente.
|
||||
- Il corpo della probe Heartbeat è il prompt Heartbeat configurato (predefinito: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Le direttive inline in un messaggio Heartbeat si applicano normalmente (ma evita di cambiare i valori predefiniti della sessione dai Heartbeat).
|
||||
- La consegna di Heartbeat usa per impostazione predefinita solo il payload finale. Per inviare anche il messaggio separato `Reasoning:` (quando disponibile), imposta `agents.defaults.heartbeat.includeReasoning: true` oppure per agente `agents.list[].heartbeat.includeReasoning: true`.
|
||||
|
||||
## Web chat UI
|
||||
## Interfaccia web chat
|
||||
|
||||
- Il selettore di thinking della web chat rispecchia il livello memorizzato della sessione dall'inbound session store/config quando la pagina viene caricata.
|
||||
- Scegliere un altro livello scrive immediatamente l'override di sessione tramite `sessions.patch`; non attende l'invio successivo e non è un override one-shot `thinkingOnce`.
|
||||
- La prima opzione è sempre `Default (<resolved level>)`, dove il valore predefinito risolto proviene dal profilo di thinking del provider del modello di sessione attivo.
|
||||
- Il selettore usa `thinkingOptions` restituito dalla riga di sessione del Gateway. L'interfaccia browser non mantiene un proprio elenco regex di provider; i Plugin gestiscono gli insiemi di livelli specifici del modello.
|
||||
- `/think:<level>` continua a funzionare e aggiorna lo stesso livello di sessione memorizzato, così direttive chat e selettore restano sincronizzati.
|
||||
- Il selettore di thinking della chat web rispecchia il livello memorizzato della sessione dall'archivio/config della sessione in ingresso quando la pagina viene caricata.
|
||||
- La selezione di un altro livello scrive immediatamente l'override di sessione tramite `sessions.patch`; non aspetta l'invio successivo e non è un override one-shot `thinkingOnce`.
|
||||
- La prima opzione è sempre `Default (<resolved level>)`, dove il valore predefinito risolto deriva dal profilo di thinking del provider del modello di sessione attivo più la stessa logica di fallback usata da `/status` e `session_status`.
|
||||
- Il selettore usa `thinkingOptions` restituito dalla riga della sessione del Gateway. L'interfaccia browser non mantiene un proprio elenco regex dei provider; i plugin possiedono gli insiemi di livelli specifici del modello.
|
||||
- `/think:<level>` continua a funzionare e aggiorna lo stesso livello di sessione memorizzato, quindi le direttive della chat e il selettore restano sincronizzati.
|
||||
|
||||
## Profili provider
|
||||
|
||||
- I Plugin provider possono esporre `resolveThinkingProfile(ctx)` per definire i livelli supportati e il valore predefinito del modello.
|
||||
- Ogni livello del profilo ha un `id` canonico memorizzato (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` oppure `max`) e può includere un `label` di visualizzazione. I provider binari usano `{ id: "low", label: "on" }`.
|
||||
- Gli hook legacy pubblicati (`supportsXHighThinking`, `isBinaryThinking` e `resolveDefaultThinkingLevel`) restano come adapter di compatibilità, ma i nuovi insiemi di livelli personalizzati dovrebbero usare `resolveThinkingProfile`.
|
||||
- Le righe del Gateway espongono `thinkingOptions` e `thinkingDefault` così i client ACP/chat rendono lo stesso profilo usato dalla validazione runtime.
|
||||
- I plugin provider possono esporre `resolveThinkingProfile(ctx)` per definire i livelli supportati e il valore predefinito del modello.
|
||||
- Ogni livello del profilo ha un `id` canonico memorizzato (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` o `max`) e può includere una `label` di visualizzazione. I provider binari usano `{ id: "low", label: "on" }`.
|
||||
- Gli hook legacy pubblicati (`supportsXHighThinking`, `isBinaryThinking` e `resolveDefaultThinkingLevel`) restano come adattatori di compatibilità, ma i nuovi insiemi di livelli personalizzati dovrebbero usare `resolveThinkingProfile`.
|
||||
- Le righe del Gateway espongono `thinkingOptions` e `thinkingDefault` così i client ACP/chat renderizzano lo stesso profilo usato dalla validazione runtime.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user