chore(i18n): refresh it translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
c5cbe0b9c2
commit
ff37537c91
@ -1,66 +1,66 @@
|
||||
---
|
||||
read_when:
|
||||
- Configurazione del controllo di accesso ai DM
|
||||
- Associazione di un nuovo nodo iOS/Android
|
||||
- Revisione della postura di sicurezza di OpenClaw
|
||||
- Abbinamento di un nuovo nodo iOS/Android
|
||||
- Esaminare la postura di sicurezza di OpenClaw
|
||||
summary: 'Panoramica dell''associazione: approva chi può inviarti messaggi diretti + quali nodi possono unirsi'
|
||||
title: Abbinamento
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T02:21:53Z"
|
||||
generated_at: "2026-05-04T08:40:01Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 4fb27840f7c9ef55e7270cc29f813e6db90b240aa2180f30952eb9485f0f8874
|
||||
source_hash: f2bce4cfba7708b0003f2ffeacada8bc1849cc301f28178b499a9a67bddcf36d
|
||||
source_path: channels/pairing.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
“Abbinamento” è il passaggio esplicito di approvazione dell'accesso di OpenClaw.
|
||||
Viene usato in due punti:
|
||||
“Associazione” è il passaggio esplicito di approvazione dell'accesso di OpenClaw.
|
||||
Viene usata in due punti:
|
||||
|
||||
1. **Abbinamento DM** (chi può parlare con il bot)
|
||||
2. **Abbinamento Node** (quali dispositivi/nodi possono unirsi alla rete Gateway)
|
||||
1. **Associazione DM** (chi è autorizzato a parlare con il bot)
|
||||
2. **Associazione Node** (quali dispositivi/nodi sono autorizzati a unirsi alla rete Gateway)
|
||||
|
||||
Contesto di sicurezza: [Sicurezza](/it/gateway/security)
|
||||
|
||||
## 1) Abbinamento DM (accesso chat in ingresso)
|
||||
## 1) Associazione DM (accesso chat in ingresso)
|
||||
|
||||
Quando un canale è configurato con la policy DM `pairing`, i mittenti sconosciuti ricevono un codice breve e il loro messaggio **non viene elaborato** finché non approvi.
|
||||
|
||||
Le policy DM predefinite sono documentate in: [Sicurezza](/it/gateway/security)
|
||||
|
||||
`dmPolicy: "open"` è pubblica solo quando l'elenco consentiti DM effettivo include `"*"`.
|
||||
La configurazione e la convalida richiedono quel carattere jolly per le configurazioni pubbliche aperte. Se lo stato esistente
|
||||
contiene `open` con voci `allowFrom` concrete, a runtime continuano a essere ammessi
|
||||
solo quei mittenti, e le approvazioni nello store di abbinamento non ampliano l'accesso `open`.
|
||||
`dmPolicy: "open"` è pubblico solo quando la lista consentiti DM effettiva include `"*"`.
|
||||
Configurazione e convalida richiedono quel carattere jolly per le configurazioni aperte al pubblico. Se lo stato esistente
|
||||
contiene `open` con voci `allowFrom` concrete, in fase di runtime vengono comunque ammessi
|
||||
solo quei mittenti, e le approvazioni nell'archivio di associazione non ampliano l'accesso `open`.
|
||||
|
||||
Codici di abbinamento:
|
||||
Codici di associazione:
|
||||
|
||||
- 8 caratteri, maiuscoli, senza caratteri ambigui (`0O1I`).
|
||||
- **Scadono dopo 1 ora**. Il bot invia il messaggio di abbinamento solo quando viene creata una nuova richiesta (circa una volta all'ora per mittente).
|
||||
- Le richieste di abbinamento DM in sospeso sono limitate a **3 per canale** per impostazione predefinita; le richieste aggiuntive vengono ignorate finché una non scade o viene approvata.
|
||||
- **Scadono dopo 1 ora**. Il bot invia il messaggio di associazione solo quando viene creata una nuova richiesta (circa una volta all'ora per mittente).
|
||||
- Le richieste di associazione DM in sospeso sono limitate a **3 per canale** per impostazione predefinita; le richieste aggiuntive vengono ignorate finché una non scade o viene approvata.
|
||||
|
||||
### Approvare un mittente
|
||||
### Approva un mittente
|
||||
|
||||
```bash
|
||||
openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Se non è ancora configurato alcun proprietario dei comandi, l'approvazione di un codice di abbinamento DM inizializza anche
|
||||
Se non è ancora configurato alcun proprietario dei comandi, l'approvazione di un codice di associazione DM inizializza anche
|
||||
`commands.ownerAllowFrom` sul mittente approvato, ad esempio `telegram:123456789`.
|
||||
Questo assegna alle configurazioni iniziali un proprietario esplicito per i comandi privilegiati e le richieste di approvazione
|
||||
exec. Dopo che esiste un proprietario, le approvazioni di abbinamento successive concedono solo l'accesso DM;
|
||||
Questo assegna alle configurazioni iniziali un proprietario esplicito per comandi privilegiati e prompt di approvazione
|
||||
exec. Dopo che esiste un proprietario, le approvazioni di associazione successive concedono solo accesso DM;
|
||||
non aggiungono altri proprietari.
|
||||
|
||||
Canali supportati: `bluebubbles`, `discord`, `feishu`, `googlechat`, `imessage`, `irc`, `line`, `matrix`, `mattermost`, `msteams`, `nextcloud-talk`, `nostr`, `openclaw-weixin`, `signal`, `slack`, `synology-chat`, `telegram`, `twitch`, `whatsapp`, `zalo`, `zalouser`.
|
||||
|
||||
### Gruppi di mittenti riutilizzabili
|
||||
|
||||
Usa `accessGroups` di primo livello quando lo stesso insieme di mittenti fidati deve applicarsi a
|
||||
più canali di messaggistica o sia agli elenchi consentiti DM sia a quelli di gruppo.
|
||||
Usa `accessGroups` di primo livello quando lo stesso insieme di mittenti attendibili deve applicarsi a
|
||||
più canali di messaggistica o sia alle liste consentiti DM sia a quelle di gruppo.
|
||||
|
||||
I gruppi statici usano `type: "message.senders"` e vengono referenziati con
|
||||
`accessGroup:<name>` dagli elenchi consentiti dei canali:
|
||||
I gruppi statici usano `type: "message.senders"` e sono referenziati con
|
||||
`accessGroup:<name>` dalle liste consentiti del canale:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -83,65 +83,72 @@ I gruppi statici usano `type: "message.senders"` e vengono referenziati con
|
||||
|
||||
I gruppi di accesso sono documentati in dettaglio qui: [Gruppi di accesso](/it/channels/access-groups)
|
||||
|
||||
### Dove si trova lo stato
|
||||
### Dove risiede lo stato
|
||||
|
||||
Archiviato sotto `~/.openclaw/credentials/`:
|
||||
Memorizzato sotto `~/.openclaw/credentials/`:
|
||||
|
||||
- Richieste in sospeso: `<channel>-pairing.json`
|
||||
- Store dell'elenco consentiti approvato:
|
||||
- Archivio della lista consentiti approvata:
|
||||
- Account predefinito: `<channel>-allowFrom.json`
|
||||
- Account non predefinito: `<channel>-<accountId>-allowFrom.json`
|
||||
|
||||
Comportamento dell'ambito account:
|
||||
Comportamento di ambito dell'account:
|
||||
|
||||
- Gli account non predefiniti leggono/scrivono solo il loro file di elenco consentiti con ambito.
|
||||
- L'account predefinito usa il file di elenco consentiti senza ambito, con ambito di canale.
|
||||
- Gli account non predefiniti leggono/scrivono solo il proprio file di lista consentiti con ambito.
|
||||
- L'account predefinito usa il file di lista consentiti senza ambito a livello di canale.
|
||||
|
||||
Trattali come sensibili (regolano l'accesso al tuo assistente).
|
||||
Trattali come sensibili (controllano l'accesso al tuo assistente).
|
||||
|
||||
<Note>
|
||||
Lo store dell'elenco consentiti di abbinamento è per l'accesso DM. L'autorizzazione dei gruppi è separata.
|
||||
L'approvazione di un codice di abbinamento DM non consente automaticamente a quel mittente di eseguire comandi di gruppo
|
||||
L'archivio della lista consentiti di associazione è per l'accesso DM. L'autorizzazione di gruppo è separata.
|
||||
L'approvazione di un codice di associazione DM non consente automaticamente a quel mittente di eseguire comandi di gruppo
|
||||
o controllare il bot nei gruppi. L'inizializzazione del primo proprietario è uno stato di configurazione separato
|
||||
in `commands.ownerAllowFrom`, e la consegna nelle chat di gruppo segue comunque gli elenchi consentiti di gruppo
|
||||
in `commands.ownerAllowFrom`, e la consegna nelle chat di gruppo segue comunque le liste consentiti di gruppo
|
||||
del canale (ad esempio `groupAllowFrom`, `groups`, oppure override per gruppo
|
||||
o per argomento a seconda del canale).
|
||||
</Note>
|
||||
|
||||
## 2) Abbinamento dei dispositivi Node (nodi iOS/Android/macOS/headless)
|
||||
## 2) Associazione dei dispositivi Node (iOS/Android/macOS/Node headless)
|
||||
|
||||
I Node si connettono al Gateway come **dispositivi** con `role: node`. Il Gateway
|
||||
crea una richiesta di abbinamento dispositivo che deve essere approvata.
|
||||
crea una richiesta di associazione dispositivo che deve essere approvata.
|
||||
|
||||
### Abbina tramite Telegram (consigliato per iOS)
|
||||
### Associa tramite Telegram (consigliato per iOS)
|
||||
|
||||
Se usi il Plugin `device-pair`, puoi completare il primo abbinamento del dispositivo interamente da Telegram:
|
||||
Se usi il Plugin `device-pair`, puoi eseguire l'associazione iniziale del dispositivo interamente da Telegram:
|
||||
|
||||
1. In Telegram, invia un messaggio al tuo bot: `/pair`
|
||||
2. Il bot risponde con due messaggi: un messaggio di istruzioni e un messaggio separato con il **codice di configurazione** (facile da copiare/incollare in Telegram).
|
||||
3. Sul telefono, apri l'app iOS OpenClaw → Impostazioni → Gateway.
|
||||
4. Incolla il codice di configurazione e connettiti.
|
||||
4. Scansiona il codice QR o incolla il codice di configurazione e connettiti.
|
||||
5. Di nuovo in Telegram: `/pair pending` (controlla ID richiesta, ruolo e ambiti), quindi approva.
|
||||
|
||||
Il codice di configurazione è un payload JSON codificato in base64 che contiene:
|
||||
|
||||
- `url`: l'URL WebSocket del Gateway (`ws://...` o `wss://...`)
|
||||
- `bootstrapToken`: un token di bootstrap a breve durata e per un singolo dispositivo usato per l'handshake di abbinamento iniziale
|
||||
- `bootstrapToken`: un token di bootstrap a breve durata per un solo dispositivo, usato per l'handshake di associazione iniziale
|
||||
|
||||
Quel token di bootstrap porta il profilo di bootstrap di abbinamento integrato:
|
||||
Quel token di bootstrap include il profilo di bootstrap di associazione integrato:
|
||||
|
||||
- il token `node` primario consegnato rimane `scopes: []`
|
||||
- qualsiasi token `operator` consegnato rimane limitato all'elenco consentiti di bootstrap:
|
||||
- il token `node` primario trasferito resta `scopes: []`
|
||||
- qualsiasi token `operator` trasferito resta limitato alla lista consentiti di bootstrap:
|
||||
`operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`
|
||||
- i controlli degli ambiti di bootstrap sono prefissati per ruolo, non un unico pool piatto di ambiti:
|
||||
le voci di ambito operatore soddisfano solo le richieste operatore, e i ruoli non operatore
|
||||
devono comunque richiedere ambiti sotto il proprio prefisso di ruolo
|
||||
- la successiva rotazione/revoca dei token rimane limitata sia dal contratto di ruolo approvato
|
||||
del dispositivo sia dagli ambiti operatore della sessione chiamante
|
||||
- i controlli degli ambiti di bootstrap hanno prefisso di ruolo, non un unico insieme piatto di ambiti:
|
||||
le voci di ambito operator soddisfano solo richieste operator, e i ruoli non operator
|
||||
devono comunque richiedere ambiti con il proprio prefisso di ruolo
|
||||
- la rotazione/revoca successiva dei token resta limitata sia dal contratto di ruolo approvato
|
||||
del dispositivo sia dagli ambiti operator della sessione chiamante
|
||||
|
||||
Tratta il codice di configurazione come una password finché è valido.
|
||||
|
||||
### Approvare un dispositivo Node
|
||||
Per Tailscale, accesso pubblico o altra associazione mobile non loopback, usa Tailscale
|
||||
Serve/Funnel o un altro URL Gateway `wss://`. Gli URL di configurazione diretti `ws://` non loopback
|
||||
vengono rifiutati prima dell'emissione del QR/codice di configurazione. I codici di configurazione
|
||||
`ws://` in chiaro sono limitati agli URL loopback; i client `ws://` su rete privata richiedono comunque l'esplicito
|
||||
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` break-glass descritto nella guida remota
|
||||
del Gateway.
|
||||
|
||||
### Approva un dispositivo Node
|
||||
|
||||
```bash
|
||||
openclaw devices list
|
||||
@ -149,25 +156,25 @@ openclaw devices approve <requestId>
|
||||
openclaw devices reject <requestId>
|
||||
```
|
||||
|
||||
Quando un'approvazione esplicita viene negata perché la sessione del dispositivo abbinato che approva
|
||||
è stata aperta con ambito di solo abbinamento, la CLI riprova la stessa richiesta con
|
||||
`operator.admin`. Questo consente a un dispositivo abbinato esistente con capacità admin di recuperare un nuovo
|
||||
abbinamento interfaccia di controllo/browser senza modificare `devices/paired.json` a mano. Il
|
||||
Quando un'approvazione esplicita viene negata perché la sessione del dispositivo associato che approva
|
||||
è stata aperta con ambito solo associazione, la CLI riprova la stessa richiesta con
|
||||
`operator.admin`. Questo consente a un dispositivo associato esistente con capacità admin di recuperare una nuova
|
||||
associazione Control UI/browser senza modificare `devices/paired.json` a mano. Il
|
||||
Gateway convalida comunque la connessione ritentata; i token che non possono autenticarsi
|
||||
con `operator.admin` rimangono bloccati.
|
||||
con `operator.admin` restano bloccati.
|
||||
|
||||
Se lo stesso dispositivo riprova con dettagli di autenticazione diversi (ad esempio ruolo/ambiti/chiave pubblica
|
||||
diversi), la richiesta in sospeso precedente viene sostituita e viene creato un nuovo
|
||||
`requestId`.
|
||||
|
||||
<Note>
|
||||
Un dispositivo già abbinato non ottiene silenziosamente un accesso più ampio. Se si riconnette chiedendo più ambiti o un ruolo più ampio, OpenClaw mantiene invariata l'approvazione esistente e crea una nuova richiesta di upgrade in sospeso. Usa `openclaw devices list` per confrontare l'accesso attualmente approvato con il nuovo accesso richiesto prima di approvare.
|
||||
Un dispositivo già associato non ottiene silenziosamente un accesso più ampio. Se si riconnette chiedendo più ambiti o un ruolo più ampio, OpenClaw mantiene l'approvazione esistente invariata e crea una nuova richiesta di aggiornamento in sospeso. Usa `openclaw devices list` per confrontare l'accesso attualmente approvato con il nuovo accesso richiesto prima di approvare.
|
||||
</Note>
|
||||
|
||||
### Approvazione automatica Node facoltativa con CIDR fidati
|
||||
### Approvazione automatica Node CIDR attendibile opzionale
|
||||
|
||||
L'abbinamento dei dispositivi resta manuale per impostazione predefinita. Per reti Node strettamente controllate,
|
||||
puoi attivare l'approvazione automatica del primo Node con CIDR espliciti o IP esatti:
|
||||
L'associazione dispositivo resta manuale per impostazione predefinita. Per reti Node strettamente controllate,
|
||||
puoi scegliere l'approvazione automatica iniziale dei Node con CIDR espliciti o IP esatti:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -181,24 +188,23 @@ puoi attivare l'approvazione automatica del primo Node con CIDR espliciti o IP e
|
||||
}
|
||||
```
|
||||
|
||||
Questo si applica solo a nuove richieste di abbinamento `role: node` senza
|
||||
ambiti richiesti. I client operatore, browser, interfaccia di controllo e WebChat richiedono comunque l'approvazione
|
||||
manuale. Le modifiche a ruolo, ambito, metadati e chiave pubblica richiedono comunque l'approvazione
|
||||
manuale.
|
||||
Questo si applica solo alle nuove richieste di associazione `role: node` senza ambiti richiesti.
|
||||
I client operator, browser, Control UI e WebChat richiedono comunque l'approvazione manuale.
|
||||
Le modifiche a ruolo, ambito, metadati e chiave pubblica richiedono comunque l'approvazione manuale.
|
||||
|
||||
### Archiviazione dello stato di abbinamento Node
|
||||
### Archiviazione dello stato di associazione Node
|
||||
|
||||
Archiviato sotto `~/.openclaw/devices/`:
|
||||
Memorizzato sotto `~/.openclaw/devices/`:
|
||||
|
||||
- `pending.json` (a breve durata; le richieste in sospeso scadono)
|
||||
- `paired.json` (dispositivi abbinati + token)
|
||||
- `paired.json` (dispositivi associati + token)
|
||||
|
||||
### Note
|
||||
|
||||
- L'API legacy `node.pair.*` (CLI: `openclaw nodes pending|approve|reject|remove|rename`) è uno
|
||||
store di abbinamento separato di proprietà del Gateway. I Node WS richiedono comunque l'abbinamento dispositivo.
|
||||
- Il record di abbinamento è la fonte di verità durevole per i ruoli approvati. I token
|
||||
dispositivo attivi rimangono limitati a quell'insieme di ruoli approvati; una voce token isolata
|
||||
- L'API legacy `node.pair.*` (CLI: `openclaw nodes pending|approve|reject|remove|rename`) è un
|
||||
archivio di associazione separato di proprietà del gateway. I Node WS richiedono comunque l'associazione dispositivo.
|
||||
- Il record di associazione è la fonte di verità durevole per i ruoli approvati. I token
|
||||
dispositivo attivi restano limitati a quell'insieme di ruoli approvati; una voce token isolata
|
||||
fuori dai ruoli approvati non crea nuovo accesso.
|
||||
|
||||
## Documenti correlati
|
||||
|
||||
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- Lavorare sulle funzionalità di Telegram o sui Webhook
|
||||
summary: Stato del supporto del bot Telegram, funzionalità e configurazione
|
||||
summary: Stato del supporto per il bot Telegram, funzionalità e configurazione
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T07:02:37Z"
|
||||
generated_at: "2026-05-04T08:39:44Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 6ef1b019a6a0e261b33972b5edffaedd29310b1333d112bade2e79e9d56887c6
|
||||
source_hash: 5711d53cf908a14024bc5a94f7d590bb4bcb6963a1d78049d7782871f4eae932
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Pronto per la produzione per DM e gruppi bot tramite grammY. Il polling lungo è la modalità predefinita; la modalità Webhook è facoltativa.
|
||||
Pronto per la produzione per DM e gruppi di bot tramite grammY. Il long polling è la modalità predefinita; la modalità Webhook è opzionale.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Associazione" icon="link" href="/it/channels/pairing">
|
||||
Il criterio DM predefinito per Telegram è l'associazione.
|
||||
</Card>
|
||||
<Card title="Risoluzione dei problemi del canale" icon="wrench" href="/it/channels/troubleshooting">
|
||||
Diagnostica multicanale e playbook di riparazione.
|
||||
<Card title="Risoluzione dei problemi dei canali" icon="wrench" href="/it/channels/troubleshooting">
|
||||
Diagnostica e playbook di riparazione tra canali.
|
||||
</Card>
|
||||
<Card title="Configurazione del Gateway" icon="settings" href="/it/gateway/configuration">
|
||||
Pattern ed esempi completi di configurazione dei canali.
|
||||
@ -30,7 +30,7 @@ Pronto per la produzione per DM e gruppi bot tramite grammY. Il polling lungo è
|
||||
|
||||
<Steps>
|
||||
<Step title="Crea il token del bot in BotFather">
|
||||
Apri Telegram e chatta con **@BotFather** (conferma 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.
|
||||
|
||||
@ -52,11 +52,11 @@ Pronto per la produzione per DM e gruppi bot tramite grammY. Il polling lungo è
|
||||
```
|
||||
|
||||
Fallback env: `TELEGRAM_BOT_TOKEN=...` (solo account predefinito).
|
||||
Telegram **non** usa `openclaw channels login telegram`; configura il token nella configurazione/env, poi avvia il Gateway.
|
||||
Telegram **non** usa `openclaw channels login telegram`; configura il token nella configurazione/env, poi avvia il gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Avvia il Gateway e approva il primo DM">
|
||||
<Step title="Avvia il gateway e approva il primo DM">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -80,7 +80,7 @@ L'ordine di risoluzione del token è consapevole dell'account. In pratica, i val
|
||||
## Impostazioni lato Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Modalità privacy e visibilità dei gruppi">
|
||||
<Accordion title="Modalità privacy e visibilità nei gruppi">
|
||||
I bot Telegram usano per impostazione predefinita la **Modalità privacy**, che limita quali messaggi di gruppo ricevono.
|
||||
|
||||
Se il bot deve vedere tutti i messaggi di gruppo, puoi:
|
||||
@ -88,26 +88,26 @@ L'ordine di risoluzione del token è consapevole dell'account. In pratica, i val
|
||||
- disabilitare la modalità privacy tramite `/setprivacy`, oppure
|
||||
- rendere il bot amministratore del gruppo.
|
||||
|
||||
Quando modifichi la modalità privacy, rimuovi e riaggiungi il bot in ogni gruppo affinché Telegram applichi la modifica.
|
||||
Quando attivi o disattivi la modalità privacy, rimuovi e aggiungi di nuovo il bot in ogni gruppo affinché Telegram applichi la modifica.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Autorizzazioni di gruppo">
|
||||
<Accordion title="Permessi del gruppo">
|
||||
Lo stato di amministratore è controllato nelle impostazioni del gruppo Telegram.
|
||||
|
||||
I bot amministratori ricevono tutti i messaggi di gruppo, cosa utile per comportamenti di gruppo sempre attivi.
|
||||
I bot amministratori ricevono tutti i messaggi di gruppo, il che è utile per un comportamento di gruppo sempre attivo.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Opzioni BotFather utili">
|
||||
<Accordion title="Opzioni utili di BotFather">
|
||||
|
||||
- `/setjoingroups` per consentire/negare l'aggiunta ai gruppi
|
||||
- `/setjoingroups` per consentire/negare le aggiunte ai gruppi
|
||||
- `/setprivacy` per il comportamento di visibilità nei gruppi
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Controllo dell'accesso e attivazione
|
||||
## Controllo degli accessi e attivazione
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Criterio DM">
|
||||
@ -118,20 +118,20 @@ L'ordine di risoluzione del token è consapevole dell'account. In pratica, i val
|
||||
- `open` (richiede che `allowFrom` includa `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`dmPolicy: "open"` con `allowFrom: ["*"]` consente a qualsiasi account Telegram che trovi o indovini il nome utente del bot di comandare il bot. Usalo solo per bot intenzionalmente pubblici con strumenti strettamente limitati; i bot con un solo proprietario dovrebbero usare `allowlist` con ID utente numerici.
|
||||
`dmPolicy: "open"` con `allowFrom: ["*"]` permette a qualsiasi account Telegram che trovi o indovini il nome utente del bot di comandare il bot. Usalo solo per bot intenzionalmente pubblici con strumenti strettamente limitati; i bot con un solo proprietario dovrebbero usare `allowlist` con ID utente numerici.
|
||||
|
||||
`channels.telegram.allowFrom` accetta ID utente Telegram numerici. I prefissi `telegram:` / `tg:` sono accettati e normalizzati.
|
||||
Nelle configurazioni multi-account, un `channels.telegram.allowFrom` restrittivo di primo livello è trattato come un confine di sicurezza: le voci `allowFrom: ["*"]` a livello di account non rendono pubblico quell'account a meno che l'allowlist effettiva dell'account contenga ancora un carattere jolly esplicito dopo l'unione.
|
||||
`dmPolicy: "allowlist"` con `allowFrom` vuoto blocca tutti i DM ed è respinto dalla validazione della configurazione.
|
||||
La configurazione iniziale richiede solo ID utente numerici.
|
||||
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).
|
||||
Nelle configurazioni multi-account, un `channels.telegram.allowFrom` di primo livello restrittivo è trattato come un confine di sicurezza: le voci `allowFrom: ["*"]` a livello di account non rendono pubblico quell'account a meno che l'allowlist effettiva dell'account contenga ancora un wildcard esplicito dopo l'unione.
|
||||
`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 l'upgrade 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 dello store di associazione, `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 numerici espliciti in `allowFrom` per mantenere il criterio di accesso durevole nella configurazione (invece di dipendere da approvazioni di associazione precedenti).
|
||||
Per bot con un solo proprietario, preferisci `dmPolicy: "allowlist"` con ID numerici espliciti in `allowFrom` per mantenere il criterio di accesso durevole nella configurazione (invece di dipendere dalle approvazioni di associazione precedenti).
|
||||
|
||||
Confusione comune: l'approvazione dell'associazione DM non significa "questo mittente è autorizzato ovunque".
|
||||
L'associazione concede l'accesso DM. Se non esiste ancora un proprietario dei comandi, la prima associazione approvata imposta anche `commands.ownerAllowFrom` affinché i comandi riservati al proprietario e le approvazioni exec abbiano un account operatore esplicito.
|
||||
L'autorizzazione del mittente nei gruppi deriva comunque dalle allowlist di configurazione esplicite.
|
||||
L'autorizzazione dei mittenti nei gruppi proviene comunque da allowlist di configurazione esplicite.
|
||||
Se vuoi "sono autorizzato una volta e funzionano sia i DM sia i comandi di gruppo", inserisci il tuo ID utente Telegram numerico in `channels.telegram.allowFrom`; per i comandi riservati al proprietario, assicurati che `commands.ownerAllowFrom` contenga `telegram:<your user id>`.
|
||||
|
||||
### Trovare il tuo ID utente Telegram
|
||||
@ -157,7 +157,7 @@ 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: "open"`: qualsiasi gruppo può superare i controlli dell'ID gruppo
|
||||
- con `groupPolicy: "allowlist"` (predefinito): i gruppi sono bloccati finché non aggiungi voci `groups` (o `"*"`)
|
||||
- `groups` configurato: agisce come allowlist (ID espliciti o `"*"`)
|
||||
|
||||
@ -166,17 +166,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `allowlist` (predefinito)
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` è usato per filtrare i mittenti nei gruppi. Se non è impostato, Telegram ricade su `allowFrom`.
|
||||
`groupAllowFrom` è usato per filtrare i mittenti del gruppo. Se non impostato, Telegram usa come fallback `allowFrom`.
|
||||
Le voci `groupAllowFrom` dovrebbero essere ID utente Telegram numerici (i prefissi `telegram:` / `tg:` sono normalizzati).
|
||||
Non inserire ID chat di gruppi o supergruppi Telegram in `groupAllowFrom`. Gli ID chat negativi appartengono a `channels.telegram.groups`.
|
||||
Le voci non numeriche sono ignorate per l'autorizzazione del mittente.
|
||||
Confine di sicurezza (`2026.2.25+`): l'autenticazione dei mittenti di gruppo **non** eredita le approvazioni dello store di associazione DM.
|
||||
L'associazione rimane solo DM. Per i gruppi, imposta `groupAllowFrom` o `allowFrom` per gruppo/per argomento.
|
||||
Se `groupAllowFrom` non è impostato, Telegram ricade sulla configurazione `allowFrom`, non sullo store di associazione.
|
||||
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 di runtime: se `channels.telegram` è completamente assente, il runtime usa il criterio fail-closed `groupPolicy="allowlist"` a meno che `channels.defaults.groupPolicy` sia impostato esplicitamente.
|
||||
Confine di sicurezza (`2026.2.25+`): l'autenticazione del mittente del gruppo **non** eredita le approvazioni dello store di associazione DM.
|
||||
L'associazione resta solo DM. Per i gruppi, imposta `groupAllowFrom` o `allowFrom` per gruppo/per topic.
|
||||
Se `groupAllowFrom` non è impostato, Telegram usa come fallback la configurazione `allowFrom`, non lo store di associazione.
|
||||
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 target in `channels.telegram.groups`.
|
||||
Nota runtime: se `channels.telegram` manca completamente, i valori predefiniti runtime sono fail-closed `groupPolicy="allowlist"` a meno che `channels.defaults.groupPolicy` sia impostato esplicitamente.
|
||||
|
||||
Esempio: consentire qualsiasi membro in un gruppo specifico:
|
||||
Esempio: consenti qualsiasi membro in un gruppo specifico:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -193,7 +193,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Esempio: consentire solo utenti specifici dentro un gruppo specifico:
|
||||
Esempio: consenti solo utenti specifici all'interno di un gruppo specifico:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -213,8 +213,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Warning>
|
||||
Errore comune: `groupAllowFrom` non è una allowlist di gruppi Telegram.
|
||||
|
||||
- Inserisci ID chat negativi di gruppi o supergruppi Telegram come `-1001234567890` in `channels.telegram.groups`.
|
||||
- Inserisci ID utente Telegram come `8734062810` in `groupAllowFrom` quando vuoi limitare quali persone dentro un gruppo consentito possono attivare il bot.
|
||||
- Inserisci ID chat negativi di gruppi o supergruppi Telegram, come `-1001234567890`, in `channels.telegram.groups`.
|
||||
- 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>
|
||||
@ -231,12 +231,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
Opzioni di comando a livello di sessione:
|
||||
Toggle di comando a livello di sessione:
|
||||
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Queste aggiornano solo lo stato della sessione. Usa la configurazione per la persistenza.
|
||||
Questi aggiornano solo lo stato della sessione. Usa la configurazione per la persistenza.
|
||||
|
||||
Esempio di configurazione persistente:
|
||||
|
||||
@ -254,43 +254,43 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Ottenere l'ID chat del gruppo:
|
||||
|
||||
- inoltra un messaggio di gruppo a `@userinfobot` / `@getidsbot`
|
||||
- inoltra un messaggio del gruppo a `@userinfobot` / `@getidsbot`
|
||||
- oppure leggi `chat.id` da `openclaw logs --follow`
|
||||
- oppure ispeziona `getUpdates` della Bot API
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Comportamento di runtime
|
||||
## Comportamento runtime
|
||||
|
||||
- Telegram è gestito dal processo Gateway.
|
||||
- Telegram è di proprietà del 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 di canale condiviso con metadati di risposta e placeholder multimediali.
|
||||
- Le sessioni di gruppo sono isolate per ID gruppo. Gli argomenti dei forum aggiungono `:topic:<threadId>` per mantenere isolati gli argomenti.
|
||||
- I messaggi DM possono contenere `message_thread_id`; OpenClaw conserva l'ID del thread per le risposte ma mantiene per impostazione predefinita i DM sulla sessione piatta. Configura `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true` o una configurazione argomento corrispondente quando vuoi intenzionalmente l'isolamento della sessione per argomento DM.
|
||||
- Il polling lungo usa grammY runner con sequenziamento per chat/per thread. La concorrenza complessiva del sink del runner usa `agents.defaults.maxConcurrent`.
|
||||
- Il polling lungo è protetto dentro ogni processo Gateway in modo che un solo poller attivo possa usare un token bot alla volta. Se vedi ancora conflitti `getUpdates` 409, è probabile che un altro Gateway OpenClaw, script o poller esterno stia usando lo stesso token.
|
||||
- I riavvii del watchdog del polling lungo si attivano per impostazione predefinita dopo 120 secondi senza liveness `getUpdates` completata. Aumenta `channels.telegram.pollingStallThresholdMs` solo se il tuo deployment vede ancora riavvii falsi 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 in ingresso sono normalizzati nell'envelope del canale condiviso con metadati di risposta e placeholder per media.
|
||||
- Le sessioni di gruppo sono isolate per ID gruppo. I topic dei forum aggiungono `:topic:<threadId>` per mantenere isolati i topic.
|
||||
- I messaggi DM possono includere `message_thread_id`; OpenClaw conserva l'ID thread per le risposte ma mantiene i DM sulla sessione piatta per impostazione predefinita. Configura `channels.telegram.dm.threadReplies: "inbound"`, `channels.telegram.direct.<chatId>.threadReplies: "inbound"`, `requireTopic: true` o una configurazione topic corrispondente quando vuoi intenzionalmente l'isolamento della sessione per topic DM.
|
||||
- Il long polling usa il runner grammY con sequenziamento per chat/per thread. La concorrenza complessiva del sink del runner usa `agents.defaults.maxConcurrent`.
|
||||
- Il long polling è protetto all'interno di ciascun processo Gateway, in modo che solo un poller attivo possa usare un token bot alla volta. Se vedi ancora conflitti `getUpdates` 409, probabilmente un altro Gateway OpenClaw, script o poller esterno sta usando lo stesso token.
|
||||
- I riavvii del watchdog del long polling si attivano per impostazione predefinita dopo 120 secondi senza liveness completata di `getUpdates`. 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.
|
||||
- La Telegram Bot API non supporta le conferme di lettura (`sendReadReceipts` non si applica).
|
||||
|
||||
## Riferimento delle funzionalità
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Anteprima live stream (modifiche dei messaggi)">
|
||||
OpenClaw può inviare risposte parziali in streaming in tempo reale:
|
||||
<Accordion title="Anteprima streaming live (modifiche dei messaggi)">
|
||||
OpenClaw può trasmettere risposte parziali in tempo reale:
|
||||
|
||||
- chat dirette: messaggio di anteprima + `editMessageText`
|
||||
- gruppi/argomenti: messaggio di anteprima + `editMessageText`
|
||||
- gruppi/topic: messaggio di anteprima + `editMessageText`
|
||||
|
||||
Requisito:
|
||||
|
||||
- `channels.telegram.streaming` è `off | partial | block | progress` (predefinito: `partial`)
|
||||
- `progress` mantiene una bozza di stato modificabile e la aggiorna con l'avanzamento degli strumenti fino alla consegna finale
|
||||
- `streaming.preview.toolProgress` controlla se gli aggiornamenti di strumenti/progresso riutilizzano lo stesso messaggio di anteprima modificato (predefinito: `true` quando lo streaming di anteprima è attivo)
|
||||
- `streaming.preview.commandText` controlla i dettagli command/exec dentro quelle righe di avanzamento strumenti: `raw` (predefinito, conserva il comportamento rilasciato) o `status` (solo etichetta dello strumento)
|
||||
- i valori legacy `channels.telegram.streamMode` e booleani `streaming` vengono rilevati; esegui `openclaw doctor --fix` per migrarli a `channels.telegram.streaming.mode`
|
||||
- `streaming.preview.toolProgress` controlla se gli aggiornamenti di strumenti/avanzamento riutilizzano lo stesso messaggio di anteprima modificato (predefinito: `true` quando lo streaming di anteprima è attivo)
|
||||
- `streaming.preview.commandText` controlla i dettagli di comando/exec all'interno di quelle righe di avanzamento strumenti: `raw` (predefinito, conserva il comportamento rilasciato) o `status` (solo etichetta dello strumento)
|
||||
- i valori legacy `channels.telegram.streamMode` e booleani `streaming` sono rilevati; esegui `openclaw doctor --fix` per migrarli a `channels.telegram.streaming.mode`
|
||||
|
||||
Gli aggiornamenti di anteprima dell'avanzamento strumenti sono le brevi righe di stato mostrate mentre gli strumenti vengono eseguiti, per esempio esecuzione di comandi, letture di file, aggiornamenti di pianificazione o riepiloghi di patch. Telegram li mantiene abilitati per impostazione predefinita per corrispondere al comportamento rilasciato di OpenClaw da `v2026.4.22` e versioni successive. Per mantenere l'anteprima modificata per il testo della risposta ma nascondere le righe di avanzamento strumenti, imposta:
|
||||
Gli aggiornamenti di anteprima dell'avanzamento strumenti sono le brevi righe di stato mostrate mentre gli strumenti sono in esecuzione, per esempio esecuzione di comandi, letture di file, aggiornamenti di pianificazione o riepiloghi di patch. Telegram li mantiene abilitati per impostazione predefinita per corrispondere al comportamento rilasciato di OpenClaw da `v2026.4.22` e versioni successive. Per mantenere l'anteprima modificata per il testo della risposta ma nascondere le righe di avanzamento strumenti, imposta:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -324,7 +324,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Per la modalità bozza di avanzamento, inserisci la stessa policy del testo del comando sotto `streaming.progress`:
|
||||
Per la modalità bozza di avanzamento, inserisci la stessa policy per il testo del comando sotto `streaming.progress`:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -342,23 +342,23 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Usa `streaming.mode: "off"` solo quando vuoi la consegna esclusivamente finale: le modifiche alle anteprime Telegram sono disabilitate e il chiacchiericcio generico di strumenti/avanzamento viene soppresso invece di essere inviato come messaggi di stato autonomi. Le richieste di approvazione, i payload multimediali e gli errori continuano a passare attraverso la normale consegna finale. Usa `streaming.preview.toolProgress: false` quando vuoi mantenere solo le modifiche all'anteprima della risposta nascondendo le righe di stato dell'avanzamento degli strumenti.
|
||||
Usa `streaming.mode: "off"` solo quando vuoi la consegna esclusivamente finale: le modifiche all'anteprima di Telegram sono disabilitate e il chatter generico di strumenti/avanzamento viene soppresso invece di essere inviato come messaggi di stato autonomi. Le richieste di approvazione, i payload multimediali e gli errori vengono comunque instradati tramite la normale consegna finale. Usa `streaming.preview.toolProgress: false` quando vuoi solo mantenere le modifiche all'anteprima della risposta nascondendo le righe di stato dell'avanzamento dello strumento.
|
||||
|
||||
<Note>
|
||||
Le risposte Telegram a citazioni selezionate sono l'eccezione. Quando `replyToMode` è `"first"`, `"all"` o `"batched"` e il messaggio in ingresso include testo di citazione selezionato, OpenClaw invia la risposta finale tramite il percorso nativo di risposta con citazione di Telegram invece di modificare l'anteprima della risposta, quindi `streaming.preview.toolProgress` non può mostrare le brevi righe di stato per quel turno. Le risposte al messaggio corrente senza testo di citazione selezionato continuano a mantenere lo streaming dell'anteprima. Imposta `replyToMode: "off"` quando la visibilità dell'avanzamento degli strumenti conta più delle risposte native con citazione, oppure imposta `streaming.preview.toolProgress: false` per accettare il compromesso.
|
||||
Le risposte con citazione selezionata di Telegram sono l'eccezione. Quando `replyToMode` è `"first"`, `"all"` o `"batched"` e il messaggio in ingresso include testo di citazione selezionato, OpenClaw invia la risposta finale tramite il percorso nativo di risposta con citazione di Telegram invece di modificare l'anteprima della risposta, quindi `streaming.preview.toolProgress` non può mostrare le brevi righe di stato per quel turno. Le risposte al messaggio corrente senza testo di citazione selezionato mantengono comunque lo streaming dell'anteprima. Imposta `replyToMode: "off"` quando la visibilità dell'avanzamento dello strumento conta più delle risposte con citazione native, oppure imposta `streaming.preview.toolProgress: false` per riconoscere il compromesso.
|
||||
</Note>
|
||||
|
||||
Per risposte solo testuali:
|
||||
Per le risposte solo testuali:
|
||||
|
||||
- anteprime brevi in DM/gruppo/topic: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale sul posto, a meno che dopo la comparsa dell'anteprima non sia stato inviato un messaggio visibile non di anteprima
|
||||
- anteprime seguite da output visibile non di anteprima: OpenClaw invia la risposta completata come nuovo messaggio finale e rimuove la vecchia anteprima, così la risposta finale appare dopo l'output intermedio
|
||||
- anteprime più vecchie di circa un minuto: OpenClaw invia la risposta completata come nuovo messaggio finale e poi rimuove l'anteprima, così il timestamp visibile di Telegram riflette l'ora di completamento invece dell'ora di creazione dell'anteprima
|
||||
- anteprime seguite da output visibile non di anteprima: OpenClaw invia la risposta completata come nuovo messaggio finale e pulisce l'anteprima precedente, quindi la risposta finale appare dopo l'output intermedio
|
||||
- anteprime più vecchie di circa un minuto: OpenClaw invia la risposta completata come nuovo messaggio finale e poi pulisce l'anteprima, quindi il timestamp visibile di Telegram riflette l'ora di completamento invece dell'ora di creazione dell'anteprima
|
||||
|
||||
Per risposte complesse (ad esempio payload multimediali), OpenClaw ripiega sulla normale consegna finale e poi rimuove il messaggio di anteprima.
|
||||
Per risposte complesse (ad esempio payload multimediali), OpenClaw ripiega sulla normale consegna finale e poi pulisce il messaggio di anteprima.
|
||||
|
||||
Lo streaming dell'anteprima è separato dallo streaming a blocchi. Quando lo streaming a blocchi è abilitato esplicitamente per Telegram, OpenClaw salta lo stream di anteprima per evitare un doppio streaming.
|
||||
Lo streaming dell'anteprima è separato dallo streaming a blocchi. Quando lo streaming a blocchi è abilitato esplicitamente per Telegram, OpenClaw salta il flusso di anteprima per evitare il doppio streaming.
|
||||
|
||||
Stream di ragionamento solo per Telegram:
|
||||
Flusso di ragionamento solo Telegram:
|
||||
|
||||
- `/reasoning stream` invia il ragionamento all'anteprima live durante la generazione
|
||||
- l'anteprima del ragionamento viene eliminata dopo la consegna finale; usa `/reasoning on` quando il ragionamento deve rimanere visibile
|
||||
@ -369,18 +369,18 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="Formattazione e fallback HTML">
|
||||
Il testo in uscita usa Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Il testo in stile Markdown viene convertito in HTML sicuro per Telegram.
|
||||
- Il testo in stile Markdown viene renderizzato in HTML sicuro per Telegram.
|
||||
- L'HTML grezzo del modello viene sottoposto a escape per ridurre gli errori di parsing di Telegram.
|
||||
- Se Telegram rifiuta l'HTML analizzato, OpenClaw riprova come testo semplice.
|
||||
- Se Telegram rifiuta l'HTML parsato, OpenClaw riprova come testo semplice.
|
||||
|
||||
Le anteprime dei link sono abilitate per impostazione predefinita e possono essere disabilitate con `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Comandi nativi e comandi personalizzati">
|
||||
La registrazione del menu dei comandi Telegram viene gestita all'avvio con `setMyCommands`.
|
||||
La registrazione del menu dei comandi di Telegram viene gestita all'avvio con `setMyCommands`.
|
||||
|
||||
Valori predefiniti dei comandi nativi:
|
||||
Impostazioni predefinite dei comandi nativi:
|
||||
|
||||
- `commands.native: "auto"` abilita i comandi nativi per Telegram
|
||||
|
||||
@ -401,7 +401,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Regole:
|
||||
|
||||
- i nomi vengono normalizzati (rimozione di `/` iniziale, minuscolo)
|
||||
- i nomi vengono normalizzati (rimozione di `/` iniziale, minuscole)
|
||||
- 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
|
||||
@ -409,18 +409,18 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Note:
|
||||
|
||||
- i comandi personalizzati sono solo voci di menu; non implementano automaticamente il comportamento
|
||||
- i comandi Plugin/skill possono comunque funzionare quando digitati, anche se non sono mostrati nel menu Telegram
|
||||
- i comandi di plugin/skill possono comunque funzionare quando digitati anche se non mostrati nel menu di 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 ha comunque superato il limite dopo il taglio; riduci i comandi Plugin/skill/personalizzati o disabilita `channels.telegram.commands.native`.
|
||||
- `deleteWebhook`, `deleteMyCommands` o `setMyCommands` che falliscono con `404: Not Found` mentre i comandi curl diretti della Bot API funzionano possono significare che `channels.telegram.apiRoot` è stato impostato sull'endpoint completo `/bot<TOKEN>`. `apiRoot` deve essere solo la radice della Bot API, e `openclaw doctor --fix` rimuove un `/bot<TOKEN>` finale accidentale.
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu di Telegram ha comunque superato il limite dopo il taglio; riduci i comandi plugin/skill/personalizzati o disabilita `channels.telegram.commands.native`.
|
||||
- `deleteWebhook`, `deleteMyCommands` o `setMyCommands` che falliscono con `404: Not Found` mentre i comandi curl diretti della Bot API funzionano possono indicare che `channels.telegram.apiRoot` è stato impostato sull'endpoint completo `/bot<TOKEN>`. `apiRoot` deve essere solo la radice della Bot API, e `openclaw doctor --fix` rimuove un `/bot<TOKEN>` finale accidentale.
|
||||
- `getMe returned 401` significa che Telegram ha rifiutato il token del bot configurato. Aggiorna `botToken`, `tokenFile` o `TELEGRAM_BOT_TOKEN` con il token BotFather corrente; OpenClaw si arresta prima del polling, quindi questo non viene segnalato come errore di pulizia del Webhook.
|
||||
- `setMyCommands failed` con errori di rete/fetch di solito significa che il DNS/HTTPS in uscita verso `api.telegram.org` è bloccato.
|
||||
- `setMyCommands failed` con errori di rete/fetch di solito significa che DNS/HTTPS in uscita verso `api.telegram.org` è bloccato.
|
||||
|
||||
### Comandi di associazione dispositivo (Plugin `device-pair`)
|
||||
### Comandi di abbinamento dispositivo (Plugin `device-pair`)
|
||||
|
||||
Quando il Plugin `device-pair` è installato:
|
||||
|
||||
@ -432,11 +432,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 di breve durata. Il passaggio bootstrap integrato mantiene il token del nodo primario a `scopes: []`; qualsiasi token operatore trasferito resta limitato a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. I controlli degli ambiti bootstrap hanno prefisso di ruolo, quindi quell'allowlist operatore soddisfa solo le richieste operatore; i ruoli non operatore richiedono comunque ambiti sotto il prefisso del proprio ruolo.
|
||||
Il codice di configurazione trasporta un token di bootstrap di breve durata. Il passaggio di bootstrap integrato mantiene il token del nodo primario a `scopes: []`; qualsiasi token operatore trasferito resta limitato a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. I controlli dell'ambito di bootstrap sono prefissati dal ruolo, quindi quella allowlist dell'operatore soddisfa solo le richieste dell'operatore; i ruoli non operatore hanno comunque bisogno di ambiti sotto il proprio prefisso di ruolo.
|
||||
|
||||
Se un dispositivo riprova con dettagli di autenticazione modificati (ad esempio ruolo/ambiti/chiave pubblica), la richiesta in sospeso precedente viene sostituita e la nuova richiesta usa un `requestId` diverso. Esegui di nuovo `/pair pending` prima di approvare.
|
||||
|
||||
Maggiori dettagli: [Associazione](/it/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
Maggiori dettagli: [Abbinamento](/it/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -481,7 +481,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `all`
|
||||
- `allowlist` (predefinito)
|
||||
|
||||
Il vecchio `capabilities: ["inlineButtons"]` viene mappato a `inlineButtons: "all"`.
|
||||
Il legacy `capabilities: ["inlineButtons"]` viene mappato a `inlineButtons: "all"`.
|
||||
|
||||
Esempio di azione messaggio:
|
||||
|
||||
@ -501,13 +501,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
I clic sui callback vengono passati all'agente come testo:
|
||||
I clic di callback vengono passati all'agente come testo:
|
||||
`callback_data: <value>`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Azioni messaggio Telegram per agenti e automazione">
|
||||
Le azioni degli strumenti Telegram includono:
|
||||
Le azioni strumento di Telegram includono:
|
||||
|
||||
- `sendMessage` (`to`, `content`, opzionale `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `react` (`chatId`, `messageId`, `emoji`)
|
||||
@ -515,7 +515,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, opzionale `iconColor`, `iconCustomEmojiId`)
|
||||
|
||||
Le azioni sui 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:
|
||||
|
||||
@ -524,8 +524,8 @@ 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 `channels.telegram.actions.*` separati.
|
||||
Gli invii runtime usano lo snapshot attivo di configurazione/segreti (avvio/ricaricamento), quindi i percorsi di azione non rieseguono la risoluzione ad hoc di SecretRef per ogni invio.
|
||||
Nota: `edit` e `topic-create` sono attualmente abilitati per impostazione predefinita e non hanno interruttori `channels.telegram.actions.*` separati.
|
||||
Gli invii runtime usano lo snapshot attivo di configurazione/segreti (avvio/ricaricamento), quindi i percorsi di azione non eseguono una nuova risoluzione SecretRef ad hoc per ogni invio.
|
||||
|
||||
Semantica di rimozione delle reazioni: [/tools/reactions](/it/tools/reactions)
|
||||
|
||||
@ -534,7 +534,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Accordion title="Tag di threading delle risposte">
|
||||
Telegram supporta tag espliciti di threading delle risposte nell'output generato:
|
||||
|
||||
- `[[reply_to_current]]` risponde al messaggio che ha attivato l'operazione
|
||||
- `[[reply_to_current]]` risponde al messaggio che ha attivato l'azione
|
||||
- `[[reply_to:<id>]]` risponde a uno specifico ID messaggio Telegram
|
||||
|
||||
`channels.telegram.replyToMode` controlla la gestione:
|
||||
@ -543,29 +543,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Quando il threading delle risposte è abilitato e il testo o la didascalia Telegram originale è disponibile, OpenClaw include automaticamente un estratto di citazione nativa Telegram. Telegram limita il testo di citazione nativo a 1024 unità di codice UTF-16, quindi i messaggi più lunghi vengono citati dall'inizio e ripiegano su una risposta semplice se Telegram rifiuta la citazione.
|
||||
Quando il threading delle risposte è abilitato e il testo o la didascalia Telegram originale è disponibile, OpenClaw include automaticamente un estratto di citazione nativo di Telegram. Telegram limita il testo di citazione nativo a 1024 unità di codice UTF-16, quindi i messaggi più lunghi vengono citati dall'inizio e ripiegano su una risposta semplice se Telegram rifiuta la citazione.
|
||||
|
||||
Nota: `off` disabilita il threading implicito delle risposte. I tag espliciti `[[reply_to_*]]` vengono comunque rispettati.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Topic dei forum e comportamento dei thread">
|
||||
<Accordion title="Topic del forum e comportamento dei thread">
|
||||
Supergruppi forum:
|
||||
|
||||
- le chiavi di sessione topic aggiungono `:topic:<threadId>`
|
||||
- risposte e indicatori di digitazione puntano al thread del topic
|
||||
- percorso di configurazione topic:
|
||||
- le chiavi di sessione dei topic aggiungono `:topic:<threadId>`
|
||||
- risposte e digitazione mirano al thread del topic
|
||||
- percorso di configurazione del topic:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Caso speciale del topic generale (`threadId=1`):
|
||||
Caso speciale topic generale (`threadId=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 di gruppo a meno che non vengano sovrascritte (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` è solo a livello di topic e non eredita dai valori predefiniti del gruppo.
|
||||
Ereditarietà dei topic: le voci dei 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.
|
||||
|
||||
**Instradamento agente per topic**: Ogni topic può indirizzare a un agente diverso impostando `agentId` nella configurazione del topic. Questo dà a ogni topic il proprio workspace, la propria memoria e la propria sessione isolati. Esempio:
|
||||
**Instradamento agente per topic**: ogni topic può instradare a un agente diverso impostando `agentId` nella configurazione del topic. Questo dà a ogni topic il proprio workspace, la propria memoria e la propria sessione isolati. Esempio:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -587,24 +587,24 @@ 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 dei topic ACP**: I topic dei forum possono fissare le 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 per topic come `-1001234567890:topic:42`). Attualmente limitato ai topic dei forum in gruppi/supergruppi. Vedi [Agenti ACP](/it/tools/acp-agents).
|
||||
**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 per topic come `-1001234567890:topic:42`). Attualmente limitato ai topic del forum in gruppi/supergruppi. Vedi [Agenti ACP](/it/tools/acp-agents).
|
||||
|
||||
**Spawn ACP vincolato al thread dalla chat**: `/acp spawn <agent> --thread here|auto` associa il topic corrente a una nuova sessione ACP; i messaggi successivi vengono instradati direttamente lì. OpenClaw fissa la conferma dello spawn nel topic. Richiede che `channels.telegram.threadBindings.spawnSessions` resti abilitato (predefinito: `true`).
|
||||
**Spawn ACP vincolato al thread dalla chat**: `/acp spawn <agent> --thread here|auto` associa il topic corrente a una nuova sessione ACP; i follow-up vengono instradati direttamente lì. OpenClaw fissa la conferma dello spawn nel topic. Richiede che `channels.telegram.threadBindings.spawnSessions` resti abilitato (predefinito: `true`).
|
||||
|
||||
Il contesto del template espone `MessageThreadId` e `IsForum`. Le chat DM con `message_thread_id` mantengono per impostazione predefinita il routing DM e i metadati di risposta nelle sessioni piatte; usano chiavi di sessione consapevoli dei thread solo quando sono configurate con `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` o una configurazione di argomento corrispondente. Usa `channels.telegram.dm.threadReplies` di primo livello per il valore predefinito dell’account, oppure `direct.<chatId>.threadReplies` per un singolo DM.
|
||||
Il contesto del template espone `MessageThreadId` e `IsForum`. Le chat DM con `message_thread_id` mantengono per impostazione predefinita il routing DM e i metadati di risposta nelle sessioni piatte; usano chiavi di sessione consapevoli dei thread solo quando sono configurate con `threadReplies: "inbound"`, `threadReplies: "always"`, `requireTopic: true` o una configurazione di topic corrispondente. Usa `channels.telegram.dm.threadReplies` di livello superiore per l’impostazione predefinita dell’account, oppure `direct.<chatId>.threadReplies` per un singolo DM.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Audio, video, and stickers">
|
||||
<Accordion title="Audio, video e sticker">
|
||||
### Messaggi audio
|
||||
|
||||
Telegram distingue le note vocali dai file audio.
|
||||
|
||||
- predefinito: comportamento da file audio
|
||||
- tag `[[audio_as_voice]]` nella risposta dell’agente per forzare l’invio come nota vocale
|
||||
- le trascrizioni delle note vocali in ingresso sono incorniciate come testo generato da macchina
|
||||
- le trascrizioni delle note vocali in ingresso sono inquadrate come testo generato da macchina
|
||||
e non attendibile nel contesto dell’agente; il rilevamento delle menzioni usa comunque la
|
||||
trascrizione grezza, quindi i messaggi vocali soggetti a gate di menzione continuano a funzionare.
|
||||
trascrizione grezza, quindi i messaggi vocali subordinati a menzione continuano a funzionare.
|
||||
|
||||
Esempio di azione messaggio:
|
||||
|
||||
@ -644,7 +644,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- TGS animato: ignorato
|
||||
- WEBM video: ignorato
|
||||
|
||||
Campi del contesto degli sticker:
|
||||
Campi del contesto sticker:
|
||||
|
||||
- `Sticker.emoji`
|
||||
- `Sticker.setName`
|
||||
@ -652,11 +652,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `Sticker.fileUniqueId`
|
||||
- `Sticker.cachedDescription`
|
||||
|
||||
File della cache degli sticker:
|
||||
File cache degli sticker:
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Gli sticker vengono descritti una volta (quando possibile) e memorizzati nella cache per ridurre le chiamate vision ripetute.
|
||||
Gli sticker vengono descritti una sola volta (quando possibile) e messi in cache per ridurre le chiamate ripetute alla visione.
|
||||
|
||||
Abilita le azioni sticker:
|
||||
|
||||
@ -696,8 +696,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reaction notifications">
|
||||
Le reazioni di Telegram arrivano come aggiornamenti `message_reaction` (separati dai payload dei messaggi).
|
||||
<Accordion title="Notifiche delle reazioni">
|
||||
Le reazioni Telegram arrivano come aggiornamenti `message_reaction` (separati dai payload dei messaggi).
|
||||
|
||||
Quando abilitate, OpenClaw accoda eventi di sistema come:
|
||||
|
||||
@ -710,25 +710,25 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Note:
|
||||
|
||||
- `own` indica solo le reazioni degli utenti ai messaggi inviati dal bot (best-effort tramite cache dei messaggi inviati).
|
||||
- Gli eventi di reazione rispettano comunque i controlli di accesso di Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); i mittenti non autorizzati vengono scartati.
|
||||
- Telegram non fornisce ID di thread negli aggiornamenti delle reazioni.
|
||||
- i gruppi non-forum vengono instradati alla sessione della chat di gruppo
|
||||
- i gruppi forum vengono instradati alla sessione dell’argomento generale del gruppo (`:topic:1`), non all’esatto argomento di origine
|
||||
- `own` indica solo le reazioni degli utenti ai messaggi inviati dal bot (best effort tramite cache dei messaggi inviati).
|
||||
- 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 della chat di gruppo
|
||||
- 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="Ack reactions">
|
||||
`ackReaction` invia un’emoji di conferma mentre OpenClaw elabora un messaggio in ingresso.
|
||||
<Accordion title="Reazioni ack">
|
||||
`ackReaction` invia un’emoji di conferma mentre OpenClaw sta elaborando un messaggio in ingresso.
|
||||
|
||||
Ordine di risoluzione:
|
||||
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- fallback emoji dell’identità dell’agente (`agents.list[].identity.emoji`, altrimenti "👀")
|
||||
- fallback all’emoji dell’identità dell’agente (`agents.list[].identity.emoji`, altrimenti "👀")
|
||||
|
||||
Note:
|
||||
|
||||
@ -737,7 +737,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Config writes from Telegram events and commands">
|
||||
<Accordion title="Scritture di configurazione da eventi e comandi Telegram">
|
||||
Le scritture della configurazione del canale sono abilitate per impostazione predefinita (`configWrites !== false`).
|
||||
|
||||
Le scritture attivate da Telegram includono:
|
||||
@ -759,39 +759,40 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Long polling vs webhook">
|
||||
<Accordion title="Long polling e Webhook">
|
||||
L’impostazione predefinita è il 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`).
|
||||
|
||||
Il listener locale si associa a `127.0.0.1:8787`. Per l’ingresso pubblico, metti un reverse proxy davanti alla porta locale oppure imposta intenzionalmente `webhookHost: "0.0.0.0"`.
|
||||
|
||||
La modalità Webhook convalida le protezioni della richiesta, il token segreto di Telegram e il corpo JSON prima di restituire `200` a Telegram.
|
||||
OpenClaw elabora quindi l’aggiornamento in modo asincrono attraverso le stesse lane bot per-chat/per-argomento usate dal long polling, quindi i turni lenti dell’agente non bloccano l’ACK di consegna di Telegram.
|
||||
La modalità Webhook convalida le protezioni della richiesta, il token segreto Telegram e il corpo JSON prima di restituire `200` a Telegram.
|
||||
OpenClaw elabora poi l’aggiornamento in modo asincrono tramite le stesse corsie bot per chat/per topic usate dal long polling, quindi i turni lenti dell’agente non trattengono l’ACK di consegna di Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Limits, retry, and CLI targets">
|
||||
- `channels.telegram.textChunkLimit` è 4000 per impostazione predefinita.
|
||||
- `channels.telegram.chunkMode="newline"` preferisce i confini di paragrafo (righe vuote) prima della suddivisione per lunghezza.
|
||||
<Accordion title="Limiti, riprova e destinazioni CLI">
|
||||
- Il valore predefinito di `channels.telegram.textChunkLimit` è 4000.
|
||||
- `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.mediaGroupFlushMs` (predefinito 500) controlla per quanto tempo gli album/gruppi di media Telegram vengono bufferizzati prima che OpenClaw li invii come un unico messaggio in ingresso. Aumentalo se le parti dell’album arrivano in ritardo; diminuiscilo per ridurre la latenza della risposta agli album.
|
||||
- `channels.telegram.timeoutSeconds` sovrascrive il timeout del client API Telegram (se non impostato, si applica il valore predefinito di grammY). I client bot limitano i valori configurati sotto la protezione di 60 secondi per richieste di testo/typing in uscita, così grammY non interrompe la consegna visibile delle risposte prima che possano essere eseguiti la protezione di trasporto e il fallback di OpenClaw. Il long polling usa comunque una protezione di richiesta `getUpdates` di 45 secondi, così i polling inattivi non vengono abbandonati indefinitamente.
|
||||
- `channels.telegram.pollingStallThresholdMs` è predefinito a `120000`; regolalo tra `30000` e `600000` solo per riavvii di polling-stall falsi positivi.
|
||||
- `channels.telegram.mediaGroupFlushMs` (predefinito 500) controlla per quanto tempo gli album/gruppi di media Telegram vengono memorizzati nel buffer prima che OpenClaw li invii come un unico messaggio in ingresso. Aumentalo se le parti dell’album arrivano in ritardo; riducilo per diminuire la latenza della risposta all’album.
|
||||
- `channels.telegram.timeoutSeconds` sovrascrive il timeout del client API Telegram (se non impostato, si applica il valore predefinito di grammY). I client bot limitano i valori configurati al di sotto della protezione di 60 secondi per le richieste di testo/typing in uscita, così grammY non interrompe la consegna della risposta visibile prima che la protezione di trasporto e il fallback di OpenClaw possano essere eseguiti. Il long polling usa comunque una protezione di 45 secondi per le richieste `getUpdates`, così i polling inattivi non vengono abbandonati indefinitamente.
|
||||
- `channels.telegram.pollingStallThresholdMs` ha valore predefinito `120000`; regola tra `30000` e `600000` solo per riavvii dovuti a falsi positivi di polling bloccato.
|
||||
- la cronologia del contesto di gruppo usa `channels.telegram.historyLimit` o `messages.groupChat.historyLimit` (predefinito 50); `0` disabilita.
|
||||
- il contesto supplementare di risposta/citazione/inoltro viene attualmente passato così come ricevuto.
|
||||
- le allowlist di Telegram principalmente controllano chi può attivare l’agente, non costituiscono un confine completo di redazione del contesto supplementare.
|
||||
- le allowlist Telegram determinano 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. Anche la consegna della risposta finale in ingresso usa un retry safe-send limitato per errori Telegram pre-connessione, ma non ritenta envelope di rete ambigue post-invio che potrebbero duplicare messaggi visibili.
|
||||
- La configurazione `channels.telegram.retry` si applica agli helper di invio Telegram (CLI/strumenti/azioni) per errori API in uscita recuperabili. Anche la consegna della risposta finale in ingresso usa un nuovo tentativo safe-send limitato per i guasti Telegram prima della connessione, ma non riprova envelope di rete ambigui dopo l’invio che potrebbero duplicare messaggi visibili.
|
||||
|
||||
Il target di invio CLI può essere un ID chat numerico o un nome utente:
|
||||
Le destinazioni di invio CLI e dello strumento messaggi possono essere un ID chat numerico, un nome utente o una destinazione topic forum:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
openclaw message send --channel telegram --target @name --message "hi"
|
||||
openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"
|
||||
```
|
||||
|
||||
I sondaggi Telegram usano `openclaw message poll` e supportano gli argomenti forum:
|
||||
I sondaggi Telegram usano `openclaw message poll` e supportano i topic forum:
|
||||
|
||||
```bash
|
||||
openclaw message poll --channel telegram --target 123456789 \
|
||||
@ -806,23 +807,23 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- `--thread-id` per gli argomenti forum (oppure usa un target `:topic:`)
|
||||
- `--thread-id` per topic forum (oppure usa una destinazione `:topic:`)
|
||||
|
||||
L’invio Telegram supporta anche:
|
||||
|
||||
- `--presentation` con blocchi `buttons` per tastiere inline quando `channels.telegram.capabilities.inlineButtons` lo consente
|
||||
- `--pin` o `--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 caricamenti di media animati
|
||||
- `--pin` o `--delivery '{"pin":true}'` per richiedere la consegna con pin quando il bot può fissare messaggi in quella chat
|
||||
- `--force-document` per inviare immagini e GIF in uscita come documenti invece che come caricamenti di foto compresse o media animati
|
||||
|
||||
Gate delle azioni:
|
||||
Controllo delle azioni:
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` disabilita i messaggi Telegram in uscita, inclusi i sondaggi
|
||||
- `channels.telegram.actions.poll=false` disabilita la creazione di sondaggi Telegram lasciando abilitati gli invii regolari
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Exec approvals in Telegram">
|
||||
Telegram supporta le approvazioni exec nei DM degli approvatori e può facoltativamente pubblicare i prompt nella chat o nell’argomento di origine. Gli approvatori devono essere ID utente Telegram numerici.
|
||||
<Accordion title="Approvazioni exec in Telegram">
|
||||
Telegram supporta le approvazioni exec nei DM degli approvatori e può facoltativamente pubblicare prompt nella chat o nel topic di origine. Gli approvatori devono essere ID utente Telegram numerici.
|
||||
|
||||
Percorso di configurazione:
|
||||
|
||||
@ -831,11 +832,11 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
- `channels.telegram.execApprovals.target`: `dm` (predefinito) | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` e `defaultTo` controllano chi può parlare con il bot e dove invia le risposte normali. Non rendono qualcuno un approvatore exec. Il primo abbinamento DM approvato inizializza `commands.ownerAllowFrom` quando non esiste ancora un proprietario dei comandi, quindi la configurazione con un solo proprietario continua a funzionare senza duplicare gli ID in `execApprovals.approvers`.
|
||||
`channels.telegram.allowFrom`, `groupAllowFrom` e `defaultTo` controllano chi può parlare al bot e dove invia le risposte normali. Non rendono qualcuno un approvatore exec. Il primo abbinamento DM approvato inizializza `commands.ownerAllowFrom` quando non esiste ancora un proprietario dei comandi, quindi la configurazione con un solo proprietario funziona comunque senza duplicare gli ID in `execApprovals.approvers`.
|
||||
|
||||
La consegna sul canale mostra il testo del comando nella chat; abilita `channel` o `both` solo in gruppi/argomenti attendibili. Quando il prompt arriva in un argomento forum, OpenClaw preserva l’argomento per il prompt di approvazione e il follow-up. Le approvazioni exec scadono per impostazione predefinita dopo 30 minuti.
|
||||
La consegna nel canale mostra il testo del comando nella chat; abilita `channel` o `both` solo in gruppi/topic attendibili. Quando il prompt arriva in un topic forum, OpenClaw preserva il topic per il prompt di approvazione e il follow-up. Le approvazioni exec scadono dopo 30 minuti per impostazione predefinita.
|
||||
|
||||
I pulsanti di approvazione inline richiedono anche che `channels.telegram.capabilities.inlineButtons` consenta la superficie target (`dm`, `group` o `all`). Gli ID approvazione con prefisso `plugin:` vengono risolti tramite le approvazioni Plugin; gli altri vengono risolti prima tramite le approvazioni exec.
|
||||
I pulsanti di approvazione inline richiedono anche che `channels.telegram.capabilities.inlineButtons` consenta la superficie di destinazione (`dm`, `group` o `all`). Gli ID approvazione con prefisso `plugin:` vengono risolti tramite le approvazioni Plugin; gli altri vengono risolti prima tramite le approvazioni exec.
|
||||
|
||||
Vedi [Approvazioni exec](/it/tools/exec-approvals).
|
||||
|
||||
@ -848,10 +849,10 @@ Quando l’agente incontra un errore di consegna o del provider, Telegram può r
|
||||
|
||||
| Chiave | Valori | Predefinito | Descrizione |
|
||||
| ----------------------------------- | ----------------- | ----------- | --------------------------------------------------------------------------------------------------- |
|
||||
| `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` | numero (ms) | `60000` | Tempo minimo tra risposte di errore alla stessa chat. Previene lo spam di errori durante le interruzioni. |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` invia un messaggio di errore amichevole alla chat. `silent` sopprime interamente le risposte di errore. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Tempo minimo tra risposte di errore alla stessa chat. Previene lo spam di errori durante le interruzioni. |
|
||||
|
||||
Sono supportate sovrascritture per account, gruppo e argomento (la stessa ereditarietà delle altre chiavi di configurazione Telegram).
|
||||
Sono supportate sovrascritture per account, per gruppo e per topic (stessa ereditarietà delle altre chiavi di configurazione Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -872,55 +873,55 @@ Sono supportate sovrascritture per account, gruppo e argomento (la stessa eredit
|
||||
## Risoluzione dei problemi
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Bot does not respond to non mention group messages">
|
||||
<Accordion title="Il bot non risponde ai messaggi di gruppo senza menzione">
|
||||
|
||||
- Se `requireMention=false`, la modalità privacy di Telegram deve consentire visibilità completa.
|
||||
- Se `requireMention=false`, la modalità privacy di Telegram deve consentire la visibilità completa.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- poi rimuovi e aggiungi di nuovo il bot al gruppo
|
||||
- `openclaw channels status` avvisa quando la configurazione si aspetta messaggi di gruppo senza menzione.
|
||||
- `openclaw channels status --probe` può controllare ID di gruppo numerici espliciti; il wildcard `"*"` non può essere verificato per appartenenza.
|
||||
- quindi 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 numerici espliciti dei gruppi; il carattere jolly `"*"` non può essere verificato tramite appartenenza.
|
||||
- test rapido della sessione: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Bot not seeing group messages at all">
|
||||
<Accordion title="Il bot non vede affatto i messaggi del gruppo">
|
||||
|
||||
- quando `channels.telegram.groups` esiste, il gruppo deve essere elencato (o includere `"*"`)
|
||||
- verifica l'appartenenza del bot al gruppo
|
||||
- controlla i log: `openclaw logs --follow` per i motivi di salto
|
||||
- controlla i log: `openclaw logs --follow` per i motivi di esclusione
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="I comandi funzionano parzialmente o non funzionano affatto">
|
||||
|
||||
- autorizza l'identità del mittente (abbinamento e/o `allowFrom` numerico)
|
||||
- autorizza l'identità del mittente (associazione e/o `allowFrom` numerico)
|
||||
- l'autorizzazione dei comandi si applica comunque anche quando la policy del gruppo è `open`
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu nativo ha troppe voci; riduci i comandi di Plugin/skill/personalizzati o disabilita i menu nativi
|
||||
- le chiamate di avvio `deleteMyCommands` / `setMyCommands` e le chiamate di digitazione `sendChatAction` sono limitate e riprovano una volta tramite il fallback di trasporto di Telegram in caso di timeout della richiesta. Errori persistenti di rete/fetch di solito indicano problemi di raggiungibilità DNS/HTTPS verso `api.telegram.org`
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu nativo ha troppe voci; riduci i comandi plugin/skill/personalizzati oppure disabilita i menu nativi
|
||||
- le chiamate di avvio `deleteMyCommands` / `setMyCommands` e le chiamate di digitazione `sendChatAction` sono limitate e ritentano una volta tramite il fallback di trasporto di Telegram in caso di timeout della richiesta. Errori persistenti di rete/fetch di solito indicano problemi di raggiungibilità DNS/HTTPS verso `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="L'avvio segnala un token non autorizzato">
|
||||
|
||||
- `getMe returned 401` è un errore di autenticazione Telegram per il token del bot configurato.
|
||||
- Ricopia o rigenera il token del bot in BotFather, poi aggiorna `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` o `TELEGRAM_BOT_TOKEN` per l'account predefinito.
|
||||
- `deleteWebhook 401 Unauthorized` durante l'avvio è anch'esso un errore di autenticazione; trattarlo come "non esiste alcun Webhook" rimanderebbe soltanto lo stesso errore di token non valido alle chiamate API successive.
|
||||
- `getMe returned 401` è un errore di autenticazione di Telegram per il token bot configurato.
|
||||
- Ricopia o rigenera il token bot in BotFather, quindi aggiorna `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` o `TELEGRAM_BOT_TOKEN` per l'account predefinito.
|
||||
- `deleteWebhook 401 Unauthorized` durante l'avvio è anch'esso un errore di autenticazione; trattarlo come "nessun webhook esiste" rinvierebbe soltanto lo stesso errore di token non valido alle chiamate API successive.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Instabilità del polling o della rete">
|
||||
<Accordion title="Instabilità di polling o rete">
|
||||
|
||||
- Node 22+ + fetch/proxy personalizzati possono attivare un comportamento di interruzione immediata se i tipi AbortSignal non corrispondono.
|
||||
- Node 22+ + fetch/proxy personalizzato può attivare un comportamento di interruzione immediata se i tipi AbortSignal non corrispondono.
|
||||
- Alcuni host risolvono prima `api.telegram.org` in IPv6; un'uscita IPv6 non funzionante può causare errori intermittenti dell'API Telegram.
|
||||
- Se i log includono `TypeError: fetch failed` o `Network request for 'getUpdates' failed!`, OpenClaw ora riprova questi errori come errori di rete recuperabili.
|
||||
- Durante l'avvio del polling, OpenClaw riutilizza il probe `getMe` di avvio riuscito per grammY, così il runner non ha bisogno di un secondo `getMe` prima del primo `getUpdates`.
|
||||
- Se `deleteWebhook` fallisce con un errore di rete transitorio durante l'avvio del polling, OpenClaw prosegue con il long polling invece di effettuare un'altra chiamata di control plane prima del polling. Un Webhook ancora attivo emerge come conflitto di `getUpdates`; OpenClaw quindi ricostruisce il trasporto Telegram e riprova la pulizia del Webhook.
|
||||
- Se i socket Telegram vengono riciclati con una cadenza fissa breve, controlla se `channels.telegram.timeoutSeconds` è basso; i client bot limitano i valori configurati sotto le protezioni delle richieste in uscita e `getUpdates`, ma le versioni precedenti potevano interrompere ogni poll o risposta quando questo valore era impostato sotto tali protezioni.
|
||||
- Se i log includono `Polling stall detected`, OpenClaw riavvia il polling e ricostruisce il trasporto Telegram dopo 120 secondi senza liveness di long-poll completata per impostazione predefinita.
|
||||
- `openclaw channels status --probe` e `openclaw doctor` avvisano quando un account di polling in esecuzione non ha completato `getUpdates` dopo il periodo di grazia dell'avvio, quando un account Webhook in esecuzione non ha completato `setWebhook` dopo il periodo di grazia dell'avvio, o quando l'ultima attività riuscita del trasporto di polling è obsoleta.
|
||||
- Aumenta `channels.telegram.pollingStallThresholdMs` solo quando le chiamate `getUpdates` a lunga durata sono sane ma il tuo host segnala comunque falsi riavvii per blocco del polling. Blocchi persistenti di solito indicano problemi di proxy, DNS, IPv6 o uscita TLS tra l'host e `api.telegram.org`.
|
||||
- Telegram rispetta anche le variabili di ambiente proxy del processo per il trasporto Bot API, incluse `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` e le loro varianti minuscole. `NO_PROXY` / `no_proxy` possono comunque bypassare `api.telegram.org`.
|
||||
- Se il proxy gestito da OpenClaw è configurato tramite `OPENCLAW_PROXY_URL` per un ambiente di servizio e non è presente alcuna variabile di ambiente proxy standard, Telegram usa quell'URL anche per il trasporto Bot API.
|
||||
- Se i log includono `TypeError: fetch failed` o `Network request for 'getUpdates' failed!`, OpenClaw ora ritenta questi errori come errori di rete recuperabili.
|
||||
- Durante l'avvio del polling, OpenClaw riutilizza per grammY la sonda di avvio `getMe` riuscita, quindi il runner non ha bisogno di un secondo `getMe` prima del primo `getUpdates`.
|
||||
- Se `deleteWebhook` fallisce con un errore di rete transitorio durante l'avvio del polling, OpenClaw passa comunque al long polling invece di effettuare un'altra chiamata control-plane prima del polling. Un webhook ancora attivo emerge come conflitto di `getUpdates`; OpenClaw quindi ricostruisce il trasporto Telegram e ritenta la pulizia del webhook.
|
||||
- Se i socket Telegram vengono riciclati con una cadenza fissa breve, controlla se `channels.telegram.timeoutSeconds` è basso; i client bot limitano i valori configurati sotto le protezioni delle richieste in uscita e `getUpdates`, ma le versioni precedenti potevano interrompere ogni polling o risposta quando questo valore era impostato sotto tali protezioni.
|
||||
- Se i log includono `Polling stall detected`, OpenClaw riavvia il polling e ricostruisce il trasporto Telegram dopo 120 secondi senza liveness completata del long-poll, per impostazione predefinita.
|
||||
- `openclaw channels status --probe` e `openclaw doctor` avvisano quando un account in polling in esecuzione non ha completato `getUpdates` dopo il periodo di tolleranza dell'avvio, quando un account webhook in esecuzione non ha completato `setWebhook` dopo il periodo di tolleranza dell'avvio, o quando l'ultima attività riuscita del trasporto di polling è obsoleta.
|
||||
- Aumenta `channels.telegram.pollingStallThresholdMs` solo quando le chiamate `getUpdates` di lunga durata sono sane ma il tuo host segnala comunque falsi riavvii per stallo del polling. Stalli persistenti di solito indicano problemi di uscita proxy, DNS, IPv6 o TLS tra l'host e `api.telegram.org`.
|
||||
- Telegram rispetta anche le variabili env proxy di processo per il trasporto Bot API, incluse `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` e le rispettive varianti minuscole. `NO_PROXY` / `no_proxy` possono comunque escludere `api.telegram.org`.
|
||||
- Se il proxy gestito da OpenClaw è configurato tramite `OPENCLAW_PROXY_URL` per un ambiente di servizio e non è presente alcuna variabile env proxy standard, Telegram usa quell'URL anche per il trasporto Bot API.
|
||||
- Sugli host VPS con uscita diretta/TLS instabile, instrada le chiamate API Telegram tramite `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
@ -929,7 +930,7 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ usa `autoSelectFamily=true` per impostazione predefinita (tranne WSL2). L'ordine dei risultati DNS di Telegram rispetta `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, poi `channels.telegram.network.dnsResultOrder`, poi il valore predefinito del processo come `NODE_OPTIONS=--dns-result-order=ipv4first`; se nessuno si applica, Node 22+ ripiega su `ipv4first`.
|
||||
- Node 22+ usa per impostazione predefinita `autoSelectFamily=true` (tranne WSL2). L'ordine dei risultati DNS di Telegram rispetta `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER`, poi `channels.telegram.network.dnsResultOrder`, poi il valore predefinito del processo come `NODE_OPTIONS=--dns-result-order=ipv4first`; se nessuno si applica, Node 22+ ripiega su `ipv4first`.
|
||||
- Se il tuo host è WSL2 o funziona esplicitamente meglio con comportamento solo IPv4, forza la selezione della famiglia:
|
||||
|
||||
```yaml
|
||||
@ -940,9 +941,9 @@ channels:
|
||||
```
|
||||
|
||||
- Le risposte nell'intervallo di benchmark RFC 2544 (`198.18.0.0/15`) sono già consentite
|
||||
per i download dei media Telegram per impostazione predefinita. Se un proxy fake-IP o
|
||||
trasparente attendibile riscrive `api.telegram.org` in qualche altro
|
||||
indirizzo privato/interno/di uso speciale durante i download dei media, puoi aderire
|
||||
per impostazione predefinita per i download dei media Telegram. Se un fake-IP attendibile o
|
||||
un proxy trasparente riscrive `api.telegram.org` verso un altro
|
||||
indirizzo privato/interno/a uso speciale durante i download dei media, puoi aderire
|
||||
al bypass solo per Telegram:
|
||||
|
||||
```yaml
|
||||
@ -952,18 +953,18 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- Lo stesso opt-in è disponibile per account in
|
||||
- La stessa adesione è 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 prima
|
||||
disattivato il flag pericoloso. I media Telegram consentono già l'intervallo
|
||||
di benchmark RFC 2544 per impostazione predefinita.
|
||||
disattivato il flag pericoloso. I media Telegram consentono già per impostazione predefinita
|
||||
l'intervallo di 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 routing fake-IP Clash, Mihomo o Surge, quando
|
||||
sintetizzano risposte private o di uso speciale fuori dall'intervallo di 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 attendibili controllati dall'operatore,
|
||||
come il routing fake-IP di Clash, Mihomo o Surge, quando sintetizzano
|
||||
risposte private o a uso speciale fuori dall'intervallo di benchmark RFC 2544.
|
||||
Lascialo disattivato per il normale accesso Telegram tramite internet pubblico.
|
||||
</Warning>
|
||||
|
||||
- Override di ambiente (temporanei):
|
||||
@ -988,16 +989,16 @@ Riferimento principale: [Riferimento di configurazione - Telegram](/it/gateway/c
|
||||
|
||||
<Accordion title="Campi Telegram ad alto segnale">
|
||||
|
||||
- avvio/autenticazione: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve puntare a un file normale; i symlink vengono rifiutati)
|
||||
- controllo degli accessi: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` di primo livello (`type: "acp"`)
|
||||
- avvio/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve puntare a un file regolare; i symlink vengono 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`
|
||||
- thread/risposte: `replyToMode`, `dm.threadReplies`, `direct.*.threadReplies`
|
||||
- streaming: `streaming` (anteprima), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- formattazione/consegna: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- media/rete: `mediaMaxMb`, `mediaGroupFlushMs`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- radice API personalizzata: `apiRoot` (solo radice Bot API; non includere `/bot<TOKEN>`)
|
||||
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- root API personalizzata: `apiRoot` (solo root Bot API; non includere `/bot<TOKEN>`)
|
||||
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- azioni/capacità: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- reazioni: `reactionNotifications`, `reactionLevel`
|
||||
- errori: `errorPolicy`, `errorCooldownMs`
|
||||
@ -1006,14 +1007,14 @@ Riferimento principale: [Riferimento di configurazione - Telegram](/it/gateway/c
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
Precedenza multi-account: quando sono configurati due o più ID account, imposta `channels.telegram.defaultAccount` (o includi `channels.telegram.accounts.default`) per rendere esplicito l'instradamento predefinito. In caso contrario OpenClaw ripiega sul primo ID account normalizzato e `openclaw doctor` avvisa. Gli account con nome ereditano `channels.telegram.allowFrom` / `groupAllowFrom`, ma non i valori `accounts.default.*`.
|
||||
Precedenza multi-account: quando sono configurati due o più ID account, imposta `channels.telegram.defaultAccount` (oppure includi `channels.telegram.accounts.default`) per rendere esplicito l'instradamento predefinito. Altrimenti OpenClaw ripiega sul primo ID account normalizzato e `openclaw doctor` avvisa. Gli account denominati ereditano `channels.telegram.allowFrom` / `groupAllowFrom`, ma non i valori `accounts.default.*`.
|
||||
</Note>
|
||||
|
||||
## Correlati
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Abbinamento" icon="link" href="/it/channels/pairing">
|
||||
Abbina un utente Telegram al Gateway.
|
||||
<Card title="Associazione" icon="link" href="/it/channels/pairing">
|
||||
Associa un utente Telegram al Gateway.
|
||||
</Card>
|
||||
<Card title="Gruppi" icon="users" href="/it/channels/groups">
|
||||
Comportamento dell'allowlist per gruppi e argomenti.
|
||||
|
||||
@ -2,13 +2,13 @@
|
||||
read_when:
|
||||
- Aggiunta o modifica delle azioni CLI per i messaggi
|
||||
- Modifica del comportamento del canale in uscita
|
||||
summary: Riferimento CLI per `openclaw message` (invio + azioni del canale)
|
||||
summary: Riferimento CLI per `openclaw message` (send + azioni di canale)
|
||||
title: Messaggio
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T20:42:34Z"
|
||||
generated_at: "2026-05-04T08:40:00Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 6b73a50da34838f80ad5d0d266f5c66f95436f8535e6312296ae022918b1ab55
|
||||
source_hash: 9ef57d33c93206a61a6d044667de4faf6340f7d8cc324300f235e838ee3b7ff1
|
||||
source_path: cli/message.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -26,19 +26,19 @@ openclaw message <subcommand> [flags]
|
||||
|
||||
Selezione del canale:
|
||||
|
||||
- `--channel` è obbligatorio se è configurato più di un canale.
|
||||
- Se è configurato esattamente un canale, diventa il predefinito.
|
||||
- `--channel` è richiesto se è configurato più di un canale.
|
||||
- Se è configurato esattamente un canale, diventa quello predefinito.
|
||||
- Valori: `discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp` (Mattermost richiede un plugin)
|
||||
- `openclaw message` risolve il canale selezionato nel relativo plugin proprietario quando è presente `--channel` o una destinazione con prefisso di canale; altrimenti carica i plugin di canale configurati per inferire il canale predefinito.
|
||||
- `openclaw message` risolve il canale selezionato nel relativo plugin proprietario quando è presente `--channel` o una destinazione con prefisso di canale; altrimenti carica i plugin di canale configurati per dedurre il canale predefinito.
|
||||
|
||||
Formati di destinazione (`--target`):
|
||||
|
||||
- WhatsApp: E.164, JID di gruppo o JID di WhatsApp Channel/Newsletter (`...@newsletter`)
|
||||
- Telegram: ID chat o `@username`
|
||||
- WhatsApp: E.164, JID del gruppo o JID di WhatsApp Channel/Newsletter (`...@newsletter`)
|
||||
- Telegram: ID chat, `@username` o destinazione di argomento forum (`-1001234567890:topic:42` o `--thread-id 42`)
|
||||
- Discord: `channel:<id>` o `user:<id>` (o menzione `<@id>`; gli ID numerici grezzi sono trattati come canali)
|
||||
- Google Chat: `spaces/<spaceId>` o `users/<userId>`
|
||||
- Slack: `channel:<id>` o `user:<id>` (l'ID di canale grezzo è accettato)
|
||||
- Mattermost (plugin): `channel:<id>`, `user:<id>` o `@username` (gli ID senza prefisso sono trattati come canali)
|
||||
- Slack: `channel:<id>` o `user:<id>` (l'ID canale grezzo è accettato)
|
||||
- Mattermost (plugin): `channel:<id>`, `user:<id>` o `@username` (gli ID semplici sono trattati come canali)
|
||||
- Signal: `+E.164`, `group:<id>`, `signal:+E.164`, `signal:group:<id>` o `username:<name>`/`u:<name>`
|
||||
- iMessage: handle, `chat_id:<id>`, `chat_guid:<guid>` o `chat_identifier:<id>`
|
||||
- Matrix: `@user:server`, `!room:server` o `#alias:server`
|
||||
@ -46,28 +46,28 @@ Formati di destinazione (`--target`):
|
||||
|
||||
Ricerca per nome:
|
||||
|
||||
- Per i provider supportati (Discord/Slack/ecc.), i nomi di canale come `Help` o `#help` vengono risolti tramite la cache della directory.
|
||||
- Per i provider supportati (Discord/Slack/ecc.), i nomi dei canali come `Help` o `#help` vengono risolti tramite la cache della directory.
|
||||
- In caso di mancato riscontro nella cache, OpenClaw tenterà una ricerca live nella directory quando il provider la supporta.
|
||||
|
||||
## Flag comuni
|
||||
|
||||
- `--channel <name>`
|
||||
- `--account <id>`
|
||||
- `--target <dest>` (canale o utente di destinazione per invio/sondaggio/lettura/ecc.)
|
||||
- `--targets <name>` (ripetibile; solo broadcast)
|
||||
- `--target <dest>` (canale o utente di destinazione per send/poll/read/ecc.)
|
||||
- `--targets <name>` (ripeti; solo broadcast)
|
||||
- `--json`
|
||||
- `--dry-run`
|
||||
- `--verbose`
|
||||
|
||||
## Comportamento di SecretRef
|
||||
## Comportamento SecretRef
|
||||
|
||||
- `openclaw message` risolve i SecretRef dei canali supportati prima di eseguire l'azione selezionata.
|
||||
- La risoluzione è limitata alla destinazione dell'azione attiva quando possibile:
|
||||
- con ambito di canale quando `--channel` è impostato (o inferito da destinazioni con prefisso come `discord:...`)
|
||||
- con ambito di account quando `--account` è impostato (globali del canale + superfici dell'account selezionato)
|
||||
- quando `--account` è omesso, OpenClaw non forza un ambito SecretRef per l'account `default`
|
||||
- con ambito canale quando `--channel` è impostato (o dedotto da destinazioni con prefisso come `discord:...`)
|
||||
- con ambito account quando `--account` è impostato (globali di canale + superfici dell'account selezionato)
|
||||
- quando `--account` è omesso, OpenClaw non forza un ambito SecretRef dell'account `default`
|
||||
- I SecretRef non risolti su canali non correlati non bloccano un'azione di messaggio mirata.
|
||||
- Se il SecretRef del canale/account selezionato non è risolto, il comando non procede per quell'azione.
|
||||
- Se il SecretRef del canale/account selezionato non è risolto, il comando fallisce in modo chiuso per quell'azione.
|
||||
|
||||
## Azioni
|
||||
|
||||
@ -75,84 +75,84 @@ Ricerca per nome:
|
||||
|
||||
- `send`
|
||||
- Canali: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Matrix/Microsoft Teams
|
||||
- Obbligatorio: `--target`, più `--message`, `--media` o `--presentation`
|
||||
- Richiesto: `--target`, più `--message`, `--media` o `--presentation`
|
||||
- Facoltativo: `--media`, `--presentation`, `--delivery`, `--pin`, `--reply-to`, `--thread-id`, `--gif-playback`, `--force-document`, `--silent`
|
||||
- Payload di presentazione condivisi: `--presentation` invia blocchi semantici (`text`, `context`, `divider`, `buttons`, `select`) che il core renderizza tramite le capacità dichiarate del canale selezionato. Consulta [Presentazione dei messaggi](/it/plugins/message-presentation).
|
||||
- Payload di presentazione condivisi: `--presentation` invia blocchi semantici (`text`, `context`, `divider`, `buttons`, `select`) che il core renderizza attraverso le capacità dichiarate dal canale selezionato. Vedi [Presentazione dei messaggi](/it/plugins/message-presentation).
|
||||
- Preferenze di consegna generiche: `--delivery` accetta suggerimenti di consegna come `{ "pin": true }`; `--pin` è una scorciatoia per la consegna fissata quando il canale la supporta.
|
||||
- Solo Telegram: `--force-document` (invia immagini e GIF come documenti per evitare la compressione di Telegram)
|
||||
- Solo Telegram: `--thread-id` (ID dell'argomento del forum)
|
||||
- Solo Telegram: `--thread-id` (ID dell'argomento forum)
|
||||
- Solo Slack: `--thread-id` (timestamp del thread; `--reply-to` usa lo stesso campo)
|
||||
- Telegram + Discord: `--silent`
|
||||
- Solo WhatsApp: `--gif-playback`; i WhatsApp Channel/Newsletter vengono indirizzati con il loro JID nativo `@newsletter`.
|
||||
- Solo WhatsApp: `--gif-playback`; WhatsApp Channels/Newsletters sono indirizzati con il loro JID nativo `@newsletter`.
|
||||
|
||||
- `poll`
|
||||
- Canali: WhatsApp/Telegram/Discord/Matrix/Microsoft Teams
|
||||
- Obbligatorio: `--target`, `--poll-question`, `--poll-option` (ripetibile)
|
||||
- Richiesto: `--target`, `--poll-question`, `--poll-option` (ripeti)
|
||||
- Facoltativo: `--poll-multi`
|
||||
- Solo Discord: `--poll-duration-hours`, `--silent`, `--message`
|
||||
- Solo Telegram: `--poll-duration-seconds` (5-600), `--silent`, `--poll-anonymous` / `--poll-public`, `--thread-id`
|
||||
|
||||
- `react`
|
||||
- Canali: Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/Matrix
|
||||
- Obbligatorio: `--message-id`, `--target`
|
||||
- Richiesto: `--message-id`, `--target`
|
||||
- Facoltativo: `--emoji`, `--remove`, `--participant`, `--from-me`, `--target-author`, `--target-author-uuid`
|
||||
- Nota: `--remove` richiede `--emoji` (ometti `--emoji` per cancellare le proprie reazioni dove supportato; vedi /tools/reactions)
|
||||
- Solo WhatsApp: `--participant`, `--from-me`
|
||||
- Reazioni di gruppo Signal: `--target-author` o `--target-author-uuid` obbligatorio
|
||||
- Reazioni di gruppo Signal: `--target-author` o `--target-author-uuid` richiesto
|
||||
|
||||
- `reactions`
|
||||
- Canali: Discord/Google Chat/Slack/Matrix
|
||||
- Obbligatorio: `--message-id`, `--target`
|
||||
- Richiesto: `--message-id`, `--target`
|
||||
- Facoltativo: `--limit`
|
||||
|
||||
- `read`
|
||||
- Canali: Discord/Slack/Matrix
|
||||
- Obbligatorio: `--target`
|
||||
- Richiesto: `--target`
|
||||
- Facoltativo: `--limit`, `--message-id`, `--before`, `--after`
|
||||
- Solo Slack: `--message-id` legge un timestamp specifico di un messaggio Slack; combina con `--thread-id` per leggere una risposta esatta in un thread.
|
||||
- Solo Slack: `--message-id` legge un timestamp di messaggio Slack specifico; combinalo con `--thread-id` per leggere una risposta esatta del thread.
|
||||
- Solo Discord: `--around`
|
||||
|
||||
- `edit`
|
||||
- Canali: Discord/Slack/Matrix
|
||||
- Obbligatorio: `--message-id`, `--message`, `--target`
|
||||
- Richiesto: `--message-id`, `--message`, `--target`
|
||||
|
||||
- `delete`
|
||||
- Canali: Discord/Slack/Telegram/Matrix
|
||||
- Obbligatorio: `--message-id`, `--target`
|
||||
- Richiesto: `--message-id`, `--target`
|
||||
|
||||
- `pin` / `unpin`
|
||||
- Canali: Discord/Slack/Matrix
|
||||
- Obbligatorio: `--message-id`, `--target`
|
||||
- Richiesto: `--message-id`, `--target`
|
||||
|
||||
- `pins` (elenco)
|
||||
- Canali: Discord/Slack/Matrix
|
||||
- Obbligatorio: `--target`
|
||||
- Richiesto: `--target`
|
||||
|
||||
- `permissions`
|
||||
- Canali: Discord/Matrix
|
||||
- Obbligatorio: `--target`
|
||||
- Richiesto: `--target`
|
||||
- Solo Matrix: disponibile quando la crittografia Matrix è abilitata e le azioni di verifica sono consentite
|
||||
|
||||
- `search`
|
||||
- Canali: Discord
|
||||
- Obbligatorio: `--guild-id`, `--query`
|
||||
- Facoltativo: `--channel-id`, `--channel-ids` (ripetibile), `--author-id`, `--author-ids` (ripetibile), `--limit`
|
||||
- Richiesto: `--guild-id`, `--query`
|
||||
- Facoltativo: `--channel-id`, `--channel-ids` (ripeti), `--author-id`, `--author-ids` (ripeti), `--limit`
|
||||
|
||||
### Thread
|
||||
|
||||
- `thread create`
|
||||
- Canali: Discord
|
||||
- Obbligatorio: `--thread-name`, `--target` (ID canale)
|
||||
- Richiesto: `--thread-name`, `--target` (ID canale)
|
||||
- Facoltativo: `--message-id`, `--message`, `--auto-archive-min`
|
||||
|
||||
- `thread list`
|
||||
- Canali: Discord
|
||||
- Obbligatorio: `--guild-id`
|
||||
- Richiesto: `--guild-id`
|
||||
- Facoltativo: `--channel-id`, `--include-archived`, `--before`, `--limit`
|
||||
|
||||
- `thread reply`
|
||||
- Canali: Discord
|
||||
- Obbligatorio: `--target` (ID thread), `--message`
|
||||
- Richiesto: `--target` (ID thread), `--message`
|
||||
- Facoltativo: `--media`, `--reply-to`
|
||||
|
||||
### Emoji
|
||||
@ -163,19 +163,19 @@ Ricerca per nome:
|
||||
|
||||
- `emoji upload`
|
||||
- Canali: Discord
|
||||
- Obbligatorio: `--guild-id`, `--emoji-name`, `--media`
|
||||
- Facoltativo: `--role-ids` (ripetibile)
|
||||
- Richiesto: `--guild-id`, `--emoji-name`, `--media`
|
||||
- Facoltativo: `--role-ids` (ripeti)
|
||||
|
||||
### Sticker
|
||||
|
||||
- `sticker send`
|
||||
- Canali: Discord
|
||||
- Obbligatorio: `--target`, `--sticker-id` (ripetibile)
|
||||
- Richiesto: `--target`, `--sticker-id` (ripeti)
|
||||
- Facoltativo: `--message`
|
||||
|
||||
- `sticker upload`
|
||||
- Canali: Discord
|
||||
- Obbligatorio: `--guild-id`, `--sticker-name`, `--sticker-desc`, `--sticker-tags`, `--media`
|
||||
- Richiesto: `--guild-id`, `--sticker-name`, `--sticker-desc`, `--sticker-tags`, `--media`
|
||||
|
||||
### Ruoli / Canali / Membri / Voce
|
||||
|
||||
@ -202,8 +202,8 @@ Ricerca per nome:
|
||||
### Broadcast
|
||||
|
||||
- `broadcast`
|
||||
- Canali: qualsiasi canale configurato; usa `--channel all` per destinare tutti i provider
|
||||
- Obbligatorio: `--targets <target...>`
|
||||
- Canali: qualsiasi canale configurato; usa `--channel all` per indirizzare tutti i provider
|
||||
- Richiesto: `--targets <target...>`
|
||||
- Facoltativo: `--message`, `--media`, `--dry-run`
|
||||
|
||||
## Esempi
|
||||
@ -223,7 +223,7 @@ openclaw message send --channel discord \
|
||||
--presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Approve","value":"approve","style":"success"},{"label":"Decline","value":"decline","style":"danger"}]}]}'
|
||||
```
|
||||
|
||||
Il core renderizza lo stesso payload `presentation` in componenti Discord, blocchi Slack, pulsanti inline Telegram, proprietà Mattermost o schede Teams/Feishu in base alle capacità del canale. Consulta [Presentazione dei messaggi](/it/plugins/message-presentation) per il contratto completo e le regole di fallback.
|
||||
Il core renderizza lo stesso payload `presentation` in componenti Discord, blocchi Slack, pulsanti inline Telegram, props Mattermost o schede Teams/Feishu in base alla capacità del canale. Vedi [Presentazione dei messaggi](/it/plugins/message-presentation) per il contratto completo e le regole di fallback.
|
||||
|
||||
Invia un payload di presentazione più ricco:
|
||||
|
||||
@ -243,7 +243,7 @@ openclaw message poll --channel discord \
|
||||
--poll-multi --poll-duration-hours 48
|
||||
```
|
||||
|
||||
Crea un sondaggio Telegram (chiusura automatica tra 2 minuti):
|
||||
Crea un sondaggio Telegram (chiusura automatica in 2 minuti):
|
||||
|
||||
```
|
||||
openclaw message poll --channel telegram \
|
||||
@ -284,14 +284,14 @@ openclaw message react --channel signal \
|
||||
--emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
|
||||
```
|
||||
|
||||
Invia pulsanti inline Telegram tramite presentazione generica:
|
||||
Invia pulsanti inline Telegram tramite la presentazione generica:
|
||||
|
||||
```
|
||||
openclaw message send --channel telegram --target @mychat --message "Choose:" \
|
||||
--presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Yes","value":"cmd:yes"},{"label":"No","value":"cmd:no"}]}]}'
|
||||
```
|
||||
|
||||
Invia una scheda Teams tramite presentazione generica:
|
||||
Invia una scheda Teams tramite la presentazione generica:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel msteams \
|
||||
|
||||
@ -1,24 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- Vuoi installare o gestire plugin del Gateway o bundle compatibili
|
||||
- Vuoi eseguire il debug degli errori di caricamento dei plugin
|
||||
- Vuoi installare o gestire i Plugin Gateway o pacchetti compatibili
|
||||
- Vuoi eseguire il debug degli errori di caricamento dei Plugin
|
||||
sidebarTitle: Plugins
|
||||
summary: Riferimento CLI per `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
|
||||
title: Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T07:02:59Z"
|
||||
generated_at: "2026-05-04T08:40:01Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 36ae7edb12986ead7e126f25e0761bf312b2644b35017181b674082105886776
|
||||
source_hash: d3f0ac9412e24f3598e9bab6389f770b3d0d26268d9907891697919d9371f1c1
|
||||
source_path: cli/plugins.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Gestisci Plugin del Gateway, pacchetti di hook e bundle compatibili.
|
||||
Gestisci i Plugin del Gateway, i pacchetti di hook e i bundle compatibili.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Sistema Plugin" href="/it/tools/plugin">
|
||||
Guida per utenti finali per installare, abilitare e risolvere problemi dei plugin.
|
||||
<Card title="Sistema di Plugin" href="/it/tools/plugin">
|
||||
Guida per l'utente finale per installare, abilitare e risolvere i problemi dei Plugin.
|
||||
</Card>
|
||||
<Card title="Gestisci Plugin" href="/it/plugins/manage-plugins">
|
||||
Esempi rapidi per installazione, elenco, aggiornamento, disinstallazione e pubblicazione.
|
||||
@ -30,7 +30,7 @@ Gestisci Plugin del Gateway, pacchetti di hook e bundle compatibili.
|
||||
Campi del manifest e schema di configurazione.
|
||||
</Card>
|
||||
<Card title="Sicurezza" href="/it/gateway/security">
|
||||
Rafforzamento della sicurezza per le installazioni di plugin.
|
||||
Rafforzamento della sicurezza per le installazioni dei Plugin.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -62,12 +62,14 @@ openclaw plugins marketplace list <marketplace>
|
||||
openclaw plugins marketplace list <marketplace> --json
|
||||
```
|
||||
|
||||
Per indagare su installazioni, ispezioni, disinstallazioni o aggiornamenti del registro lenti, esegui il comando con `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. La traccia scrive i tempi delle fasi su stderr e mantiene analizzabile l'output JSON. Vedi [Debug](/it/help/debugging#plugin-lifecycle-trace).
|
||||
Per analizzare installazioni, ispezioni, disinstallazioni o aggiornamenti del registro lenti, esegui il
|
||||
comando con `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`. La traccia scrive i tempi delle fasi
|
||||
su stderr e mantiene analizzabile l'output JSON. Vedi [Debugging](/it/help/debugging#plugin-lifecycle-trace).
|
||||
|
||||
<Note>
|
||||
I plugin inclusi vengono distribuiti con OpenClaw. Alcuni sono abilitati per impostazione predefinita (ad esempio provider di modelli inclusi, provider vocali inclusi e il plugin browser incluso); altri richiedono `plugins enable`.
|
||||
I Plugin inclusi vengono distribuiti con OpenClaw. Alcuni sono abilitati per impostazione predefinita (per esempio provider di modelli inclusi, provider vocali inclusi e il Plugin browser incluso); altri richiedono `plugins enable`.
|
||||
|
||||
I Plugin OpenClaw nativi devono distribuire `openclaw.plugin.json` con uno schema JSON inline (`configSchema`, anche se vuoto). I bundle compatibili usano invece i propri manifest di bundle.
|
||||
I Plugin OpenClaw nativi devono distribuire `openclaw.plugin.json` con un JSON Schema inline (`configSchema`, anche se vuoto). I bundle compatibili usano invece i propri manifest di bundle.
|
||||
|
||||
`plugins list` mostra `Format: openclaw` o `Format: bundle`. L'output dettagliato di elenco/info mostra anche il sottotipo del bundle (`codex`, `claude` o `cursor`) più le funzionalità del bundle rilevate.
|
||||
</Note>
|
||||
@ -91,63 +93,71 @@ openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Durante il passaggio di lancio, i nomi di pacchetto semplici installano da npm per impostazione predefinita. Usa `clawhub:<package>` per ClawHub. Tratta le installazioni di plugin come esecuzione di codice. Preferisci versioni fissate.
|
||||
I nomi di pacchetto senza prefisso vengono installati da npm per impostazione predefinita durante la transizione di lancio. Usa `clawhub:<package>` per ClawHub. Tratta le installazioni dei Plugin come codice in esecuzione. Preferisci versioni fissate.
|
||||
</Warning>
|
||||
|
||||
`plugins search` interroga ClawHub per pacchetti di plugin installabili e stampa nomi di pacchetto pronti per l'installazione. Cerca pacchetti di plugin di codice e plugin bundle, non Skills. Usa `openclaw skills search` per le Skills di ClawHub.
|
||||
`plugins search` interroga ClawHub per pacchetti Plugin installabili e stampa
|
||||
nomi di pacchetto pronti per l'installazione. Cerca pacchetti code-plugin e bundle-plugin,
|
||||
non Skills. Usa `openclaw skills search` per le Skills di ClawHub.
|
||||
|
||||
<Note>
|
||||
ClawHub è la superficie principale di distribuzione e scoperta per la maggior parte dei plugin. Npm rimane un fallback supportato e un percorso di installazione diretta. I pacchetti di plugin `@openclaw/*` di proprietà di OpenClaw sono di nuovo pubblicati su npm; vedi l'elenco attuale su [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) o l'[inventario dei plugin](/it/plugins/plugin-inventory). Le installazioni stabili usano `latest`. Le installazioni e gli aggiornamenti del canale beta preferiscono il dist-tag npm `beta` quando quel tag è disponibile, poi ripiegano su `latest`.
|
||||
ClawHub è la superficie principale di distribuzione e scoperta per la maggior parte dei Plugin. Npm
|
||||
rimane un fallback supportato e un percorso di installazione diretta. I pacchetti Plugin
|
||||
`@openclaw/*` di proprietà di OpenClaw sono di nuovo pubblicati su npm; vedi l'elenco attuale
|
||||
su [npmjs.com/org/openclaw](https://www.npmjs.com/org/openclaw) o
|
||||
[l'inventario dei Plugin](/it/plugins/plugin-inventory). Le installazioni stabili usano `latest`.
|
||||
Le installazioni e gli aggiornamenti del canale beta preferiscono il dist-tag npm `beta` quando quel tag
|
||||
è disponibile, poi ripiegano su `latest`.
|
||||
</Note>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Include di configurazione e riparazione di configurazioni non valide">
|
||||
Se la tua sezione `plugins` è supportata da un `$include` a file singolo, `plugins install/update/enable/disable/uninstall` scrive direttamente in quel file incluso e lascia `openclaw.json` intatto. Include radice, array di include e include con override fratelli falliscono in modo chiuso invece di essere appiattiti. Vedi [include di configurazione](/it/gateway/configuration) per le forme supportate.
|
||||
<Accordion title="Include di configurazione e riparazione di configurazione non valida">
|
||||
Se la tua sezione `plugins` è supportata da un `$include` a file singolo, `plugins install/update/enable/disable/uninstall` scrive in quel file incluso e lascia `openclaw.json` intatto. Include root, array di include e include con override fratelli falliscono in modo chiuso invece di essere appiattiti. Vedi [Include di configurazione](/it/gateway/configuration) per le forme supportate.
|
||||
|
||||
Se la configurazione non è valida durante l'installazione, `plugins install` normalmente fallisce in modo chiuso e ti indica di eseguire prima `openclaw doctor --fix`. Durante l'avvio del Gateway e il ricaricamento a caldo, una configurazione plugin non valida fallisce in modo chiuso come qualsiasi altra configurazione non valida; `openclaw doctor --fix` può mettere in quarantena la voce plugin non valida. L'unica eccezione documentata in fase di installazione è un percorso ristretto di recupero dei plugin inclusi per plugin che scelgono esplicitamente `openclaw.install.allowInvalidConfigRecovery`.
|
||||
Se la configurazione non è valida durante l'installazione, `plugins install` normalmente fallisce in modo chiuso e ti dice di eseguire prima `openclaw doctor --fix`. Durante l'avvio del Gateway e il ricaricamento a caldo, una configurazione Plugin non valida fallisce in modo chiuso come qualsiasi altra configurazione non valida; `openclaw doctor --fix` può mettere in quarantena la voce Plugin non valida. L'unica eccezione documentata in fase di installazione è uno stretto percorso di ripristino per Plugin inclusi che aderiscono esplicitamente a `openclaw.install.allowInvalidConfigRecovery`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--force e reinstallazione rispetto ad aggiornamento">
|
||||
`--force` riutilizza la destinazione di installazione esistente e sovrascrive sul posto un plugin o pacchetto di hook già installato. Usalo quando stai reinstallando intenzionalmente lo stesso id da un nuovo percorso locale, archivio, pacchetto ClawHub o artefatto npm. Per gli aggiornamenti di routine di un plugin npm già tracciato, preferisci `openclaw plugins update <id-or-npm-spec>`.
|
||||
`--force` riutilizza la destinazione di installazione esistente e sovrascrive sul posto un Plugin o pacchetto di hook già installato. Usalo quando stai reinstallando intenzionalmente lo stesso id da un nuovo percorso locale, archivio, pacchetto ClawHub o artefatto npm. Per aggiornamenti ordinari di un Plugin npm già tracciato, preferisci `openclaw plugins update <id-or-npm-spec>`.
|
||||
|
||||
Se esegui `plugins install` per un id plugin già installato, OpenClaw si ferma e ti indirizza a `plugins update <id-or-npm-spec>` per un normale aggiornamento, oppure a `plugins install <package> --force` quando vuoi davvero sovrascrivere l'installazione corrente da una fonte diversa.
|
||||
Se esegui `plugins install` per un id Plugin già installato, OpenClaw si ferma e ti indirizza a `plugins update <id-or-npm-spec>` per un aggiornamento normale, oppure a `plugins install <package> --force` quando vuoi davvero sovrascrivere l'installazione corrente da una fonte diversa.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Ambito di --pin">
|
||||
`--pin` si applica solo alle installazioni npm. Non è supportato con installazioni `git:`; usa un riferimento git esplicito come `git:github.com/acme/plugin@v1.2.3` quando vuoi una fonte fissata. Non è supportato con `--marketplace`, perché le installazioni marketplace conservano i metadati della fonte marketplace invece di una specifica npm.
|
||||
`--pin` si applica solo alle installazioni npm. Non è supportato con installazioni `git:`; usa un ref git esplicito come `git:github.com/acme/plugin@v1.2.3` quando vuoi una fonte fissata. Non è supportato con `--marketplace`, perché le installazioni marketplace persistono metadati della fonte marketplace invece di una spec npm.
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install">
|
||||
`--dangerously-force-unsafe-install` è un'opzione di emergenza per falsi positivi nello scanner integrato di codice pericoloso. Consente all'installazione di continuare anche quando lo scanner integrato segnala risultati `critical`, ma **non** aggira i blocchi di policy degli hook `before_install` del plugin e **non** aggira gli errori di scansione.
|
||||
`--dangerously-force-unsafe-install` è un'opzione di emergenza per falsi positivi nello scanner integrato di codice pericoloso. Permette all'installazione di continuare anche quando lo scanner integrato segnala risultati `critical`, ma **non** aggira i blocchi di policy dell'hook `before_install` del Plugin e **non** aggira i fallimenti della scansione.
|
||||
|
||||
Questo flag CLI si applica ai flussi di installazione/aggiornamento dei plugin. Le installazioni di dipendenze Skills gestite dal Gateway usano l'override di richiesta corrispondente `dangerouslyForceUnsafeInstall`, mentre `openclaw skills install` rimane un flusso separato di download/installazione Skills da ClawHub.
|
||||
Questo flag CLI si applica ai flussi di installazione/aggiornamento dei Plugin. Le installazioni delle dipendenze Skills supportate dal Gateway usano l'override di richiesta corrispondente `dangerouslyForceUnsafeInstall`, mentre `openclaw skills install` rimane un flusso separato di download/installazione di Skills ClawHub.
|
||||
|
||||
Se un plugin che hai pubblicato su ClawHub viene bloccato da una scansione del registro, usa i passaggi per publisher in [ClawHub](/it/tools/clawhub).
|
||||
Se un Plugin che hai pubblicato su ClawHub è bloccato da una scansione del registro, usa i passaggi per publisher in [ClawHub](/it/tools/clawhub).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Pacchetti di hook e specifiche npm">
|
||||
<Accordion title="Pacchetti di hook e spec npm">
|
||||
`plugins install` è anche la superficie di installazione per pacchetti di hook che espongono `openclaw.hooks` in `package.json`. Usa `openclaw hooks` per visibilità filtrata degli hook e abilitazione per singolo hook, non per l'installazione del pacchetto.
|
||||
|
||||
Le specifiche npm sono **solo registro** (nome del pacchetto + **versione esatta** o **dist-tag** opzionale). Specifiche Git/URL/file e intervalli semver vengono rifiutati. Le installazioni di dipendenze vengono eseguite localmente al progetto con `--ignore-scripts` per sicurezza, anche quando la tua shell ha impostazioni globali di installazione npm.
|
||||
Le spec npm sono **solo registro** (nome pacchetto + **versione esatta** facoltativa o **dist-tag**). Spec Git/URL/file e intervalli semver vengono rifiutati. Le installazioni delle dipendenze vengono eseguite localmente al progetto con `--ignore-scripts` per sicurezza, anche quando la tua shell ha impostazioni globali di installazione npm.
|
||||
|
||||
Usa `npm:<package>` quando vuoi rendere esplicita la risoluzione npm. Durante il passaggio di lancio, anche le specifiche di pacchetto semplici installano direttamente da npm.
|
||||
Usa `npm:<package>` quando vuoi rendere esplicita la risoluzione npm. Anche le spec di pacchetto senza prefisso installano direttamente da npm durante la transizione di lancio.
|
||||
|
||||
Le specifiche semplici e `@latest` restano sul canale stabile. Le versioni di correzione OpenClaw con data, come `2026.5.3-1`, sono release stabili per questo controllo. Se npm risolve una di queste in una prerelease, OpenClaw si ferma e ti chiede di aderire esplicitamente con un tag prerelease come `@beta`/`@rc` o una versione prerelease esatta come `@1.2.3-beta.4`.
|
||||
Le spec senza prefisso e `@latest` restano sul canale stabile. Le versioni correttive datate di OpenClaw come `2026.5.3-1` sono release stabili per questo controllo. Se npm risolve una di queste in una prerelease, OpenClaw si ferma e ti chiede di aderire esplicitamente con un tag prerelease come `@beta`/`@rc` o una versione prerelease esatta come `@1.2.3-beta.4`.
|
||||
|
||||
Se una specifica di installazione semplice corrisponde a un id plugin ufficiale (ad esempio `diffs`), OpenClaw installa direttamente la voce del catalogo. Per installare un pacchetto npm con lo stesso nome, usa una specifica scoped esplicita (ad esempio `@scope/diffs`).
|
||||
Se una spec di installazione senza prefisso corrisponde a un id Plugin ufficiale (per esempio `diffs`), OpenClaw installa direttamente la voce del catalogo. Per installare un pacchetto npm con lo stesso nome, usa una spec con scope esplicito (per esempio `@scope/diffs`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Repository Git">
|
||||
Usa `git:<repo>` per installare direttamente da un repository git. Le forme supportate includono URL di clone `git:github.com/owner/repo`, `git:owner/repo`, `https://` completo, `ssh://`, `git://`, `file://` e `git@host:owner/repo.git`. Aggiungi `@<ref>` o `#<ref>` per eseguire il checkout di un branch, tag o commit prima dell'installazione.
|
||||
Usa `git:<repo>` per installare direttamente da un repository git. Le forme supportate includono URL clone `git:github.com/owner/repo`, `git:owner/repo`, `https://` completo, `ssh://`, `git://`, `file://` e `git@host:owner/repo.git`. Aggiungi `@<ref>` o `#<ref>` per fare il checkout di un branch, tag o commit prima dell'installazione.
|
||||
|
||||
Le installazioni Git clonano in una directory temporanea, eseguono il checkout del ref richiesto quando presente, poi usano il normale installatore di directory plugin. Questo significa che convalida del manifest, scansione di codice pericoloso, lavoro di installazione del package manager e record di installazione si comportano come nelle installazioni npm. Le installazioni git registrate includono l'URL/ref della fonte più il commit risolto, così `openclaw plugins update` può risolvere di nuovo la fonte in seguito.
|
||||
Le installazioni Git clonano in una directory temporanea, fanno il checkout del ref richiesto quando presente, poi usano il normale installer della directory Plugin. Questo significa che validazione del manifest, scansione di codice pericoloso, lavoro di installazione del package manager e record di installazione si comportano come installazioni npm. Le installazioni git registrate includono URL/ref di origine più il commit risolto, così `openclaw plugins update` può risolvere di nuovo la fonte in seguito.
|
||||
|
||||
Dopo l'installazione da git, usa `openclaw plugins inspect <id> --runtime --json` per verificare registrazioni runtime come metodi Gateway e comandi CLI. Se il plugin ha registrato una radice CLI con `api.registerCli`, esegui quel comando direttamente tramite la CLI radice di OpenClaw, ad esempio `openclaw demo-plugin ping`.
|
||||
Dopo l'installazione da git, usa `openclaw plugins inspect <id> --runtime --json` per verificare registrazioni runtime come metodi del Gateway e comandi CLI. Se il Plugin ha registrato una root CLI con `api.registerCli`, esegui quel comando direttamente tramite la CLI root di OpenClaw, per esempio `openclaw demo-plugin ping`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Archivi">
|
||||
Archivi supportati: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Gli archivi di Plugin OpenClaw nativi devono contenere un `openclaw.plugin.json` valido nella radice del plugin estratto; gli archivi che contengono solo `package.json` vengono rifiutati prima che OpenClaw scriva record di installazione.
|
||||
Archivi supportati: `.zip`, `.tgz`, `.tar.gz`, `.tar`. Gli archivi Plugin OpenClaw nativi devono contenere un `openclaw.plugin.json` valido alla root estratta del Plugin; gli archivi che contengono solo `package.json` vengono rifiutati prima che OpenClaw scriva record di installazione.
|
||||
|
||||
Sono supportate anche le installazioni dal marketplace Claude.
|
||||
Sono supportate anche le installazioni marketplace Claude.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -159,7 +169,7 @@ openclaw plugins install clawhub:openclaw-codex-app-server
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
|
||||
```
|
||||
|
||||
Durante il passaggio di lancio, le specifiche di plugin compatibili con npm installano da npm per impostazione predefinita:
|
||||
Le spec Plugin compatibili con npm senza prefisso installano da npm per impostazione predefinita durante la transizione di lancio:
|
||||
|
||||
```bash
|
||||
openclaw plugins install openclaw-codex-app-server
|
||||
@ -172,8 +182,8 @@ openclaw plugins install npm:openclaw-codex-app-server
|
||||
openclaw plugins install npm:@scope/plugin-name@1.0.1
|
||||
```
|
||||
|
||||
OpenClaw controlla la compatibilità dichiarata dell'API plugin / Gateway minimo prima dell'installazione. Quando la versione ClawHub selezionata pubblica un artefatto ClawPack, OpenClaw scarica il `.tgz` npm-pack versionato, verifica l'header digest di ClawHub e il digest dell'artefatto, poi lo installa tramite il normale percorso archivio. Le versioni ClawHub meno recenti senza metadati ClawPack continuano a installarsi tramite il percorso legacy di verifica dell'archivio pacchetto. Le installazioni registrate conservano i metadati della fonte ClawHub, il tipo di artefatto, l'integrità npm, lo shasum npm, il nome del tarball e i dati del digest ClawPack per aggiornamenti successivi.
|
||||
Le installazioni ClawHub senza versione mantengono una specifica registrata senza versione, così `openclaw plugins update` può seguire release ClawHub più nuove; i selettori espliciti di versione o tag come `clawhub:pkg@1.2.3` e `clawhub:pkg@beta` rimangono fissati a quel selettore.
|
||||
OpenClaw controlla la compatibilità dichiarata dell'API Plugin / del Gateway minimo prima dell'installazione. Quando la versione ClawHub selezionata pubblica un artefatto ClawPack, OpenClaw scarica il `.tgz` npm-pack versionato, verifica l'header digest ClawHub e il digest dell'artefatto, poi lo installa tramite il normale percorso archivio. Le versioni ClawHub più vecchie senza metadati ClawPack installano ancora tramite il percorso di verifica dell'archivio pacchetto legacy. Le installazioni registrate conservano i propri metadati della fonte ClawHub, tipo di artefatto, integrità npm, shasum npm, nome tarball e dati digest ClawPack per aggiornamenti successivi.
|
||||
Le installazioni ClawHub senza versione mantengono una spec registrata senza versione così `openclaw plugins update` può seguire release ClawHub più recenti; selettori espliciti di versione o tag come `clawhub:pkg@1.2.3` e `clawhub:pkg@beta` rimangono fissati a quel selettore.
|
||||
|
||||
#### Abbreviazione marketplace
|
||||
|
||||
@ -184,7 +194,7 @@ openclaw plugins marketplace list <marketplace-name>
|
||||
openclaw plugins install <plugin-name>@<marketplace-name>
|
||||
```
|
||||
|
||||
Usa `--marketplace` quando vuoi passare esplicitamente la fonte del marketplace:
|
||||
Usa `--marketplace` quando vuoi passare esplicitamente la fonte marketplace:
|
||||
|
||||
```bash
|
||||
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
|
||||
@ -194,16 +204,16 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
|
||||
```
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Origini del marketplace">
|
||||
- un nome di marketplace noto di Claude da `~/.claude/plugins/known_marketplaces.json`
|
||||
<Tab title="Marketplace sources">
|
||||
- un nome di marketplace Claude noto da `~/.claude/plugins/known_marketplaces.json`
|
||||
- una radice di marketplace locale o un percorso `marketplace.json`
|
||||
- una forma abbreviata di repository GitHub come `owner/repo`
|
||||
- un URL di repository GitHub come `https://github.com/owner/repo`
|
||||
- un URL git
|
||||
|
||||
</Tab>
|
||||
<Tab title="Regole dei marketplace remoti">
|
||||
Per i marketplace remoti caricati da GitHub o git, le voci dei Plugin devono restare all'interno del repository del marketplace clonato. OpenClaw accetta origini con percorsi relativi da quel repository e rifiuta origini di Plugin HTTP(S), con percorso assoluto, git, GitHub e altre origini non basate su percorso dai manifest remoti.
|
||||
<Tab title="Remote marketplace rules">
|
||||
Per i marketplace remoti caricati da GitHub o git, le voci Plugin devono rimanere all'interno del repository marketplace clonato. OpenClaw accetta sorgenti con percorso relativo da quel repository e rifiuta sorgenti Plugin HTTP(S), con percorso assoluto, git, GitHub e altre sorgenti Plugin non basate su percorso dai manifest remoti.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
@ -215,7 +225,7 @@ Per percorsi locali e archivi, OpenClaw rileva automaticamente:
|
||||
- bundle compatibili con Cursor (`.cursor-plugin/plugin.json`)
|
||||
|
||||
<Note>
|
||||
I bundle compatibili vengono installati nella normale radice dei Plugin e partecipano allo stesso flusso list/info/enable/disable. Oggi sono supportati bundle skills, command-skills di Claude, valori predefiniti Claude `settings.json`, valori predefiniti Claude `.lsp.json` / `lspServers` dichiarati nel manifest, command-skills di Cursor e directory di hook Codex compatibili; le altre funzionalità dei bundle rilevate sono mostrate in diagnostica/info ma non sono ancora collegate all'esecuzione runtime.
|
||||
I bundle compatibili vengono installati nella normale radice dei Plugin e partecipano allo stesso flusso di elenco/info/abilitazione/disabilitazione. Oggi sono supportati Skills dei bundle, Skills di comando Claude, valori predefiniti Claude `settings.json`, valori predefiniti Claude `.lsp.json` / `lspServers` dichiarati nel manifest, Skills di comando Cursor e directory hook compatibili con Codex; altre funzionalità dei bundle rilevate sono mostrate in diagnostica/info ma non sono ancora collegate all'esecuzione runtime.
|
||||
</Note>
|
||||
|
||||
### Elenco
|
||||
@ -234,37 +244,35 @@ openclaw plugins search <query> --json
|
||||
Mostra solo i Plugin abilitati.
|
||||
</ParamField>
|
||||
<ParamField path="--verbose" type="boolean">
|
||||
Passa dalla vista tabellare a righe di dettaglio per Plugin con metadati di origine/provenienza/versione/attivazione.
|
||||
Passa dalla vista tabellare a righe di dettaglio per Plugin con metadati di sorgente/origine/versione/attivazione.
|
||||
</ParamField>
|
||||
<ParamField path="--json" type="boolean">
|
||||
Inventario leggibile da macchina più diagnostica del registro e stato di installazione delle dipendenze del pacchetto.
|
||||
Inventario leggibile dalla macchina più diagnostica del registro e stato di installazione delle dipendenze del pacchetto.
|
||||
</ParamField>
|
||||
|
||||
<Note>
|
||||
`plugins list` legge prima il registro locale persistente dei Plugin, con un fallback derivato solo dal manifest quando il registro è mancante o non valido. È utile per verificare se un Plugin è installato, abilitato e visibile alla pianificazione dell'avvio a freddo, ma non è una sonda runtime live di un processo Gateway già in esecuzione. Dopo aver modificato codice del Plugin, abilitazione, policy degli hook o `plugins.load.paths`, riavvia il Gateway che serve il canale prima di aspettarti che nuovo codice `register(api)` o nuovi hook vengano eseguiti. Per distribuzioni remote/container, verifica di riavviare l'effettivo processo figlio `openclaw gateway run`, non solo un processo wrapper.
|
||||
`plugins list` legge prima il registro Plugin locale persistito, con un fallback derivato solo dal manifest quando il registro è mancante o non valido. È utile per verificare se un Plugin è installato, abilitato e visibile alla pianificazione dell'avvio a freddo, ma non è una sonda runtime live di un processo Gateway già in esecuzione. Dopo aver modificato codice Plugin, abilitazione, policy degli hook o `plugins.load.paths`, riavvia il Gateway che serve il canale prima di aspettarti l'esecuzione del nuovo codice `register(api)` o degli hook. Per distribuzioni remote/container, verifica di riavviare il vero processo figlio `openclaw gateway run`, non solo un processo wrapper.
|
||||
|
||||
`plugins list --json` include il `dependencyStatus` di ogni Plugin da `package.json`
|
||||
`plugins list --json` include il `dependencyStatus` di ciascun Plugin da `package.json`
|
||||
`dependencies` e `optionalDependencies`. OpenClaw verifica se quei nomi di pacchetto
|
||||
sono presenti lungo il normale percorso di ricerca Node `node_modules` del Plugin; non
|
||||
importa codice runtime del Plugin, non esegue un package manager e non ripara
|
||||
sono presenti lungo il normale percorso di lookup Node `node_modules` del Plugin; non
|
||||
importa codice runtime del Plugin, non esegue un gestore di pacchetti e non ripara
|
||||
dipendenze mancanti.
|
||||
</Note>
|
||||
|
||||
`plugins search` è una ricerca remota nel catalogo ClawHub. Non ispeziona lo
|
||||
stato locale, non modifica la configurazione, non installa pacchetti né carica codice runtime del Plugin. I
|
||||
risultati della ricerca includono nome pacchetto ClawHub, famiglia, canale, versione, riepilogo e
|
||||
un suggerimento di installazione come `openclaw plugins install clawhub:<package>`.
|
||||
`plugins search` è una ricerca nel catalogo remoto ClawHub. Non ispeziona lo
|
||||
stato locale, non modifica la configurazione, non installa pacchetti e non carica codice runtime dei Plugin. I risultati di ricerca includono il nome del pacchetto ClawHub, famiglia, canale, versione, riepilogo e un suggerimento di installazione come `openclaw plugins install clawhub:<package>`.
|
||||
|
||||
Per lavorare su Plugin inclusi in un'immagine Docker pacchettizzata, monta con bind la directory
|
||||
sorgente del Plugin sopra il percorso sorgente pacchettizzato corrispondente, come
|
||||
Per lavorare su Plugin inclusi all'interno di un'immagine Docker pacchettizzata, monta con bind la directory
|
||||
sorgente del Plugin sopra il percorso sorgente pacchettizzato corrispondente, ad esempio
|
||||
`/app/extensions/synology-chat`. OpenClaw scoprirà quell'overlay sorgente montato
|
||||
prima di `/app/dist/extensions/synology-chat`; una semplice directory sorgente copiata
|
||||
rimane inerte, così le normali installazioni pacchettizzate continuano a usare la dist compilata.
|
||||
|
||||
Per il debug degli hook runtime:
|
||||
|
||||
- `openclaw plugins inspect <id> --runtime --json` mostra hook registrati e diagnostica da un passaggio di ispezione con modulo caricato. L'ispezione runtime non installa mai dipendenze; usa `openclaw doctor --fix` per pulire lo stato delle dipendenze legacy o installare Plugin scaricabili configurati mancanti.
|
||||
- `openclaw gateway status --deep --require-rpc` conferma il Gateway raggiungibile, suggerimenti su servizio/processo, percorso di configurazione e salute RPC.
|
||||
- `openclaw plugins inspect <id> --runtime --json` mostra hook registrati e diagnostica da un passaggio di ispezione con modulo caricato. L'ispezione runtime non installa mai dipendenze; usa `openclaw doctor --fix` per pulire lo stato legacy delle dipendenze o installare Plugin scaricabili configurati mancanti.
|
||||
- `openclaw gateway status --deep --require-rpc` conferma il Gateway raggiungibile, suggerimenti su servizio/processo, percorso di configurazione e stato RPC.
|
||||
- Gli hook di conversazione non inclusi (`llm_input`, `llm_output`, `before_agent_finalize`, `agent_end`) richiedono `plugins.entries.<id>.hooks.allowConversationAccess=true`.
|
||||
|
||||
Usa `--link` per evitare di copiare una directory locale (aggiunge a `plugins.load.paths`):
|
||||
@ -274,16 +282,16 @@ openclaw plugins install -l ./my-plugin
|
||||
```
|
||||
|
||||
<Note>
|
||||
`--force` non è supportato con `--link` perché le installazioni collegate riusano il percorso sorgente invece di copiare sopra una destinazione di installazione gestita.
|
||||
`--force` non è supportato con `--link` perché le installazioni collegate riutilizzano il percorso sorgente invece di copiare sopra una destinazione di installazione gestita.
|
||||
|
||||
Usa `--pin` sulle installazioni npm per salvare la specifica esatta risolta (`name@version`) nell'indice dei Plugin gestiti mantenendo non fissato il comportamento predefinito.
|
||||
Usa `--pin` nelle installazioni npm per salvare la specifica esatta risolta (`name@version`) nell'indice Plugin gestito mantenendo non fissato il comportamento predefinito.
|
||||
</Note>
|
||||
|
||||
### Indice dei Plugin
|
||||
### Indice Plugin
|
||||
|
||||
I metadati di installazione dei Plugin sono stato gestito dalla macchina, non configurazione utente. Installazioni e aggiornamenti li scrivono in `plugins/installs.json` sotto la directory di stato OpenClaw attiva. La sua mappa di primo livello `installRecords` è l'origine durevole dei metadati di installazione, inclusi i record per manifest di Plugin rotti o mancanti. L'array `plugins` è la cache del registro a freddo derivata dai manifest. Il file include un avviso di non modifica ed è usato da `openclaw plugins update`, disinstallazione, diagnostica e registro Plugin a freddo.
|
||||
I metadati di installazione dei Plugin sono stato gestito dalla macchina, non configurazione utente. Installazioni e aggiornamenti li scrivono in `plugins/installs.json` sotto la directory di stato OpenClaw attiva. La sua mappa di primo livello `installRecords` è la sorgente durevole dei metadati di installazione, inclusi i record per manifest Plugin danneggiati o mancanti. L'array `plugins` è la cache del registro a freddo derivata dal manifest. Il file include un avviso di non modifica ed è usato da `openclaw plugins update`, disinstallazione, diagnostica e registro Plugin a freddo.
|
||||
|
||||
Quando OpenClaw vede record legacy distribuiti `plugins.installs` nella configurazione, li sposta nell'indice dei Plugin e rimuove la chiave di configurazione; se una delle due scritture fallisce, i record di configurazione vengono mantenuti così i metadati di installazione non vanno persi.
|
||||
Quando OpenClaw vede record legacy forniti `plugins.installs` nella configurazione, li sposta nell'indice Plugin e rimuove la chiave di configurazione; se una delle due scritture fallisce, i record di configurazione vengono mantenuti affinché i metadati di installazione non vadano persi.
|
||||
|
||||
### Disinstallazione
|
||||
|
||||
@ -293,7 +301,7 @@ openclaw plugins uninstall <id> --dry-run
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
```
|
||||
|
||||
`uninstall` rimuove i record dei Plugin da `plugins.entries`, dall'indice persistente dei Plugin, dalle voci dell'elenco allow/deny dei Plugin e dalle voci collegate `plugins.load.paths` quando applicabile. A meno che `--keep-files` sia impostato, la disinstallazione rimuove anche la directory di installazione gestita tracciata quando è dentro la radice delle estensioni Plugin di OpenClaw. Per i Plugin di Active Memory, lo slot di memoria viene reimpostato su `memory-core`.
|
||||
`uninstall` rimuove i record Plugin da `plugins.entries`, dall'indice Plugin persistito, dalle voci dell'elenco allow/deny dei Plugin e dalle voci collegate `plugins.load.paths` quando applicabile. A meno che `--keep-files` non sia impostato, la disinstallazione rimuove anche la directory di installazione gestita tracciata quando si trova all'interno della radice delle estensioni Plugin di OpenClaw. Per i Plugin di memoria attiva, lo slot di memoria viene reimpostato a `memory-core`.
|
||||
|
||||
<Note>
|
||||
`--keep-config` è supportato come alias deprecato di `--keep-files`.
|
||||
@ -309,29 +317,29 @@ openclaw plugins update @openclaw/voice-call
|
||||
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
|
||||
```
|
||||
|
||||
Gli aggiornamenti si applicano alle installazioni di Plugin tracciate nell'indice dei Plugin gestiti e alle installazioni di hook-pack tracciate in `hooks.internal.installs`.
|
||||
Gli aggiornamenti si applicano alle installazioni Plugin tracciate nell'indice Plugin gestito e alle installazioni hook-pack tracciate in `hooks.internal.installs`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Risoluzione tra id del Plugin e specifica npm">
|
||||
Quando passi un id di Plugin, OpenClaw riusa la specifica di installazione registrata per quel Plugin. Questo significa che dist-tag memorizzati in precedenza, come `@beta`, e versioni esatte fissate continuano a essere usati nelle esecuzioni successive di `update <id>`.
|
||||
<Accordion title="Resolving plugin id vs npm spec">
|
||||
Quando passi un id Plugin, OpenClaw riutilizza la specifica di installazione registrata per quel Plugin. Ciò significa che dist-tag memorizzati in precedenza come `@beta` e versioni esatte fissate continuano a essere usati nelle esecuzioni successive di `update <id>`.
|
||||
|
||||
Per installazioni npm, puoi anche passare una specifica esplicita di pacchetto npm con un dist-tag o una versione esatta. OpenClaw risolve quel nome pacchetto riconducendolo al record del Plugin tracciato, aggiorna quel Plugin installato e registra la nuova specifica npm per aggiornamenti futuri basati su id.
|
||||
Per le installazioni npm, puoi anche passare una specifica esplicita di pacchetto npm con un dist-tag o una versione esatta. OpenClaw risolve quel nome di pacchetto tornando al record Plugin tracciato, aggiorna quel Plugin installato e registra la nuova specifica npm per futuri aggiornamenti basati su id.
|
||||
|
||||
Passare il nome del pacchetto npm senza una versione o un tag viene risolto anch'esso nel record del Plugin tracciato. Usalo quando un Plugin era fissato a una versione esatta e vuoi riportarlo alla linea di rilascio predefinita del registro.
|
||||
Passare il nome del pacchetto npm senza una versione o tag risolve anch'esso tornando al record Plugin tracciato. Usalo quando un Plugin era fissato a una versione esatta e vuoi riportarlo alla linea di rilascio predefinita del registro.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Aggiornamenti del canale beta">
|
||||
`openclaw plugins update` riusa la specifica del Plugin tracciata a meno che tu non passi una nuova specifica. `openclaw update` conosce inoltre il canale di aggiornamento OpenClaw attivo: sul canale beta, i record Plugin npm e ClawHub della linea predefinita provano prima `@beta`, poi ripiegano sulla specifica default/latest registrata se non esiste alcun rilascio beta del Plugin. Versioni esatte e tag espliciti restano fissati a quel selettore.
|
||||
<Accordion title="Beta channel updates">
|
||||
`openclaw plugins update` riutilizza la specifica Plugin tracciata a meno che tu non passi una nuova specifica. `openclaw update` conosce inoltre il canale di aggiornamento OpenClaw attivo: sul canale beta, i record Plugin npm e ClawHub della linea predefinita provano prima `@beta`, poi ripiegano sulla specifica predefinita/latest registrata se non esiste alcun rilascio beta del Plugin. Versioni esatte e tag espliciti restano fissati a quel selettore.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Controlli di versione e deriva dell'integrità">
|
||||
Prima di un aggiornamento npm live, OpenClaw controlla la versione del pacchetto installato rispetto ai metadati del registro npm. Se la versione installata e l'identità dell'artefatto registrata corrispondono già alla destinazione risolta, l'aggiornamento viene saltato senza scaricare, reinstallare o riscrivere `openclaw.json`.
|
||||
<Accordion title="Version checks and integrity drift">
|
||||
Prima di un aggiornamento npm live, OpenClaw controlla la versione del pacchetto installato rispetto ai metadati del registro npm. Se la versione installata e l'identità dell'artefatto registrata corrispondono già al target risolto, l'aggiornamento viene saltato senza scaricare, reinstallare o riscrivere `openclaw.json`.
|
||||
|
||||
Quando esiste un hash di integrità memorizzato e l'hash dell'artefatto recuperato cambia, OpenClaw lo tratta come deriva dell'artefatto npm. Il comando interattivo `openclaw plugins update` stampa gli hash atteso ed effettivo e chiede conferma prima di procedere. Gli helper di aggiornamento non interattivi falliscono in modo chiuso a meno che il chiamante fornisca una policy di continuazione esplicita.
|
||||
Quando esiste un hash di integrità memorizzato e l'hash dell'artefatto recuperato cambia, OpenClaw lo tratta come deriva dell'artefatto npm. Il comando interattivo `openclaw plugins update` stampa gli hash attesi ed effettivi e chiede conferma prima di procedere. Gli helper di aggiornamento non interattivi falliscono in modo chiuso a meno che il chiamante non fornisca una policy di continuazione esplicita.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="--dangerously-force-unsafe-install in aggiornamento">
|
||||
`--dangerously-force-unsafe-install` è disponibile anche su `plugins update` come override di emergenza per falsi positivi della scansione del codice pericoloso integrata durante gli aggiornamenti dei Plugin. Non aggira comunque i blocchi della policy `before_install` del Plugin o il blocco per fallimento della scansione, e si applica solo agli aggiornamenti dei Plugin, non agli aggiornamenti degli hook-pack.
|
||||
<Accordion title="--dangerously-force-unsafe-install on update">
|
||||
`--dangerously-force-unsafe-install` è disponibile anche su `plugins update` come override di emergenza per falsi positivi della scansione integrata di codice pericoloso durante gli aggiornamenti Plugin. Non aggira comunque i blocchi di policy `before_install` dei Plugin né il blocco per fallimento della scansione, e si applica solo agli aggiornamenti Plugin, non agli aggiornamenti hook-pack.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -343,21 +351,21 @@ openclaw plugins inspect <id> --runtime
|
||||
openclaw plugins inspect <id> --json
|
||||
```
|
||||
|
||||
Inspect mostra identità, stato di caricamento, origine, funzionalità del manifest, flag di policy, diagnostica, metadati di installazione, funzionalità del bundle e qualsiasi supporto server MCP o LSP rilevato senza importare codice runtime del Plugin per impostazione predefinita. Aggiungi `--runtime` per caricare il modulo del Plugin e includere hook, strumenti, comandi, servizi, metodi gateway e route HTTP registrati. L'ispezione runtime segnala direttamente le dipendenze mancanti del Plugin; installazioni e riparazioni restano in `openclaw plugins install`, `openclaw plugins update` e `openclaw doctor --fix`.
|
||||
Inspect mostra identità, stato di caricamento, sorgente, funzionalità del manifest, flag di policy, diagnostica, metadati di installazione, funzionalità dei bundle e qualsiasi supporto server MCP o LSP rilevato senza importare codice runtime del Plugin per impostazione predefinita. Aggiungi `--runtime` per caricare il modulo Plugin e includere hook registrati, strumenti, comandi, servizi, metodi Gateway e route HTTP. L'ispezione runtime segnala direttamente le dipendenze Plugin mancanti; installazioni e riparazioni restano in `openclaw plugins install`, `openclaw plugins update` e `openclaw doctor --fix`.
|
||||
|
||||
I comandi CLI di proprietà del Plugin sono installati come gruppi di comandi radice `openclaw`. Dopo che `inspect --runtime` mostra un comando sotto `cliCommands`, eseguilo come `openclaw <command> ...`; per esempio un Plugin che registra `demo-git` può essere verificato con `openclaw demo-git ping`.
|
||||
I comandi CLI di proprietà dei Plugin sono installati come gruppi di comandi root `openclaw`. Dopo che `inspect --runtime` mostra un comando sotto `cliCommands`, eseguilo come `openclaw <command> ...`; per esempio, un Plugin che registra `demo-git` può essere verificato con `openclaw demo-git ping`.
|
||||
|
||||
Ogni Plugin è classificato in base a ciò che registra effettivamente a runtime:
|
||||
|
||||
- **plain-capability** — un tipo di funzionalità (per esempio un Plugin solo provider)
|
||||
- **hybrid-capability** — più tipi di funzionalità (per esempio testo + voce + immagini)
|
||||
- **plain-capability** — un tipo di funzionalità (ad esempio un Plugin solo provider)
|
||||
- **hybrid-capability** — più tipi di funzionalità (ad esempio testo + parlato + immagini)
|
||||
- **hook-only** — solo hook, nessuna funzionalità o superficie
|
||||
- **non-capability** — strumenti/comandi/servizi ma nessuna funzionalità
|
||||
|
||||
Vedi [Forme dei Plugin](/it/plugins/architecture#plugin-shapes) per maggiori dettagli sul modello delle funzionalità.
|
||||
Vedi [Forme dei Plugin](/it/plugins/architecture#plugin-shapes) per maggiori informazioni sul modello delle funzionalità.
|
||||
|
||||
<Note>
|
||||
Il flag `--json` produce un report leggibile da macchina adatto a scripting e audit. `inspect --all` renderizza una tabella a livello di flotta con colonne di forma, tipi di funzionalità, avvisi di compatibilità, funzionalità del bundle e riepilogo degli hook. `info` è un alias di `inspect`.
|
||||
Il flag `--json` produce un report leggibile dalla macchina adatto a scripting e audit. `inspect --all` renderizza una tabella a livello di flotta con colonne per forma, tipi di funzionalità, avvisi di compatibilità, funzionalità dei bundle e riepilogo degli hook. `info` è un alias di `inspect`.
|
||||
</Note>
|
||||
|
||||
### Doctor
|
||||
@ -366,11 +374,11 @@ Il flag `--json` produce un report leggibile da macchina adatto a scripting e au
|
||||
openclaw plugins doctor
|
||||
```
|
||||
|
||||
`doctor` segnala errori di caricamento dei Plugin, diagnostica di manifest/discovery e avvisi di compatibilità. Quando tutto è pulito stampa `No plugin issues detected.`
|
||||
`doctor` segnala errori di caricamento dei Plugin, diagnostica di manifest/discovery e avvisi di compatibilità. Quando tutto è pulito, stampa `No plugin issues detected.`
|
||||
|
||||
Se un Plugin configurato è presente su disco ma bloccato dai controlli di sicurezza del percorso del loader, la validazione della configurazione mantiene la voce del Plugin e la segnala come `present but blocked`. Correggi la diagnostica precedente del Plugin bloccato, come proprietà del percorso o permessi world-writable, invece di rimuovere la configurazione `plugins.entries.<id>` o `plugins.allow`.
|
||||
Se un Plugin configurato è presente su disco ma bloccato dai controlli di sicurezza dei percorsi del loader, la validazione della configurazione mantiene la voce Plugin e la segnala come `present but blocked`. Correggi la diagnostica precedente del Plugin bloccato, come proprietà del percorso o permessi world-writable, invece di rimuovere la configurazione `plugins.entries.<id>` o `plugins.allow`.
|
||||
|
||||
Per fallimenti di forma del modulo come esportazioni `register`/`activate` mancanti, riesegui con `OPENCLAW_PLUGIN_LOAD_DEBUG=1` per includere un riepilogo compatto della forma delle esportazioni nell'output diagnostico.
|
||||
Per errori di forma del modulo come export `register`/`activate` mancanti, riesegui con `OPENCLAW_PLUGIN_LOAD_DEBUG=1` per includere un riepilogo compatto della forma degli export nell'output diagnostico.
|
||||
|
||||
### Registro
|
||||
|
||||
@ -380,12 +388,14 @@ openclaw plugins registry --refresh
|
||||
openclaw plugins registry --json
|
||||
```
|
||||
|
||||
Il registro locale dei Plugin è il modello di lettura a freddo persistente di OpenClaw per identità dei Plugin installati, abilitazione, metadati di origine e proprietà dei contributi. Avvio normale, ricerca del proprietario del provider, classificazione della configurazione del canale e inventario dei Plugin possono leggerlo senza importare moduli runtime dei Plugin.
|
||||
Il registro Plugin locale è il modello di lettura a freddo persistito di OpenClaw per identità Plugin installata, abilitazione, metadati sorgente e proprietà dei contributi. Avvio normale, lookup del proprietario provider, classificazione della configurazione del canale e inventario Plugin possono leggerlo senza importare moduli runtime dei Plugin.
|
||||
|
||||
Usa `plugins registry` per verificare se il registro persistente è presente, aggiornato o obsoleto. Usa `--refresh` per ricostruirlo dall'indice dei plugin persistente, dalla policy di configurazione e dai metadati di manifest/package. Questo è un percorso di riparazione, non un percorso di attivazione a runtime.
|
||||
Usa `plugins registry` per verificare se il registry persistente è presente, aggiornato o obsoleto. Usa `--refresh` per ricrearlo dall’indice dei plugin persistente, dalla policy di configurazione e dai metadati di manifest/pacchetto. Questo è un percorso di riparazione, non un percorso di attivazione a runtime.
|
||||
|
||||
`openclaw doctor --fix` ripara anche la deriva npm gestita adiacente al registry: se un pacchetto `@openclaw/*` orfano sotto la radice npm dei plugin gestiti oscura un plugin incluso, doctor rimuove quel pacchetto obsoleto e ricrea il registry in modo che l’avvio convalidi rispetto al manifest incluso.
|
||||
|
||||
<Warning>
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` è uno switch di compatibilità break-glass deprecato per gli errori di lettura del registro. Preferisci `plugins registry --refresh` o `openclaw doctor --fix`; il fallback env è solo per il ripristino di emergenza dell'avvio durante il rollout della migrazione.
|
||||
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` è un interruttore di compatibilità di emergenza deprecato per errori di lettura del registry. Preferisci `plugins registry --refresh` o `openclaw doctor --fix`; il fallback env serve solo per il ripristino di emergenza dell’avvio mentre la migrazione viene distribuita.
|
||||
</Warning>
|
||||
|
||||
### Marketplace
|
||||
@ -395,10 +405,10 @@ openclaw plugins marketplace list <source>
|
||||
openclaw plugins marketplace list <source> --json
|
||||
```
|
||||
|
||||
Marketplace list accetta un percorso marketplace locale, un percorso `marketplace.json`, una forma abbreviata GitHub come `owner/repo`, un URL di repository GitHub o un URL git. `--json` stampa l'etichetta dell'origine risolta più il manifest marketplace analizzato e le voci dei plugin.
|
||||
L’elenco del marketplace accetta un percorso di marketplace locale, un percorso `marketplace.json`, un’abbreviazione GitHub come `owner/repo`, un URL di repository GitHub o un URL git. `--json` stampa l’etichetta della sorgente risolta più il manifest marketplace analizzato e le voci dei plugin.
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Creazione di plugin](/it/plugins/building-plugins)
|
||||
- [Creare plugin](/it/plugins/building-plugins)
|
||||
- [Riferimento CLI](/it/cli)
|
||||
- [Plugin della community](/it/plugins/community)
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Aggiunta o modifica delle migrazioni di doctor
|
||||
- Aggiungere o modificare le migrazioni di doctor
|
||||
- Introduzione di modifiche di configurazione incompatibili
|
||||
sidebarTitle: Doctor
|
||||
summary: 'Comando doctor: controlli di integrità, migrazioni della configurazione e passaggi di riparazione'
|
||||
title: Diagnostica
|
||||
x-i18n:
|
||||
generated_at: "2026-05-03T21:33:12Z"
|
||||
generated_at: "2026-05-04T08:39:57Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 20b2cb3c3cd88e01050cb285a08a020603642439bd35668b7414360801fc03ff
|
||||
source_hash: 00124eb5d85445080439d2603c65b78e85b0a2fded1cff121f21c330464f42cf
|
||||
source_path: gateway/doctor.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
`openclaw doctor` è lo strumento di riparazione + migrazione per OpenClaw. Corregge configurazione/stato obsoleti, verifica lo stato di salute e fornisce passaggi di riparazione attuabili.
|
||||
`openclaw doctor` è lo strumento di riparazione e migrazione per OpenClaw. Corregge configurazioni/stati obsoleti, controlla l'integrità e fornisce passaggi di riparazione attuabili.
|
||||
|
||||
## Avvio rapido
|
||||
|
||||
@ -22,7 +22,7 @@ x-i18n:
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
### Modalità senza interfaccia e di automazione
|
||||
### Modalità headless e di automazione
|
||||
|
||||
<Tabs>
|
||||
<Tab title="--yes">
|
||||
@ -30,7 +30,7 @@ openclaw doctor
|
||||
openclaw doctor --yes
|
||||
```
|
||||
|
||||
Accetta i valori predefiniti senza richieste di conferma (inclusi i passaggi di riparazione di riavvio/servizio/sandbox quando applicabili).
|
||||
Accetta le impostazioni predefinite senza richieste interattive (inclusi i passaggi di riavvio/servizio/riparazione sandbox quando applicabile).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair">
|
||||
@ -38,7 +38,7 @@ openclaw doctor
|
||||
openclaw doctor --repair
|
||||
```
|
||||
|
||||
Applica le riparazioni consigliate senza richieste di conferma (riparazioni + riavvii quando sicuri).
|
||||
Applica le riparazioni consigliate senza richieste interattive (riparazioni + riavvii quando sono sicuri).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair --force">
|
||||
@ -46,7 +46,7 @@ openclaw doctor
|
||||
openclaw doctor --repair --force
|
||||
```
|
||||
|
||||
Applica anche le riparazioni aggressive (sovrascrive le configurazioni personalizzate del supervisore).
|
||||
Applica anche le riparazioni aggressive (sovrascrive le configurazioni supervisor personalizzate).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--non-interactive">
|
||||
@ -54,7 +54,7 @@ openclaw doctor
|
||||
openclaw doctor --non-interactive
|
||||
```
|
||||
|
||||
Esegui senza richieste di conferma e applica solo migrazioni sicure (normalizzazione della configurazione + spostamenti dello stato su disco). Salta le azioni di riavvio/servizio/sandbox che richiedono conferma umana. Le migrazioni dello stato legacy vengono eseguite automaticamente quando rilevate.
|
||||
Esegue senza richieste interattive e applica solo migrazioni sicure (normalizzazione della configurazione + spostamenti dello stato su disco). Salta le azioni di riavvio/servizio/sandbox che richiedono conferma umana. Le migrazioni dello stato legacy vengono eseguite automaticamente quando rilevate.
|
||||
|
||||
</Tab>
|
||||
<Tab title="--deep">
|
||||
@ -62,12 +62,12 @@ openclaw doctor
|
||||
openclaw doctor --deep
|
||||
```
|
||||
|
||||
Analizza i servizi di sistema per installazioni Gateway aggiuntive (launchd/systemd/schtasks).
|
||||
Scansiona i servizi di sistema per installazioni Gateway aggiuntive (launchd/systemd/schtasks).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Se vuoi rivedere le modifiche prima della scrittura, apri prima il file di configurazione:
|
||||
Se vuoi esaminare le modifiche prima di scrivere, apri prima il file di configurazione:
|
||||
|
||||
```bash
|
||||
cat ~/.openclaw/openclaw.json
|
||||
@ -76,126 +76,126 @@ cat ~/.openclaw/openclaw.json
|
||||
## Cosa fa (riepilogo)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Salute, UI e aggiornamenti">
|
||||
- Aggiornamento pre-flight facoltativo per installazioni git (solo interattivo).
|
||||
<Accordion title="Integrità, UI e aggiornamenti">
|
||||
- Aggiornamento pre-flight opzionale per installazioni git (solo interattivo).
|
||||
- Controllo di freschezza del protocollo UI (ricompila Control UI quando lo schema del protocollo è più recente).
|
||||
- Controllo di salute + richiesta di riavvio.
|
||||
- Controllo di integrità + richiesta di riavvio.
|
||||
- Riepilogo dello stato Skills (idonee/mancanti/bloccate) e stato dei Plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Configurazione e migrazioni">
|
||||
- Normalizzazione della configurazione per valori legacy.
|
||||
- Migrazione della configurazione Talk dai campi flat legacy `talk.*` a `talk.provider` + `talk.providers.<provider>`.
|
||||
- Controlli di migrazione browser per configurazioni legacy dell’estensione Chrome e disponibilità Chrome MCP.
|
||||
- Migrazione della configurazione Talk dai campi piatti legacy `talk.*` a `talk.provider` + `talk.providers.<provider>`.
|
||||
- Controlli di migrazione del browser per configurazioni legacy dell'estensione Chrome e prontezza Chrome MCP.
|
||||
- Avvisi sulle sostituzioni del provider OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
|
||||
- Avvisi di shadowing OAuth di Codex (`models.providers.openai-codex`).
|
||||
- Controllo dei prerequisiti TLS OAuth per i profili OAuth di OpenAI Codex.
|
||||
- Avvisi allowlist Plugin/strumenti quando `plugins.allow` è restrittivo ma la policy degli strumenti richiede ancora wildcard o strumenti di proprietà del Plugin.
|
||||
- Migrazione dello stato legacy su disco (sessioni/directory agente/autenticazione WhatsApp).
|
||||
- Migrazione delle chiavi legacy del contratto del manifest Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Migrazione dello store Cron legacy (`jobId`, `schedule.cron`, campi delivery/payload di primo livello, payload `provider`, job fallback Webhook semplici `notify: true`).
|
||||
- Migrazione legacy della policy runtime agente a `agents.defaults.agentRuntime` e `agents.list[].agentRuntime`.
|
||||
- Pulizia della configurazione Plugin obsoleta quando i Plugin sono abilitati; quando `plugins.enabled=false`, i riferimenti Plugin obsoleti vengono trattati come configurazione di contenimento inerte e preservati.
|
||||
- Controllo dei prerequisiti OAuth TLS per i profili OAuth OpenAI Codex.
|
||||
- Avvisi sulla allowlist di Plugin/strumenti quando `plugins.allow` è restrittivo ma la policy degli strumenti richiede ancora wildcard o strumenti di proprietà dei Plugin.
|
||||
- Migrazione dello stato legacy su disco (sessioni/directory agent/autenticazione WhatsApp).
|
||||
- Migrazione delle chiavi legacy del contratto del manifesto Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Migrazione dello store Cron legacy (`jobId`, `schedule.cron`, campi delivery/payload di primo livello, payload `provider`, processi fallback Webhook semplici `notify: true`).
|
||||
- Migrazione della runtime-policy legacy degli agent a `agents.defaults.agentRuntime` e `agents.list[].agentRuntime`.
|
||||
- Pulizia della configurazione Plugin obsoleta quando i Plugin sono abilitati; quando `plugins.enabled=false`, i riferimenti Plugin obsoleti vengono trattati come configurazione di contenimento inerte e conservati.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Stato e integrità">
|
||||
- Ispezione dei file di lock delle sessioni e pulizia dei lock obsoleti.
|
||||
- Riparazione delle trascrizioni di sessione per rami di riscrittura prompt duplicati creati dalle build 2026.4.24 interessate.
|
||||
- Rilevamento di tombstone di recupero-riavvio per subagenti bloccati, con supporto `--fix` per cancellare flag di recupero interrotto obsoleti, così l’avvio non continua a trattare il child come interrotto dal riavvio.
|
||||
- Controlli di integrità dello stato e dei permessi (sessioni, trascrizioni, directory di stato).
|
||||
- Controlli dei permessi del file di configurazione (chmod 600) durante l’esecuzione in locale.
|
||||
- Salute dell’autenticazione modello: controlla la scadenza OAuth, può aggiornare token in scadenza e segnala stati di cooldown/disabilitazione dei profili di autenticazione.
|
||||
- Riparazione delle trascrizioni delle sessioni per rami duplicati di riscrittura prompt creati dalle build 2026.4.24 interessate.
|
||||
- Rilevamento di tombstone di recupero-riavvio per subagent bloccati, con supporto `--fix` per cancellare flag di recupero interrotto obsoleti, così l'avvio non continua a trattare il child come interrotto dal riavvio.
|
||||
- Controlli di integrità dello stato e dei permessi (sessioni, trascrizioni, directory dello stato).
|
||||
- Controlli dei permessi del file di configurazione (chmod 600) durante l'esecuzione locale.
|
||||
- Integrità dell'autenticazione dei modelli: controlla la scadenza OAuth, può aggiornare token in scadenza e segnala stati di cooldown/disabilitazione dei profili di autenticazione.
|
||||
- Rilevamento di directory workspace aggiuntive (`~/openclaw`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Gateway, servizi e supervisori">
|
||||
- Riparazione dell’immagine sandbox quando il sandboxing è abilitato.
|
||||
<Accordion title="Gateway, servizi e supervisor">
|
||||
- Riparazione dell'immagine sandbox quando il sandboxing è abilitato.
|
||||
- Migrazione dei servizi legacy e rilevamento di Gateway aggiuntivi.
|
||||
- Migrazione dello stato legacy del canale Matrix (in modalità `--fix` / `--repair`).
|
||||
- Controlli runtime del Gateway (servizio installato ma non in esecuzione; etichetta launchd memorizzata nella cache).
|
||||
- Avvisi sullo stato dei canali (sondati dal Gateway in esecuzione).
|
||||
- Audit della configurazione del supervisore (launchd/systemd/schtasks) con riparazione facoltativa.
|
||||
- Pulizia dell’ambiente proxy incorporato per servizi Gateway che hanno acquisito valori shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` durante installazione o aggiornamento.
|
||||
- Audit della configurazione supervisor (launchd/systemd/schtasks) con riparazione opzionale.
|
||||
- Pulizia dell'ambiente proxy incorporato per servizi Gateway che hanno acquisito valori shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` durante installazione o aggiornamento.
|
||||
- Controlli delle best practice runtime del Gateway (Node vs Bun, percorsi dei gestori di versione).
|
||||
- Diagnostica delle collisioni della porta Gateway (predefinita `18789`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Autenticazione, sicurezza e pairing">
|
||||
<Accordion title="Autenticazione, sicurezza e associazione">
|
||||
- Avvisi di sicurezza per policy DM aperte.
|
||||
- Controlli di autenticazione Gateway per la modalità token locale (offre la generazione di token quando non esiste alcuna sorgente token; non sovrascrive le configurazioni SecretRef dei token).
|
||||
- Rilevamento di problemi di pairing del dispositivo (richieste di primo pairing in sospeso, upgrade ruolo/scope in sospeso, drift obsoleto della cache locale dei token dispositivo e drift di autenticazione dei record associati).
|
||||
- Controlli di autenticazione del Gateway per la modalità token locale (offre la generazione del token quando non esiste una sorgente token; non sovrascrive le configurazioni token SecretRef).
|
||||
- Rilevamento dei problemi di associazione dei dispositivi (richieste di prima associazione in sospeso, upgrade ruolo/ambito in sospeso, deriva obsoleta della cache token dispositivo locale e deriva dell'autenticazione dei record associati).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Workspace e shell">
|
||||
- Controllo systemd linger su Linux.
|
||||
- Controllo della dimensione del file bootstrap del workspace (avvisi di troncamento/quasi limite per file di contesto).
|
||||
- Controllo di disponibilità Skills per l’agente predefinito; segnala Skills consentite con binari, env, configurazione o requisiti OS mancanti, e `--fix` può disabilitare Skills non disponibili in `skills.entries`.
|
||||
- Controllo della dimensione dei file bootstrap del workspace (avvisi di troncamento/quasi limite per file di contesto).
|
||||
- Controllo di prontezza Skills per l'agent predefinito; segnala skill consentite con binari, env, configurazione o requisiti OS mancanti, e `--fix` può disabilitare skill non disponibili in `skills.entries`.
|
||||
- Controllo dello stato del completamento shell e installazione/upgrade automatici.
|
||||
- Controllo di disponibilità del provider di embedding per la ricerca in memoria (modello locale, chiave API remota o binario QMD).
|
||||
- Controlli dell’installazione da sorgente (mismatch workspace pnpm, asset UI mancanti, binario tsx mancante).
|
||||
- Scrive configurazione aggiornata + metadati della procedura guidata.
|
||||
- Controllo di prontezza del provider di embedding per la ricerca in memoria (modello locale, chiave API remota o binario QMD).
|
||||
- Controlli delle installazioni da sorgente (mancata corrispondenza del workspace pnpm, asset UI mancanti, binario tsx mancante).
|
||||
- Scrive configurazione aggiornata + metadati del wizard.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Riempimento retroattivo e reset della UI Dreams
|
||||
## Riempimento retroattivo e ripristino dell'UI Dreams
|
||||
|
||||
La scena Dreams di Control UI include azioni **Riempimento retroattivo**, **Reset** e **Cancella ancorati** per il flusso di lavoro Dreaming ancorato. Queste azioni usano metodi RPC in stile doctor del Gateway, ma **non** fanno parte della riparazione/migrazione CLI `openclaw doctor`.
|
||||
La scena Dreams di Control UI include le azioni **Riempimento retroattivo**, **Reimposta** e **Cancella elementi fondati** per il flusso di lavoro di Dreaming fondato. Queste azioni usano metodi RPC in stile Gateway doctor, ma **non** fanno parte della riparazione/migrazione CLI di `openclaw doctor`.
|
||||
|
||||
Cosa fanno:
|
||||
|
||||
- **Riempimento retroattivo** analizza i file storici `memory/YYYY-MM-DD.md` nel workspace attivo, esegue il passaggio del diario REM ancorato e scrive voci di riempimento retroattivo reversibili in `DREAMS.md`.
|
||||
- **Reset** rimuove da `DREAMS.md` solo quelle voci di diario di riempimento retroattivo contrassegnate.
|
||||
- **Cancella ancorati** rimuove solo le voci staged a breve termine esclusivamente ancorate che provengono dal replay storico e non hanno ancora accumulato richiamo live o supporto giornaliero.
|
||||
- **Riempimento retroattivo** scansiona i file storici `memory/YYYY-MM-DD.md` nel workspace attivo, esegue il passaggio del diario REM fondato e scrive voci di riempimento retroattivo reversibili in `DREAMS.md`.
|
||||
- **Reimposta** rimuove da `DREAMS.md` solo quelle voci di diario contrassegnate come riempimento retroattivo.
|
||||
- **Cancella elementi fondati** rimuove solo le voci a breve termine solo fondate preparate che provengono dalla riproduzione storica e non hanno ancora accumulato richiamo live o supporto quotidiano.
|
||||
|
||||
Cosa **non** fanno da sole:
|
||||
|
||||
- non modificano `MEMORY.md`
|
||||
- non eseguono migrazioni doctor complete
|
||||
- non mettono automaticamente in staging i candidati ancorati nello store live di promozione a breve termine, a meno che tu non esegua esplicitamente prima il percorso CLI staged
|
||||
- non preparano automaticamente candidati fondati nello store live di promozione a breve termine, a meno che tu non esegua esplicitamente prima il percorso CLI staged
|
||||
|
||||
Se vuoi che il replay storico ancorato influenzi il normale percorso di promozione profonda, usa invece il flusso CLI:
|
||||
Se vuoi che la riproduzione storica fondata influenzi il normale percorso di promozione profonda, usa invece il flusso CLI:
|
||||
|
||||
```bash
|
||||
openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
```
|
||||
|
||||
Questo mette in staging i candidati durevoli ancorati nello store Dreaming a breve termine mantenendo `DREAMS.md` come superficie di revisione.
|
||||
Questo prepara candidati durevoli fondati nello store di Dreaming a breve termine, mantenendo `DREAMS.md` come superficie di revisione.
|
||||
|
||||
## Comportamento dettagliato e motivazione
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="0. Aggiornamento facoltativo (installazioni git)">
|
||||
Se si tratta di un checkout git e doctor viene eseguito in modo interattivo, offre di aggiornare (fetch/rebase/build) prima di eseguire doctor.
|
||||
<Accordion title="0. Aggiornamento opzionale (installazioni git)">
|
||||
Se si tratta di un checkout git e doctor è in esecuzione in modo interattivo, offre di aggiornare (fetch/rebase/build) prima di eseguire doctor.
|
||||
</Accordion>
|
||||
<Accordion title="1. Normalizzazione della configurazione">
|
||||
Se la configurazione contiene forme di valori legacy (per esempio `messages.ackReaction` senza una sostituzione specifica del canale), doctor le normalizza nello schema corrente.
|
||||
Se la configurazione contiene forme di valori legacy (per esempio `messages.ackReaction` senza una sostituzione specifica per canale), doctor le normalizza nello schema corrente.
|
||||
|
||||
Questo include i campi flat legacy di Talk. La configurazione Talk pubblica corrente è `talk.provider` + `talk.providers.<provider>`. Doctor riscrive le vecchie forme `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` nella mappa dei provider.
|
||||
Questo include i campi piatti legacy Talk. La configurazione Talk pubblica corrente è `talk.provider` + `talk.providers.<provider>`. Doctor riscrive le vecchie forme `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` nella mappa provider.
|
||||
|
||||
Doctor avvisa anche quando `plugins.allow` non è vuoto e la policy degli strumenti usa
|
||||
voci wildcard o strumenti di proprietà del Plugin. `tools.allow: ["*"]` corrisponde solo agli strumenti
|
||||
dei Plugin che vengono effettivamente caricati; non aggira l’allowlist esclusiva dei Plugin.
|
||||
wildcard o voci strumento di proprietà dei Plugin. `tools.allow: ["*"]` corrisponde solo agli strumenti
|
||||
dei Plugin che vengono effettivamente caricati; non aggira la allowlist esclusiva dei Plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. Migrazioni delle chiavi di configurazione legacy">
|
||||
Quando la configurazione contiene chiavi deprecate, gli altri comandi rifiutano di essere eseguiti e ti chiedono di eseguire `openclaw doctor`.
|
||||
Quando la configurazione contiene chiavi deprecate, gli altri comandi si rifiutano di essere eseguiti e chiedono di eseguire `openclaw doctor`.
|
||||
|
||||
Doctor:
|
||||
|
||||
- Spiega quali chiavi legacy sono state trovate.
|
||||
- Mostra la migrazione applicata.
|
||||
- Riscrive `~/.openclaw/openclaw.json` con lo schema aggiornato.
|
||||
- Spiegherà quali chiavi legacy sono state trovate.
|
||||
- Mostrerà la migrazione applicata.
|
||||
- Riscriverà `~/.openclaw/openclaw.json` con lo schema aggiornato.
|
||||
|
||||
Il Gateway esegue automaticamente anche le migrazioni doctor all’avvio quando rileva un formato di configurazione legacy, quindi le configurazioni obsolete vengono riparate senza intervento manuale. Le migrazioni dello store dei job Cron vengono gestite da `openclaw doctor --fix`.
|
||||
Il Gateway esegue automaticamente anche le migrazioni doctor all'avvio quando rileva un formato di configurazione legacy, quindi le configurazioni obsolete vengono riparate senza intervento manuale. Le migrazioni dello store dei processi Cron sono gestite da `openclaw doctor --fix`.
|
||||
|
||||
Migrazioni correnti:
|
||||
Migrazioni attuali:
|
||||
|
||||
- `routing.allowFrom` → `channels.whatsapp.allowFrom`
|
||||
- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
|
||||
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
|
||||
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
|
||||
- configurazioni dei canali configurati senza criterio di risposta visibile → `messages.groupChat.visibleReplies: "message_tool"`
|
||||
- configurazioni dei canali configurati senza policy di risposta visibile → `messages.groupChat.visibleReplies: "message_tool"`
|
||||
- `routing.queue` → `messages.queue`
|
||||
- `routing.bindings` → `bindings` di primo livello
|
||||
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
|
||||
@ -213,15 +213,15 @@ Questo mette in staging i candidati durevoli ancorati nello store Dreaming a bre
|
||||
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
|
||||
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
|
||||
- `bindings[].match.accountID` → `bindings[].match.accountId`
|
||||
- Per i canali con `accounts` denominati ma con valori di canale di primo livello per account singolo ancora presenti, sposta quei valori con ambito account nell'account promosso scelto per quel canale (`accounts.default` per la maggior parte dei canali; Matrix può conservare un target denominato/predefinito corrispondente esistente)
|
||||
- Per i canali con `accounts` denominati ma con valori di canale di primo livello ad account singolo ancora presenti, sposta quei valori con ambito account nell'account promosso scelto per quel canale (`accounts.default` per la maggior parte dei canali; Matrix può preservare una destinazione denominata/predefinita corrispondente esistente)
|
||||
- `identity` → `agents.list[].identity`
|
||||
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
|
||||
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
|
||||
- rimuovi `agents.defaults.llm`; usa `models.providers.<id>.timeoutSeconds` per i timeout di provider/modelli lenti
|
||||
- rimuovi `agents.defaults.llm`; usa `models.providers.<id>.timeoutSeconds` per timeout lenti di provider/modello
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
|
||||
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
|
||||
- rimuovi `browser.relayBindHost` (impostazione legacy del relay dell'estensione)
|
||||
- legacy `models.providers.*.api: "openai"` → `"openai-completions"` (l'avvio del Gateway salta anche i provider il cui `api` è impostato su un valore enum futuro o sconosciuto invece di fallire in modo chiuso)
|
||||
- legacy `models.providers.*.api: "openai"` → `"openai-completions"` (l'avvio del Gateway salta anche i provider il cui `api` è impostato su un valore enum futuro o sconosciuto invece di fallire chiudendo l'avvio)
|
||||
|
||||
Gli avvisi di doctor includono anche indicazioni sull'account predefinito per i canali multi-account:
|
||||
|
||||
@ -229,54 +229,54 @@ Questo mette in staging i candidati durevoli ancorati nello store Dreaming a bre
|
||||
- Se `channels.<channel>.defaultAccount` è impostato su un ID account sconosciuto, doctor avvisa ed elenca gli ID account configurati.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2b. Override dei provider OpenCode">
|
||||
Se hai aggiunto manualmente `models.providers.opencode`, `opencode-zen` o `opencode-go`, questo sovrascrive il catalogo OpenCode integrato da `@mariozechner/pi-ai`. Ciò può forzare i modelli sull'API sbagliata o azzerare i costi. Doctor avvisa così puoi rimuovere l'override e ripristinare il routing API per modello + i costi.
|
||||
<Accordion title="2b. Override del provider OpenCode">
|
||||
Se hai aggiunto manualmente `models.providers.opencode`, `opencode-zen` o `opencode-go`, sovrascrive il catalogo OpenCode integrato da `@mariozechner/pi-ai`. Questo può forzare i modelli sull'API sbagliata o azzerare i costi. Doctor avvisa così puoi rimuovere l'override e ripristinare routing API + costi per modello.
|
||||
</Accordion>
|
||||
<Accordion title="2c. Migrazione del browser e preparazione per Chrome MCP">
|
||||
Se la tua configurazione del browser punta ancora al percorso rimosso dell'estensione Chrome, doctor la normalizza al modello di collegamento Chrome MCP host-local corrente:
|
||||
<Accordion title="2c. Migrazione del browser e preparazione a Chrome MCP">
|
||||
Se la tua configurazione del browser punta ancora al percorso della vecchia estensione Chrome rimossa, doctor la normalizza al modello corrente di collegamento Chrome MCP locale all'host:
|
||||
|
||||
- `browser.profiles.*.driver: "extension"` diventa `"existing-session"`
|
||||
- `browser.relayBindHost` viene rimosso
|
||||
|
||||
Doctor verifica anche il percorso Chrome MCP host-local quando usi `defaultProfile: "user"` o un profilo `existing-session` configurato:
|
||||
Doctor verifica anche il percorso Chrome MCP locale all'host quando usi `defaultProfile: "user"` o un profilo `existing-session` configurato:
|
||||
|
||||
- controlla se Google Chrome è installato sullo stesso host per i profili di connessione automatica predefiniti
|
||||
- controlla la versione rilevata di Chrome e avvisa quando è inferiore a Chrome 144
|
||||
- ti ricorda di abilitare il debug remoto nella pagina di ispezione del browser (ad esempio `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` o `edge://inspect/#remote-debugging`)
|
||||
- controlla se Google Chrome è installato sullo stesso host per i profili predefiniti di connessione automatica
|
||||
- controlla la versione Chrome rilevata e avvisa quando è inferiore a Chrome 144
|
||||
- ti ricorda di abilitare il debug remoto nella pagina di ispezione del browser (per esempio `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` o `edge://inspect/#remote-debugging`)
|
||||
|
||||
Doctor non può abilitare l'impostazione lato Chrome per te. Chrome MCP host-local richiede comunque:
|
||||
Doctor non può abilitare l'impostazione lato Chrome al posto tuo. Chrome MCP locale all'host richiede ancora:
|
||||
|
||||
- un browser basato su Chromium 144+ sull'host gateway/node
|
||||
- il browser in esecuzione localmente
|
||||
- debug remoto abilitato in quel browser
|
||||
- approvazione del primo prompt di consenso al collegamento nel browser
|
||||
|
||||
La preparazione qui riguarda solo i prerequisiti di collegamento locale. Existing-session mantiene gli attuali limiti di routing Chrome MCP; route avanzate come `responsebody`, esportazione PDF, intercettazione dei download e azioni batch richiedono ancora un browser gestito o un profilo CDP grezzo.
|
||||
Qui la preparazione riguarda solo i prerequisiti di collegamento locale. Existing-session mantiene i limiti di route correnti di Chrome MCP; route avanzate come `responsebody`, esportazione PDF, intercettazione dei download e azioni batch richiedono ancora un browser gestito o un profilo CDP raw.
|
||||
|
||||
Questo controllo **non** si applica a Docker, sandbox, remote-browser o altri flussi headless. Questi continuano a usare CDP grezzo.
|
||||
Questo controllo **non** si applica a Docker, sandbox, remote-browser o altri flussi headless. Questi continuano a usare CDP raw.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2d. Prerequisiti OAuth TLS">
|
||||
Quando è configurato un profilo OAuth OpenAI Codex, doctor interroga l'endpoint di autorizzazione OpenAI per verificare che lo stack TLS locale Node/OpenSSL possa convalidare la catena di certificati. Se il probe fallisce con un errore di certificato (ad esempio `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificato scaduto o certificato autofirmato), doctor stampa indicazioni di correzione specifiche per la piattaforma. Su macOS con un Node Homebrew, la correzione è di solito `brew postinstall ca-certificates`. Con `--deep`, il probe viene eseguito anche se il gateway è sano.
|
||||
<Accordion title="2d. Prerequisiti TLS OAuth">
|
||||
Quando è configurato un profilo OAuth OpenAI Codex, doctor sonda l'endpoint di autorizzazione OpenAI per verificare che lo stack TLS locale Node/OpenSSL possa convalidare la catena di certificati. Se la sonda fallisce con un errore di certificato (per esempio `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificato scaduto o certificato autofirmato), doctor stampa indicazioni di correzione specifiche per la piattaforma. Su macOS con un Node Homebrew, la correzione di solito è `brew postinstall ca-certificates`. Con `--deep`, la sonda viene eseguita anche se il gateway è integro.
|
||||
</Accordion>
|
||||
<Accordion title="2e. Override del provider OAuth Codex">
|
||||
Se in precedenza hai aggiunto impostazioni legacy di trasporto OpenAI sotto `models.providers.openai-codex`, queste possono oscurare il percorso del provider OAuth Codex integrato che le versioni più recenti usano automaticamente. Doctor avvisa quando vede quelle vecchie impostazioni di trasporto insieme a OAuth Codex, così puoi rimuovere o riscrivere l'override di trasporto obsoleto e recuperare il comportamento integrato di routing/fallback. Proxy personalizzati e override solo header sono ancora supportati e non attivano questo avviso.
|
||||
<Accordion title="2e. Override del provider Codex OAuth">
|
||||
Se in precedenza hai aggiunto impostazioni di trasporto OpenAI legacy sotto `models.providers.openai-codex`, possono oscurare il percorso del provider Codex OAuth integrato che le versioni più recenti usano automaticamente. Doctor avvisa quando rileva quelle vecchie impostazioni di trasporto insieme a Codex OAuth, così puoi rimuovere o riscrivere l'override di trasporto obsoleto e recuperare il comportamento integrato di routing/fallback. Proxy personalizzati e override solo-header sono ancora supportati e non attivano questo avviso.
|
||||
</Accordion>
|
||||
<Accordion title="2f. Avvisi sulle route del Plugin Codex">
|
||||
Quando il Plugin Codex in bundle è abilitato, doctor controlla anche se i riferimenti al modello primario `openai-codex/*` si risolvono ancora tramite il runner PI predefinito. Questa combinazione è valida quando vuoi l'autenticazione OAuth/abbonamento Codex tramite PI, ma è facile confonderla con l'harness app-server Codex nativo. Doctor avvisa e punta alla forma app-server esplicita: `openai/*` più `agentRuntime.id: "codex"` o `OPENCLAW_AGENT_RUNTIME=codex`.
|
||||
Quando il Plugin Codex in bundle è abilitato, doctor controlla anche se i riferimenti al modello primario `openai-codex/*` si risolvono ancora tramite il runner PI predefinito. Questa combinazione è valida quando vuoi l'autenticazione OAuth/subscription di Codex tramite PI, ma è facile confonderla con l'harness app-server Codex nativo. Doctor avvisa e indica la forma app-server esplicita: `openai/*` più `agentRuntime.id: "codex"` oppure `OPENCLAW_AGENT_RUNTIME=codex`.
|
||||
|
||||
Doctor non lo ripara automaticamente perché entrambe le route sono valide:
|
||||
Doctor non ripara automaticamente questo caso perché entrambe le route sono valide:
|
||||
|
||||
- `openai-codex/*` + PI significa "usa l'autenticazione OAuth/abbonamento Codex tramite il runner normale di OpenClaw."
|
||||
- `openai-codex/*` + PI significa "usa l'autenticazione OAuth/subscription Codex tramite il normale runner OpenClaw."
|
||||
- `openai/*` + `agentRuntime.id: "codex"` significa "esegui il turno incorporato tramite app-server Codex nativo."
|
||||
- `/codex ...` significa "controlla o associa una conversazione Codex nativa dalla chat."
|
||||
- `/acp ...` o `runtime: "acp"` significa "usa l'adapter ACP/acpx esterno."
|
||||
|
||||
Se l'avviso appare, scegli la route che intendevi usare e modifica manualmente la configurazione. Mantieni l'avviso invariato quando OAuth Codex PI è intenzionale.
|
||||
Se compare l'avviso, scegli la route che intendevi e modifica manualmente la configurazione. Mantieni l'avviso così com'è quando PI Codex OAuth è intenzionale.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. Migrazioni di stato legacy (layout su disco)">
|
||||
Doctor può migrare i vecchi layout su disco nella struttura corrente:
|
||||
<Accordion title="3. Migrazioni dello stato legacy (layout su disco)">
|
||||
Doctor può migrare layout su disco più vecchi nella struttura corrente:
|
||||
|
||||
- Archivio sessioni + trascrizioni:
|
||||
- da `~/.openclaw/sessions/` a `~/.openclaw/agents/<agentId>/sessions/`
|
||||
@ -286,56 +286,56 @@ Questo mette in staging i candidati durevoli ancorati nello store Dreaming a bre
|
||||
- da legacy `~/.openclaw/credentials/*.json` (tranne `oauth.json`)
|
||||
- a `~/.openclaw/credentials/whatsapp/<accountId>/...` (ID account predefinito: `default`)
|
||||
|
||||
Queste migrazioni sono best-effort e idempotenti; doctor emetterà avvisi quando lascia eventuali cartelle legacy come backup. Anche Gateway/CLI esegue la migrazione automatica dell'archivio sessioni legacy + della directory agente all'avvio, così cronologia/autenticazione/modelli finiscono nel percorso per agente senza un'esecuzione manuale di doctor. L'autenticazione WhatsApp viene intenzionalmente migrata solo tramite `openclaw doctor`. La normalizzazione provider/mappa-provider di Talk ora confronta per uguaglianza strutturale, quindi le differenze dovute solo all'ordine delle chiavi non attivano più modifiche no-op ripetute di `doctor --fix`.
|
||||
Queste migrazioni sono best-effort e idempotenti; doctor emetterà avvisi quando lascia cartelle legacy come backup. Anche Gateway/CLI esegue automaticamente la migrazione dello store sessioni legacy + directory agente all'avvio, così cronologia/auth/modelli finiscono nel percorso per-agente senza un'esecuzione manuale di doctor. L'autenticazione WhatsApp viene intenzionalmente migrata solo tramite `openclaw doctor`. La normalizzazione provider/mappa provider di talk ora confronta per uguaglianza strutturale, quindi le diff dovute solo all'ordine delle chiavi non attivano più modifiche no-op ripetute con `doctor --fix`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3a. Migrazioni dei manifest Plugin legacy">
|
||||
Doctor analizza tutti i manifest dei Plugin installati alla ricerca di chiavi di capability di primo livello deprecate (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Quando le trova, propone di spostarle nell'oggetto `contracts` e riscrivere il file manifest in-place. Questa migrazione è idempotente; se la chiave `contracts` ha già gli stessi valori, la chiave legacy viene rimossa senza duplicare i dati.
|
||||
Doctor analizza tutti i manifest dei Plugin installati alla ricerca di chiavi di capability di primo livello deprecate (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Quando le trova, offre di spostarle nell'oggetto `contracts` e riscrivere il file manifest in-place. Questa migrazione è idempotente; se la chiave `contracts` contiene già gli stessi valori, la chiave legacy viene rimossa senza duplicare i dati.
|
||||
</Accordion>
|
||||
<Accordion title="3b. Migrazioni dell'archivio Cron legacy">
|
||||
Doctor controlla anche l'archivio dei job cron (`~/.openclaw/cron/jobs.json` per impostazione predefinita, o `cron.store` quando sovrascritto) alla ricerca di vecchie forme di job che lo scheduler accetta ancora per compatibilità.
|
||||
<Accordion title="3b. Migrazioni dello store Cron legacy">
|
||||
Doctor controlla anche lo store dei job cron (`~/.openclaw/cron/jobs.json` per impostazione predefinita, o `cron.store` quando sovrascritto) per vecchie forme di job che lo scheduler accetta ancora per compatibilità.
|
||||
|
||||
Le pulizie cron correnti includono:
|
||||
Le pulizie Cron correnti includono:
|
||||
|
||||
- `jobId` → `id`
|
||||
- `schedule.cron` → `schedule.expr`
|
||||
- campi payload di primo livello (`message`, `model`, `thinking`, ...) → `payload`
|
||||
- campi di consegna di primo livello (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- alias di consegna payload `provider` → `delivery.channel` esplicito
|
||||
- semplici job legacy di fallback webhook `notify: true` → `delivery.mode="webhook"` esplicito con `delivery.to=cron.webhook`
|
||||
- alias di consegna `provider` del payload → `delivery.channel` esplicito
|
||||
- semplici job webhook fallback legacy `notify: true` → `delivery.mode="webhook"` esplicito con `delivery.to=cron.webhook`
|
||||
|
||||
Doctor migra automaticamente i job `notify: true` solo quando può farlo senza cambiare comportamento. Se un job combina il fallback notify legacy con una modalità di consegna non-webhook esistente, doctor avvisa e lascia quel job alla revisione manuale.
|
||||
|
||||
Su Linux, doctor avvisa anche quando il crontab dell'utente invoca ancora il legacy `~/.openclaw/bin/ensure-whatsapp.sh`. Quello script host-local non è mantenuto dall'attuale OpenClaw e può scrivere messaggi `Gateway inactive` falsi in `~/.openclaw/logs/whatsapp-health.log` quando cron non riesce a raggiungere il bus utente systemd. Rimuovi la voce crontab obsoleta con `crontab -e`; usa `openclaw channels status --probe`, `openclaw doctor` e `openclaw gateway status` per i controlli di salute correnti.
|
||||
Su Linux, doctor avvisa anche quando il crontab dell'utente invoca ancora il legacy `~/.openclaw/bin/ensure-whatsapp.sh`. Quello script locale all'host non è mantenuto da OpenClaw corrente e può scrivere falsi messaggi `Gateway inactive` in `~/.openclaw/logs/whatsapp-health.log` quando cron non riesce a raggiungere il bus utente systemd. Rimuovi la voce crontab obsoleta con `crontab -e`; usa `openclaw channels status --probe`, `openclaw doctor` e `openclaw gateway status` per i controlli di integrità correnti.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3c. Pulizia dei lock di sessione">
|
||||
Doctor esamina ogni directory di sessione degli agenti alla ricerca di file di write-lock obsoleti — file rimasti quando una sessione è terminata in modo anomalo. Per ogni file di lock trovato segnala: il percorso, il PID, se il PID è ancora attivo, l'età del lock e se è considerato obsoleto (PID morto o più vecchio di 30 minuti). In modalità `--fix` / `--repair` rimuove automaticamente i file di lock obsoleti; altrimenti stampa una nota e indica di eseguire di nuovo con `--fix`.
|
||||
Doctor esamina ogni directory di sessione degli agenti alla ricerca di file di write-lock obsoleti, cioè file rimasti quando una sessione è terminata in modo anomalo. Per ogni file di lock trovato segnala: il percorso, il PID, se il PID è ancora attivo, l'età del lock e se è considerato obsoleto (PID morto o più vecchio di 30 minuti). In modalità `--fix` / `--repair` rimuove automaticamente i file di lock obsoleti; altrimenti stampa una nota e indica di rieseguire con `--fix`.
|
||||
</Accordion>
|
||||
<Accordion title="3d. Riparazione del branch della trascrizione di sessione">
|
||||
Doctor esamina i file JSONL delle sessioni degli agenti alla ricerca della forma di branch duplicata creata dal bug di riscrittura della trascrizione del prompt del 2026.4.24: un turno utente abbandonato con il contesto runtime interno di OpenClaw più un elemento sibling attivo contenente lo stesso prompt utente visibile. In modalità `--fix` / `--repair`, doctor esegue il backup di ogni file interessato accanto all'originale e riscrive la trascrizione sul branch attivo, così la cronologia del Gateway e i lettori di memoria non vedono più turni duplicati.
|
||||
<Accordion title="3d. Riparazione del ramo della trascrizione di sessione">
|
||||
Doctor esamina i file JSONL delle sessioni degli agenti alla ricerca della forma di ramo duplicata creata dal bug di riscrittura della trascrizione del prompt del 2026.4.24: un turno utente abbandonato con contesto di runtime interno di OpenClaw più un elemento fratello attivo contenente lo stesso prompt utente visibile. In modalità `--fix` / `--repair`, doctor crea un backup di ogni file interessato accanto all'originale e riscrive la trascrizione sul ramo attivo, così la cronologia del gateway e i lettori di memoria non vedono più turni duplicati.
|
||||
</Accordion>
|
||||
<Accordion title="4. Controlli di integrità dello stato (persistenza delle sessioni, instradamento e sicurezza)">
|
||||
La directory di stato è il tronco encefalico operativo. Se scompare, perdi sessioni, credenziali, log e configurazione (a meno che tu non abbia backup altrove).
|
||||
<Accordion title="4. Controlli di integrità dello stato (persistenza delle sessioni, routing e sicurezza)">
|
||||
La directory di stato è il centro operativo essenziale. Se scompare, perdi sessioni, credenziali, log e configurazione (a meno che tu non abbia backup altrove).
|
||||
|
||||
Doctor controlla:
|
||||
|
||||
- **Directory di stato mancante**: avvisa della perdita catastrofica dello stato, chiede di ricreare la directory e ricorda che non può recuperare i dati mancanti.
|
||||
- **Permessi della directory di stato**: verifica la scrivibilità; offre di riparare i permessi (ed emette un suggerimento `chown` quando viene rilevata una mancata corrispondenza tra proprietario/gruppo).
|
||||
- **Directory di stato macOS sincronizzata nel cloud**: avvisa quando lo stato si risolve sotto iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) o `~/Library/CloudStorage/...` perché i percorsi basati su sincronizzazione possono causare I/O più lento e race di lock/sincronizzazione.
|
||||
- **Directory di stato Linux su SD o eMMC**: avvisa quando lo stato si risolve in una sorgente di mount `mmcblk*`, perché l'I/O casuale basato su SD o eMMC può essere più lento e usurarsi più rapidamente durante le scritture di sessioni e credenziali.
|
||||
- **Directory di sessione mancanti**: `sessions/` e la directory dello store delle sessioni sono richieste per persistere la cronologia ed evitare crash `ENOENT`.
|
||||
- **Mancata corrispondenza della trascrizione**: avvisa quando le voci di sessione recenti hanno file di trascrizione mancanti.
|
||||
- **Permessi della directory di stato**: verifica la scrivibilità; offre di riparare i permessi (ed emette un suggerimento `chown` quando rileva una mancata corrispondenza tra proprietario/gruppo).
|
||||
- **Directory di stato sincronizzata su cloud macOS**: avvisa quando lo stato risolve sotto iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) o `~/Library/CloudStorage/...`, perché i percorsi basati su sincronizzazione possono causare I/O più lento e race tra lock e sincronizzazione.
|
||||
- **Directory di stato Linux su SD o eMMC**: avvisa quando lo stato risolve a una sorgente di mount `mmcblk*`, perché l'I/O casuale basato su SD o eMMC può essere più lento e usurarsi più rapidamente con le scritture di sessioni e credenziali.
|
||||
- **Directory di sessione mancanti**: `sessions/` e la directory dell'archivio sessioni sono necessarie per conservare la cronologia ed evitare crash `ENOENT`.
|
||||
- **Mancata corrispondenza della trascrizione**: avvisa quando voci di sessione recenti hanno file di trascrizione mancanti.
|
||||
- **Sessione principale "JSONL a 1 riga"**: segnala quando la trascrizione principale ha una sola riga (la cronologia non si sta accumulando).
|
||||
- **Più directory di stato**: avvisa quando esistono più cartelle `~/.openclaw` in diverse home directory o quando `OPENCLAW_STATE_DIR` punta altrove (la cronologia può dividersi tra installazioni).
|
||||
- **Più directory di stato**: avvisa quando esistono più cartelle `~/.openclaw` in diverse directory home o quando `OPENCLAW_STATE_DIR` punta altrove (la cronologia può dividersi tra installazioni).
|
||||
- **Promemoria modalità remota**: se `gateway.mode=remote`, doctor ricorda di eseguirlo sull'host remoto (lo stato vive lì).
|
||||
- **Permessi del file di configurazione**: avvisa se `~/.openclaw/openclaw.json` è leggibile da gruppo/mondo e offre di restringere a `600`.
|
||||
- **Permessi del file di configurazione**: avvisa se `~/.openclaw/openclaw.json` è leggibile da gruppo/mondo e offre di restringere i permessi a `600`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="5. Stato dell'autenticazione dei modelli (scadenza OAuth)">
|
||||
Doctor ispeziona i profili OAuth nello store di autenticazione, avvisa quando i token stanno per scadere o sono scaduti e può aggiornarli quando è sicuro. Se il profilo OAuth/token di Anthropic è obsoleto, suggerisce una chiave API Anthropic o il percorso setup-token di Anthropic. Le richieste di aggiornamento appaiono solo durante l'esecuzione interattiva (TTY); `--non-interactive` salta i tentativi di aggiornamento.
|
||||
<Accordion title="5. Salute dell'autenticazione dei modelli (scadenza OAuth)">
|
||||
Doctor ispeziona i profili OAuth nell'archivio di autenticazione, avvisa quando i token stanno per scadere o sono scaduti e può aggiornarli quando è sicuro. Se il profilo OAuth/token Anthropic è obsoleto, suggerisce una chiave API Anthropic o il percorso setup-token di Anthropic. Le richieste di aggiornamento compaiono solo durante l'esecuzione interattiva (TTY); `--non-interactive` salta i tentativi di aggiornamento.
|
||||
|
||||
Quando un aggiornamento OAuth fallisce in modo permanente (per esempio `refresh_token_reused`, `invalid_grant` o un provider che ti indica di accedere di nuovo), doctor segnala che è necessaria una nuova autenticazione e stampa il comando esatto `openclaw models auth login --provider ...` da eseguire.
|
||||
Quando un aggiornamento OAuth fallisce in modo permanente (per esempio `refresh_token_reused`, `invalid_grant` o un provider che indica di accedere di nuovo), doctor segnala che è necessaria una nuova autenticazione e stampa il comando esatto `openclaw models auth login --provider ...` da eseguire.
|
||||
|
||||
Doctor segnala anche i profili di autenticazione temporaneamente inutilizzabili a causa di:
|
||||
|
||||
@ -344,70 +344,70 @@ Questo mette in staging i candidati durevoli ancorati nello store Dreaming a bre
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="6. Validazione del modello degli hook">
|
||||
Se `hooks.gmail.model` è impostato, doctor valida il riferimento al modello rispetto al catalogo e all'allowlist e avvisa quando non si risolve o non è consentito.
|
||||
Se `hooks.gmail.model` è impostato, doctor valida il riferimento del modello rispetto al catalogo e all'allowlist e avvisa quando non si risolverà o non è consentito.
|
||||
</Accordion>
|
||||
<Accordion title="7. Riparazione dell'immagine sandbox">
|
||||
Quando il sandboxing è abilitato, doctor controlla le immagini Docker e offre di creare o passare a nomi legacy se l'immagine corrente manca.
|
||||
Quando il sandboxing è abilitato, doctor controlla le immagini Docker e offre di creare o passare ai nomi legacy se l'immagine corrente manca.
|
||||
</Accordion>
|
||||
<Accordion title="7b. Pulizia dell'installazione dei Plugin">
|
||||
Doctor rimuove lo stato legacy di staging delle dipendenze dei Plugin generato da OpenClaw in modalità `openclaw doctor --fix` / `openclaw doctor --repair`. Questo copre root di dipendenze generate obsolete, vecchie directory di install-stage e residui locali al pacchetto provenienti dal precedente codice di riparazione delle dipendenze dei Plugin in bundle.
|
||||
Doctor rimuove lo stato legacy di staging delle dipendenze dei Plugin generato da OpenClaw in modalità `openclaw doctor --fix` / `openclaw doctor --repair`. Questo copre radici di dipendenze generate obsolete, vecchie directory install-stage, residui locali del pacchetto dal precedente codice di riparazione delle dipendenze dei bundled-plugin e copie npm gestite orfane dei Plugin `@openclaw/*` inclusi che possono oscurare il manifest incluso corrente.
|
||||
|
||||
Doctor può anche reinstallare i Plugin scaricabili configurati quando la configurazione li referenzia ma il registro locale dei Plugin non riesce a trovarli. Per l'esternalizzazione dei Plugin in bundle del 2026.5.2, doctor installa automaticamente i Plugin scaricabili che la configurazione esistente usa già e poi si affida a `meta.lastTouchedVersion` per eseguire quel passaggio di rilascio una sola volta. L'avvio del Gateway e il ricaricamento della configurazione non eseguono package manager; le installazioni dei Plugin restano lavoro esplicito di doctor/install/update.
|
||||
Doctor può anche reinstallare i Plugin scaricabili configurati quando la configurazione li riferimento ma il registry locale dei Plugin non riesce a trovarli. Per l'esternalizzazione dei bundled-plugin del 2026.5.2, doctor installa automaticamente i Plugin scaricabili che la configurazione esistente usa già e poi si affida a `meta.lastTouchedVersion` per eseguire quel passaggio di release una sola volta. L'avvio del Gateway e il ricaricamento della configurazione non eseguono package manager; le installazioni dei Plugin restano operazioni esplicite di doctor/install/update.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8. Migrazioni del servizio Gateway e suggerimenti di pulizia">
|
||||
Doctor rileva i servizi gateway legacy (launchd/systemd/schtasks) e offre di rimuoverli e installare il servizio OpenClaw usando la porta Gateway corrente. Può anche esaminare servizi aggiuntivi simili a gateway e stampare suggerimenti di pulizia. I servizi Gateway OpenClaw con nome profilo sono considerati di prima classe e non vengono segnalati come "extra".
|
||||
Doctor rileva i servizi Gateway legacy (launchd/systemd/schtasks) e offre di rimuoverli e installare il servizio OpenClaw usando la porta Gateway corrente. Può anche esaminare servizi aggiuntivi simili al Gateway e stampare suggerimenti di pulizia. I servizi Gateway OpenClaw con nome di profilo sono considerati di prima classe e non vengono segnalati come "extra".
|
||||
|
||||
Su Linux, se il servizio Gateway a livello utente manca ma esiste un servizio Gateway OpenClaw a livello di sistema, doctor non installa automaticamente un secondo servizio a livello utente. Ispeziona con `openclaw gateway status --deep` o `openclaw doctor --deep`, quindi rimuovi il duplicato o imposta `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando un supervisore di sistema gestisce il ciclo di vita del Gateway.
|
||||
Su Linux, se il servizio Gateway a livello utente manca ma esiste un servizio Gateway OpenClaw a livello di sistema, doctor non installa automaticamente un secondo servizio a livello utente. Ispeziona con `openclaw gateway status --deep` o `openclaw doctor --deep`, poi rimuovi il duplicato o imposta `OPENCLAW_SERVICE_REPAIR_POLICY=external` quando un supervisore di sistema possiede il ciclo di vita del Gateway.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8b. Migrazione all'avvio di Matrix">
|
||||
Quando un account del canale Matrix ha una migrazione dello stato legacy in sospeso o azionabile, doctor (in modalità `--fix` / `--repair`) crea uno snapshot pre-migrazione e poi esegue i passaggi di migrazione best-effort: migrazione dello stato Matrix legacy e preparazione dello stato cifrato legacy. Entrambi i passaggi non sono fatali; gli errori vengono registrati e l'avvio continua. In modalità sola lettura (`openclaw doctor` senza `--fix`) questo controllo viene saltato completamente.
|
||||
<Accordion title="8b. Migrazione Matrix all'avvio">
|
||||
Quando un account di canale Matrix ha una migrazione dello stato legacy in sospeso o azionabile, doctor (in modalità `--fix` / `--repair`) crea uno snapshot pre-migrazione e poi esegue i passaggi di migrazione best-effort: migrazione dello stato legacy Matrix e preparazione dello stato cifrato legacy. Entrambi i passaggi non sono fatali; gli errori vengono registrati e l'avvio continua. In modalità sola lettura (`openclaw doctor` senza `--fix`) questo controllo viene saltato completamente.
|
||||
</Accordion>
|
||||
<Accordion title="8c. Associazione dei dispositivi e deriva dell'autenticazione">
|
||||
Doctor ora ispeziona lo stato di associazione dei dispositivi come parte del normale passaggio di salute.
|
||||
Doctor ora ispeziona lo stato di associazione dei dispositivi come parte del normale controllo di salute.
|
||||
|
||||
Cosa segnala:
|
||||
|
||||
- richieste di prima associazione in sospeso
|
||||
- aggiornamenti di ruolo in sospeso per dispositivi già associati
|
||||
- aggiornamenti di ambito in sospeso per dispositivi già associati
|
||||
- riparazioni di mancata corrispondenza della chiave pubblica dove l'id del dispositivo corrisponde ancora ma l'identità del dispositivo non corrisponde più al record approvato
|
||||
- record associati privi di un token attivo per un ruolo approvato
|
||||
- token associati i cui ambiti derivano fuori dalla baseline di associazione approvata
|
||||
- voci locali memorizzate nella cache del token dispositivo per la macchina corrente che precedono una rotazione del token lato Gateway o portano metadati di ambito obsoleti
|
||||
- upgrade di ruolo in sospeso per dispositivi già associati
|
||||
- upgrade di ambito in sospeso per dispositivi già associati
|
||||
- riparazioni di mancata corrispondenza della chiave pubblica in cui l'id del dispositivo corrisponde ancora ma l'identità del dispositivo non corrisponde più al record approvato
|
||||
- record associati senza un token attivo per un ruolo approvato
|
||||
- token associati i cui ambiti derivano fuori dal baseline di associazione approvato
|
||||
- voci locali memorizzate nella cache del token dispositivo per la macchina corrente precedenti a una rotazione del token lato Gateway o con metadati di ambito obsoleti
|
||||
|
||||
Doctor non approva automaticamente le richieste di associazione né ruota automaticamente i token dei dispositivi. Stampa invece i passaggi successivi esatti:
|
||||
Doctor non approva automaticamente richieste di associazione né ruota automaticamente i token dei dispositivi. Stampa invece i passaggi successivi esatti:
|
||||
|
||||
- ispeziona le richieste in sospeso con `openclaw devices list`
|
||||
- approva la richiesta esatta con `openclaw devices approve <requestId>`
|
||||
- ruota un token nuovo con `openclaw devices rotate --device <deviceId> --role <role>`
|
||||
- ruota un token fresco con `openclaw devices rotate --device <deviceId> --role <role>`
|
||||
- rimuovi e riapprova un record obsoleto con `openclaw devices remove <deviceId>`
|
||||
|
||||
Questo chiude il comune vuoto "già associato ma riceve ancora richiesta di associazione": doctor ora distingue la prima associazione dagli aggiornamenti di ruolo/ambito in sospeso e dalla deriva di token/identità dispositivo obsoleti.
|
||||
Questo chiude il comune caso "già associato ma riceve ancora richiesta di associazione": doctor ora distingue la prima associazione dagli upgrade di ruolo/ambito in sospeso e dalla deriva obsoleta di token/identità dispositivo.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="9. Avvisi di sicurezza">
|
||||
Doctor emette avvisi quando un provider è aperto ai DM senza un'allowlist, o quando una policy è configurata in modo pericoloso.
|
||||
</Accordion>
|
||||
<Accordion title="10. systemd linger (Linux)">
|
||||
Se in esecuzione come servizio utente systemd, doctor assicura che il lingering sia abilitato così il gateway resta attivo dopo il logout.
|
||||
Se in esecuzione come servizio utente systemd, doctor assicura che il lingering sia abilitato così il Gateway resta attivo dopo il logout.
|
||||
</Accordion>
|
||||
<Accordion title="11. Stato del workspace (Skills, Plugin e directory legacy)">
|
||||
Doctor stampa un riepilogo dello stato del workspace per l'agente predefinito:
|
||||
|
||||
- **Stato delle Skills**: conta Skills idonee, con requisiti mancanti e bloccate dall'allowlist.
|
||||
- **Directory workspace legacy**: avvisa quando `~/openclaw` o altre directory workspace legacy esistono accanto al workspace corrente.
|
||||
- **Stato dei Plugin**: conta Plugin abilitati/disabilitati/con errori; elenca gli ID dei Plugin per eventuali errori; segnala le capacità dei Plugin in bundle.
|
||||
- **Directory workspace legacy**: avvisa quando `~/openclaw` o altre directory workspace legacy esistono insieme al workspace corrente.
|
||||
- **Stato dei Plugin**: conta Plugin abilitati/disabilitati/con errori; elenca gli ID dei Plugin per eventuali errori; segnala le capacità dei Plugin inclusi.
|
||||
- **Avvisi di compatibilità dei Plugin**: segnala i Plugin che hanno problemi di compatibilità con il runtime corrente.
|
||||
- **Diagnostica dei Plugin**: mostra eventuali avvisi o errori in fase di caricamento emessi dal registro dei Plugin.
|
||||
- **Diagnostica dei Plugin**: espone eventuali avvisi o errori in fase di caricamento emessi dal registry dei Plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="11b. Dimensione del file di bootstrap">
|
||||
Doctor controlla se i file di bootstrap del workspace (per esempio `AGENTS.md`, `CLAUDE.md` o altri file di contesto iniettati) sono vicini o oltre il budget di caratteri configurato. Segnala per ogni file conteggi di caratteri grezzi rispetto a quelli iniettati, percentuale di troncamento, causa del troncamento (`max/file` o `max/total`) e caratteri iniettati totali come frazione del budget totale. Quando i file sono troncati o vicini al limite, doctor stampa suggerimenti per regolare `agents.defaults.bootstrapMaxChars` e `agents.defaults.bootstrapTotalMaxChars`.
|
||||
<Accordion title="11b. Dimensione del file bootstrap">
|
||||
Doctor controlla se i file bootstrap del workspace (per esempio `AGENTS.md`, `CLAUDE.md` o altri file di contesto iniettati) sono vicini o superiori al budget di caratteri configurato. Segnala per ogni file il conteggio dei caratteri grezzi rispetto a quelli iniettati, la percentuale di troncamento, la causa del troncamento (`max/file` o `max/total`) e il totale dei caratteri iniettati come frazione del budget totale. Quando i file vengono troncati o sono vicini al limite, doctor stampa suggerimenti per regolare `agents.defaults.bootstrapMaxChars` e `agents.defaults.bootstrapTotalMaxChars`.
|
||||
</Accordion>
|
||||
<Accordion title="11d. Pulizia dei Plugin di canale obsoleti">
|
||||
Quando `openclaw doctor --fix` rimuove un Plugin di canale mancante, rimuove anche la configurazione dangling con ambito di canale che referenziava quel Plugin: voci `channels.<id>`, target heartbeat che nominavano il canale e override `agents.*.models["<channel>/*"]`. Questo previene loop di avvio del Gateway in cui il runtime del canale è sparito ma la configurazione chiede ancora al gateway di associarsi a esso.
|
||||
Quando `openclaw doctor --fix` rimuove un Plugin di canale mancante, rimuove anche la configurazione pendente con ambito di canale che faceva riferimento a quel Plugin: voci `channels.<id>`, destinazioni Heartbeat che nominavano il canale e override `agents.*.models["<channel>/*"]`. Questo impedisce loop di avvio del Gateway in cui il runtime del canale non esiste più ma la configurazione chiede ancora al gateway di collegarsi a esso.
|
||||
</Accordion>
|
||||
<Accordion title="11c. Completamento della shell">
|
||||
Doctor controlla se il completamento con tab è installato per la shell corrente (zsh, bash, fish o PowerShell):
|
||||
@ -419,78 +419,78 @@ Questo mette in staging i candidati durevoli ancorati nello store Dreaming a bre
|
||||
Esegui `openclaw completion --write-state` per rigenerare manualmente la cache.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12. Controlli di autenticazione del Gateway (token locale)">
|
||||
Doctor controlla la prontezza dell'autenticazione con token locale del Gateway.
|
||||
<Accordion title="12. Controlli di autenticazione Gateway (token locale)">
|
||||
Doctor controlla la prontezza dell'autenticazione con token del Gateway locale.
|
||||
|
||||
- Se la modalità token richiede un token e non esiste alcuna sorgente di token, doctor offre di generarne uno.
|
||||
- Se la modalità token richiede un token e non esiste alcuna sorgente token, doctor offre di generarne uno.
|
||||
- Se `gateway.auth.token` è gestito da SecretRef ma non disponibile, doctor avvisa e non lo sovrascrive con testo in chiaro.
|
||||
- `openclaw doctor --generate-gateway-token` forza la generazione solo quando non è configurato alcun token SecretRef.
|
||||
- `openclaw doctor --generate-gateway-token` forza la generazione solo quando non è configurato alcun SecretRef del token.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12b. Riparazioni in sola lettura consapevoli di SecretRef">
|
||||
Alcuni flussi di riparazione devono ispezionare le credenziali configurate senza indebolire il comportamento fail-fast del runtime.
|
||||
|
||||
- `openclaw doctor --fix` ora usa lo stesso modello di riepilogo SecretRef in sola lettura dei comandi della famiglia status per riparazioni di configurazione mirate.
|
||||
- Esempio: la riparazione `allowFrom` / `groupAllowFrom` `@username` di Telegram prova a usare le credenziali bot configurate quando disponibili.
|
||||
- Se il token bot di Telegram è configurato tramite SecretRef ma non disponibile nel percorso del comando corrente, doctor segnala che la credenziale è configurata-ma-non-disponibile e salta l'auto-risoluzione invece di andare in crash o segnalare erroneamente il token come mancante.
|
||||
- Esempio: la riparazione di `allowFrom` / `groupAllowFrom` `@username` di Telegram prova a usare le credenziali bot configurate quando disponibili.
|
||||
- Se il token bot Telegram è configurato tramite SecretRef ma non disponibile nel percorso del comando corrente, doctor segnala che la credenziale è configurata ma non disponibile e salta la risoluzione automatica invece di andare in crash o segnalare erroneamente il token come mancante.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="13. Controllo di integrità del Gateway + riavvio">
|
||||
Doctor esegue un controllo di integrità e propone di riavviare il Gateway quando sembra non essere integro.
|
||||
Doctor esegue un controllo di integrità e propone di riavviare il Gateway quando sembra non integro.
|
||||
</Accordion>
|
||||
<Accordion title="13b. Preparazione della ricerca in memoria">
|
||||
Doctor verifica se il provider di embedding per la ricerca in memoria configurato è pronto per l’agente predefinito. Il comportamento dipende dal backend e dal provider configurati:
|
||||
<Accordion title="13b. Prontezza della ricerca in memoria">
|
||||
Doctor verifica se il provider di embedding per la ricerca in memoria configurato è pronto per l'agente predefinito. Il comportamento dipende dal backend e dal provider configurati:
|
||||
|
||||
- **Backend QMD**: verifica se il binario `qmd` è disponibile e avviabile. In caso contrario, stampa indicazioni di correzione che includono il pacchetto npm e un’opzione per il percorso manuale del binario.
|
||||
- **Provider locale esplicito**: verifica la presenza di un file di modello locale o di un URL di modello remoto/scaricabile riconosciuto. Se manca, suggerisce di passare a un provider remoto.
|
||||
- **Provider remoto esplicito** (`openai`, `voyage`, ecc.): verifica che una chiave API sia presente nell’ambiente o nell’archivio di autenticazione. Stampa suggerimenti di correzione utilizzabili se manca.
|
||||
- **Provider automatico**: controlla prima la disponibilità del modello locale, poi prova ogni provider remoto nell’ordine di selezione automatica.
|
||||
- **Backend QMD**: verifica se il binario `qmd` è disponibile e avviabile. In caso contrario, stampa indicazioni per la correzione, inclusi il pacchetto npm e un'opzione per il percorso manuale del binario.
|
||||
- **Provider locale esplicito**: controlla la presenza di un file di modello locale o di un URL di modello remoto/scaricabile riconosciuto. Se manca, suggerisce di passare a un provider remoto.
|
||||
- **Provider remoto esplicito** (`openai`, `voyage`, ecc.): verifica che una chiave API sia presente nell'ambiente o nell'archivio di autenticazione. Stampa suggerimenti di correzione applicabili se manca.
|
||||
- **Provider automatico**: controlla prima la disponibilità del modello locale, poi prova ciascun provider remoto nell'ordine di selezione automatica.
|
||||
|
||||
Quando è disponibile un risultato memorizzato nella cache della verifica del Gateway (il Gateway era integro al momento del controllo), doctor lo confronta con la configurazione visibile dalla CLI e segnala eventuali discrepanze. Doctor non avvia un nuovo ping di embedding nel percorso predefinito; usa il comando di stato approfondito della memoria quando vuoi un controllo live del provider.
|
||||
Quando è disponibile un risultato memorizzato nella cache del probe del Gateway (il Gateway era integro al momento del controllo), doctor confronta il risultato con la configurazione visibile dalla CLI e segnala eventuali discrepanze. Doctor non avvia un nuovo ping di embedding nel percorso predefinito; usa il comando di stato memoria approfondito quando vuoi un controllo live del provider.
|
||||
|
||||
Usa `openclaw memory status --deep` per verificare la preparazione degli embedding in fase di esecuzione.
|
||||
Usa `openclaw memory status --deep` per verificare la prontezza degli embedding in fase di esecuzione.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="14. Avvisi di stato dei canali">
|
||||
Se il Gateway è integro, doctor esegue una verifica dello stato dei canali e segnala avvisi con correzioni suggerite.
|
||||
<Accordion title="14. Avvisi sullo stato del canale">
|
||||
Se il Gateway è integro, doctor esegue un probe dello stato del canale e segnala avvisi con correzioni suggerite.
|
||||
</Accordion>
|
||||
<Accordion title="15. Audit + riparazione della configurazione del supervisore">
|
||||
Doctor controlla la configurazione del supervisore installata (launchd/systemd/schtasks) per individuare impostazioni predefinite mancanti o obsolete (ad esempio, dipendenze systemd da network-online e ritardo di riavvio). Quando trova una mancata corrispondenza, consiglia un aggiornamento e può riscrivere il file di servizio/task con le impostazioni predefinite correnti.
|
||||
Doctor controlla la configurazione del supervisore installata (launchd/systemd/schtasks) per individuare valori predefiniti mancanti o obsoleti (ad esempio, dipendenze systemd network-online e ritardo di riavvio). Quando trova una mancata corrispondenza, consiglia un aggiornamento e può riscrivere il file di servizio/attività con i valori predefiniti correnti.
|
||||
|
||||
Note:
|
||||
|
||||
- `openclaw doctor` chiede conferma prima di riscrivere la configurazione del supervisore.
|
||||
- `openclaw doctor --yes` accetta le richieste di riparazione predefinite.
|
||||
- `openclaw doctor --repair` applica le correzioni consigliate senza richieste di conferma.
|
||||
- `openclaw doctor --repair --force` sovrascrive le configurazioni personalizzate del supervisore.
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` mantiene doctor in sola lettura per il ciclo di vita del servizio Gateway. Segnala comunque l’integrità del servizio ed esegue riparazioni non relative al servizio, ma salta installazione/avvio/riavvio/bootstrap del servizio, riscritture della configurazione del supervisore e pulizia dei servizi legacy perché quel ciclo di vita è gestito da un supervisore esterno.
|
||||
- Su Linux, doctor non riscrive i metadati di comando/entrypoint mentre l’unità systemd Gateway corrispondente è attiva. Inoltre ignora le unità aggiuntive inattive non legacy simili al Gateway durante la scansione dei servizi duplicati, così i file di servizio companion non creano rumore di pulizia.
|
||||
- Se l’autenticazione con token richiede un token e `gateway.auth.token` è gestito da SecretRef, l’installazione/riparazione del servizio doctor convalida il SecretRef ma non persiste valori di token in testo semplice risolti nei metadati dell’ambiente del servizio del supervisore.
|
||||
- Doctor rileva valori di ambiente del servizio gestiti basati su `.env`/SecretRef che installazioni LaunchAgent, systemd o Windows Scheduled Task più vecchie avevano incorporato inline e riscrive i metadati del servizio in modo che quei valori vengano caricati dalla sorgente runtime invece che dalla definizione del supervisore.
|
||||
- Doctor rileva quando il comando del servizio fissa ancora un vecchio `--port` dopo modifiche a `gateway.port` e riscrive i metadati del servizio sulla porta corrente.
|
||||
- Se l’autenticazione con token richiede un token e il SecretRef del token configurato non è risolto, doctor blocca il percorso di installazione/riparazione con indicazioni utilizzabili.
|
||||
- Se sia `gateway.auth.token` sia `gateway.auth.password` sono configurati e `gateway.auth.mode` non è impostato, doctor blocca installazione/riparazione finché la modalità non viene impostata esplicitamente.
|
||||
- Per le unità systemd utente su Linux, i controlli di deriva del token di doctor ora includono sia le sorgenti `Environment=` sia `EnvironmentFile=` quando confrontano i metadati di autenticazione del servizio.
|
||||
- Le riparazioni del servizio doctor rifiutano di riscrivere, arrestare o riavviare un servizio Gateway da un binario OpenClaw più vecchio quando la configurazione è stata scritta l’ultima volta da una versione più recente. Vedi [Risoluzione dei problemi del Gateway](/it/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
|
||||
- `openclaw doctor --repair` applica le correzioni consigliate senza richieste.
|
||||
- `openclaw doctor --repair --force` sovrascrive le configurazioni del supervisore personalizzate.
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` mantiene doctor in sola lettura per il ciclo di vita del servizio Gateway. Continua a segnalare l'integrità del servizio ed esegue riparazioni non relative al servizio, ma salta installazione/avvio/riavvio/bootstrap del servizio, riscritture della configurazione del supervisore e pulizia dei servizi legacy perché quel ciclo di vita è gestito da un supervisore esterno.
|
||||
- Su Linux, doctor non riscrive i metadati di comando/entrypoint mentre l'unità Gateway systemd corrispondente è attiva. Ignora inoltre le unità aggiuntive inattive non legacy simili al Gateway durante la scansione dei servizi duplicati, così i file di servizio companion non generano rumore di pulizia.
|
||||
- Se l'autenticazione con token richiede un token e `gateway.auth.token` è gestito da SecretRef, l'installazione/riparazione del servizio doctor convalida il SecretRef ma non persiste i valori del token in chiaro risolti nei metadati dell'ambiente del servizio del supervisore.
|
||||
- Doctor rileva valori di ambiente del servizio gestiti e basati su `.env`/SecretRef che installazioni LaunchAgent, systemd o Windows Scheduled Task più vecchie incorporavano inline e riscrive i metadati del servizio in modo che tali valori vengano caricati dalla sorgente di runtime anziché dalla definizione del supervisore.
|
||||
- Doctor rileva quando il comando del servizio mantiene ancora un vecchio `--port` dopo modifiche a `gateway.port` e riscrive i metadati del servizio sulla porta corrente.
|
||||
- Se l'autenticazione con token richiede un token e il SecretRef del token configurato non viene risolto, doctor blocca il percorso di installazione/riparazione con indicazioni applicabili.
|
||||
- Se sono configurati sia `gateway.auth.token` sia `gateway.auth.password` e `gateway.auth.mode` non è impostato, doctor blocca installazione/riparazione finché la modalità non viene impostata esplicitamente.
|
||||
- Per le unità Linux user-systemd, i controlli di divergenza del token di doctor ora includono sia le sorgenti `Environment=` sia `EnvironmentFile=` quando confrontano i metadati di autenticazione del servizio.
|
||||
- Le riparazioni del servizio doctor rifiutano di riscrivere, arrestare o riavviare un servizio Gateway da un binario OpenClaw più vecchio quando la configurazione è stata scritta l'ultima volta da una versione più recente. Consulta [Risoluzione dei problemi del Gateway](/it/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
|
||||
- Puoi sempre forzare una riscrittura completa tramite `openclaw gateway install --force`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="16. Diagnostica runtime + porta del Gateway">
|
||||
Doctor ispeziona il runtime del servizio (PID, ultimo stato di uscita) e avvisa quando il servizio è installato ma non è realmente in esecuzione. Controlla anche collisioni di porta sulla porta del Gateway (predefinita `18789`) e segnala le cause probabili (Gateway già in esecuzione, tunnel SSH).
|
||||
<Accordion title="16. Runtime del Gateway + diagnostica della porta">
|
||||
Doctor ispeziona il runtime del servizio (PID, ultimo stato di uscita) e avvisa quando il servizio è installato ma non è effettivamente in esecuzione. Controlla anche collisioni di porta sulla porta del Gateway (predefinita `18789`) e segnala le cause probabili (Gateway già in esecuzione, tunnel SSH).
|
||||
</Accordion>
|
||||
<Accordion title="17. Buone pratiche per il runtime del Gateway">
|
||||
Doctor avvisa quando il servizio Gateway viene eseguito su Bun o su un percorso Node gestito da versione (`nvm`, `fnm`, `volta`, `asdf`, ecc.). I canali WhatsApp + Telegram richiedono Node, e i percorsi dei gestori di versione possono interrompersi dopo gli aggiornamenti perché il servizio non carica l’inizializzazione della shell. Doctor propone di migrare a un’installazione Node di sistema quando disponibile (Homebrew/apt/choco).
|
||||
Doctor avvisa quando il servizio Gateway viene eseguito su Bun o su un percorso Node gestito da version manager (`nvm`, `fnm`, `volta`, `asdf`, ecc.). I canali WhatsApp + Telegram richiedono Node, e i percorsi dei version manager possono interrompersi dopo gli aggiornamenti perché il servizio non carica l'inizializzazione della shell. Doctor propone di migrare a un'installazione Node di sistema quando disponibile (Homebrew/apt/choco).
|
||||
|
||||
I LaunchAgent macOS appena installati o riparati usano un PATH di sistema canonico (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) invece di copiare il PATH della shell interattiva, quindi Volta, asdf, fnm, pnpm e altre directory dei gestori di versione non cambiano quale Node viene risolto dai processi figli. I servizi Linux mantengono ancora le radici di ambiente esplicite (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) e le directory user-bin stabili, ma le directory fallback dei gestori di versione dedotte vengono scritte nel PATH del servizio solo quando quelle directory esistono su disco.
|
||||
I LaunchAgent macOS appena installati o riparati usano un PATH di sistema canonico (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) invece di copiare il PATH della shell interattiva, così Volta, asdf, fnm, pnpm e altre directory dei version manager non modificano quale Node viene risolto dai processi figli. I servizi Linux mantengono comunque radici di ambiente esplicite (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) e directory user-bin stabili, ma le directory di fallback dei version manager stimate vengono scritte nel PATH del servizio solo quando tali directory esistono su disco.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="18. Scrittura della configurazione + metadati del wizard">
|
||||
Doctor persiste eventuali modifiche alla configurazione e appone un timestamp nei metadati del wizard per registrare l’esecuzione di doctor.
|
||||
<Accordion title="18. Scrittura della configurazione + metadati della procedura guidata">
|
||||
Doctor persiste eventuali modifiche alla configurazione e timbra i metadati della procedura guidata per registrare l'esecuzione di doctor.
|
||||
</Accordion>
|
||||
<Accordion title="19. Suggerimenti per il workspace (backup + sistema di memoria)">
|
||||
Doctor suggerisce un sistema di memoria del workspace quando manca e stampa un suggerimento di backup se il workspace non è già sotto git.
|
||||
<Accordion title="19. Suggerimenti per l'area di lavoro (backup + sistema di memoria)">
|
||||
Doctor suggerisce un sistema di memoria dell'area di lavoro quando manca e stampa un suggerimento di backup se l'area di lavoro non è già sotto git.
|
||||
|
||||
Vedi [/concepts/agent-workspace](/it/concepts/agent-workspace) per una guida completa alla struttura del workspace e al backup git (consigliato GitHub privato o GitLab).
|
||||
Consulta [/concepts/agent-workspace](/it/concepts/agent-workspace) per una guida completa alla struttura dell'area di lavoro e al backup git (consigliati GitHub o GitLab privati).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- È necessario chiamare helper del core da un plugin (TTS, STT, generazione di immagini, ricerca web, subagent, nodi)
|
||||
- Devi chiamare gli helper core da un Plugin (TTS, STT, generazione di immagini, ricerca web, sottoagente, nodi)
|
||||
- Vuoi capire cosa espone api.runtime
|
||||
- Stai accedendo alle funzioni di supporto per configurazione, agente o contenuti multimediali dal codice del Plugin
|
||||
- Stai accedendo agli helper di configurazione, agente o media dal codice del Plugin
|
||||
sidebarTitle: Runtime helpers
|
||||
summary: api.runtime -- gli helper di runtime iniettati disponibili per i plugin
|
||||
title: Funzioni di supporto per l'ambiente di esecuzione del Plugin
|
||||
summary: api.runtime -- gli helper di runtime iniettati disponibili per i Plugin
|
||||
title: Helper di runtime dei Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T20:59:43Z"
|
||||
generated_at: "2026-05-04T08:40:05Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 26df37a2ad0dcd29648e382eb579b6892068af4dea1c47460cfd379458a8081c
|
||||
source_hash: c968f30052ecba4359bdaa9b1c640c1220268933ce01ccef06bcade225b50b7d
|
||||
source_path: plugins/sdk-runtime.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Riferimento per l'oggetto `api.runtime` iniettato in ogni Plugin durante la registrazione. Usa queste funzioni di supporto invece di importare direttamente i componenti interni dell'host.
|
||||
Riferimento per l'oggetto `api.runtime` iniettato in ogni Plugin durante la registrazione. Usa questi helper invece di importare direttamente gli elementi interni dell'host.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Plugin di canale" href="/it/plugins/sdk-channel-plugins">
|
||||
Guida passo passo che usa queste funzioni di supporto nel contesto dei Plugin di canale.
|
||||
Guida passo passo che usa questi helper nel contesto dei Plugin di canale.
|
||||
</Card>
|
||||
<Card title="Plugin provider" href="/it/plugins/sdk-provider-plugins">
|
||||
Guida passo passo che usa queste funzioni di supporto nel contesto dei Plugin provider.
|
||||
Guida passo passo che usa questi helper nel contesto dei Plugin provider.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -32,30 +32,31 @@ register(api) {
|
||||
}
|
||||
```
|
||||
|
||||
## Caricamento e scritture della configurazione
|
||||
## Caricamento E Scrittura Della Configurazione
|
||||
|
||||
Preferisci la configurazione già passata nel percorso di chiamata attivo, per esempio `api.config` durante la registrazione o un argomento `cfg` nei callback di canale/provider. Questo mantiene un solo snapshot del processo lungo il lavoro invece di rileggere la configurazione nei percorsi frequenti.
|
||||
Preferisci la configurazione già passata nel percorso di chiamata attivo, per esempio `api.config` durante la registrazione o un argomento `cfg` nei callback di canale/provider. In questo modo una singola istantanea del processo attraversa il lavoro invece di rieseguire il parsing della configurazione nei percorsi critici.
|
||||
|
||||
Usa `api.runtime.config.current()` solo quando un handler a lunga durata ha bisogno dello snapshot del processo corrente e a quella funzione non è stata passata alcuna configurazione. Il valore restituito è readonly; clonalo o usa una funzione di supporto per le mutazioni prima di modificarlo.
|
||||
Usa `api.runtime.config.current()` solo quando un handler a lunga durata ha bisogno dell'istantanea corrente del processo e a quella funzione non è stata passata alcuna configurazione. Il valore restituito è di sola lettura; clonalo o usa un helper di mutazione prima di modificarlo.
|
||||
|
||||
Le factory di tool ricevono `ctx.runtimeConfig` più `ctx.getRuntimeConfig()`. Usa il getter dentro il callback `execute` di un tool a lunga durata quando la configurazione può cambiare dopo la creazione della definizione del tool.
|
||||
Le factory degli strumenti ricevono `ctx.runtimeConfig` più `ctx.getRuntimeConfig()`. Usa il getter dentro il callback `execute` di uno strumento a lunga durata quando la configurazione può cambiare dopo la creazione della definizione dello strumento.
|
||||
|
||||
Rendi persistenti le modifiche con `api.runtime.config.mutateConfigFile(...)` o `api.runtime.config.replaceConfigFile(...)`. Ogni scrittura deve scegliere una policy `afterWrite` esplicita:
|
||||
|
||||
- `afterWrite: { mode: "auto" }` lascia decidere al meccanismo di ricaricamento del planner del gateway.
|
||||
- `afterWrite: { mode: "restart", reason: "..." }` forza un riavvio pulito quando chi scrive sa che il reload a caldo non è sicuro.
|
||||
- `afterWrite: { mode: "none", reason: "..." }` sopprime ricaricamento/riavvio automatici solo quando il chiamante è responsabile del seguito.
|
||||
- `afterWrite: { mode: "auto" }` lascia decidere al ricaricamento del planner del gateway.
|
||||
- `afterWrite: { mode: "restart", reason: "..." }` forza un riavvio pulito quando il writer sa che il ricaricamento a caldo non è sicuro.
|
||||
- `afterWrite: { mode: "none", reason: "..." }` sopprime il ricaricamento/riavvio automatico solo quando il chiamante gestisce il follow-up.
|
||||
|
||||
Le funzioni di supporto per le mutazioni restituiscono `afterWrite` più un riepilogo `followUp` tipizzato, così i chiamanti possono registrare nei log o testare se hanno richiesto un riavvio. Il gateway resta comunque responsabile di quando quel riavvio avviene effettivamente.
|
||||
Gli helper di mutazione restituiscono `afterWrite` più un riepilogo tipizzato `followUp`, così i chiamanti possono registrare nei log o testare se hanno richiesto un riavvio. Il gateway resta comunque responsabile di quando quel riavvio avviene effettivamente.
|
||||
|
||||
`api.runtime.config.loadConfig()` e `api.runtime.config.writeConfigFile(...)` sono funzioni di supporto di compatibilità deprecate sotto `runtime-config-load-write`. Generano un avviso una volta a runtime e restano disponibili per i vecchi Plugin esterni durante la finestra di migrazione. I Plugin inclusi non devono usarle; le guardie del confine di configurazione falliscono se il codice del Plugin le chiama o importa tali funzioni di supporto dai sottopercorsi dell'SDK dei Plugin.
|
||||
`api.runtime.config.loadConfig()` e `api.runtime.config.writeConfigFile(...)` sono helper di compatibilità deprecati sotto `runtime-config-load-write`. Avvisano una volta a runtime e restano disponibili per i vecchi Plugin esterni durante la finestra di migrazione. I Plugin inclusi non devono usarli; le protezioni del confine di configurazione falliscono se il codice del Plugin li chiama o importa quegli helper dai sottopercorsi dell'SDK dei Plugin.
|
||||
|
||||
Per gli import diretti dell'SDK, usa i sottopercorsi di configurazione mirati invece del barrel di compatibilità generico
|
||||
`openclaw/plugin-sdk/config-runtime`: `config-types` per i tipi, `plugin-config-runtime` per le asserzioni sulla configurazione già caricata e la ricerca delle voci dei Plugin, `runtime-config-snapshot` per gli snapshot del processo corrente e `config-mutation` per le scritture. I test dei Plugin inclusi dovrebbero mockare direttamente questi sottopercorsi mirati invece di mockare il barrel di compatibilità generico.
|
||||
Per le importazioni dirette dell'SDK, usa i sottopercorsi di configurazione mirati invece del barrel di compatibilità ampio
|
||||
`openclaw/plugin-sdk/config-runtime`: `config-types` per i tipi, `plugin-config-runtime` per le asserzioni sulla configurazione già caricata e la ricerca delle entry dei Plugin, `runtime-config-snapshot` per le istantanee correnti del processo e
|
||||
`config-mutation` per le scritture. I test dei Plugin inclusi dovrebbero mockare direttamente questi sottopercorsi mirati invece di mockare il barrel di compatibilità ampio.
|
||||
|
||||
Il codice runtime interno di OpenClaw segue la stessa direzione: caricare la configurazione una volta al confine della CLI, del gateway o del processo, poi passare quel valore lungo il flusso. Le scritture di mutazione riuscite aggiornano lo snapshot runtime del processo e incrementano la sua revisione interna; le cache a lunga durata dovrebbero usare come chiave la cache key di proprietà del runtime invece di serializzare localmente la configurazione. I moduli runtime a lunga durata hanno uno scanner a tolleranza zero per le chiamate ambientali a `loadConfig()`; usa un `cfg` passato, un `context.getRuntimeConfig()` della richiesta o `getRuntimeConfig()` a un confine di processo esplicito.
|
||||
Il codice runtime interno di OpenClaw segue la stessa direzione: caricare la configurazione una sola volta al confine della CLI, del gateway o del processo, quindi passare quel valore lungo il flusso. Le scritture di mutazione riuscite aggiornano l'istantanea runtime del processo e avanzano la sua revisione interna; le cache a lunga durata dovrebbero usare come chiave la chiave di cache posseduta dal runtime invece di serializzare localmente la configurazione. I moduli runtime a lunga durata hanno uno scanner a tolleranza zero per chiamate ambientali a `loadConfig()`; usa un `cfg` passato, un `context.getRuntimeConfig()` della richiesta o `getRuntimeConfig()` in un confine di processo esplicito.
|
||||
|
||||
I percorsi di esecuzione di provider e canali devono usare lo snapshot della configurazione runtime attiva, non uno snapshot del file restituito per rilettura o modifica della configurazione. Gli snapshot dei file preservano i valori sorgente, come i marcatori SecretRef, per l'interfaccia utente e le scritture; i callback dei provider richiedono la vista runtime risolta. Quando una funzione di supporto può essere chiamata con lo snapshot sorgente attivo oppure con lo snapshot runtime attivo, passa da `selectApplicableRuntimeConfig()` prima di leggere le credenziali.
|
||||
I percorsi di esecuzione di provider e canali devono usare l'istantanea della configurazione runtime attiva, non un'istantanea del file restituita per rilettura o modifica della configurazione. Le istantanee dei file preservano i valori di origine, come i marker SecretRef, per UI e scritture; i callback dei provider hanno bisogno della vista runtime risolta. Quando un helper può essere chiamato con l'istantanea di origine attiva oppure con l'istantanea runtime attiva, passa da `selectApplicableRuntimeConfig()` prima di leggere le credenziali.
|
||||
|
||||
## Namespace runtime
|
||||
|
||||
@ -105,15 +106,15 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
});
|
||||
```
|
||||
|
||||
`runEmbeddedAgent(...)` è la funzione di supporto neutra per avviare un normale turno di agente OpenClaw dal codice di un Plugin. Usa la stessa risoluzione provider/modello e la stessa selezione dell'harness dell'agente delle risposte attivate da canale.
|
||||
`runEmbeddedAgent(...)` è l'helper neutrale per avviare un normale turno dell'agente OpenClaw dal codice di un Plugin. Usa la stessa risoluzione provider/modello e la stessa selezione dell'harness dell'agente delle risposte attivate da canale.
|
||||
|
||||
`runEmbeddedPiAgent(...)` resta come alias di compatibilità.
|
||||
|
||||
`resolveThinkingPolicy(...)` restituisce i livelli di ragionamento supportati dal provider/modello e l'eventuale valore predefinito. I Plugin provider possiedono il profilo specifico del modello tramite i propri hook di ragionamento, quindi i Plugin di tool dovrebbero chiamare questa funzione runtime invece di importare o duplicare elenchi di provider.
|
||||
`resolveThinkingPolicy(...)` restituisce i livelli di ragionamento supportati dal provider/modello e il default opzionale. I Plugin provider possiedono il profilo specifico del modello tramite i loro hook di ragionamento, quindi i Plugin di strumenti dovrebbero chiamare questo helper runtime invece di importare o duplicare liste di provider.
|
||||
|
||||
`normalizeThinkingLevel(...)` converte testo utente come `on`, `x-high` o `extra high` nel livello canonico memorizzato prima di confrontarlo con la policy risolta.
|
||||
`normalizeThinkingLevel(...)` converte testo utente come `on`, `x-high` o `extra high` nel livello canonico memorizzato prima di verificarlo rispetto alla policy risolta.
|
||||
|
||||
Le **funzioni di supporto per l'archivio sessioni** sono sotto `api.runtime.agent.session`:
|
||||
**Gli helper dello store delle sessioni** sono sotto `api.runtime.agent.session`:
|
||||
|
||||
```typescript
|
||||
const storePath = api.runtime.agent.session.resolveStorePath(cfg);
|
||||
@ -125,11 +126,11 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId);
|
||||
```
|
||||
|
||||
Preferisci `updateSessionStore(...)` o `updateSessionStoreEntry(...)` per le scritture runtime. Passano dallo scrittore dell'archivio sessioni di proprietà del Gateway, preservano gli aggiornamenti concorrenti e riutilizzano la cache a caldo. `saveSessionStore(...)` resta disponibile per compatibilità e riscritture in stile manutenzione offline.
|
||||
Preferisci `updateSessionStore(...)` o `updateSessionStoreEntry(...)` per le scritture runtime. Passano attraverso il writer dello store delle sessioni posseduto dal Gateway, preservano gli aggiornamenti concorrenti e riutilizzano la cache a caldo. `saveSessionStore(...)` resta disponibile per compatibilità e riscritture offline in stile manutenzione.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.agent.defaults">
|
||||
Costanti predefinite di modello e provider:
|
||||
Modello e costanti del provider predefiniti:
|
||||
|
||||
```typescript
|
||||
const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6"
|
||||
@ -169,11 +170,11 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
Gli override del modello (`provider`/`model`) richiedono l'opt-in dell'operatore tramite `plugins.entries.<id>.subagent.allowModelOverride: true` nella configurazione. I Plugin non attendibili possono comunque eseguire subagenti, ma le richieste di override vengono rifiutate.
|
||||
</Warning>
|
||||
|
||||
`deleteSession(...)` può eliminare sessioni create dallo stesso Plugin tramite `api.runtime.subagent.run(...)`. L'eliminazione di sessioni utente o operatore arbitrarie richiede comunque una richiesta Gateway con ambito admin.
|
||||
`deleteSession(...)` può eliminare le sessioni create dallo stesso Plugin tramite `api.runtime.subagent.run(...)`. L'eliminazione di sessioni arbitrarie di utenti o operatori richiede comunque una richiesta Gateway con scope admin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.nodes">
|
||||
Elenca i nodi connessi e invoca un comando ospitato da un nodo dal codice di Plugin caricato dal Gateway o dai comandi CLI del Plugin. Usalo quando un Plugin possiede lavoro locale su un dispositivo associato, per esempio un bridge browser o audio su un altro Mac.
|
||||
Elenca i nodi connessi e invoca un comando ospitato su nodo dal codice del Plugin caricato dal Gateway o dai comandi CLI del Plugin. Usalo quando un Plugin possiede lavoro locale su un dispositivo associato, per esempio un bridge browser o audio su un altro Mac.
|
||||
|
||||
```typescript
|
||||
const { nodes } = await api.runtime.nodes.list({ connected: true });
|
||||
@ -186,13 +187,13 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
});
|
||||
```
|
||||
|
||||
Dentro il Gateway questo runtime è in-process. Nei comandi CLI dei Plugin chiama il Gateway configurato tramite RPC, quindi comandi come `openclaw googlemeet recover-tab` possono ispezionare i nodi associati dal terminale. I comandi Node passano comunque dal normale pairing dei nodi del Gateway, dalle allowlist dei comandi, dalle policy node-invoke dei Plugin e dalla gestione dei comandi locale al nodo.
|
||||
Dentro il Gateway questo runtime è in-process. Nei comandi CLI del Plugin chiama il Gateway configurato tramite RPC, quindi comandi come `openclaw googlemeet recover-tab` possono ispezionare i nodi associati dal terminale. I comandi Node passano comunque attraverso la normale associazione dei nodi del Gateway, gli allowlist dei comandi, le policy node-invoke dei Plugin e la gestione dei comandi locale al nodo.
|
||||
|
||||
I Plugin che espongono comandi ospitati da nodo pericolosi dovrebbero registrare una policy node-invoke con `api.registerNodeInvokePolicy(...)`. La policy viene eseguita nel Gateway dopo i controlli della allowlist dei comandi e prima che il comando sia inoltrato al nodo, quindi le chiamate dirette `node.invoke` e i tool dei Plugin di livello superiore condividono lo stesso percorso di applicazione.
|
||||
I Plugin che espongono comandi per host nodo pericolosi dovrebbero registrare una policy node-invoke con `api.registerNodeInvokePolicy(...)`. La policy viene eseguita nel Gateway dopo i controlli dell'allowlist dei comandi e prima che il comando venga inoltrato al nodo, quindi le chiamate dirette `node.invoke` e gli strumenti Plugin di livello superiore condividono lo stesso percorso di applicazione.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.tasks.managedFlows">
|
||||
Associa un runtime Task Flow a una chiave di sessione OpenClaw esistente o a un contesto tool attendibile, quindi crea e gestisci Task Flow senza passare un proprietario a ogni chiamata.
|
||||
Associa un runtime Task Flow a una chiave di sessione OpenClaw esistente o a un contesto strumento attendibile, quindi crea e gestisci Task Flow senza passare un owner a ogni chiamata.
|
||||
|
||||
```typescript
|
||||
const taskFlow = api.runtime.tasks.managedFlows.fromToolContext(ctx);
|
||||
@ -219,11 +220,11 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
});
|
||||
```
|
||||
|
||||
Usa `bindSession({ sessionKey, requesterOrigin })` quando hai già una chiave di sessione OpenClaw attendibile dal tuo livello di binding. Non associare da input utente grezzo.
|
||||
Usa `bindSession({ sessionKey, requesterOrigin })` quando hai già una chiave di sessione OpenClaw attendibile dal tuo livello di binding. Non eseguire il binding da input utente grezzo.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.tts">
|
||||
Sintesi vocale.
|
||||
Sintesi text-to-speech.
|
||||
|
||||
```typescript
|
||||
// Standard TTS
|
||||
@ -279,7 +280,7 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
});
|
||||
```
|
||||
|
||||
Restituisce `{ text: undefined }` quando non viene prodotto alcun output (ad esempio input ignorato).
|
||||
Restituisce `{ text: undefined }` quando non viene prodotto alcun output (ad es. input ignorato).
|
||||
|
||||
<Info>
|
||||
`api.runtime.stt.transcribeAudioFile(...)` rimane un alias di compatibilità per `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`.
|
||||
@ -313,7 +314,7 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.media">
|
||||
Utilità multimediali di basso livello.
|
||||
Utility multimediali di basso livello.
|
||||
|
||||
```typescript
|
||||
const webMedia = await api.runtime.media.loadWebMedia(url);
|
||||
@ -338,9 +339,9 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.config">
|
||||
Snapshot della configurazione runtime corrente e scritture transazionali della configurazione. Preferisci
|
||||
la configurazione che è già stata passata al percorso di chiamata attivo; usa
|
||||
`current()` solo quando l'handler ha bisogno direttamente dello snapshot del processo.
|
||||
Snapshot della configurazione di runtime corrente e scritture transazionali della configurazione. Preferisci
|
||||
la configurazione già passata nel percorso di chiamata attivo; usa
|
||||
`current()` solo quando il gestore necessita direttamente dello snapshot del processo.
|
||||
|
||||
```typescript
|
||||
const cfg = api.runtime.config.current();
|
||||
@ -352,14 +353,14 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
});
|
||||
```
|
||||
|
||||
`mutateConfigFile(...)` e `replaceConfigFile(...)` restituiscono un valore `followUp`,
|
||||
ad esempio `{ mode: "restart", requiresRestart: true, reason }`,
|
||||
che registra l'intento dello scrittore senza sottrarre al
|
||||
Gateway il controllo del riavvio.
|
||||
`mutateConfigFile(...)` e `replaceConfigFile(...)` restituiscono un valore
|
||||
`followUp`, ad esempio `{ mode: "restart", requiresRestart: true, reason }`,
|
||||
che registra l'intento di scrittura senza sottrarre al
|
||||
gateway il controllo del riavvio.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.system">
|
||||
Utilità a livello di sistema.
|
||||
Utility a livello di sistema.
|
||||
|
||||
```typescript
|
||||
await api.runtime.system.enqueueSystemEvent(event);
|
||||
@ -397,7 +398,7 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.modelAuth">
|
||||
Risoluzione dell'autenticazione per modello e provider.
|
||||
Risoluzione dell'autenticazione per modelli e provider.
|
||||
|
||||
```typescript
|
||||
const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
|
||||
@ -409,7 +410,7 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.state">
|
||||
Risoluzione della directory di stato e archiviazione chiave-valore basata su SQLite.
|
||||
Risoluzione della directory di stato e archiviazione con chiavi basata su SQLite.
|
||||
|
||||
```typescript
|
||||
const stateDir = api.runtime.state.resolveStateDir(process.env);
|
||||
@ -420,15 +421,16 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
});
|
||||
|
||||
await store.register("key-1", { value: "hello" });
|
||||
const claimed = await store.registerIfAbsent("dedupe-key", { value: "first" });
|
||||
const value = await store.lookup("key-1");
|
||||
await store.consume("key-1");
|
||||
await store.clear();
|
||||
```
|
||||
|
||||
Gli archivi chiave-valore sopravvivono ai riavvii e sono isolati dall'id del Plugin vincolato al runtime. Limiti: `maxEntries` per namespace, 1.000 righe live per Plugin, valori JSON inferiori a 64 KB e scadenza TTL opzionale.
|
||||
Gli store con chiavi sopravvivono ai riavvii e sono isolati dall'id del plugin associato al runtime. Usa `registerIfAbsent(...)` per rivendicazioni atomiche di deduplicazione: restituisce `true` quando la chiave era mancante o scaduta ed è stata registrata, oppure `false` quando esiste già un valore attivo senza sovrascriverne valore, ora di creazione o TTL. Limiti: `maxEntries` per namespace, 1.000 righe attive per plugin, valori JSON inferiori a 64 KB e scadenza TTL opzionale.
|
||||
|
||||
<Warning>
|
||||
Solo Plugin in bundle in questa release.
|
||||
Solo plugin inclusi in questa release.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
@ -443,9 +445,9 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.channel">
|
||||
Helper runtime specifici del canale (disponibili quando viene caricato un Plugin di canale).
|
||||
Helper di runtime specifici del canale (disponibili quando è caricato un plugin di canale).
|
||||
|
||||
`api.runtime.channel.mentions` è la superficie condivisa delle policy di menzione in ingresso per i Plugin di canale in bundle che usano l'iniezione runtime:
|
||||
`api.runtime.channel.mentions` è la superficie condivisa per i criteri di menzione in ingresso per i plugin di canale inclusi che usano l'iniezione runtime:
|
||||
|
||||
```typescript
|
||||
const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
|
||||
@ -480,7 +482,7 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
`api.runtime.channel.mentions` intenzionalmente non espone i vecchi helper di compatibilità `resolveMentionGating*`. Preferisci il percorso normalizzato `{ facts, policy }`.
|
||||
`api.runtime.channel.mentions` non espone intenzionalmente gli helper di compatibilità `resolveMentionGating*` precedenti. Preferisci il percorso normalizzato `{ facts, policy }`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -490,7 +492,7 @@ I percorsi di esecuzione di provider e canali devono usare lo snapshot della con
|
||||
Usa `createPluginRuntimeStore` per archiviare il riferimento runtime da usare al di fuori della callback `register`:
|
||||
|
||||
<Steps>
|
||||
<Step title="Crea l'archivio">
|
||||
<Step title="Crea lo store">
|
||||
```typescript
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
|
||||
@ -502,7 +504,7 @@ Usa `createPluginRuntimeStore` per archiviare il riferimento runtime da usare al
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="Collega al punto di ingresso">
|
||||
<Step title="Collega all'entry point">
|
||||
```typescript
|
||||
export default defineChannelPluginEntry({
|
||||
id: "my-plugin",
|
||||
@ -528,7 +530,7 @@ Usa `createPluginRuntimeStore` per archiviare il riferimento runtime da usare al
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Preferisci `pluginId` per l'identità del runtime-store. La forma di livello inferiore `key` è per casi non comuni in cui un Plugin ha intenzionalmente bisogno di più di uno slot runtime.
|
||||
Preferisci `pluginId` per l'identità dello store runtime. La forma `key` di livello inferiore è per casi non comuni in cui un plugin necessita intenzionalmente di più di uno slot runtime.
|
||||
</Note>
|
||||
|
||||
## Altri campi `api` di primo livello
|
||||
@ -536,29 +538,29 @@ Preferisci `pluginId` per l'identità del runtime-store. La forma di livello inf
|
||||
Oltre a `api.runtime`, l'oggetto API fornisce anche:
|
||||
|
||||
<ParamField path="api.id" type="string">
|
||||
Id del Plugin.
|
||||
Id del plugin.
|
||||
</ParamField>
|
||||
<ParamField path="api.name" type="string">
|
||||
Nome visualizzato del Plugin.
|
||||
Nome visualizzato del plugin.
|
||||
</ParamField>
|
||||
<ParamField path="api.config" type="OpenClawConfig">
|
||||
Snapshot della configurazione corrente (snapshot runtime attivo in memoria, quando disponibile).
|
||||
Snapshot della configurazione corrente (snapshot runtime in memoria attivo quando disponibile).
|
||||
</ParamField>
|
||||
<ParamField path="api.pluginConfig" type="Record<string, unknown>">
|
||||
Configurazione specifica del Plugin da `plugins.entries.<id>.config`.
|
||||
Configurazione specifica del plugin da `plugins.entries.<id>.config`.
|
||||
</ParamField>
|
||||
<ParamField path="api.logger" type="PluginLogger">
|
||||
Logger con ambito (`debug`, `info`, `warn`, `error`).
|
||||
</ParamField>
|
||||
<ParamField path="api.registrationMode" type="PluginRegistrationMode">
|
||||
Modalità di caricamento corrente; `"setup-runtime"` è la finestra leggera di avvio/configurazione precedente all'entry completa.
|
||||
Modalità di caricamento corrente; `"setup-runtime"` è la finestra leggera di avvio/configurazione precedente all'entry point completo.
|
||||
</ParamField>
|
||||
<ParamField path="api.resolvePath(input)" type="(string) => string">
|
||||
Risolve un percorso relativo alla radice del Plugin.
|
||||
Risolve un percorso relativo alla radice del plugin.
|
||||
</ParamField>
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Interni dei Plugin](/it/plugins/architecture) — modello di capacità e registry
|
||||
- [Punti di ingresso SDK](/it/plugins/sdk-entrypoints) — opzioni di `definePluginEntry`
|
||||
- [Panoramica SDK](/it/plugins/sdk-overview) — riferimento dei sottopercorsi
|
||||
- [Interni dei plugin](/it/plugins/architecture) — modello di capacità e registro
|
||||
- [Entry point SDK](/it/plugins/sdk-entrypoints) — opzioni di `definePluginEntry`
|
||||
- [Panoramica SDK](/it/plugins/sdk-overview) — riferimento ai sottopercorsi
|
||||
|
||||
@ -3,18 +3,18 @@ read_when:
|
||||
- Vuoi gestire il Gateway da un browser
|
||||
- Vuoi accedere alla Tailnet senza tunnel SSH
|
||||
sidebarTitle: Control UI
|
||||
summary: Interfaccia di controllo basata su browser per il Gateway (chat, nodi, configurazione)
|
||||
title: Interfaccia utente di controllo
|
||||
summary: Interfaccia utente di controllo basata su browser per il Gateway (chat, nodi, configurazione)
|
||||
title: Interfaccia di controllo
|
||||
x-i18n:
|
||||
generated_at: "2026-05-04T07:09:58Z"
|
||||
generated_at: "2026-05-04T08:39:49Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 07fbbe1c7fec5f67a04a231e02bdf0f7d16be9c5fe188915674d71fcd69002a5
|
||||
source_hash: 896c75116d7a396571017ac6e6db7ff6ce328617e44470c303fd41af58aa2bd7
|
||||
source_path: web/control-ui.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
L'UI di controllo è una piccola app single-page **Vite + Lit** servita dal Gateway:
|
||||
La UI di controllo è una piccola app a pagina singola **Vite + Lit** servita dal Gateway:
|
||||
|
||||
- predefinito: `http://<host>:18789/`
|
||||
- prefisso opzionale: imposta `gateway.controlUi.basePath` (ad es. `/openclaw`)
|
||||
@ -25,7 +25,7 @@ Comunica **direttamente con il WebSocket del Gateway** sulla stessa porta.
|
||||
|
||||
Se il Gateway è in esecuzione sullo stesso computer, apri:
|
||||
|
||||
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (o [http://localhost:18789/](http://localhost:18789/))
|
||||
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (oppure [http://localhost:18789/](http://localhost:18789/))
|
||||
|
||||
Se la pagina non si carica, avvia prima il Gateway: `openclaw gateway`.
|
||||
|
||||
@ -33,120 +33,121 @@ L'autenticazione viene fornita durante l'handshake WebSocket tramite:
|
||||
|
||||
- `connect.params.auth.token`
|
||||
- `connect.params.auth.password`
|
||||
- header di identità di Tailscale Serve quando `gateway.auth.allowTailscale: true`
|
||||
- header di identità trusted-proxy quando `gateway.auth.mode: "trusted-proxy"`
|
||||
- header di identità Tailscale Serve quando `gateway.auth.allowTailscale: true`
|
||||
- header di identità di proxy attendibile quando `gateway.auth.mode: "trusted-proxy"`
|
||||
|
||||
Il pannello delle impostazioni della dashboard conserva un token per la sessione della scheda del browser corrente e l'URL del gateway selezionato; le password non vengono mantenute. L'onboarding di solito genera un token gateway per l'autenticazione a segreto condiviso alla prima connessione, ma anche l'autenticazione tramite password funziona quando `gateway.auth.mode` è `"password"`.
|
||||
Il pannello delle impostazioni della dashboard conserva un token per la sessione della scheda corrente del browser e per l'URL del gateway selezionato; le password non vengono mantenute. L'onboarding di solito genera un token del gateway per l'autenticazione a segreto condiviso alla prima connessione, ma anche l'autenticazione con password funziona quando `gateway.auth.mode` è `"password"`.
|
||||
|
||||
## Associazione del dispositivo (prima connessione)
|
||||
## Abbinamento del dispositivo (prima connessione)
|
||||
|
||||
Quando ti connetti all'UI di controllo da un nuovo browser o dispositivo, il Gateway di solito richiede una **approvazione di associazione una tantum**. È una misura di sicurezza per impedire accessi non autorizzati.
|
||||
Quando ti connetti alla UI di controllo da un nuovo browser o dispositivo, il Gateway di solito richiede una **approvazione di abbinamento una tantum**. È una misura di sicurezza per impedire accessi non autorizzati.
|
||||
|
||||
**Cosa vedrai:** "disconnesso (1008): associazione richiesta"
|
||||
**Cosa vedrai:** "disconnesso (1008): abbinamento richiesto"
|
||||
|
||||
<Steps>
|
||||
<Step title="Elenca le richieste in sospeso">
|
||||
<Step title="List pending requests">
|
||||
```bash
|
||||
openclaw devices list
|
||||
```
|
||||
</Step>
|
||||
<Step title="Approva tramite ID richiesta">
|
||||
<Step title="Approve by request ID">
|
||||
```bash
|
||||
openclaw devices approve <requestId>
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Se il browser ritenta l'associazione con dettagli di autenticazione modificati (ruolo/ambiti/chiave pubblica), la richiesta in sospeso precedente viene sostituita e viene creato un nuovo `requestId`. Riesegui `openclaw devices list` prima dell'approvazione.
|
||||
Se il browser riprova l'abbinamento con dettagli di autenticazione modificati (ruolo/ambiti/chiave pubblica), la richiesta in sospeso precedente viene sostituita e viene creato un nuovo `requestId`. Esegui di nuovo `openclaw devices list` prima dell'approvazione.
|
||||
|
||||
Se il browser è già associato e lo modifichi dall'accesso in lettura all'accesso in scrittura/admin, questo viene trattato come un aggiornamento dell'approvazione, non come una riconnessione silenziosa. OpenClaw mantiene attiva la vecchia approvazione, blocca la riconnessione più ampia e ti chiede di approvare esplicitamente il nuovo insieme di ambiti.
|
||||
Se il browser è già abbinato e lo modifichi da accesso in lettura ad accesso in scrittura/admin, questa operazione viene trattata come un upgrade dell'approvazione, non come una riconnessione silenziosa. OpenClaw mantiene attiva la vecchia approvazione, blocca la riconnessione con permessi più ampi e ti chiede di approvare esplicitamente il nuovo insieme di ambiti.
|
||||
|
||||
Una volta approvato, il dispositivo viene ricordato e non richiederà una nuova approvazione a meno che tu non lo revochi con `openclaw devices revoke --device <id> --role <role>`. Vedi [CLI dispositivi](/it/cli/devices) per la rotazione e la revoca dei token.
|
||||
Una volta approvato, il dispositivo viene ricordato e non richiederà una nuova approvazione a meno che tu non lo revochi con `openclaw devices revoke --device <id> --role <role>`. Consulta [CLI dispositivi](/it/cli/devices) per rotazione e revoca dei token.
|
||||
|
||||
<Note>
|
||||
- Le connessioni dirette del browser tramite local loopback (`127.0.0.1` / `localhost`) sono approvate automaticamente.
|
||||
- Tailscale Serve può saltare il round trip di associazione per le sessioni operatore dell'UI di controllo quando `gateway.auth.allowTailscale: true`, l'identità Tailscale viene verificata e il browser presenta la propria identità del dispositivo.
|
||||
- Bind Tailnet diretti, connessioni browser LAN e profili browser senza identità del dispositivo richiedono comunque l'approvazione esplicita.
|
||||
- Ogni profilo browser genera un ID dispositivo univoco, quindi cambiare browser o cancellare i dati del browser richiederà una nuova associazione.
|
||||
- Le connessioni dirette del browser tramite local loopback (`127.0.0.1` / `localhost`) vengono approvate automaticamente.
|
||||
- Tailscale Serve può saltare il viaggio di andata e ritorno dell'abbinamento per le sessioni operatore della UI di controllo quando `gateway.auth.allowTailscale: true`, l'identità Tailscale viene verificata e il browser presenta la propria identità dispositivo.
|
||||
- Bind diretti Tailnet, connessioni browser LAN e profili browser senza identità dispositivo richiedono comunque approvazione esplicita.
|
||||
- Ogni profilo browser genera un ID dispositivo univoco, quindi cambiare browser o cancellare i dati del browser richiederà un nuovo abbinamento.
|
||||
|
||||
</Note>
|
||||
|
||||
## Identità personale (locale al browser)
|
||||
|
||||
L'UI di controllo supporta un'identità personale per browser (nome visualizzato e avatar) allegata ai messaggi in uscita per l'attribuzione nelle sessioni condivise. Risiede nello storage del browser, è limitata al profilo browser corrente e non viene sincronizzata con altri dispositivi né mantenuta lato server oltre ai normali metadati di autorialità della trascrizione sui messaggi che invii effettivamente. Cancellare i dati del sito o cambiare browser la reimposta a vuota.
|
||||
La UI di controllo supporta un'identità personale per browser (nome visualizzato e avatar) allegata ai messaggi in uscita per l'attribuzione nelle sessioni condivise. Risiede nell'archiviazione del browser, è limitata al profilo browser corrente e non viene sincronizzata su altri dispositivi né mantenuta lato server oltre ai normali metadati di paternità della trascrizione sui messaggi che invii effettivamente. Cancellare i dati del sito o cambiare browser la reimposta a vuota.
|
||||
|
||||
Lo stesso modello locale al browser si applica all'override dell'avatar dell'assistente. Gli avatar dell'assistente caricati sovrappongono l'identità risolta dal gateway solo nel browser locale e non fanno mai round-trip tramite `config.patch`. Il campo di configurazione condiviso `ui.assistant.avatar` resta disponibile per i client non UI che scrivono direttamente il campo (come gateway scriptati o dashboard personalizzate).
|
||||
Lo stesso modello locale al browser si applica all'override dell'avatar dell'assistente. Gli avatar dell'assistente caricati si sovrappongono all'identità risolta dal gateway solo nel browser locale e non fanno mai un viaggio di andata e ritorno tramite `config.patch`. Il campo di configurazione condiviso `ui.assistant.avatar` resta disponibile per i client non UI che scrivono direttamente il campo (come gateway con script o dashboard personalizzate).
|
||||
|
||||
## Endpoint di configurazione runtime
|
||||
|
||||
L'UI di controllo recupera le impostazioni runtime da `/__openclaw/control-ui-config.json`. Questo endpoint è protetto dalla stessa autenticazione del gateway del resto della superficie HTTP: i browser non autenticati non possono recuperarlo, e un recupero riuscito richiede un token/password gateway già valido, l'identità Tailscale Serve o un'identità trusted-proxy.
|
||||
La UI di controllo recupera le proprie impostazioni runtime da `/__openclaw/control-ui-config.json`. Quell'endpoint è protetto dalla stessa autenticazione del gateway del resto della superficie HTTP: i browser non autenticati non possono recuperarlo, e un recupero riuscito richiede un token/password del gateway già valido, un'identità Tailscale Serve o un'identità di proxy attendibile.
|
||||
|
||||
## Supporto lingue
|
||||
## Supporto linguistico
|
||||
|
||||
L'UI di controllo può localizzarsi al primo caricamento in base alla locale del tuo browser. Per sovrascriverla in seguito, apri **Panoramica -> Accesso Gateway -> Lingua**. Il selettore della locale si trova nella scheda Accesso Gateway, non sotto Aspetto.
|
||||
La UI di controllo può localizzarsi al primo caricamento in base alla lingua del browser. Per modificarla in seguito, apri **Panoramica -> Accesso Gateway -> Lingua**. Il selettore della lingua si trova nella scheda Accesso Gateway, non sotto Aspetto.
|
||||
|
||||
- Locale supportate: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
|
||||
- Le traduzioni non inglesi vengono caricate in modo lazy nel browser.
|
||||
- La locale selezionata viene salvata nello storage del browser e riutilizzata nelle visite future.
|
||||
- Le chiavi di traduzione mancanti ripiegano sull'inglese.
|
||||
- Lingue supportate: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
|
||||
- Le traduzioni diverse dall'inglese vengono caricate in modo lazy nel browser.
|
||||
- La lingua selezionata viene salvata nell'archiviazione del browser e riutilizzata nelle visite future.
|
||||
- Le chiavi di traduzione mancanti ricadono sull'inglese.
|
||||
|
||||
Le traduzioni della documentazione vengono generate per lo stesso insieme di locale non inglesi, ma il selettore lingua integrato del sito di documentazione Mintlify è limitato ai codici locale accettati da Mintlify. La documentazione in thailandese (`th`) e persiano (`fa`) viene comunque generata nel repository di pubblicazione; potrebbe non comparire in quel selettore finché Mintlify non supporterà quei codici.
|
||||
Le traduzioni della documentazione vengono generate per lo stesso insieme di lingue non inglesi, ma il selettore lingua integrato del sito di documentazione Mintlify è limitato ai codici lingua accettati da Mintlify. La documentazione in thailandese (`th`) e persiano (`fa`) viene comunque generata nel repo di pubblicazione; potrebbe non comparire in quel selettore finché Mintlify non supporterà quei codici.
|
||||
|
||||
## Temi di aspetto
|
||||
|
||||
Il pannello Aspetto mantiene i temi integrati Claw, Knot e Dash, più uno slot di importazione tweakcn locale al browser. Per importare un tema, apri [editor tweakcn](https://tweakcn.com/editor/theme), scegli o crea un tema, fai clic su **Condividi** e incolla il link del tema copiato in Aspetto. L'importatore accetta anche URL di registro `https://tweakcn.com/r/themes/<id>`, URL dell'editor come `https://tweakcn.com/editor/theme?theme=amethyst-haze`, percorsi relativi `/themes/<id>`, ID tema grezzi e nomi di temi predefiniti come `amethyst-haze`.
|
||||
|
||||
I temi importati vengono archiviati solo nel profilo browser corrente. Non vengono scritti nella configurazione del gateway e non si sincronizzano tra dispositivi. Sostituire il tema importato aggiorna l'unico slot locale; cancellarlo riporta il tema attivo a Claw se il tema importato era selezionato.
|
||||
I temi importati vengono memorizzati solo nel profilo browser corrente. Non vengono scritti nella configurazione del gateway e non si sincronizzano tra dispositivi. Sostituire il tema importato aggiorna l'unico slot locale; cancellarlo riporta il tema attivo a Claw se il tema importato era selezionato.
|
||||
|
||||
## Cosa può fare (oggi)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Chat e conversazione vocale">
|
||||
<Accordion title="Chat and Talk">
|
||||
- Chatta con il modello tramite Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
|
||||
- Parla tramite sessioni realtime del browser. OpenAI usa WebRTC diretto, Google Live usa un token browser monouso vincolato su WebSocket, e i plugin voce realtime solo backend usano il trasporto relay del Gateway. Il relay mantiene le credenziali provider sul Gateway mentre il browser trasmette PCM del microfono tramite RPC `talk.realtime.relay*` e invia chiamate tool `openclaw_agent_consult` tramite `chat.send` al modello OpenClaw configurato più grande.
|
||||
- Riproduci in streaming chiamate tool + schede di output tool live in Chat (eventi agente).
|
||||
- Parla tramite sessioni realtime nel browser. OpenAI usa WebRTC diretto, Google Live usa un token browser monouso vincolato su WebSocket, e i Plugin vocali realtime solo backend usano il trasporto relay del Gateway. Il relay mantiene le credenziali del provider sul Gateway mentre il browser trasmette PCM del microfono tramite RPC `talk.realtime.relay*` e invia chiamate tool `openclaw_agent_consult` tramite `chat.send` al modello OpenClaw configurato più grande.
|
||||
- Trasmetti in streaming chiamate tool + schede di output tool live in Chat (eventi agente).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Canali, istanze, sessioni, sogni">
|
||||
- Canali: stato dei canali integrati più quelli dei plugin inclusi/esterni, login QR e configurazione per canale (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Istanze: elenco presenze + aggiornamento (`system-presence`).
|
||||
<Accordion title="Channels, instances, sessions, dreams">
|
||||
- Canali: stato dei canali integrati più canali Plugin in bundle/esterni, accesso QR e configurazione per canale (`channels.status`, `web.login.*`, `config.patch`).
|
||||
- Istanze: elenco presenza + aggiornamento (`system-presence`).
|
||||
- Sessioni: elenco + override per sessione di modello/thinking/fast/verbose/trace/reasoning (`sessions.list`, `sessions.patch`).
|
||||
- Sogni: stato di dreaming, interruttore abilita/disabilita e lettore Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
- Dreams: stato dreaming, toggle abilita/disabilita e lettore Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Cron, Skills, nodi, approvazioni exec">
|
||||
<Accordion title="Cron, skills, nodes, exec approvals">
|
||||
- Job Cron: elenco/aggiunta/modifica/esecuzione/abilitazione/disabilitazione + cronologia esecuzioni (`cron.*`).
|
||||
- Skills: stato, abilita/disabilita, installazione, aggiornamenti chiave API (`skills.*`).
|
||||
- Nodi: elenco + capacità (`node.list`).
|
||||
- Approvazioni exec: modifica allowlist gateway o nodo + criterio di richiesta per `exec host=gateway/node` (`exec.approvals.*`).
|
||||
- Node: elenco + capacità (`node.list`).
|
||||
- Approvazioni exec: modifica allowlist gateway o Node + criterio di richiesta per `exec host=gateway/node` (`exec.approvals.*`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Configurazione">
|
||||
<Accordion title="Config">
|
||||
- Visualizza/modifica `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
|
||||
- Applica + riavvia con validazione (`config.apply`) e risveglia l'ultima sessione attiva.
|
||||
- Le scritture includono una protezione base-hash per evitare di sovrascrivere modifiche concorrenti.
|
||||
- Le scritture (`config.set`/`config.apply`/`config.patch`) eseguono un preflight della risoluzione SecretRef attiva per i riferimenti nel payload di configurazione inviato; i riferimenti inviati attivi non risolti vengono rifiutati prima della scrittura.
|
||||
- Rendering di schema + modulo (`config.schema` / `config.schema.lookup`, inclusi `title` / `description` del campo, suggerimenti UI corrispondenti, riepiloghi dei figli immediati, metadati docs su nodi oggetto annidato/wildcard/array/composizione, più schemi plugin + canale quando disponibili); l'editor JSON grezzo è disponibile solo quando lo snapshot ha un round-trip grezzo sicuro.
|
||||
- Se uno snapshot non può eseguire in sicurezza il round-trip del testo grezzo, l'UI di controllo forza la modalità Modulo e disabilita la modalità Grezza per quello snapshot.
|
||||
- Nell'editor JSON grezzo, "Reimposta a salvato" conserva la forma creata in modalità grezza (formattazione, commenti, layout `$include`) invece di rieseguire il rendering di uno snapshot appiattito, così le modifiche esterne sopravvivono a un reset quando lo snapshot può eseguire in sicurezza il round-trip.
|
||||
- I valori oggetto SecretRef strutturati vengono visualizzati in sola lettura negli input di testo del modulo per impedire la corruzione accidentale da oggetto a stringa.
|
||||
- Le scritture includono una protezione base-hash per impedire di sovrascrivere modifiche concorrenti.
|
||||
- Le scritture (`config.set`/`config.apply`/`config.patch`) eseguono un preflight della risoluzione SecretRef attiva per i riferimenti nel payload di configurazione inviato; i riferimenti attivi inviati non risolti vengono rifiutati prima della scrittura.
|
||||
- Rendering schema + modulo (`config.schema` / `config.schema.lookup`, inclusi `title` / `description` del campo, suggerimenti UI corrispondenti, riepiloghi immediati dei figli, metadati documentazione su nodi oggetto/wildcard/array/composizione annidati, più schemi Plugin + canali quando disponibili); l'editor JSON grezzo è disponibile solo quando lo snapshot consente un round-trip grezzo sicuro.
|
||||
- Se uno snapshot non può eseguire in sicurezza il round-trip del testo grezzo, la UI di controllo forza la modalità Modulo e disabilita la modalità Grezza per quello snapshot.
|
||||
- "Ripristina al salvato" dell'editor JSON grezzo conserva la forma scritta in grezzo (formattazione, commenti, layout `$include`) invece di rigenerare uno snapshot appiattito, così le modifiche esterne sopravvivono a un ripristino quando lo snapshot può eseguire in sicurezza il round-trip.
|
||||
- I valori oggetto SecretRef strutturati vengono renderizzati in sola lettura negli input di testo del modulo per impedire la corruzione accidentale da oggetto a stringa.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Debug, log, aggiornamento">
|
||||
- Debug: snapshot di stato/salute/modelli + log eventi + chiamate RPC manuali (`status`, `health`, `models.list`).
|
||||
<Accordion title="Debug, logs, update">
|
||||
- Debug: snapshot di stato/salute/modelli + registro eventi + chiamate RPC manuali (`status`, `health`, `models.list`).
|
||||
- Il registro eventi include tempi di aggiornamento/RPC della UI di controllo più voci di reattività del browser per frame di animazione lunghi o attività lunghe quando il browser espone quei tipi di entry PerformanceObserver.
|
||||
- Log: tail live dei log file del gateway con filtro/esportazione (`logs.tail`).
|
||||
- Aggiornamento: esegui un aggiornamento package/git + riavvio (`update.run`) con un report di riavvio, poi esegui il polling di `update.status` dopo la riconnessione per verificare la versione del gateway in esecuzione.
|
||||
- Aggiornamento: esegui un aggiornamento pacchetto/git + riavvio (`update.run`) con report di riavvio, poi esegui il polling di `update.status` dopo la riconnessione per verificare la versione del gateway in esecuzione.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Note del pannello job Cron">
|
||||
- Per i job isolati, la consegna predefinita è l'annuncio del riepilogo. Puoi passare a nessuna se vuoi esecuzioni solo interne.
|
||||
- I campi canale/target compaiono quando è selezionato annuncia.
|
||||
- La modalità Webhook usa `delivery.mode = "webhook"` con `delivery.to` impostato a un URL webhook HTTP(S) valido.
|
||||
- Per i job della sessione principale, sono disponibili le modalità di consegna webhook e nessuna.
|
||||
- I controlli di modifica avanzati includono elimina-dopo-esecuzione, cancella override agente, opzioni cron esatto/scaglionato, override di modello/thinking agente e interruttori di consegna best-effort.
|
||||
- La validazione del modulo è inline con errori a livello di campo; i valori non validi disabilitano il pulsante di salvataggio finché non vengono corretti.
|
||||
<Accordion title="Cron jobs panel notes">
|
||||
- Per job isolati, la consegna predefinita annuncia il riepilogo. Puoi passare a nessuna se vuoi esecuzioni solo interne.
|
||||
- I campi canale/destinazione compaiono quando annuncio è selezionato.
|
||||
- La modalità Webhook usa `delivery.mode = "webhook"` con `delivery.to` impostato su un URL webhook HTTP(S) valido.
|
||||
- Per i job della sessione principale sono disponibili le modalità di consegna webhook e nessuna.
|
||||
- I controlli di modifica avanzata includono elimina dopo l'esecuzione, cancella override agente, opzioni cron esatto/scaglionato, override modello/thinking agente e toggle di consegna best-effort.
|
||||
- La validazione del modulo è inline con errori a livello di campo; valori non validi disabilitano il pulsante di salvataggio finché non vengono corretti.
|
||||
- Imposta `cron.webhookToken` per inviare un token bearer dedicato; se omesso, il webhook viene inviato senza header di autenticazione.
|
||||
- Fallback deprecato: i job legacy archiviati con `notify: true` possono ancora usare `cron.webhook` finché non vengono migrati.
|
||||
- Fallback deprecato: i job legacy memorizzati con `notify: true` possono ancora usare `cron.webhook` finché non vengono migrati.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -154,63 +155,63 @@ I temi importati vengono archiviati solo nel profilo browser corrente. Non vengo
|
||||
## Comportamento della chat
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Semantica di invio e cronologia">
|
||||
<Accordion title="Send and history semantics">
|
||||
- `chat.send` è **non bloccante**: conferma subito con `{ runId, status: "started" }` e la risposta viene trasmessa tramite eventi `chat`.
|
||||
- I caricamenti in chat accettano immagini più file non video. Le immagini mantengono il percorso immagine nativo; gli altri file vengono archiviati come media gestiti e mostrati nella cronologia come link ad allegati.
|
||||
- Inviare di nuovo con lo stesso `idempotencyKey` restituisce `{ status: "in_flight" }` durante l’esecuzione e `{ status: "ok" }` dopo il completamento.
|
||||
- Le risposte di `chat.history` hanno dimensioni limitate per la sicurezza della UI. Quando le voci della trascrizione sono troppo grandi, il Gateway può troncare campi di testo lunghi, omettere blocchi di metadati pesanti e sostituire i messaggi fuori misura con un segnaposto (`[chat.history omitted: message too large]`).
|
||||
- Le immagini dell’assistente/generate vengono conservate come riferimenti a media gestiti e restituite tramite URL multimediali autenticati del Gateway, quindi i ricaricamenti non dipendono dal mantenimento dei payload immagine base64 grezzi nella risposta della cronologia chat.
|
||||
- `chat.history` rimuove anche dal testo visibile dell’assistente i tag di direttiva inline solo visuali (per esempio `[[reply_to_*]]` e `[[audio_as_voice]]`), i payload XML di chiamate a strumenti in testo semplice (inclusi `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` e blocchi di chiamate a strumenti troncati) e i token di controllo del modello ASCII/a larghezza piena trapelati, e omette le voci dell’assistente il cui intero testo visibile è solo il token silenzioso esatto `NO_REPLY` / `no_reply`.
|
||||
- Durante un invio attivo e l’aggiornamento finale della cronologia, la vista chat mantiene visibili i messaggi utente/assistente ottimistici locali se `chat.history` restituisce brevemente uno snapshot precedente; la trascrizione canonica sostituisce quei messaggi locali quando la cronologia del Gateway si aggiorna.
|
||||
- Gli eventi `chat` live sono stato di consegna, mentre `chat.history` viene ricostruito dalla trascrizione durevole della sessione. Dopo gli eventi finali degli strumenti, la Control UI ricarica la cronologia e unisce solo una piccola coda ottimistica; il confine della trascrizione è documentato in [WebChat](/it/web/webchat).
|
||||
- `chat.inject` aggiunge una nota dell’assistente alla trascrizione della sessione e trasmette un evento `chat` per aggiornamenti solo UI (nessuna esecuzione dell’agente, nessuna consegna al canale).
|
||||
- I selettori del modello e del ragionamento nell’intestazione della chat applicano subito patch alla sessione attiva tramite `sessions.patch`; sono override persistenti della sessione, non opzioni di invio valide per un solo turno.
|
||||
- Digitare `/new` nella Control UI crea e passa alla stessa nuova sessione dashboard di New Chat. Digitare `/reset` mantiene il reset esplicito sul posto del Gateway per la sessione corrente.
|
||||
- Il selettore del modello chat richiede la vista dei modelli configurata del Gateway. Se `agents.defaults.models` è presente, quella allowlist guida il selettore. Altrimenti il selettore mostra le voci esplicite `models.providers.*.models` più i provider con autenticazione utilizzabile. Il catalogo completo resta disponibile tramite la RPC di debug `models.list` con `view: "all"`.
|
||||
- Quando i report aggiornati di utilizzo della sessione del Gateway mostrano alta pressione sul contesto, l’area del compositore chat mostra un avviso di contesto e, ai livelli di Compaction consigliati, un pulsante compatto che esegue il normale percorso di Compaction della sessione. Gli snapshot token obsoleti vengono nascosti finché il Gateway non segnala di nuovo un utilizzo aggiornato.
|
||||
- I caricamenti della chat accettano immagini e file non video. Le immagini mantengono il percorso immagine nativo; gli altri file vengono archiviati come media gestiti e mostrati nella cronologia come link di allegato.
|
||||
- Reinviare con lo stesso `idempotencyKey` restituisce `{ status: "in_flight" }` mentre è in esecuzione, e `{ status: "ok" }` dopo il completamento.
|
||||
- Le risposte di `chat.history` hanno limiti di dimensione per la sicurezza dell'interfaccia. Quando le voci della trascrizione sono troppo grandi, Gateway può troncare i campi di testo lunghi, omettere blocchi di metadati pesanti e sostituire i messaggi troppo grandi con un segnaposto (`[chat.history omitted: message too large]`).
|
||||
- Le immagini assistente/generate vengono persistite come riferimenti a media gestiti e restituite tramite URL media autenticati di Gateway, quindi i ricaricamenti non dipendono dal fatto che i payload immagine raw base64 rimangano nella risposta della cronologia chat.
|
||||
- `chat.history` rimuove inoltre dal testo visibile dell'assistente i tag direttiva inline solo di visualizzazione (per esempio `[[reply_to_*]]` e `[[audio_as_voice]]`), i payload XML delle chiamate agli strumenti in testo normale (inclusi `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` e blocchi di chiamate agli strumenti troncati), e i token di controllo del modello ASCII/a larghezza piena trapelati, e omette le voci dell'assistente il cui intero testo visibile è solo l'esatto token silenzioso `NO_REPLY` / `no_reply`.
|
||||
- Durante un invio attivo e l'aggiornamento finale della cronologia, la vista chat mantiene visibili i messaggi utente/assistente locali ottimistici se `chat.history` restituisce brevemente uno snapshot precedente; la trascrizione canonica sostituisce quei messaggi locali quando la cronologia Gateway si aggiorna.
|
||||
- Gli eventi `chat` live sono stato di consegna, mentre `chat.history` viene ricostruito dalla trascrizione durevole della sessione. Dopo gli eventi finali degli strumenti, l'interfaccia di controllo ricarica la cronologia e unisce solo una piccola coda ottimistica; il confine della trascrizione è documentato in [WebChat](/it/web/webchat).
|
||||
- `chat.inject` aggiunge una nota dell'assistente alla trascrizione della sessione e trasmette un evento `chat` per aggiornamenti solo interfaccia (nessuna esecuzione dell'agente, nessuna consegna al canale).
|
||||
- I selettori del modello e del thinking nell'intestazione della chat aggiornano immediatamente la sessione attiva tramite `sessions.patch`; sono override persistenti della sessione, non opzioni di invio valide per un solo turno.
|
||||
- Digitare `/new` nell'interfaccia di controllo crea e passa alla stessa nuova sessione dashboard di New Chat. Digitare `/reset` mantiene il reset esplicito in-place di Gateway per la sessione corrente.
|
||||
- Il selettore del modello chat richiede la vista modello configurata di Gateway. Se `agents.defaults.models` è presente, quella allowlist guida il selettore. Altrimenti il selettore mostra le voci esplicite `models.providers.*.models` più i provider con autenticazione utilizzabile. Il catalogo completo resta disponibile tramite l'RPC di debug `models.list` con `view: "all"`.
|
||||
- Quando i report di utilizzo freschi della sessione Gateway mostrano alta pressione di contesto, l'area del compositore chat mostra un avviso di contesto e, ai livelli di Compaction consigliati, un pulsante compatto che esegue il normale percorso di Compaction della sessione. Gli snapshot dei token obsoleti sono nascosti finché Gateway non segnala di nuovo un utilizzo fresco.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Modalità conversazione (tempo reale nel browser)">
|
||||
La modalità conversazione usa un provider vocale realtime registrato. Configura OpenAI con `talk.provider: "openai"` più `talk.providers.openai.apiKey`, oppure configura Google con `talk.provider: "google"` più `talk.providers.google.apiKey`; la configurazione del provider realtime di Voice Call può ancora essere riutilizzata come fallback. Il browser non riceve mai una chiave API standard del provider. OpenAI riceve un client secret Realtime effimero per WebRTC. Google Live riceve un token di autenticazione Live API vincolato monouso per una sessione WebSocket del browser, con istruzioni e dichiarazioni degli strumenti bloccate nel token dal Gateway. I provider che espongono solo un bridge realtime backend passano attraverso il trasporto relay del Gateway, quindi credenziali e socket del vendor restano lato server mentre l’audio del browser passa tramite RPC autenticate del Gateway. Il prompt della sessione Realtime viene assemblato dal Gateway; `talk.realtime.session` non accetta override delle istruzioni forniti dal chiamante.
|
||||
<Accordion title="Talk mode (browser realtime)">
|
||||
La modalità Talk usa un provider vocale realtime registrato. Configura OpenAI con `talk.provider: "openai"` più `talk.providers.openai.apiKey`, oppure configura Google con `talk.provider: "google"` più `talk.providers.google.apiKey`; la configurazione del provider realtime di Voice Call può comunque essere riutilizzata come fallback. Il browser non riceve mai una chiave API provider standard. OpenAI riceve un segreto client Realtime effimero per WebRTC. Google Live riceve un token di autenticazione Live API vincolato monouso per una sessione WebSocket del browser, con istruzioni e dichiarazioni degli strumenti bloccate nel token da Gateway. I provider che espongono solo un bridge realtime backend passano attraverso il trasporto relay di Gateway, quindi credenziali e socket del fornitore restano lato server mentre l'audio del browser passa tramite RPC Gateway autenticati. Il prompt della sessione Realtime è assemblato da Gateway; `talk.realtime.session` non accetta override delle istruzioni forniti dal chiamante.
|
||||
|
||||
Nel compositore Chat, il controllo Talk è il pulsante con le onde accanto al pulsante del microfono per la dettatura. Quando Talk si avvia, la riga di stato del compositore mostra `Connecting Talk...`, poi `Talk live` mentre l’audio è connesso, oppure `Asking OpenClaw...` mentre una chiamata realtime a uno strumento consulta il modello più grande configurato tramite `chat.send`.
|
||||
Nel compositore Chat, il controllo Talk è il pulsante con onde accanto al pulsante di dettatura tramite microfono. Quando Talk si avvia, la riga di stato del compositore mostra `Connecting Talk...`, poi `Talk live` mentre l'audio è connesso, oppure `Asking OpenClaw...` mentre una chiamata realtime a uno strumento consulta il modello più grande configurato tramite `chat.send`.
|
||||
|
||||
Smoke live per maintainer: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifica lo scambio SDP WebRTC del browser OpenAI, la configurazione WebSocket del browser Google Live con token vincolato e l’adattatore browser relay del Gateway con media microfono fittizi. Il comando stampa solo lo stato del provider e non registra segreti.
|
||||
Smoke live per maintainer: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` verifica lo scambio SDP WebRTC del browser OpenAI, la configurazione WebSocket browser con token vincolato di Google Live e l'adattatore browser del relay Gateway con media microfono fittizi. Il comando stampa solo lo stato del provider e non registra segreti.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Arresto e interruzione">
|
||||
<Accordion title="Stop and abort">
|
||||
- Fai clic su **Stop** (chiama `chat.abort`).
|
||||
- Mentre un’esecuzione è attiva, i normali follow-up vengono accodati. Fai clic su **Steer** su un messaggio accodato per iniettare quel follow-up nel turno in esecuzione.
|
||||
- Digita `/stop` (o frasi autonome di interruzione come `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) per interrompere fuori banda.
|
||||
- Mentre un'esecuzione è attiva, i follow-up normali vengono accodati. Fai clic su **Steer** su un messaggio in coda per iniettare quel follow-up nel turno in esecuzione.
|
||||
- Digita `/stop` (o frasi di interruzione autonome come `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`) per interrompere fuori banda.
|
||||
- `chat.abort` supporta `{ sessionKey }` (senza `runId`) per interrompere tutte le esecuzioni attive per quella sessione.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Conservazione parziale dopo interruzione">
|
||||
- Quando un’esecuzione viene interrotta, il testo parziale dell’assistente può comunque essere mostrato nella UI.
|
||||
- Il Gateway conserva il testo parziale interrotto dell’assistente nella cronologia della trascrizione quando esiste output in buffer.
|
||||
- Le voci conservate includono metadati di interruzione, così i consumatori della trascrizione possono distinguere i parziali interrotti dall’output di completamento normale.
|
||||
<Accordion title="Abort partial retention">
|
||||
- Quando un'esecuzione viene interrotta, il testo parziale dell'assistente può comunque essere mostrato nell'interfaccia.
|
||||
- Gateway persiste il testo parziale interrotto dell'assistente nella cronologia della trascrizione quando esiste output bufferizzato.
|
||||
- Le voci persistite includono metadati di interruzione, così i consumatori della trascrizione possono distinguere i parziali interrotti dall'output di completamento normale.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Installazione PWA e web push
|
||||
|
||||
La Control UI include un `manifest.webmanifest` e un service worker, quindi i browser moderni possono installarla come PWA autonoma. Web Push consente al Gateway di riattivare la PWA installata con notifiche anche quando la scheda o la finestra del browser non è aperta.
|
||||
L'interfaccia di controllo include un `manifest.webmanifest` e un service worker, quindi i browser moderni possono installarla come PWA autonoma. Web Push consente a Gateway di riattivare la PWA installata con notifiche anche quando la scheda o la finestra del browser non è aperta.
|
||||
|
||||
| Superficie | Cosa fa |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| `ui/public/manifest.webmanifest` | Manifest PWA. I browser offrono "Installa app" quando è raggiungibile. |
|
||||
| `ui/public/sw.js` | Service worker che gestisce eventi `push` e clic sulle notifiche. |
|
||||
| `push/vapid-keys.json` (sotto la directory di stato di OpenClaw) | Coppia di chiavi VAPID generata automaticamente usata per firmare i payload Web Push. |
|
||||
| `push/web-push-subscriptions.json` | Endpoint di sottoscrizione del browser conservati. |
|
||||
| `ui/public/sw.js` | Service worker che gestisce eventi `push` e clic sulle notifiche. |
|
||||
| `push/vapid-keys.json` (nella directory di stato di OpenClaw) | Coppia di chiavi VAPID generata automaticamente, usata per firmare payload Web Push. |
|
||||
| `push/web-push-subscriptions.json` | Endpoint di sottoscrizione browser persistiti. |
|
||||
|
||||
Sovrascrivi la coppia di chiavi VAPID tramite variabili d’ambiente sul processo Gateway quando vuoi bloccare le chiavi (per distribuzioni multi-host, rotazione dei segreti o test):
|
||||
Esegui l'override della coppia di chiavi VAPID tramite variabili d'ambiente sul processo Gateway quando vuoi fissare le chiavi (per distribuzioni multi-host, rotazione dei segreti o test):
|
||||
|
||||
- `OPENCLAW_VAPID_PUBLIC_KEY`
|
||||
- `OPENCLAW_VAPID_PRIVATE_KEY`
|
||||
- `OPENCLAW_VAPID_SUBJECT` (predefinito: `mailto:openclaw@localhost`)
|
||||
- `OPENCLAW_VAPID_SUBJECT` (predefinito a `mailto:openclaw@localhost`)
|
||||
|
||||
La Control UI usa questi metodi Gateway limitati per ambito per registrare e testare le sottoscrizioni del browser:
|
||||
L'interfaccia di controllo usa questi metodi Gateway con ambito controllato per registrare e testare le sottoscrizioni browser:
|
||||
|
||||
- `push.web.vapidPublicKey` — recupera la chiave pubblica VAPID attiva.
|
||||
- `push.web.subscribe` — registra un `endpoint` più `keys.p256dh`/`keys.auth`.
|
||||
@ -218,22 +219,22 @@ La Control UI usa questi metodi Gateway limitati per ambito per registrare e tes
|
||||
- `push.web.test` — invia una notifica di test alla sottoscrizione del chiamante.
|
||||
|
||||
<Note>
|
||||
Web Push è indipendente dal percorso relay APNS di iOS (vedi [Configurazione](/it/gateway/configuration) per il push basato su relay) e dal metodo esistente `push.test`, che riguarda l’abbinamento mobile nativo.
|
||||
Web Push è indipendente dal percorso relay iOS APNS (vedi [Configurazione](/it/gateway/configuration) per il push con backend relay) e dal metodo `push.test` esistente, che hanno come destinazione l'abbinamento mobile nativo.
|
||||
</Note>
|
||||
|
||||
## Embed ospitati
|
||||
|
||||
I messaggi dell’assistente possono renderizzare contenuti web ospitati inline con lo shortcode `[embed ...]`. La policy sandbox dell’iframe è controllata da `gateway.controlUi.embedSandbox`:
|
||||
I messaggi dell'assistente possono renderizzare contenuti web ospitati inline con lo shortcode `[embed ...]`. La policy sandbox dell'iframe è controllata da `gateway.controlUi.embedSandbox`:
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
Disabilita l’esecuzione di script dentro gli embed ospitati.
|
||||
Disabilita l'esecuzione degli script dentro gli embed ospitati.
|
||||
</Tab>
|
||||
<Tab title="scripts (predefinito)">
|
||||
Consente embed interattivi mantenendo l’isolamento dell’origine; questo è il valore predefinito e di solito basta per giochi/widget browser autonomi.
|
||||
<Tab title="scripts (default)">
|
||||
Consente embed interattivi mantenendo l'isolamento dell'origine; è il valore predefinito ed è di solito sufficiente per giochi/widget browser autonomi.
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
Aggiunge `allow-same-origin` oltre a `allow-scripts` per documenti dello stesso sito che richiedono intenzionalmente privilegi più forti.
|
||||
Aggiunge `allow-same-origin` oltre a `allow-scripts` per documenti dello stesso sito che necessitano intenzionalmente di privilegi più forti.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
@ -250,14 +251,14 @@ Esempio:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Usa `trusted` solo quando il documento incorporato richiede davvero comportamento same-origin. Per la maggior parte dei giochi e canvas interattivi generati dagli agenti, `scripts` è la scelta più sicura.
|
||||
Usa `trusted` solo quando il documento incorporato ha davvero bisogno di comportamento same-origin. Per la maggior parte dei giochi generati da agenti e delle canvas interattive, `scripts` è la scelta più sicura.
|
||||
</Warning>
|
||||
|
||||
Gli URL embed `http(s)` esterni assoluti restano bloccati per impostazione predefinita. Se vuoi intenzionalmente che `[embed url="https://..."]` carichi pagine di terze parti, imposta `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
Gli URL embed esterni assoluti `http(s)` restano bloccati per impostazione predefinita. Se vuoi intenzionalmente che `[embed url="https://..."]` carichi pagine di terze parti, imposta `gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
|
||||
## Larghezza dei messaggi chat
|
||||
|
||||
I messaggi chat raggruppati usano una larghezza massima predefinita leggibile. Le distribuzioni su monitor ampi possono sovrascriverla senza applicare patch al CSS integrato impostando `gateway.controlUi.chatMessageMaxWidth`:
|
||||
I messaggi chat raggruppati usano una max-width predefinita leggibile. Le distribuzioni su monitor ampi possono sostituirla senza modificare il CSS incluso impostando `gateway.controlUi.chatMessageMaxWidth`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -274,8 +275,8 @@ Il valore viene validato prima di raggiungere il browser. I valori supportati in
|
||||
## Accesso tailnet (consigliato)
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Tailscale Serve integrato (preferito)">
|
||||
Mantieni il Gateway su loopback e lascia che Tailscale Serve lo proxii con HTTPS:
|
||||
<Tab title="Integrated Tailscale Serve (preferred)">
|
||||
Mantieni Gateway su loopback e lascia che Tailscale Serve lo proxii con HTTPS:
|
||||
|
||||
```bash
|
||||
openclaw gateway --tailscale serve
|
||||
@ -285,16 +286,16 @@ Il valore viene validato prima di raggiungere il browser. I valori supportati in
|
||||
|
||||
- `https://<magicdns>/` (o il tuo `gateway.controlUi.basePath` configurato)
|
||||
|
||||
Per impostazione predefinita, le richieste Serve di Control UI/WebSocket possono autenticarsi tramite header di identità Tailscale (`tailscale-user-login`) quando `gateway.auth.allowTailscale` è `true`. OpenClaw verifica l’identità risolvendo l’indirizzo `x-forwarded-for` con `tailscale whois` e confrontandolo con l’header, e accetta questi header solo quando la richiesta arriva su loopback con gli header `x-forwarded-*` di Tailscale. Per le sessioni operatore della Control UI con identità del dispositivo browser, questo percorso Serve verificato salta anche il round trip di abbinamento dispositivo; i browser senza dispositivo e le connessioni con ruolo nodo seguono comunque i normali controlli del dispositivo. Imposta `gateway.auth.allowTailscale: false` se vuoi richiedere credenziali esplicite con segreto condiviso anche per il traffico Serve. Poi usa `gateway.auth.mode: "token"` o `"password"`.
|
||||
Per impostazione predefinita, le richieste Control UI/WebSocket Serve possono autenticarsi tramite header identità Tailscale (`tailscale-user-login`) quando `gateway.auth.allowTailscale` è `true`. OpenClaw verifica l'identità risolvendo l'indirizzo `x-forwarded-for` con `tailscale whois` e confrontandolo con l'header, e li accetta solo quando la richiesta raggiunge local loopback con gli header `x-forwarded-*` di Tailscale. Per le sessioni operatore dell'interfaccia di controllo con identità dispositivo browser, questo percorso Serve verificato salta anche il round trip di abbinamento del dispositivo; i browser senza dispositivo e le connessioni con ruolo nodo seguono comunque i normali controlli dispositivo. Imposta `gateway.auth.allowTailscale: false` se vuoi richiedere credenziali esplicite con segreto condiviso anche per il traffico Serve. Poi usa `gateway.auth.mode: "token"` o `"password"`.
|
||||
|
||||
Per quel percorso asincrono di identità Serve, i tentativi di autenticazione falliti per lo stesso IP client e ambito di autenticazione vengono serializzati prima delle scritture del rate limit. Tentativi errati concorrenti dallo stesso browser possono quindi mostrare `retry later` alla seconda richiesta invece di due semplici mismatch in gara in parallelo.
|
||||
Per quel percorso identità Serve asincrono, i tentativi di autenticazione falliti per lo stesso IP client e ambito di autenticazione vengono serializzati prima delle scritture del rate-limit. Retry errati concorrenti dallo stesso browser possono quindi mostrare `retry later` sulla seconda richiesta invece di due semplici mancati riscontri in competizione parallela.
|
||||
|
||||
<Warning>
|
||||
L’autenticazione Serve senza token presume che l’host gateway sia attendibile. Se codice locale non attendibile può essere eseguito su quell’host, richiedi autenticazione con token/password.
|
||||
L'autenticazione Serve senza token presume che l'host gateway sia attendibile. Se codice locale non attendibile può essere eseguito su quell'host, richiedi autenticazione token/password.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
<Tab title="Bind alla tailnet + token">
|
||||
<Tab title="Bind to tailnet + token">
|
||||
```bash
|
||||
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
```
|
||||
@ -303,25 +304,25 @@ Il valore viene validato prima di raggiungere il browser. I valori supportati in
|
||||
|
||||
- `http://<tailscale-ip>:18789/` (o il tuo `gateway.controlUi.basePath` configurato)
|
||||
|
||||
Incolla il segreto condiviso corrispondente nelle impostazioni della UI (inviato come `connect.params.auth.token` o `connect.params.auth.password`).
|
||||
Incolla il segreto condiviso corrispondente nelle impostazioni dell'interfaccia (inviato come `connect.params.auth.token` o `connect.params.auth.password`).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## HTTP non sicuro
|
||||
|
||||
Se apri la dashboard tramite HTTP semplice (`http://<lan-ip>` o `http://<tailscale-ip>`), il browser viene eseguito in un **contesto non sicuro** e blocca WebCrypto. Per impostazione predefinita, OpenClaw **blocca** le connessioni Control UI senza identità del dispositivo.
|
||||
Se apri la dashboard tramite HTTP semplice (`http://<lan-ip>` o `http://<tailscale-ip>`), il browser viene eseguito in un **contesto non sicuro** e blocca WebCrypto. Per impostazione predefinita, OpenClaw **blocca** le connessioni dell'interfaccia di controllo senza identità dispositivo.
|
||||
|
||||
Eccezioni documentate:
|
||||
|
||||
- compatibilità HTTP non sicuro solo localhost con `gateway.controlUi.allowInsecureAuth=true`
|
||||
- autenticazione operatore Control UI riuscita tramite `gateway.auth.mode: "trusted-proxy"`
|
||||
- opzione di emergenza `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
- autenticazione riuscita dell'interfaccia di controllo operatore tramite `gateway.auth.mode: "trusted-proxy"`
|
||||
- emergenza `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
|
||||
**Correzione consigliata:** usa HTTPS (Tailscale Serve) oppure apri la UI localmente:
|
||||
|
||||
- `https://<magicdns>/` (Serve)
|
||||
- `http://127.0.0.1:18789/` (sull'host del gateway)
|
||||
- `http://127.0.0.1:18789/` (sull'host del Gateway)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Comportamento dell'opzione di autenticazione non sicura">
|
||||
@ -337,12 +338,12 @@ Eccezioni documentate:
|
||||
|
||||
`allowInsecureAuth` è solo un'opzione di compatibilità locale:
|
||||
|
||||
- Consente alle sessioni localhost della UI di controllo di procedere senza identità del dispositivo in contesti HTTP non sicuri.
|
||||
- Non aggira i controlli di pairing.
|
||||
- Consente alle sessioni Control UI localhost di procedere senza identità del dispositivo in contesti HTTP non sicuri.
|
||||
- Non bypassa i controlli di pairing.
|
||||
- Non allenta i requisiti di identità del dispositivo remoto (non localhost).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Solo per emergenze">
|
||||
<Accordion title="Solo emergenza">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -354,14 +355,14 @@ Eccezioni documentate:
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` disabilita i controlli di identità del dispositivo della UI di controllo ed è un grave indebolimento della sicurezza. Ripristina rapidamente dopo l'uso di emergenza.
|
||||
`dangerouslyDisableDeviceAuth` disabilita i controlli di identità del dispositivo della Control UI ed è un grave indebolimento della sicurezza. Ripristina rapidamente dopo l'uso di emergenza.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Nota sul proxy attendibile">
|
||||
- Un'autenticazione tramite proxy attendibile riuscita può ammettere sessioni **operatore** della UI di controllo senza identità del dispositivo.
|
||||
- Questo **non** si estende alle sessioni della UI di controllo con ruolo nodo.
|
||||
- I proxy inversi loopback sullo stesso host continuano a non soddisfare l'autenticazione tramite proxy attendibile; vedi [Autenticazione tramite proxy attendibile](/it/gateway/trusted-proxy-auth).
|
||||
- Un'autenticazione con proxy attendibile riuscita può ammettere sessioni Control UI **operatore** senza identità del dispositivo.
|
||||
- Questo **non** si estende alle sessioni Control UI con ruolo nodo.
|
||||
- I reverse proxy local loopback sullo stesso host continuano a non soddisfare l'autenticazione con proxy attendibile; consulta [Autenticazione con proxy attendibile](/it/gateway/trusted-proxy-auth).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -370,40 +371,40 @@ Consulta [Tailscale](/it/gateway/tailscale) per indicazioni sulla configurazione
|
||||
|
||||
## Criterio di sicurezza dei contenuti
|
||||
|
||||
La UI di controllo include un criterio `img-src` restrittivo: sono consentiti solo asset **same-origin**, URL `data:` e URL `blob:` generati localmente. Gli URL immagine remoti `http(s)` e relativi al protocollo vengono rifiutati dal browser e non generano richieste di rete.
|
||||
La Control UI viene distribuita con un criterio `img-src` restrittivo: sono consentiti solo asset **same-origin**, URL `data:` e URL `blob:` generati localmente. Gli URL di immagini remoti `http(s)` e relativi al protocollo vengono rifiutati dal browser e non generano richieste di rete.
|
||||
|
||||
Cosa significa in pratica:
|
||||
In pratica significa che:
|
||||
|
||||
- Avatar e immagini serviti sotto percorsi relativi (per esempio `/avatars/<id>`) vengono comunque renderizzati, incluse le route avatar autenticate che la UI recupera e converte in URL `blob:` locali.
|
||||
- Gli URL inline `data:image/...` vengono comunque renderizzati (utile per payload nel protocollo).
|
||||
- Gli URL `blob:` locali creati dalla UI di controllo vengono comunque renderizzati.
|
||||
- Gli URL avatar remoti emessi dai metadati dei canali vengono rimossi dagli helper avatar della UI di controllo e sostituiti con il logo/badge integrato, quindi un canale compromesso o malevolo non può forzare recuperi di immagini remote arbitrarie dal browser di un operatore.
|
||||
- Avatar e immagini serviti tramite percorsi relativi (per esempio `/avatars/<id>`) vengono comunque visualizzati, incluse le route avatar autenticate che la UI recupera e converte in URL `blob:` locali.
|
||||
- Gli URL inline `data:image/...` vengono comunque visualizzati (utile per payload nel protocollo).
|
||||
- Gli URL `blob:` locali creati dalla Control UI vengono comunque visualizzati.
|
||||
- Gli URL avatar remoti emessi dai metadati del canale vengono rimossi dagli helper avatar della Control UI e sostituiti con il logo/badge integrato, quindi un canale compromesso o malevolo non può forzare recuperi arbitrari di immagini remote dal browser di un operatore.
|
||||
|
||||
Non devi modificare nulla per ottenere questo comportamento: è sempre attivo e non configurabile.
|
||||
|
||||
## Autenticazione della route avatar
|
||||
|
||||
Quando l'autenticazione del gateway è configurata, l'endpoint avatar della UI di controllo richiede lo stesso token del gateway del resto dell'API:
|
||||
Quando l'autenticazione del Gateway è configurata, l'endpoint avatar della Control UI richiede lo stesso token del Gateway del resto dell'API:
|
||||
|
||||
- `GET /avatar/<agentId>` restituisce l'immagine avatar solo ai chiamanti autenticati. `GET /avatar/<agentId>?meta=1` restituisce i metadati dell'avatar con la stessa regola.
|
||||
- Le richieste non autenticate a entrambe le route vengono rifiutate (come la route assistant-media adiacente). Questo impedisce alla route avatar di esporre l'identità dell'agente su host che sono altrimenti protetti.
|
||||
- La UI di controllo inoltra il token del gateway come header bearer quando recupera gli avatar e usa URL blob autenticati, così l'immagine viene comunque renderizzata nelle dashboard.
|
||||
- `GET /avatar/<agentId>` restituisce l'immagine avatar solo ai chiamanti autenticati. `GET /avatar/<agentId>?meta=1` restituisce i metadati avatar con la stessa regola.
|
||||
- Le richieste non autenticate a entrambe le route vengono rifiutate (come la route sibling assistant-media). Questo impedisce alla route avatar di esporre l'identità dell'agente su host altrimenti protetti.
|
||||
- La Control UI inoltra il token del Gateway come header bearer quando recupera gli avatar e usa URL blob autenticati, così l'immagine viene comunque visualizzata nelle dashboard.
|
||||
|
||||
Se disabiliti l'autenticazione del gateway (sconsigliato su host condivisi), anche la route avatar diventa non autenticata, in linea con il resto del gateway.
|
||||
Se disabiliti l'autenticazione del Gateway (sconsigliato su host condivisi), anche la route avatar diventa non autenticata, in linea con il resto del Gateway.
|
||||
|
||||
## Autenticazione della route media dell'assistente
|
||||
|
||||
Quando l'autenticazione del gateway è configurata, le anteprime dei media locali dell'assistente usano una route in due passaggi:
|
||||
Quando l'autenticazione del Gateway è configurata, le anteprime dei media locali dell'assistente usano una route in due passaggi:
|
||||
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` richiede la normale autenticazione operatore della UI di controllo. Il browser invia il token del gateway come header bearer quando controlla la disponibilità.
|
||||
- Le risposte di metadati riuscite includono un `mediaTicket` di breve durata limitato a quel percorso sorgente esatto.
|
||||
- Gli URL di immagini, audio, video e documenti renderizzati dal browser usano `mediaTicket=<ticket>` invece del token o della password attivi del gateway. Il ticket scade rapidamente e non può autorizzare una sorgente diversa.
|
||||
- `GET /__openclaw__/assistant-media?meta=1&source=<path>` richiede la normale autenticazione operatore della Control UI. Il browser invia il token del Gateway come header bearer quando controlla la disponibilità.
|
||||
- Le risposte di metadati riuscite includono un `mediaTicket` di breve durata limitato a quello specifico percorso sorgente.
|
||||
- Gli URL di immagini, audio, video e documenti renderizzati dal browser usano `mediaTicket=<ticket>` invece del token o della password attivi del Gateway. Il ticket scade rapidamente e non può autorizzare una sorgente diversa.
|
||||
|
||||
Questo mantiene il normale rendering dei media compatibile con gli elementi media nativi del browser senza inserire credenziali del gateway riutilizzabili negli URL media visibili.
|
||||
Questo mantiene il normale rendering dei media compatibile con gli elementi multimediali nativi del browser senza inserire credenziali riutilizzabili del Gateway negli URL media visibili.
|
||||
|
||||
## Compilare la UI
|
||||
## Creazione della UI
|
||||
|
||||
Il Gateway serve file statici da `dist/control-ui`. Compilali con:
|
||||
Il Gateway serve file statici da `dist/control-ui`. Creali con:
|
||||
|
||||
```bash
|
||||
pnpm ui:build
|
||||
@ -421,11 +422,11 @@ Per lo sviluppo locale (server di sviluppo separato):
|
||||
pnpm ui:dev
|
||||
```
|
||||
|
||||
Poi punta la UI all'URL WS del tuo Gateway (ad esempio `ws://127.0.0.1:18789`).
|
||||
Poi indirizza la UI all'URL WS del tuo Gateway (ad es. `ws://127.0.0.1:18789`).
|
||||
|
||||
## Debug/test: server di sviluppo + Gateway remoto
|
||||
|
||||
La UI di controllo è composta da file statici; la destinazione WebSocket è configurabile e può essere diversa dall'origine HTTP. È utile quando vuoi il server di sviluppo Vite localmente ma il Gateway è in esecuzione altrove.
|
||||
La Control UI è composta da file statici; il target WebSocket è configurabile e può essere diverso dall'origine HTTP. Questo è utile quando vuoi usare il server di sviluppo Vite localmente ma il Gateway viene eseguito altrove.
|
||||
|
||||
<Steps>
|
||||
<Step title="Avvia il server di sviluppo della UI">
|
||||
@ -438,7 +439,7 @@ La UI di controllo è composta da file statici; la destinazione WebSocket è con
|
||||
http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
|
||||
```
|
||||
|
||||
Autenticazione monouso opzionale (se necessaria):
|
||||
Autenticazione una tantum opzionale (se necessaria):
|
||||
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
|
||||
@ -449,17 +450,17 @@ La UI di controllo è composta da file statici; la destinazione WebSocket è con
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Note">
|
||||
- `gatewayUrl` viene memorizzato in localStorage dopo il caricamento e rimosso dall'URL.
|
||||
- Se passi un endpoint `ws://` o `wss://` completo tramite `gatewayUrl`, codifica come URL il valore di `gatewayUrl` in modo che il browser analizzi correttamente la stringa di query.
|
||||
- `token` dovrebbe essere passato tramite il frammento URL (`#token=...`) quando possibile. I frammenti non vengono inviati al server, evitando perdite nei log delle richieste e nel Referer. I parametri di query legacy `?token=` vengono ancora importati una volta per compatibilità, ma solo come fallback, e vengono rimossi immediatamente dopo il bootstrap.
|
||||
- `gatewayUrl` viene salvato in localStorage dopo il caricamento e rimosso dall'URL.
|
||||
- Se passi un endpoint completo `ws://` o `wss://` tramite `gatewayUrl`, codifica come URL il valore di `gatewayUrl` in modo che il browser analizzi correttamente la stringa di query.
|
||||
- `token` dovrebbe essere passato tramite il frammento URL (`#token=...`) ogni volta che è possibile. I frammenti non vengono inviati al server, evitando perdite nei log delle richieste e nel Referer. I parametri di query legacy `?token=` vengono ancora importati una volta per compatibilità, ma solo come fallback, e vengono rimossi immediatamente dopo il bootstrap.
|
||||
- `password` viene mantenuta solo in memoria.
|
||||
- Quando `gatewayUrl` è impostato, la UI non ricorre alle credenziali di configurazione o di ambiente. Fornisci esplicitamente `token` (o `password`). La mancanza di credenziali esplicite è un errore.
|
||||
- Quando `gatewayUrl` è impostato, la UI non ripiega su credenziali di configurazione o di ambiente. Fornisci esplicitamente `token` (o `password`). Le credenziali esplicite mancanti sono un errore.
|
||||
- Usa `wss://` quando il Gateway è dietro TLS (Tailscale Serve, proxy HTTPS, ecc.).
|
||||
- `gatewayUrl` viene accettato solo in una finestra di primo livello (non incorporata) per prevenire il clickjacking.
|
||||
- Le distribuzioni non loopback della UI di controllo devono impostare esplicitamente `gateway.controlUi.allowedOrigins` (origini complete). Questo include le configurazioni di sviluppo remote.
|
||||
- L'avvio del Gateway può inizializzare origini locali come `http://localhost:<port>` e `http://127.0.0.1:<port>` dal bind e dalla porta runtime effettivi, ma le origini browser remote richiedono comunque voci esplicite.
|
||||
- Non usare `gateway.controlUi.allowedOrigins: ["*"]` tranne che per test locali strettamente controllati. Significa consentire qualsiasi origine browser, non "corrispondi a qualunque host io stia usando."
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` abilita la modalità di fallback dell'origine dall'header Host, ma è una modalità di sicurezza pericolosa.
|
||||
- Le distribuzioni Control UI non loopback devono impostare esplicitamente `gateway.controlUi.allowedOrigins` (origini complete). Questo include le configurazioni di sviluppo remoto.
|
||||
- L'avvio del Gateway può inizializzare origini locali come `http://localhost:<port>` e `http://127.0.0.1:<port>` dal bind e dalla porta effettivi di runtime, ma le origini dei browser remoti richiedono comunque voci esplicite.
|
||||
- Non usare `gateway.controlUi.allowedOrigins: ["*"]` tranne che per test locali strettamente controllati. Significa consentire qualsiasi origine browser, non "corrispondi all'host che sto usando".
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` abilita la modalità di fallback dell'origine basata sull'header Host, ma è una modalità di sicurezza pericolosa.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -480,7 +481,7 @@ Dettagli di configurazione dell'accesso remoto: [Accesso remoto](/it/gateway/rem
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Dashboard](/it/web/dashboard) — dashboard del gateway
|
||||
- [Controlli di integrità](/it/gateway/health) — monitoraggio dell'integrità del gateway
|
||||
- [Dashboard](/it/web/dashboard) — dashboard del Gateway
|
||||
- [Controlli di integrità](/it/gateway/health) — monitoraggio dell'integrità del Gateway
|
||||
- [TUI](/it/web/tui) — interfaccia utente terminale
|
||||
- [WebChat](/it/web/webchat) — interfaccia chat basata su browser
|
||||
|
||||
Loading…
Reference in New Issue
Block a user