chore(i18n): refresh it translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
c8a0079821
commit
023b636ec7
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Configurazione del controllo degli accessi DM
|
||||
- Pairing di un nuovo nodo iOS/Android
|
||||
- Configurazione del controllo di accesso ai messaggi diretti
|
||||
- Associazione di un nuovo Node iOS/Android
|
||||
- Revisione della postura di sicurezza di OpenClaw
|
||||
summary: 'Panoramica del pairing: approva chi può inviarti DM e quali nodi possono unirsi'
|
||||
title: Pairing
|
||||
summary: 'Panoramica dell''associazione: approva chi può inviarti messaggi diretti + quali nodi possono unirsi'
|
||||
title: Associazione
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:43:36Z"
|
||||
generated_at: "2026-04-20T08:30:53Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2bd99240b3530def23c05a26915d07cf8b730565c2822c6338437f8fb3f285c9
|
||||
source_hash: 4161629ead02dc0bdcd283cc125fe6579a579e03740127f4feb22dfe344bd028
|
||||
source_path: channels/pairing.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Pairing
|
||||
# Associazione
|
||||
|
||||
Il “pairing” è il passaggio esplicito di **approvazione del proprietario** di OpenClaw.
|
||||
Viene usato in due punti:
|
||||
L’“associazione” è il passaggio esplicito di **approvazione del proprietario** di OpenClaw.
|
||||
Viene utilizzata in due casi:
|
||||
|
||||
1. **DM pairing** (chi è autorizzato a parlare con il bot)
|
||||
2. **Node pairing** (quali dispositivi/nodi sono autorizzati a unirsi alla rete del gateway)
|
||||
1. **Associazione DM** (chi è autorizzato a parlare con il bot)
|
||||
2. **Associazione del Node** (quali dispositivi/nodi sono autorizzati a unirsi alla rete Gateway)
|
||||
|
||||
Contesto di sicurezza: [Security](/gateway/security)
|
||||
Contesto di sicurezza: [Security](/it/gateway/security)
|
||||
|
||||
## 1) DM pairing (accesso alla chat in ingresso)
|
||||
## 1) Associazione DM (accesso alla 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.
|
||||
Quando un canale è configurato con il criterio 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: [Security](/gateway/security)
|
||||
I criteri DM predefiniti sono documentati in: [Security](/it/gateway/security)
|
||||
|
||||
Codici di pairing:
|
||||
Codici di associazione:
|
||||
|
||||
- 8 caratteri, maiuscoli, senza caratteri ambigui (`0O1I`).
|
||||
- **Scadono dopo 1 ora**. Il bot invia il messaggio di pairing solo quando viene creata una nuova richiesta (all'incirca una volta all'ora per mittente).
|
||||
- Le richieste di DM pairing in sospeso sono limitate per impostazione predefinita a **3 per canale**; le richieste aggiuntive vengono ignorate finché una non scade o non 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 DM di associazione in sospeso sono limitate a **3 per canale** per impostazione predefinita; le richieste aggiuntive vengono ignorate finché una non scade o non viene approvata.
|
||||
|
||||
### Approvare un mittente
|
||||
|
||||
@ -45,57 +45,57 @@ openclaw pairing approve telegram <CODE>
|
||||
|
||||
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`.
|
||||
|
||||
### Dove si trova lo stato
|
||||
### Dove risiede lo stato
|
||||
|
||||
Memorizzato in `~/.openclaw/credentials/`:
|
||||
|
||||
- Richieste in sospeso: `<channel>-pairing.json`
|
||||
- Archivio allowlist approvata:
|
||||
- Archivio delle allowlist approvate:
|
||||
- Account predefinito: `<channel>-allowFrom.json`
|
||||
- Account non predefinito: `<channel>-<accountId>-allowFrom.json`
|
||||
|
||||
Comportamento dell'ambito account:
|
||||
Comportamento dell’ambito account:
|
||||
|
||||
- Gli account non predefiniti leggono/scrivono solo il proprio file allowlist con ambito.
|
||||
- L'account predefinito usa il file allowlist senza ambito, con ambito del canale.
|
||||
- Gli account non predefiniti leggono/scrivono solo il proprio file allowlist con ambito specifico.
|
||||
- L’account predefinito usa il file allowlist senza ambito specifico del canale.
|
||||
|
||||
Tratta questi file come sensibili (controllano l'accesso al tuo assistente).
|
||||
Trattali come dati sensibili (controllano l’accesso al tuo assistente).
|
||||
|
||||
Importante: questo archivio serve per l'accesso DM. L'autorizzazione dei gruppi è separata.
|
||||
Approvare un codice di DM pairing non consente automaticamente a quel mittente di eseguire comandi di gruppo o controllare il bot nei gruppi. Per l'accesso ai gruppi, configura le allowlist esplicite del canale per i gruppi (ad esempio `groupAllowFrom`, `groups` o override per gruppo/per argomento a seconda del canale).
|
||||
Importante: questo archivio è per l’accesso DM. L’autorizzazione dei gruppi è separata.
|
||||
Approvare un codice di associazione DM non consente automaticamente a quel mittente di eseguire comandi di gruppo o controllare il bot nei gruppi. Per l’accesso ai gruppi, configura le allowlist esplicite del canale per i gruppi (ad esempio `groupAllowFrom`, `groups` o override per gruppo/per topic, a seconda del canale).
|
||||
|
||||
## 2) Pairing del dispositivo nodo (nodi iOS/Android/macOS/headless)
|
||||
## 2) Associazione del dispositivo Node (nodi iOS/Android/macOS/headless)
|
||||
|
||||
I nodi si connettono al Gateway come **dispositivi** con `role: node`. Il Gateway
|
||||
crea una richiesta di pairing del dispositivo che deve essere approvata.
|
||||
I Node si connettono al Gateway come **dispositivi** con `role: node`. Il Gateway
|
||||
crea una richiesta di associazione del dispositivo che deve essere approvata.
|
||||
|
||||
### Pairing tramite Telegram (consigliato per iOS)
|
||||
### Associare tramite Telegram (consigliato per iOS)
|
||||
|
||||
Se usi il plugin `device-pair`, puoi eseguire il primo pairing del dispositivo interamente da Telegram:
|
||||
Se utilizzi il plugin `device-pair`, puoi eseguire la prima associazione del dispositivo interamente da Telegram:
|
||||
|
||||
1. In Telegram, invia al tuo bot: `/pair`
|
||||
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 di OpenClaw → Impostazioni → Gateway.
|
||||
3. Sul telefono, apri l’app OpenClaw iOS → Settings → Gateway.
|
||||
4. Incolla il codice di configurazione e connettiti.
|
||||
5. Tornato in Telegram: `/pair pending` (rivedi ID richiesta, ruolo e scope), quindi approva.
|
||||
5. Torna 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://...` oppure `wss://...`)
|
||||
- `bootstrapToken`: un bootstrap token a breve durata, per un solo dispositivo, usato per l'handshake iniziale di pairing
|
||||
- `url`: l’URL WebSocket del Gateway (`ws://...` o `wss://...`)
|
||||
- `bootstrapToken`: un token bootstrap temporaneo per singolo dispositivo usato per l’handshake iniziale di associazione
|
||||
|
||||
Quel bootstrap token contiene il profilo bootstrap di pairing integrato:
|
||||
Quel token bootstrap include il profilo bootstrap di associazione integrato:
|
||||
|
||||
- il token `node` primario trasferito resta `scopes: []`
|
||||
- qualsiasi token `operator` trasferito resta vincolato all'allowlist bootstrap:
|
||||
- il token `node` primario passato rimane `scopes: []`
|
||||
- qualsiasi token `operator` passato rimane limitato alla bootstrap allowlist:
|
||||
`operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`
|
||||
- i controlli degli scope bootstrap usano prefissi di ruolo, non un unico pool di scope:
|
||||
le voci di scope operator soddisfano solo richieste operator, e i ruoli non operator
|
||||
devono comunque richiedere scope sotto il proprio prefisso di ruolo
|
||||
- i controlli degli ambiti bootstrap sono prefissati per ruolo, non un unico pool piatto di ambiti:
|
||||
le voci di ambito operator soddisfano solo richieste operator, e i ruoli non-operator
|
||||
devono comunque richiedere ambiti con il prefisso del proprio ruolo
|
||||
|
||||
Tratta il codice di configurazione come una password finché è valido.
|
||||
|
||||
### Approvare un dispositivo nodo
|
||||
### Approvare un dispositivo Node
|
||||
|
||||
```bash
|
||||
openclaw devices list
|
||||
@ -103,34 +103,40 @@ openclaw devices approve <requestId>
|
||||
openclaw devices reject <requestId>
|
||||
```
|
||||
|
||||
Se lo stesso dispositivo ritenta con dettagli di autenticazione diversi (ad esempio
|
||||
ruolo/scope/chiave pubblica diversi), la precedente richiesta in sospeso viene sostituita e viene creato un nuovo
|
||||
Se lo stesso dispositivo riprova con dettagli di autenticazione diversi (ad esempio
|
||||
ruolo/ambiti/chiave pubblica differenti), la precedente richiesta in sospeso viene sostituita e viene creato un nuovo
|
||||
`requestId`.
|
||||
|
||||
### Archiviazione dello stato di pairing del nodo
|
||||
Importante: un dispositivo già associato non ottiene automaticamente un accesso più ampio. Se
|
||||
si riconnette richiedendo più ambiti o un ruolo più esteso, OpenClaw mantiene
|
||||
l’approvazione esistente così com’è e crea una nuova richiesta di aggiornamento in sospeso. Usa
|
||||
`openclaw devices list` per confrontare l’accesso attualmente approvato con quello appena
|
||||
richiesto prima di approvare.
|
||||
|
||||
### Archiviazione dello stato di associazione del Node
|
||||
|
||||
Memorizzato in `~/.openclaw/devices/`:
|
||||
|
||||
- `pending.json` (a breve durata; le richieste in sospeso scadono)
|
||||
- `paired.json` (dispositivi abbinati + token)
|
||||
- `pending.json` (temporaneo; le richieste in sospeso scadono)
|
||||
- `paired.json` (dispositivi associati + token)
|
||||
|
||||
### Note
|
||||
|
||||
- L'API legacy `node.pair.*` (CLI: `openclaw nodes pending|approve|reject|rename`) è un
|
||||
archivio di pairing separato di proprietà del gateway. I nodi WS richiedono comunque il pairing del dispositivo.
|
||||
- Il record di pairing è la fonte di verità durevole per i ruoli approvati. I token attivi del
|
||||
dispositivo restano vincolati a quell'insieme di ruoli approvati; una voce token isolata
|
||||
- L’API legacy `node.pair.*` (CLI: `openclaw nodes pending|approve|reject|rename`) è un
|
||||
archivio di associazione separato gestito dal gateway. I Node WS richiedono comunque l’associazione del dispositivo.
|
||||
- Il record di associazione è la fonte di verità durevole per i ruoli approvati. I token del
|
||||
dispositivo attivi restano limitati a quell’insieme di ruoli approvati; una voce token errata
|
||||
al di fuori dei ruoli approvati non crea nuovo accesso.
|
||||
|
||||
## Documenti correlati
|
||||
|
||||
- Modello di sicurezza + prompt injection: [Security](/gateway/security)
|
||||
- Aggiornare in sicurezza (esegui doctor): [Updating](/install/updating)
|
||||
- Modello di sicurezza + prompt injection: [Security](/it/gateway/security)
|
||||
- Aggiornare in sicurezza (esegui doctor): [Updating](/it/install/updating)
|
||||
- Configurazioni dei canali:
|
||||
- Telegram: [Telegram](/channels/telegram)
|
||||
- WhatsApp: [WhatsApp](/channels/whatsapp)
|
||||
- Signal: [Signal](/channels/signal)
|
||||
- BlueBubbles (iMessage): [BlueBubbles](/channels/bluebubbles)
|
||||
- iMessage (legacy): [iMessage](/channels/imessage)
|
||||
- Discord: [Discord](/channels/discord)
|
||||
- Slack: [Slack](/channels/slack)
|
||||
- Telegram: [Telegram](/it/channels/telegram)
|
||||
- WhatsApp: [WhatsApp](/it/channels/whatsapp)
|
||||
- Signal: [Signal](/it/channels/signal)
|
||||
- BlueBubbles (iMessage): [BlueBubbles](/it/channels/bluebubbles)
|
||||
- iMessage (legacy): [iMessage](/it/channels/imessage)
|
||||
- Discord: [Discord](/it/channels/discord)
|
||||
- Slack: [Slack](/it/channels/slack)
|
||||
|
||||
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- Quando lavori su funzionalità Telegram o webhook
|
||||
- Lavorare sulle funzionalità di Telegram o sui Webhook
|
||||
summary: Stato del supporto del bot Telegram, capacità e configurazione
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:47:50Z"
|
||||
generated_at: "2026-04-20T08:30:49Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 39fbf328375fbc5d08ec2e3eed58b19ee0afa102010ecbc02e074a310ced157e
|
||||
source_hash: b9903fae98bca0c345aa86d5c29015539c375442524a34d26bd28181470b8477
|
||||
source_path: channels/telegram.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Telegram (Bot API)
|
||||
|
||||
Stato: pronto per la produzione per DM bot + gruppi tramite grammY. Il long polling è la modalità predefinita; la modalità webhook è opzionale.
|
||||
Stato: pronto per la produzione per DM bot + gruppi tramite grammY. Il long polling è la modalità predefinita; la modalità Webhook è facoltativa.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Abbinamento" icon="link" href="/it/channels/pairing">
|
||||
La policy DM predefinita per Telegram è l'abbinamento.
|
||||
Il criterio DM predefinito per Telegram è l'abbinamento.
|
||||
</Card>
|
||||
<Card title="Risoluzione dei problemi del canale" icon="wrench" href="/channels/troubleshooting">
|
||||
Diagnostica cross-channel e playbook di riparazione.
|
||||
<Card title="Risoluzione dei problemi del canale" icon="wrench" href="/it/channels/troubleshooting">
|
||||
Diagnostica tra canali e procedure di ripristino.
|
||||
</Card>
|
||||
<Card title="Configurazione del gateway" icon="settings" href="/gateway/configuration">
|
||||
Modelli di configurazione completi del canale ed esempi.
|
||||
<Card title="Configurazione del Gateway" icon="settings" href="/it/gateway/configuration">
|
||||
Modelli ed esempi completi di configurazione dei canali.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -32,13 +32,13 @@ Stato: pronto per la produzione per DM bot + gruppi tramite grammY. Il long poll
|
||||
|
||||
<Steps>
|
||||
<Step title="Crea il token del bot in BotFather">
|
||||
Apri Telegram e avvia una chat con **@BotFather** (conferma che l'handle sia esattamente `@BotFather`).
|
||||
Apri Telegram e chatta con **@BotFather** (verifica che l'handle sia esattamente `@BotFather`).
|
||||
|
||||
Esegui `/newbot`, segui le istruzioni e salva il token.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Configura token e policy DM">
|
||||
<Step title="Configura il token e il criterio DM">
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -54,7 +54,7 @@ Stato: pronto per la produzione per DM bot + gruppi tramite grammY. Il long poll
|
||||
```
|
||||
|
||||
Fallback env: `TELEGRAM_BOT_TOKEN=...` (solo account predefinito).
|
||||
Telegram **non** usa `openclaw channels login telegram`; configura il token in config/env, poi avvia il gateway.
|
||||
Telegram **non** usa `openclaw channels login telegram`; configura il token nel config/env, quindi avvia il gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -76,32 +76,32 @@ openclaw pairing approve telegram <CODE>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
L'ordine di risoluzione del token è sensibile all'account. In pratica, i valori della config hanno priorità rispetto al fallback env, e `TELEGRAM_BOT_TOKEN` si applica solo all'account predefinito.
|
||||
L'ordine di risoluzione del token è sensibile all'account. In pratica, i valori del config hanno priorità sul fallback env e `TELEGRAM_BOT_TOKEN` si applica solo all'account predefinito.
|
||||
</Note>
|
||||
|
||||
## Impostazioni lato Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Modalità privacy e visibilità nei gruppi">
|
||||
I bot Telegram usano per impostazione predefinita la **Modalità privacy**, che limita i messaggi di gruppo che ricevono.
|
||||
I bot Telegram usano per impostazione predefinita la **Modalità Privacy**, che limita i messaggi di gruppo che possono ricevere.
|
||||
|
||||
Se il bot deve vedere tutti i messaggi del gruppo, puoi:
|
||||
|
||||
- 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 modifichi la modalità privacy, rimuovi e riaggiungi il bot in ogni gruppo in modo che Telegram applichi la modifica.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Permessi di gruppo">
|
||||
<Accordion title="Permessi del gruppo">
|
||||
Lo stato di amministratore è controllato nelle impostazioni del gruppo Telegram.
|
||||
|
||||
I bot amministratori ricevono tutti i messaggi del gruppo, il che è utile per un comportamento di gruppo sempre attivo.
|
||||
I bot amministratori ricevono tutti i messaggi del gruppo, il che è utile per un comportamento sempre attivo nel gruppo.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Impostazioni BotFather utili">
|
||||
<Accordion title="Impostazioni utili di BotFather">
|
||||
|
||||
- `/setjoingroups` per consentire/negare l'aggiunta ai gruppi
|
||||
- `/setprivacy` per il comportamento di visibilità nei gruppi
|
||||
@ -112,7 +112,7 @@ L'ordine di risoluzione del token è sensibile all'account. In pratica, i valori
|
||||
## Controllo degli accessi e attivazione
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Policy DM">
|
||||
<Tab title="Criterio DM">
|
||||
`channels.telegram.dmPolicy` controlla l'accesso ai messaggi diretti:
|
||||
|
||||
- `pairing` (predefinito)
|
||||
@ -121,20 +121,20 @@ L'ordine di risoluzione del token è sensibile all'account. In pratica, i valori
|
||||
- `disabled`
|
||||
|
||||
`channels.telegram.allowFrom` accetta ID utente Telegram numerici. I prefissi `telegram:` / `tg:` sono accettati e normalizzati.
|
||||
`dmPolicy: "allowlist"` con `allowFrom` vuoto blocca tutti i DM ed è rifiutato dalla validazione della config.
|
||||
L'onboarding accetta input `@username` e lo risolve in ID numerici.
|
||||
Se hai eseguito un aggiornamento e la tua config contiene voci allowlist `@username`, esegui `openclaw doctor --fix` per risolverle (best-effort; richiede un token bot Telegram).
|
||||
Se in precedenza ti affidavi ai file allowlist del pairing-store, `openclaw doctor --fix` può recuperare le voci in `channels.telegram.allowFrom` nei flussi allowlist (per esempio quando `dmPolicy: "allowlist"` non ha ancora ID espliciti).
|
||||
`dmPolicy: "allowlist"` con `allowFrom` vuoto blocca tutti i DM ed è rifiutato dalla validazione della configurazione.
|
||||
La configurazione richiede solo ID utente numerici.
|
||||
Se hai effettuato un aggiornamento e il tuo config contiene voci allowlist `@username`, esegui `openclaw doctor --fix` per risolverle (best-effort; richiede un token bot Telegram).
|
||||
Se in precedenza facevi affidamento sui file allowlist del pairing-store, `openclaw doctor --fix` può recuperare le voci in `channels.telegram.allowFrom` nei flussi allowlist (ad esempio quando `dmPolicy: "allowlist"` non ha ancora ID espliciti).
|
||||
|
||||
Per bot con un solo proprietario, preferisci `dmPolicy: "allowlist"` con ID `allowFrom` numerici espliciti per mantenere durevole la policy di accesso nella config (invece di dipendere da precedenti approvazioni di abbinamento).
|
||||
Per i bot con un solo proprietario, preferisci `dmPolicy: "allowlist"` con ID `allowFrom` numerici espliciti per mantenere duraturo il criterio di accesso nella configurazione (invece di dipendere da approvazioni di abbinamento precedenti).
|
||||
|
||||
Confusione comune: l'approvazione dell'abbinamento DM non significa "questo mittente è autorizzato ovunque".
|
||||
L'abbinamento concede solo l'accesso DM. L'autorizzazione del mittente nei gruppi deriva ancora da allowlist esplicite nella config.
|
||||
Se vuoi "sono autorizzato una volta sola e funzionano sia i DM sia i comandi di gruppo", inserisci il tuo ID utente Telegram numerico in `channels.telegram.allowFrom`.
|
||||
L'abbinamento concede solo l'accesso ai DM. L'autorizzazione del mittente nei gruppi continua invece a dipendere da allowlist esplicite nel config.
|
||||
Se vuoi che "io sia autorizzato una volta sola e che funzionino sia i DM sia i comandi nei gruppi", inserisci il tuo ID utente Telegram numerico in `channels.telegram.allowFrom`.
|
||||
|
||||
### Trovare il tuo ID utente Telegram
|
||||
|
||||
Metodo più sicuro (senza bot di terze parti):
|
||||
Più sicuro (nessun bot di terze parti):
|
||||
|
||||
1. Invia un DM al tuo bot.
|
||||
2. Esegui `openclaw logs --follow`.
|
||||
@ -150,13 +150,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Policy di gruppo e allowlist">
|
||||
<Tab title="Criterio di gruppo e allowlist">
|
||||
Si applicano insieme due controlli:
|
||||
|
||||
1. **Quali gruppi sono consentiti** (`channels.telegram.groups`)
|
||||
- nessuna config `groups`:
|
||||
- con `groupPolicy: "open"`: qualsiasi gruppo può superare i controlli dell'ID gruppo
|
||||
- con `groupPolicy: "allowlist"` (predefinito): i gruppi sono bloccati finché non aggiungi voci a `groups` (o `"*"`)
|
||||
- nessun config `groups`:
|
||||
- con `groupPolicy: "open"`: qualsiasi gruppo può superare i controlli sull'ID gruppo
|
||||
- con `groupPolicy: "allowlist"` (predefinito): i gruppi sono bloccati finché non aggiungi voci in `groups` (o `"*"`)
|
||||
- `groups` configurato: agisce come allowlist (ID espliciti o `"*"`)
|
||||
|
||||
2. **Quali mittenti sono consentiti nei gruppi** (`channels.telegram.groupPolicy`)
|
||||
@ -165,16 +165,16 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` è usato per il filtro dei mittenti nei gruppi. Se non è impostato, Telegram usa `allowFrom` come fallback.
|
||||
Le voci `groupAllowFrom` devono essere ID utente Telegram numerici (`telegram:` / `tg:` sono normalizzati).
|
||||
Non inserire ID chat di gruppi o supergruppi Telegram in `groupAllowFrom`. Gli ID chat negativi vanno sotto `channels.telegram.groups`.
|
||||
Le voci non numeriche vengono ignorate per l'autorizzazione del mittente.
|
||||
Limite di sicurezza (`2026.2.25+`): l'autorizzazione del mittente nei gruppi **non** eredita le approvazioni DM del pairing-store.
|
||||
L'abbinamento resta solo per i DM. Per i gruppi, imposta `groupAllowFrom` o `allowFrom` per gruppo/per topic.
|
||||
Se `groupAllowFrom` non è impostato, Telegram usa come fallback `allowFrom` della config, non il pairing store.
|
||||
Modello pratico per bot con un solo proprietario: imposta il tuo ID utente in `channels.telegram.allowFrom`, lascia `groupAllowFrom` non impostato e consenti i gruppi target sotto `channels.telegram.groups`.
|
||||
Nota runtime: se `channels.telegram` manca completamente, i valori predefiniti di runtime sono fail-closed con `groupPolicy="allowlist"` a meno che `channels.defaults.groupPolicy` non sia impostato esplicitamente.
|
||||
Le voci di `groupAllowFrom` devono essere ID utente Telegram numerici (i prefissi `telegram:` / `tg:` sono normalizzati).
|
||||
Non inserire ID chat di gruppo o supergruppo Telegram in `groupAllowFrom`. Gli ID chat negativi appartengono a `channels.telegram.groups`.
|
||||
Le voci non numeriche sono ignorate per l'autorizzazione del mittente.
|
||||
Confine di sicurezza (`2026.2.25+`): l'autorizzazione dei mittenti nei gruppi **non** eredita le approvazioni del pairing-store dei DM.
|
||||
L'abbinamento resta solo per i DM. Per i gruppi, imposta `groupAllowFrom` oppure `allowFrom` per gruppo/per topic.
|
||||
Se `groupAllowFrom` non è impostato, Telegram usa come fallback `allowFrom` dal config, non il pairing store.
|
||||
Modello pratico per bot con un solo proprietario: imposta il tuo ID utente in `channels.telegram.allowFrom`, lascia `groupAllowFrom` non impostato e consenti i gruppi di destinazione in `channels.telegram.groups`.
|
||||
Nota di runtime: se `channels.telegram` manca completamente, i valori predefiniti di runtime sono fail-closed con `groupPolicy="allowlist"`, a meno che `channels.defaults.groupPolicy` non sia impostato esplicitamente.
|
||||
|
||||
Esempio: consenti qualsiasi membro in un gruppo specifico:
|
||||
Esempio: consenti qualsiasi membro in uno specifico gruppo:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -191,7 +191,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Esempio: consenti solo utenti specifici in un gruppo specifico:
|
||||
Esempio: consenti solo utenti specifici in uno specifico gruppo:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -211,31 +211,31 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Warning>
|
||||
Errore comune: `groupAllowFrom` non è una allowlist di gruppi Telegram.
|
||||
|
||||
- Inserisci gli ID negativi di gruppi o supergruppi Telegram come `-1001234567890` sotto `channels.telegram.groups`.
|
||||
- Inserisci ID utente Telegram come `8734062810` sotto `groupAllowFrom` quando vuoi limitare quali persone all'interno di un gruppo consentito possono attivare il bot.
|
||||
- Inserisci ID negativi di gruppi o supergruppi Telegram come `-1001234567890` sotto `channels.telegram.groups`.
|
||||
- Inserisci ID utente Telegram come `8734062810` sotto `groupAllowFrom` quando vuoi limitare quali persone, all'interno di un gruppo consentito, possono attivare il bot.
|
||||
- Usa `groupAllowFrom: ["*"]` solo quando vuoi che qualsiasi membro di un gruppo consentito possa parlare con il bot.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Comportamento delle menzioni">
|
||||
Le risposte nei gruppi richiedono una menzione per impostazione predefinita.
|
||||
Per impostazione predefinita, le risposte nei gruppi richiedono una menzione.
|
||||
|
||||
La menzione può arrivare da:
|
||||
La menzione può provenire da:
|
||||
|
||||
- menzione nativa `@botusername`, oppure
|
||||
- pattern di menzione in:
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
Interruttori dei comandi a livello di sessione:
|
||||
Attivazioni dei comandi a livello di sessione:
|
||||
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Questi aggiornano solo lo stato della sessione. Usa la config per la persistenza.
|
||||
Questi aggiornano solo lo stato della sessione. Usa il config per la persistenza.
|
||||
|
||||
Esempio di config persistente:
|
||||
Esempio di configurazione persistente:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -249,29 +249,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Ottenere l'ID chat del gruppo:
|
||||
Ottenere l'ID della chat di gruppo:
|
||||
|
||||
- inoltra un messaggio del gruppo a `@userinfobot` / `@getidsbot`
|
||||
- inoltra un messaggio di gruppo a `@userinfobot` / `@getidsbot`
|
||||
- oppure leggi `chat.id` da `openclaw logs --follow`
|
||||
- oppure ispeziona Bot API `getUpdates`
|
||||
- oppure ispeziona `getUpdates` della Bot API
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Comportamento runtime
|
||||
## Comportamento di runtime
|
||||
|
||||
- Telegram è gestito dal processo gateway.
|
||||
- Il routing è deterministico: le risposte in ingresso da Telegram tornano su Telegram (il modello non sceglie i canali).
|
||||
- I messaggi in ingresso vengono normalizzati nell'envelope condivisa del canale con metadati di risposta e segnaposto media.
|
||||
- I messaggi in ingresso sono normalizzati nell'envelope condivisa del canale con metadati di risposta e segnaposto per i media.
|
||||
- Le sessioni di gruppo sono isolate per ID gruppo. I topic del forum aggiungono `:topic:<threadId>` per mantenere i topic isolati.
|
||||
- I messaggi DM possono includere `message_thread_id`; OpenClaw li instrada con chiavi di sessione sensibili al thread e preserva l'ID del thread per le risposte.
|
||||
- Il long polling usa grammY runner con sequenziamento per chat/per thread. La concorrenza complessiva del runner sink usa `agents.defaults.maxConcurrent`.
|
||||
- Telegram Bot API non supporta le conferme di lettura (`sendReadReceipts` non si applica).
|
||||
- I messaggi DM possono includere `message_thread_id`; OpenClaw li instrada con chiavi di sessione sensibili al thread e preserva l'ID thread per le risposte.
|
||||
- Il long polling usa il runner grammY con sequenziamento per chat/per thread. La concorrenza complessiva del runner sink usa `agents.defaults.maxConcurrent`.
|
||||
- La Telegram Bot API non supporta le conferme di lettura (`sendReadReceipts` non si applica).
|
||||
|
||||
## Riferimento delle funzionalità
|
||||
## Riferimento funzionalità
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Anteprima live dello stream (modifiche ai messaggi)">
|
||||
<Accordion title="Anteprima del flusso live (modifiche ai messaggi)">
|
||||
OpenClaw può trasmettere risposte parziali in tempo reale:
|
||||
|
||||
- chat dirette: messaggio di anteprima + `editMessageText`
|
||||
@ -281,23 +281,23 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `channels.telegram.streaming` è `off | partial | block | progress` (predefinito: `partial`)
|
||||
- `progress` corrisponde a `partial` su Telegram (compatibilità con la denominazione cross-channel)
|
||||
- i valori legacy `channels.telegram.streamMode` e booleani `streaming` vengono mappati automaticamente
|
||||
- i valori legacy `channels.telegram.streamMode` e booleani `streaming` sono mappati automaticamente
|
||||
|
||||
Per risposte solo testo:
|
||||
|
||||
- DM: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale in place (nessun secondo messaggio)
|
||||
- gruppo/topic: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale in place (nessun secondo messaggio)
|
||||
- DM: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale sul posto (nessun secondo messaggio)
|
||||
- gruppo/topic: OpenClaw mantiene lo stesso messaggio di anteprima ed esegue una modifica finale sul posto (nessun secondo messaggio)
|
||||
|
||||
Per risposte complesse (per esempio payload media), OpenClaw torna alla normale consegna finale e poi rimuove il messaggio di anteprima.
|
||||
Per risposte complesse (ad esempio payload media), OpenClaw usa come fallback la normale consegna finale e poi rimuove il messaggio di anteprima.
|
||||
|
||||
Lo streaming di anteprima è separato dallo streaming a blocchi. Quando lo streaming a blocchi è abilitato esplicitamente per Telegram, OpenClaw salta lo stream di anteprima per evitare il doppio streaming.
|
||||
L'anteprima in streaming è separata dal block streaming. Quando il block streaming è esplicitamente abilitato per Telegram, OpenClaw salta l'anteprima in streaming per evitare uno streaming doppio.
|
||||
|
||||
Se il trasporto draft nativo non è disponibile/viene rifiutato, OpenClaw usa automaticamente `sendMessage` + `editMessageText` come fallback.
|
||||
Se il trasporto bozza nativo non è disponibile/viene rifiutato, OpenClaw usa automaticamente come fallback `sendMessage` + `editMessageText`.
|
||||
|
||||
Stream di reasoning solo Telegram:
|
||||
Flusso di ragionamento solo Telegram:
|
||||
|
||||
- `/reasoning stream` invia il reasoning all'anteprima live durante la generazione
|
||||
- la risposta finale viene inviata senza testo di reasoning
|
||||
- `/reasoning stream` invia il ragionamento all'anteprima live durante la generazione
|
||||
- la risposta finale viene inviata senza testo di ragionamento
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -305,7 +305,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Il testo in uscita usa Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Il testo in stile Markdown viene renderizzato in HTML sicuro per Telegram.
|
||||
- L'HTML grezzo del modello viene escapato per ridurre gli errori di parsing di Telegram.
|
||||
- L'HTML grezzo del modello viene escaped per ridurre gli errori di parsing di Telegram.
|
||||
- Se Telegram rifiuta l'HTML parsato, OpenClaw ritenta come testo semplice.
|
||||
|
||||
Le anteprime dei link sono abilitate per impostazione predefinita e possono essere disabilitate con `channels.telegram.linkPreview: false`.
|
||||
@ -336,7 +336,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Regole:
|
||||
|
||||
- i nomi vengono normalizzati (rimozione di `/` iniziale, minuscolo)
|
||||
- i nomi sono normalizzati (rimozione di `/` iniziale, minuscolo)
|
||||
- pattern valido: `a-z`, `0-9`, `_`, lunghezza `1..32`
|
||||
- i comandi personalizzati non possono sovrascrivere i comandi nativi
|
||||
- conflitti/duplicati vengono saltati e registrati nei log
|
||||
@ -344,13 +344,13 @@ 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/Skills possono comunque funzionare se digitati, anche se non mostrati nel menu Telegram
|
||||
- i comandi plugin/Skills possono comunque funzionare se digitati, anche se non sono mostrati nel menu Telegram
|
||||
|
||||
Se i comandi nativi sono disabilitati, i comandi built-in vengono rimossi. I comandi personalizzati/plugin possono comunque essere registrati se configurati.
|
||||
Se i comandi nativi sono disabilitati, i built-in vengono rimossi. I comandi personalizzati/plugin possono comunque essere registrati se configurati.
|
||||
|
||||
Errori comuni di configurazione:
|
||||
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu Telegram è ancora troppo pieno dopo il trimming; riduci plugin/Skills/comandi personalizzati o disabilita `channels.telegram.commands.native`.
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu Telegram continua a essere troppo pieno dopo il trimming; riduci i comandi plugin/Skills/personalizzati o disabilita `channels.telegram.commands.native`.
|
||||
- `setMyCommands failed` con errori di rete/fetch di solito significa che il DNS/HTTPS in uscita verso `api.telegram.org` è bloccato.
|
||||
|
||||
### Comandi di abbinamento dispositivo (plugin `device-pair`)
|
||||
@ -359,15 +359,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
1. `/pair` genera un codice di configurazione
|
||||
2. incolla il codice nell'app iOS
|
||||
3. `/pair pending` elenca le richieste in attesa (inclusi ruolo/scopes)
|
||||
3. `/pair pending` elenca le richieste in sospeso (inclusi ruolo/scopes)
|
||||
4. approva la richiesta:
|
||||
- `/pair approve <requestId>` per approvazione esplicita
|
||||
- `/pair approve` quando c'è una sola richiesta in attesa
|
||||
- `/pair approve <requestId>` per l'approvazione esplicita
|
||||
- `/pair approve` quando c'è una sola richiesta in sospeso
|
||||
- `/pair approve latest` per la più recente
|
||||
|
||||
Il codice di configurazione contiene un token bootstrap a vita breve. Il passaggio bootstrap built-in mantiene il token del nodo primario con `scopes: []`; qualsiasi token operatore passato resta limitato a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. I controlli bootstrap degli scope usano prefissi di ruolo, quindi quella allowlist operatore soddisfa solo richieste operatore; i ruoli non operatore richiedono ancora scope sotto il proprio prefisso di ruolo.
|
||||
Il codice di configurazione contiene un token bootstrap a breve durata. Il passaggio bootstrap integrato mantiene il token del Node primario con `scopes: []`; qualsiasi token operatore trasferito resta limitato a `operator.approvals`, `operator.read`, `operator.talk.secrets` e `operator.write`. I controlli degli scope bootstrap usano prefissi basati sul ruolo, quindi tale allowlist dell'operatore soddisfa solo le richieste dell'operatore; i ruoli non operatore richiedono comunque scopes sotto il proprio prefisso di ruolo.
|
||||
|
||||
Se un dispositivo riprova con dettagli auth cambiati (per esempio ruolo/scopes/chiave pubblica), la precedente richiesta in attesa viene sostituita e la nuova richiesta usa un `requestId` diverso. Esegui di nuovo `/pair pending` prima di approvare.
|
||||
Se un dispositivo riprova con dettagli di autenticazione modificati (ad esempio ruolo/scopes/chiave pubblica), la precedente richiesta in sospeso viene sostituita e la nuova richiesta usa un `requestId` diverso. Esegui di nuovo `/pair pending` prima di approvare.
|
||||
|
||||
Maggiori dettagli: [Abbinamento](/it/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
@ -406,7 +406,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Ambiti:
|
||||
Scopes:
|
||||
|
||||
- `off`
|
||||
- `dm`
|
||||
@ -440,13 +440,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Azioni messaggio Telegram per agenti e automazione">
|
||||
Le azioni tool Telegram includono:
|
||||
Le azioni strumento Telegram includono:
|
||||
|
||||
- `sendMessage` (`to`, `content`, opzionale `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `sendMessage` (`to`, `content`, facoltativi `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `react` (`chatId`, `messageId`, `emoji`)
|
||||
- `deleteMessage` (`chatId`, `messageId`)
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, opzionale `iconColor`, `iconCustomEmojiId`)
|
||||
- `createForumTopic` (`chatId`, `name`, facoltativi `iconColor`, `iconCustomEmojiId`)
|
||||
|
||||
Le azioni messaggio del canale espongono alias ergonomici (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
@ -458,9 +458,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `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 config/secrets (avvio/ricarica), quindi i percorsi azione non eseguono una nuova risoluzione ad hoc di SecretRef per ogni invio.
|
||||
Gli invii a runtime usano l'istantanea attiva di config/segreti (avvio/ricarica), quindi i percorsi azione non eseguono una nuova risoluzione ad hoc di SecretRef per ogni invio.
|
||||
|
||||
Semantica di rimozione delle reazioni: [/tools/reactions](/tools/reactions)
|
||||
Semantica della rimozione delle reazioni: [/tools/reactions](/it/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -484,19 +484,19 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Supergruppi forum:
|
||||
|
||||
- le chiavi di sessione del topic aggiungono `:topic:<threadId>`
|
||||
- le risposte e l'indicatore di digitazione puntano al thread del topic
|
||||
- le risposte e la digitazione sono indirizzate al thread del topic
|
||||
- percorso config del topic:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Caso speciale del topic generale (`threadId=1`):
|
||||
|
||||
- l'invio dei messaggi omette `message_thread_id` (Telegram rifiuta `sendMessage(...thread_id=1)`)
|
||||
- gli invii di messaggi omettono `message_thread_id` (Telegram rifiuta `sendMessage(...thread_id=1)`)
|
||||
- le azioni di digitazione includono comunque `message_thread_id`
|
||||
|
||||
Ereditarietà dei topic: le voci del 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.
|
||||
Ereditarietà dei topic: le voci topic ereditano le impostazioni del gruppo salvo override (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` è solo del topic e non viene ereditato dalle impostazioni predefinite del gruppo.
|
||||
|
||||
**Routing agente per topic**: ogni topic può instradare verso un agente diverso impostando `agentId` nella config del topic. Questo fornisce a ogni topic il proprio workspace, memoria e sessione isolati. Esempio:
|
||||
**Instradamento agente per topic**: ogni topic può essere instradato a un agente diverso impostando `agentId` nel config del topic. Questo assegna a ogni topic il proprio workspace, memoria e sessione isolati. Esempio:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -506,7 +506,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
"-1001234567890": {
|
||||
topics: {
|
||||
"1": { agentId: "main" }, // Topic generale → agente main
|
||||
"3": { agentId: "zu" }, // Topic dev → agente zu
|
||||
"3": { agentId: "zu" }, // Topic sviluppo → agente zu
|
||||
"5": { agentId: "coder" } // Revisione codice → agente coder
|
||||
}
|
||||
}
|
||||
@ -569,13 +569,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Attualmente questo è limitato ai topic del forum in gruppi e supergruppi.
|
||||
Questo è attualmente limitato ai topic del forum in gruppi e supergruppi.
|
||||
|
||||
**Avvio ACP vincolato al thread dalla chat**:
|
||||
**Spawn ACP vincolato al thread dalla chat**:
|
||||
|
||||
- `/acp spawn <agent> --thread here|auto` può associare il topic Telegram corrente a una nuova sessione ACP.
|
||||
- I messaggi successivi nel topic vengono instradati direttamente alla sessione ACP associata (non è richiesto `/acp steer`).
|
||||
- OpenClaw fissa il messaggio di conferma dell'avvio nel topic dopo un'associazione riuscita.
|
||||
- I messaggi successivi nel topic vengono instradati direttamente alla sessione ACP associata (senza bisogno di `/acp steer`).
|
||||
- OpenClaw fissa il messaggio di conferma dello spawn nel topic dopo un binding riuscito.
|
||||
- Richiede `channels.telegram.threadBindings.spawnAcpSessions=true`.
|
||||
|
||||
Il contesto del template include:
|
||||
@ -583,9 +583,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `MessageThreadId`
|
||||
- `IsForum`
|
||||
|
||||
Comportamento del thread DM:
|
||||
Comportamento thread nei DM:
|
||||
|
||||
- le chat private con `message_thread_id` mantengono il routing DM ma usano chiavi di sessione e target di risposta sensibili al thread.
|
||||
- le chat private con `message_thread_id` mantengono l'instradamento DM ma usano chiavi di sessione e destinazioni di risposta sensibili al thread.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -625,7 +625,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Le video note non supportano didascalie; il testo del messaggio fornito viene inviato separatamente.
|
||||
Le video note non supportano didascalie; l'eventuale testo del messaggio viene inviato separatamente.
|
||||
|
||||
### Sticker
|
||||
|
||||
@ -635,7 +635,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- TGS animato: ignorato
|
||||
- WEBM video: ignorato
|
||||
|
||||
Campi di contesto sticker:
|
||||
Campi del contesto sticker:
|
||||
|
||||
- `Sticker.emoji`
|
||||
- `Sticker.setName`
|
||||
@ -647,7 +647,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Gli sticker vengono descritti una volta (quando possibile) e memorizzati nella cache per ridurre chiamate ripetute alla vision.
|
||||
Gli sticker vengono descritti una sola volta (quando possibile) e memorizzati in cache per ridurre le chiamate ripetute alla visione.
|
||||
|
||||
Abilita le azioni sticker:
|
||||
|
||||
@ -663,7 +663,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Azione di invio sticker:
|
||||
Azione per inviare uno sticker:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -674,7 +674,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Cerca sticker nella cache:
|
||||
Cerca negli sticker in cache:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -692,7 +692,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Quando abilitato, OpenClaw mette in coda eventi di sistema come:
|
||||
|
||||
- `Telegram reaction added: 👍 by Alice (@alice) on msg 42`
|
||||
- `Reazione Telegram aggiunta: 👍 da Alice (@alice) al msg 42`
|
||||
|
||||
Config:
|
||||
|
||||
@ -701,40 +701,40 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Note:
|
||||
|
||||
- `own` significa solo reazioni utente ai messaggi inviati dal bot (best-effort tramite cache dei messaggi inviati).
|
||||
- `own` significa solo reazioni dell'utente 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 di reazione.
|
||||
- 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 di origine esatto
|
||||
- i gruppi forum vengono instradati alla sessione del topic generale del gruppo (`:topic:1`), non all'esatto topic di origine
|
||||
|
||||
`allowed_updates` per polling/webhook include automaticamente `message_reaction`.
|
||||
`allowed_updates` per polling/Webhook include automaticamente `message_reaction`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reazioni di conferma">
|
||||
`ackReaction` invia un'emoji di conferma mentre OpenClaw elabora un messaggio in ingresso.
|
||||
<Accordion title="Reazioni di 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 identità agente (`agents.list[].identity.emoji`, altrimenti "👀")
|
||||
- fallback all'emoji identità dell'agente (`agents.list[].identity.emoji`, altrimenti "👀")
|
||||
|
||||
Note:
|
||||
|
||||
- Telegram si aspetta emoji unicode (per esempio "👀").
|
||||
- Telegram si aspetta emoji unicode (ad esempio "👀").
|
||||
- Usa `""` per disabilitare la reazione per un canale o account.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Scritture di config da eventi e comandi Telegram">
|
||||
Le scritture della config del canale sono abilitate per impostazione predefinita (`configWrites !== false`).
|
||||
<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:
|
||||
|
||||
- eventi di migrazione del gruppo (`migrate_to_chat_id`) per aggiornare `channels.telegram.groups`
|
||||
- `/config set` e `/config unset` (richiede l'abilitazione del comando)
|
||||
- `/config set` e `/config unset` (richiede l'abilitazione dei comandi)
|
||||
|
||||
Disabilita:
|
||||
|
||||
@ -750,45 +750,45 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Long polling vs webhook">
|
||||
<Accordion title="Long polling vs Webhook">
|
||||
Predefinito: long polling.
|
||||
|
||||
Modalità webhook:
|
||||
Modalità Webhook:
|
||||
|
||||
- imposta `channels.telegram.webhookUrl`
|
||||
- imposta `channels.telegram.webhookSecret` (obbligatorio quando è impostato l'URL webhook)
|
||||
- opzionale `channels.telegram.webhookPath` (predefinito `/telegram-webhook`)
|
||||
- opzionale `channels.telegram.webhookHost` (predefinito `127.0.0.1`)
|
||||
- opzionale `channels.telegram.webhookPort` (predefinito `8787`)
|
||||
- imposta `channels.telegram.webhookSecret` (obbligatorio quando è impostato l'URL Webhook)
|
||||
- `channels.telegram.webhookPath` facoltativo (predefinito `/telegram-webhook`)
|
||||
- `channels.telegram.webhookHost` facoltativo (predefinito `127.0.0.1`)
|
||||
- `channels.telegram.webhookPort` facoltativo (predefinito `8787`)
|
||||
|
||||
Il listener locale predefinito per la modalità webhook si collega a `127.0.0.1:8787`.
|
||||
Il listener locale predefinito per la modalità Webhook si associa a `127.0.0.1:8787`.
|
||||
|
||||
Se il tuo endpoint pubblico è diverso, metti un reverse proxy davanti e punta `webhookUrl` all'URL pubblico.
|
||||
Imposta `webhookHost` (per esempio `0.0.0.0`) quando hai intenzionalmente bisogno di ingress esterno.
|
||||
Imposta `webhookHost` (ad esempio `0.0.0.0`) quando hai intenzionalmente bisogno di ingress esterno.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Limiti, retry e target CLI">
|
||||
<Accordion title="Limiti, retry 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.mediaMaxMb` (predefinito 100) impone un limite alla dimensione dei media Telegram in ingresso e in uscita.
|
||||
- `channels.telegram.timeoutSeconds` sovrascrive il timeout del client Telegram API (se non impostato, si applica il valore predefinito di grammY).
|
||||
- la cronologia del contesto di gruppo usa `channels.telegram.historyLimit` o `messages.groupChat.historyLimit` (predefinito 50); `0` la disabilita.
|
||||
- il contesto supplementare di risposta/citazione/inoltro è attualmente passato così come ricevuto.
|
||||
- le allowlist Telegram regolano principalmente chi può attivare l'agente, non un limite completo di redazione del contesto supplementare.
|
||||
- controlli cronologia DM:
|
||||
- il contesto supplementare di risposta/citazione/inoltro viene attualmente passato così come ricevuto.
|
||||
- le allowlist Telegram limitano 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 config `channels.telegram.retry` si applica agli helper di invio Telegram (CLI/tools/actions) per errori API in uscita recuperabili.
|
||||
- la configurazione `channels.telegram.retry` si applica agli helper di invio Telegram (CLI/tools/actions) per gli errori recuperabili della API in uscita.
|
||||
|
||||
Il target di invio CLI può essere un ID chat numerico o un username:
|
||||
La destinazione di invio CLI può essere un ID chat numerico o un username:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
openclaw message send --channel telegram --target @name --message "hi"
|
||||
```
|
||||
|
||||
I sondaggi Telegram usano `openclaw message poll` e supportano i topic del forum:
|
||||
I poll Telegram usano `openclaw message poll` e supportano i topic del forum:
|
||||
|
||||
```bash
|
||||
openclaw message poll --channel telegram --target 123456789 \
|
||||
@ -798,79 +798,79 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
--poll-duration-seconds 300 --poll-public
|
||||
```
|
||||
|
||||
Flag dei sondaggi solo Telegram:
|
||||
Flag dei poll solo per Telegram:
|
||||
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- `--thread-id` per i topic del forum (oppure usa un target `:topic:`)
|
||||
- `--thread-id` per i topic del forum (oppure usa una destinazione `:topic:`)
|
||||
|
||||
L'invio Telegram supporta anche:
|
||||
|
||||
- `--buttons` per tastiere inline quando `channels.telegram.capabilities.inlineButtons` lo consente
|
||||
- `--force-document` per inviare immagini e GIF in uscita come documenti invece che come foto compresse o upload di media animati
|
||||
- `--force-document` per inviare immagini e GIF in uscita come documenti invece che come foto compresse o caricamenti di media animati
|
||||
|
||||
Gating 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 i normali invii
|
||||
- `channels.telegram.actions.sendMessage=false` disabilita i messaggi Telegram in uscita, inclusi i poll
|
||||
- `channels.telegram.actions.poll=false` disabilita la creazione di poll Telegram lasciando abilitati i normali invii
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Approvazioni exec in Telegram">
|
||||
Telegram supporta le approvazioni exec nei DM degli approvatori e può opzionalmente pubblicare i prompt di approvazione nella chat o nel topic di origine.
|
||||
Telegram supporta le approvazioni exec nei DM degli approvatori e può facoltativamente pubblicare i prompt di approvazione nella chat o nel topic di origine.
|
||||
|
||||
Percorso config:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled`
|
||||
- `channels.telegram.execApprovals.approvers` (opzionale; usa come fallback gli ID proprietario numerici dedotti da `allowFrom` e `defaultTo` diretto quando possibile)
|
||||
- `channels.telegram.execApprovals.approvers` (facoltativo; usa come fallback gli ID proprietario numerici dedotti da `allowFrom` e da `defaultTo` diretto quando possibile)
|
||||
- `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, predefinito: `dm`)
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
Gli approvatori devono essere ID utente Telegram numerici. Telegram abilita automaticamente le approvazioni exec native quando `enabled` non è impostato o è `"auto"` e almeno un approvatore può essere risolto, o da `execApprovals.approvers` oppure dalla config numerica del proprietario dell'account (`allowFrom` e `defaultTo` dei messaggi diretti). Imposta `enabled: false` per disabilitare esplicitamente Telegram come client di approvazione nativo. Altrimenti le richieste di approvazione usano come fallback altre route di approvazione configurate o la policy di fallback per le approvazioni exec.
|
||||
Gli approvatori devono essere ID utente Telegram numerici. Telegram abilita automaticamente le approvazioni exec native quando `enabled` non è impostato o è `"auto"` e può essere risolto almeno un approvatore, da `execApprovals.approvers` oppure dalla configurazione numerica del proprietario dell'account (`allowFrom` e `defaultTo` del messaggio diretto). Imposta `enabled: false` per disabilitare esplicitamente Telegram come client di approvazione nativo. In caso contrario, le richieste di approvazione usano come fallback altre route di approvazione configurate o il criterio di fallback delle approvazioni exec.
|
||||
|
||||
Telegram renderizza anche i pulsanti di approvazione condivisi usati dagli altri canali chat. L'adapter nativo Telegram aggiunge principalmente il routing ai DM degli approvatori, il fanout verso canali/topic e gli hint di digitazione prima della consegna.
|
||||
Quando questi pulsanti sono presenti, rappresentano la UX di approvazione primaria; OpenClaw
|
||||
dovrebbe includere un comando manuale `/approve` solo quando il risultato del tool indica
|
||||
che le approvazioni in chat non sono disponibili o che l'approvazione manuale è l'unico percorso.
|
||||
Telegram rende anche i pulsanti di approvazione condivisi usati dagli altri canali chat. L'adapter Telegram nativo aggiunge principalmente l'instradamento ai DM degli approvatori, il fanout verso canali/topic e gli indicatori di digitazione prima della consegna.
|
||||
Quando questi pulsanti sono presenti, sono la UX di approvazione primaria; OpenClaw
|
||||
dovrebbe includere un comando manuale `/approve` solo quando il risultato dello strumento indica
|
||||
che le approvazioni via chat non sono disponibili o che l'approvazione manuale è l'unico percorso.
|
||||
|
||||
Regole di consegna:
|
||||
|
||||
- `target: "dm"` invia i prompt di approvazione solo ai DM degli approvatori risolti
|
||||
- `target: "channel"` rimanda il prompt alla chat/topic Telegram di origine
|
||||
- `target: "both"` invia ai DM degli approvatori e alla chat/topic Telegram di origine
|
||||
- `target: "channel"` invia il prompt di nuovo alla chat/topic Telegram di origine
|
||||
- `target: "both"` invia ai DM degli approvatori e alla chat/topic di origine
|
||||
|
||||
Solo gli approvatori risolti possono approvare o negare. I non approvatori non possono usare `/approve` e non possono usare i pulsanti di approvazione Telegram.
|
||||
|
||||
Comportamento di risoluzione dell'approvazione:
|
||||
Comportamento di risoluzione delle approvazioni:
|
||||
|
||||
- gli ID con prefisso `plugin:` vengono sempre risolti tramite approvazioni plugin.
|
||||
- gli altri ID provano prima `exec.approval.resolve`.
|
||||
- Se Telegram è autorizzato anche per approvazioni plugin e il gateway dice
|
||||
- Gli ID con prefisso `plugin:` vengono sempre risolti tramite le approvazioni del plugin.
|
||||
- Gli altri ID di approvazione provano prima `exec.approval.resolve`.
|
||||
- Se Telegram è autorizzato anche per le approvazioni del plugin e il gateway dice
|
||||
che l'approvazione exec è sconosciuta/scaduta, Telegram ritenta una volta tramite
|
||||
`plugin.approval.resolve`.
|
||||
- I rifiuti/errori reali delle approvazioni exec non ricadono silenziosamente sulla
|
||||
risoluzione delle approvazioni plugin.
|
||||
- I dinieghi/errori reali delle approvazioni exec non ricadono silenziosamente sulla
|
||||
risoluzione delle approvazioni del plugin.
|
||||
|
||||
La consegna nel canale mostra il testo del comando nella chat, quindi abilita `channel` o `both` solo in gruppi/topic fidati. Quando il prompt arriva in un topic del forum, OpenClaw preserva il topic sia per il prompt di approvazione sia per il follow-up post-approvazione. Le approvazioni exec scadono per impostazione predefinita dopo 30 minuti.
|
||||
La consegna nel canale mostra il testo del comando nella chat, quindi abilita `channel` o `both` solo in gruppi/topic fidati. Quando il prompt arriva in un topic del forum, OpenClaw preserva il topic sia per il prompt di approvazione sia per il follow-up post-approvazione. Le approvazioni exec scadono dopo 30 minuti per impostazione predefinita.
|
||||
|
||||
I pulsanti di approvazione inline dipendono anche dal fatto che `channels.telegram.capabilities.inlineButtons` consenta la superficie target (`dm`, `group` o `all`).
|
||||
I pulsanti di approvazione inline dipendono anche dal fatto che `channels.telegram.capabilities.inlineButtons` consenta la superficie di destinazione (`dm`, `group` o `all`).
|
||||
|
||||
Documenti correlati: [Approvazioni exec](/tools/exec-approvals)
|
||||
Documentazione correlata: [Approvazioni exec](/it/tools/exec-approvals)
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Controlli delle risposte di errore
|
||||
|
||||
Quando l'agente incontra un errore di consegna o del provider, Telegram può rispondere con il testo dell'errore oppure sopprimerlo. Due chiavi di config controllano questo comportamento:
|
||||
Quando l'agente incontra un errore di consegna o del provider, Telegram può rispondere con il testo dell'errore oppure sopprimerlo. Due chiavi di configurazione controllano questo comportamento:
|
||||
|
||||
| Key | Values | Default | Description |
|
||||
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` invia un messaggio di errore amichevole alla chat. `silent` sopprime completamente le risposte di errore. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Tempo minimo tra risposte di errore alla stessa chat. Previene spam di errori durante interruzioni del servizio. |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` invia un messaggio di errore amichevole nella chat. `silent` sopprime completamente le risposte di errore. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Tempo minimo tra le risposte di errore nella stessa chat. Previene lo spam di errori durante le interruzioni. |
|
||||
|
||||
Sono supportati override per account, gruppo e topic (stessa ereditarietà delle altre chiavi di config Telegram).
|
||||
Sono supportati override per account, per gruppo e per topic (stessa ereditarietà delle altre chiavi di configurazione Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -880,7 +880,7 @@ Sono supportati override per account, gruppo e topic (stessa ereditarietà delle
|
||||
errorCooldownMs: 120000,
|
||||
groups: {
|
||||
"-1001234567890": {
|
||||
errorPolicy: "silent", // sopprimi errori in questo gruppo
|
||||
errorPolicy: "silent", // sopprimi gli errori in questo gruppo
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -895,34 +895,34 @@ Sono supportati override per account, gruppo e topic (stessa ereditarietà delle
|
||||
|
||||
- Se `requireMention=false`, la modalità privacy di Telegram deve consentire piena visibilità.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- poi rimuovi e riaggiungi il bot al gruppo
|
||||
- `openclaw channels status` avvisa quando la config prevede messaggi di gruppo senza menzione.
|
||||
- `openclaw channels status --probe` può controllare ID gruppo numerici espliciti; il carattere jolly `"*"` non può essere verificato come appartenenza.
|
||||
- quindi rimuovi e riaggiungi il bot al gruppo
|
||||
- `openclaw channels status` avvisa quando la configurazione prevede messaggi di gruppo senza menzione.
|
||||
- `openclaw channels status --probe` può controllare ID di gruppo numerici espliciti; il carattere jolly `"*"` non può essere verificato come appartenenza.
|
||||
- test rapido della sessione: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Il bot non vede affatto i messaggi di gruppo">
|
||||
|
||||
- quando `channels.telegram.groups` esiste, il gruppo deve essere elencato (oppure includere `"*"`)
|
||||
- verifica l'appartenenza del bot al gruppo
|
||||
- controlla i log: `openclaw logs --follow` per i motivi di skip
|
||||
- quando esiste `channels.telegram.groups`, il gruppo deve essere elencato (oppure includere `"*"`)
|
||||
- verifica che il bot sia membro del gruppo
|
||||
- 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)
|
||||
- l'autorizzazione dei comandi si applica comunque anche quando la policy di gruppo è `open`
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu nativo ha troppe voci; riduci plugin/Skills/comandi personalizzati o disabilita i menu nativi
|
||||
- autorizza la tua identità mittente (abbinamento e/o `allowFrom` numerico)
|
||||
- l'autorizzazione dei comandi si applica comunque anche quando il criterio di gruppo è `open`
|
||||
- `setMyCommands failed` con `BOT_COMMANDS_TOO_MUCH` significa che il menu nativo ha troppe voci; riduci i comandi plugin/Skills/personalizzati o disabilita i menu nativi
|
||||
- `setMyCommands failed` con errori di rete/fetch di solito indica problemi di raggiungibilità DNS/HTTPS verso `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Instabilità del polling o della rete">
|
||||
|
||||
- Node 22+ + fetch/proxy personalizzato può attivare un comportamento di abort immediato se i tipi AbortSignal non corrispondono.
|
||||
- Alcuni host risolvono `api.telegram.org` prima in IPv6; un'uscita IPv6 difettosa può causare errori intermittenti delle API Telegram.
|
||||
- Node 22+ + fetch/proxy personalizzato possono attivare un comportamento di abort immediato se i tipi AbortSignal non corrispondono.
|
||||
- Alcuni host risolvono `api.telegram.org` prima in IPv6; un'uscita IPv6 difettosa può causare errori intermittenti della Telegram API.
|
||||
- Se i log includono `TypeError: fetch failed` o `Network request for 'getUpdates' failed!`, OpenClaw ora li ritenta come errori di rete recuperabili.
|
||||
- Su host VPS con uscita diretta/TLS instabile, instrada le chiamate Telegram API tramite `channels.telegram.proxy`:
|
||||
|
||||
@ -932,7 +932,7 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ usa come predefiniti `autoSelectFamily=true` (eccetto WSL2) e `dnsResultOrder=ipv4first`.
|
||||
- Node 22+ usa per impostazione predefinita `autoSelectFamily=true` (eccetto WSL2) e `dnsResultOrder=ipv4first`.
|
||||
- Se il tuo host è WSL2 o funziona esplicitamente meglio con comportamento solo IPv4, forza la selezione della famiglia:
|
||||
|
||||
```yaml
|
||||
@ -943,10 +943,10 @@ channels:
|
||||
```
|
||||
|
||||
- Le risposte nell'intervallo benchmark RFC 2544 (`198.18.0.0/15`) sono già consentite
|
||||
per i download dei media Telegram per impostazione predefinita. Se un fake-IP
|
||||
fidato o un proxy trasparente riscrive `api.telegram.org` verso un altro
|
||||
indirizzo privato/interno/special-use durante i download dei media, puoi scegliere
|
||||
il bypass solo Telegram:
|
||||
per impostazione predefinita per i download dei media Telegram. Se un fake-IP affidabile o un
|
||||
proxy trasparente riscrive `api.telegram.org` verso un altro
|
||||
indirizzo privato/interno/special-use durante i download dei media, puoi
|
||||
attivare il bypass solo per Telegram:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -957,23 +957,19 @@ channels:
|
||||
|
||||
- Lo stesso opt-in è disponibile per account in
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Se il tuo proxy risolve gli host media Telegram in `198.18.x.x`, lascia prima disattivato il flag
|
||||
pericoloso. I media Telegram consentono già per impostazione predefinita l'intervallo benchmark RFC 2544.
|
||||
- Se il tuo proxy risolve gli host media Telegram in `198.18.x.x`, lascia prima disattivato il
|
||||
flag pericoloso. I media Telegram già consentono per impostazione predefinita l'intervallo
|
||||
benchmark RFC 2544.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` indebolisce le protezioni SSRF dei
|
||||
media Telegram. Usalo solo in ambienti proxy fidati controllati
|
||||
dall'operatore, come instradamento fake-IP di Clash, Mihomo o Surge, quando
|
||||
sintetizzano risposte private o special-use fuori
|
||||
dall'intervallo benchmark RFC 2544. Lascialo disattivato per il normale accesso
|
||||
Telegram su internet pubblico.
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` indebolisce le protezioni SSRF dei media Telegram. Usalo solo per ambienti proxy affidabili controllati dall'operatore come Clash, Mihomo o routing fake-IP di Surge quando sintetizzano risposte private o special-use al di fuori dell'intervallo benchmark RFC 2544. Lascialo disattivato per il normale accesso Telegram su internet pubblico.
|
||||
</Warning>
|
||||
|
||||
- Override di ambiente (temporanei):
|
||||
- Override ambiente (temporanei):
|
||||
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
|
||||
- Valida le risposte DNS:
|
||||
- Convalida le risposte DNS:
|
||||
|
||||
```bash
|
||||
dig +short api.telegram.org A
|
||||
@ -983,87 +979,87 @@ dig +short api.telegram.org AAAA
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Altro aiuto: [Risoluzione dei problemi del canale](/channels/troubleshooting).
|
||||
Altro aiuto: [Risoluzione dei problemi del canale](/it/channels/troubleshooting).
|
||||
|
||||
## Riferimenti della config Telegram
|
||||
## Puntatori al riferimento della configurazione Telegram
|
||||
|
||||
Riferimento principale:
|
||||
|
||||
- `channels.telegram.enabled`: abilita/disabilita l'avvio del canale.
|
||||
- `channels.telegram.botToken`: token del bot (BotFather).
|
||||
- `channels.telegram.tokenFile`: legge il token da un percorso di file regolare. I symlink sono rifiutati.
|
||||
- `channels.telegram.tokenFile`: legge il token da un normale percorso file. I symlink vengono rifiutati.
|
||||
- `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (predefinito: pairing).
|
||||
- `channels.telegram.allowFrom`: allowlist DM (ID utente Telegram numerici). `allowlist` richiede almeno un ID mittente. `open` richiede `"*"`. `openclaw doctor --fix` può risolvere voci legacy `@username` in ID e può recuperare voci allowlist dai file del pairing-store nei flussi di migrazione allowlist.
|
||||
- `channels.telegram.actions.poll`: abilita o disabilita la creazione di sondaggi Telegram (predefinito: abilitato; richiede comunque `sendMessage`).
|
||||
- `channels.telegram.defaultTo`: target Telegram predefinito usato dal CLI `--deliver` quando non viene fornito alcun `--reply-to` esplicito.
|
||||
- `channels.telegram.allowFrom`: allowlist DM (ID utente Telegram numerici). `allowlist` richiede almeno un ID mittente. `open` richiede `"*"`. `openclaw doctor --fix` può risolvere le voci legacy `@username` in ID e può recuperare voci allowlist dai file pairing-store nei flussi di migrazione allowlist.
|
||||
- `channels.telegram.actions.poll`: abilita o disabilita la creazione di poll Telegram (predefinito: abilitato; richiede comunque `sendMessage`).
|
||||
- `channels.telegram.defaultTo`: destinazione Telegram predefinita usata da CLI `--deliver` quando non viene fornito alcun `--reply-to` esplicito.
|
||||
- `channels.telegram.groupPolicy`: `open | allowlist | disabled` (predefinito: allowlist).
|
||||
- `channels.telegram.groupAllowFrom`: allowlist dei mittenti nei gruppi (ID utente Telegram numerici). `openclaw doctor --fix` può risolvere voci legacy `@username` in ID. Le voci non numeriche vengono ignorate in fase di auth. L'auth di gruppo non usa il fallback DM del pairing-store (`2026.2.25+`).
|
||||
- `channels.telegram.groupAllowFrom`: allowlist dei mittenti nei gruppi (ID utente Telegram numerici). `openclaw doctor --fix` può risolvere le voci legacy `@username` in ID. Le voci non numeriche vengono ignorate al momento dell'autorizzazione. L'autorizzazione dei gruppi non usa il fallback del pairing-store DM (`2026.2.25+`).
|
||||
- Precedenza multi-account:
|
||||
- Quando sono configurati due o più ID account, imposta `channels.telegram.defaultAccount` (oppure includi `channels.telegram.accounts.default`) per rendere esplicito il routing predefinito.
|
||||
- Se nessuno dei due è impostato, OpenClaw usa come fallback il primo ID account normalizzato e `openclaw doctor` emette un avviso.
|
||||
- Quando sono configurati due o più ID account, imposta `channels.telegram.defaultAccount` (oppure includi `channels.telegram.accounts.default`) per rendere esplicito l'instradamento predefinito.
|
||||
- Se nessuno dei due è impostato, OpenClaw usa come fallback il primo ID account normalizzato e `openclaw doctor` mostra un avviso.
|
||||
- `channels.telegram.accounts.default.allowFrom` e `channels.telegram.accounts.default.groupAllowFrom` si applicano solo all'account `default`.
|
||||
- Gli account nominati ereditano `channels.telegram.allowFrom` e `channels.telegram.groupAllowFrom` quando i valori a livello account non sono impostati.
|
||||
- Gli account nominati non ereditano `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`.
|
||||
- `channels.telegram.groups`: valori predefiniti per gruppo + allowlist (usa `"*"` per valori predefiniti globali).
|
||||
- Gli account con nome ereditano `channels.telegram.allowFrom` e `channels.telegram.groupAllowFrom` quando i valori a livello di account non sono impostati.
|
||||
- Gli account con nome non ereditano `channels.telegram.accounts.default.allowFrom` / `groupAllowFrom`.
|
||||
- `channels.telegram.groups`: valori predefiniti per gruppo + allowlist (usa `"*"` per i valori predefiniti globali).
|
||||
- `channels.telegram.groups.<id>.groupPolicy`: override per gruppo di groupPolicy (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.requireMention`: gating delle menzioni predefinito.
|
||||
- `channels.telegram.groups.<id>.skills`: filtro Skills (ometti = tutte le Skills, vuoto = nessuna).
|
||||
- `channels.telegram.groups.<id>.allowFrom`: override per gruppo della allowlist mittenti.
|
||||
- `channels.telegram.groups.<id>.systemPrompt`: prompt di sistema aggiuntivo per il gruppo.
|
||||
- `channels.telegram.groups.<id>.enabled`: disabilita il gruppo quando `false`.
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.*`: override per topic (campi di gruppo + `agentId` solo topic).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.agentId`: instrada questo topic a un agente specifico (sovrascrive il routing a livello di gruppo e binding).
|
||||
- `channels.telegram.groups.<id>.requireMention`: valore predefinito del gating per menzione.
|
||||
- `channels.telegram.groups.<id>.skills`: filtro Skills (omesso = tutte le Skills, vuoto = nessuna).
|
||||
- `channels.telegram.groups.<id>.allowFrom`: override dell'allowlist dei mittenti per gruppo.
|
||||
- `channels.telegram.groups.<id>.systemPrompt`: system prompt aggiuntivo per il gruppo.
|
||||
- `channels.telegram.groups.<id>.enabled`: disabilita il gruppo quando è `false`.
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.*`: override per topic (campi del gruppo + `agentId` solo-topic).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.agentId`: instrada questo topic a un agente specifico (sovrascrive l'instradamento a livello di gruppo e tramite binding).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.groupPolicy`: override per topic di groupPolicy (`open | allowlist | disabled`).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention`: override per topic del gating delle menzioni.
|
||||
- `bindings[]` di primo livello con `type: "acp"` e ID topic canonico `chatId:topic:topicId` in `match.peer.id`: campi del binding persistente del topic ACP (vedi [Agenti ACP](/tools/acp-agents#channel-specific-settings)).
|
||||
- `channels.telegram.groups.<id>.topics.<threadId>.requireMention`: override per topic del gating per menzione.
|
||||
- `bindings[]` di primo livello con `type: "acp"` e ID topic canonico `chatId:topic:topicId` in `match.peer.id`: campi di binding persistente del topic ACP (vedi [Agenti ACP](/it/tools/acp-agents#channel-specific-settings)).
|
||||
- `channels.telegram.direct.<id>.topics.<threadId>.agentId`: instrada i topic DM a un agente specifico (stesso comportamento dei topic del forum).
|
||||
- `channels.telegram.execApprovals.enabled`: abilita Telegram come client di approvazione exec basato su chat per questo account.
|
||||
- `channels.telegram.execApprovals.approvers`: ID utente Telegram autorizzati ad approvare o negare richieste exec. Opzionale quando `channels.telegram.allowFrom` o un `channels.telegram.defaultTo` diretto identifica già il proprietario.
|
||||
- `channels.telegram.execApprovals.approvers`: ID utente Telegram autorizzati ad approvare o negare richieste exec. Facoltativo quando `channels.telegram.allowFrom` o un `channels.telegram.defaultTo` diretto identifica già il proprietario.
|
||||
- `channels.telegram.execApprovals.target`: `dm | channel | both` (predefinito: `dm`). `channel` e `both` preservano il topic Telegram di origine quando presente.
|
||||
- `channels.telegram.execApprovals.agentFilter`: filtro opzionale per ID agente per i prompt di approvazione inoltrati.
|
||||
- `channels.telegram.execApprovals.sessionFilter`: filtro opzionale per chiave di sessione (substring o regex) per i prompt di approvazione inoltrati.
|
||||
- `channels.telegram.accounts.<account>.execApprovals`: override per account del routing delle approvazioni exec Telegram e dell'autorizzazione degli approvatori.
|
||||
- `channels.telegram.execApprovals.agentFilter`: filtro facoltativo per ID agente per i prompt di approvazione inoltrati.
|
||||
- `channels.telegram.execApprovals.sessionFilter`: filtro facoltativo per chiave sessione (sottostringa o regex) per i prompt di approvazione inoltrati.
|
||||
- `channels.telegram.accounts.<account>.execApprovals`: override per account dell'instradamento delle approvazioni exec Telegram e dell'autorizzazione degli approvatori.
|
||||
- `channels.telegram.capabilities.inlineButtons`: `off | dm | group | all | allowlist` (predefinito: allowlist).
|
||||
- `channels.telegram.accounts.<account>.capabilities.inlineButtons`: override per account.
|
||||
- `channels.telegram.commands.nativeSkills`: abilita/disabilita i comandi Skills nativi di Telegram.
|
||||
- `channels.telegram.commands.nativeSkills`: abilita/disabilita i comandi nativi Skills di Telegram.
|
||||
- `channels.telegram.replyToMode`: `off | first | all` (predefinito: `off`).
|
||||
- `channels.telegram.textChunkLimit`: dimensione del chunk in uscita (caratteri).
|
||||
- `channels.telegram.textChunkLimit`: dimensione dei chunk in uscita (caratteri).
|
||||
- `channels.telegram.chunkMode`: `length` (predefinito) oppure `newline` per dividere sulle righe vuote (confini di paragrafo) prima del chunking per lunghezza.
|
||||
- `channels.telegram.linkPreview`: attiva/disattiva le anteprime link per i messaggi in uscita (predefinito: true).
|
||||
- `channels.telegram.streaming`: `off | partial | block | progress` (anteprima live dello stream; predefinito: `partial`; `progress` corrisponde a `partial`; `block` è compatibilità legacy della modalità anteprima). Lo streaming di anteprima Telegram usa un singolo messaggio di anteprima modificato in place.
|
||||
- `channels.telegram.mediaMaxMb`: limite media Telegram in ingresso/uscita (MB, predefinito: 100).
|
||||
- `channels.telegram.retry`: policy di retry per gli helper di invio Telegram (CLI/tools/actions) su errori API in uscita recuperabili (attempts, minDelayMs, maxDelayMs, jitter).
|
||||
- `channels.telegram.network.autoSelectFamily`: override di Node autoSelectFamily (true=abilita, false=disabilita). Per impostazione predefinita è abilitato su Node 22+, con WSL2 impostato come predefinito su disabilitato.
|
||||
- `channels.telegram.network.dnsResultOrder`: override dell'ordine dei risultati DNS (`ipv4first` o `verbatim`). Il valore predefinito su Node 22+ è `ipv4first`.
|
||||
- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: opt-in pericoloso per ambienti fidati con fake-IP o proxy trasparenti in cui i download dei media Telegram risolvono `api.telegram.org` verso indirizzi privati/interni/special-use fuori dall'intervallo benchmark RFC 2544 consentito per impostazione predefinita.
|
||||
- `channels.telegram.proxy`: URL proxy per chiamate Bot API (SOCKS/HTTP).
|
||||
- `channels.telegram.webhookUrl`: abilita la modalità webhook (richiede `channels.telegram.webhookSecret`).
|
||||
- `channels.telegram.webhookSecret`: secret webhook (obbligatorio quando è impostato webhookUrl).
|
||||
- `channels.telegram.webhookPath`: percorso webhook locale (predefinito `/telegram-webhook`).
|
||||
- `channels.telegram.webhookHost`: host di bind webhook locale (predefinito `127.0.0.1`).
|
||||
- `channels.telegram.webhookPort`: porta di bind webhook locale (predefinito `8787`).
|
||||
- `channels.telegram.actions.reactions`: gating delle reazioni tool Telegram.
|
||||
- `channels.telegram.actions.sendMessage`: gating degli invii di messaggi tool Telegram.
|
||||
- `channels.telegram.actions.deleteMessage`: gating delle eliminazioni di messaggi tool Telegram.
|
||||
- `channels.telegram.linkPreview`: attiva/disattiva le anteprime dei link per i messaggi in uscita (predefinito: true).
|
||||
- `channels.telegram.streaming`: `off | partial | block | progress` (anteprima del flusso live; predefinito: `partial`; `progress` corrisponde a `partial`; `block` è compatibilità legacy con la modalità anteprima). Lo streaming di anteprima Telegram usa un singolo messaggio di anteprima che viene modificato sul posto.
|
||||
- `channels.telegram.mediaMaxMb`: limite dei media Telegram in ingresso/uscita (MB, predefinito: 100).
|
||||
- `channels.telegram.retry`: criterio di retry per gli helper di invio Telegram (CLI/tools/actions) sugli errori recuperabili della API in uscita (tentativi, minDelayMs, maxDelayMs, jitter).
|
||||
- `channels.telegram.network.autoSelectFamily`: sovrascrive Node autoSelectFamily (true=abilita, false=disabilita). Per impostazione predefinita è abilitato su Node 22+, mentre su WSL2 è disabilitato per impostazione predefinita.
|
||||
- `channels.telegram.network.dnsResultOrder`: sovrascrive l'ordine dei risultati DNS (`ipv4first` o `verbatim`). Per impostazione predefinita è `ipv4first` su Node 22+.
|
||||
- `channels.telegram.network.dangerouslyAllowPrivateNetwork`: opt-in pericoloso per ambienti fidati fake-IP o transparent-proxy in cui i download dei media Telegram risolvono `api.telegram.org` verso indirizzi privati/interni/special-use al di fuori dell'intervallo benchmark RFC 2544 consentito per impostazione predefinita.
|
||||
- `channels.telegram.proxy`: URL proxy per le chiamate Bot API (SOCKS/HTTP).
|
||||
- `channels.telegram.webhookUrl`: abilita la modalità Webhook (richiede `channels.telegram.webhookSecret`).
|
||||
- `channels.telegram.webhookSecret`: segreto Webhook (obbligatorio quando è impostato `webhookUrl`).
|
||||
- `channels.telegram.webhookPath`: percorso Webhook locale (predefinito `/telegram-webhook`).
|
||||
- `channels.telegram.webhookHost`: host di bind del Webhook locale (predefinito `127.0.0.1`).
|
||||
- `channels.telegram.webhookPort`: porta di bind del Webhook locale (predefinito `8787`).
|
||||
- `channels.telegram.actions.reactions`: gating delle reazioni dello strumento Telegram.
|
||||
- `channels.telegram.actions.sendMessage`: gating degli invii di messaggi dello strumento Telegram.
|
||||
- `channels.telegram.actions.deleteMessage`: gating delle eliminazioni di messaggi dello strumento Telegram.
|
||||
- `channels.telegram.actions.sticker`: gating delle azioni sticker Telegram — invio e ricerca (predefinito: false).
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` — controlla quali reazioni attivano eventi di sistema (predefinito: `own` quando non impostato).
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — controlla la capacità di reazione dell'agente (predefinito: `minimal` quando non impostato).
|
||||
- `channels.telegram.errorPolicy`: `reply | silent` — controlla il comportamento delle risposte di errore (predefinito: `reply`). Supporta override per account/gruppo/topic.
|
||||
- `channels.telegram.errorCooldownMs`: ms minimi tra risposte di errore alla stessa chat (predefinito: `60000`). Previene spam di errori durante interruzioni del servizio.
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` — controlla quali reazioni attivano eventi di sistema (predefinito: `own` se non impostato).
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` — controlla la capacità di reazione dell'agente (predefinito: `minimal` se non impostato).
|
||||
- `channels.telegram.errorPolicy`: `reply | silent` — controlla il comportamento delle risposte di errore (predefinito: `reply`). Sono supportati override per account/gruppo/topic.
|
||||
- `channels.telegram.errorCooldownMs`: ms minimi tra risposte di errore nella stessa chat (predefinito: `60000`). Previene lo spam di errori durante le interruzioni.
|
||||
|
||||
- [Riferimento configurazione - Telegram](/gateway/configuration-reference#telegram)
|
||||
- [Riferimento configurazione - Telegram](/it/gateway/configuration-reference#telegram)
|
||||
|
||||
Campi Telegram specifici ad alto segnale:
|
||||
|
||||
- avvio/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve puntare a un file regolare; i symlink sono rifiutati)
|
||||
- avvio/autenticazione: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` deve puntare a un file normale; i symlink vengono rifiutati)
|
||||
- controllo accessi: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` di primo livello (`type: "acp"`)
|
||||
- approvazioni exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- comando/menu: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- comandi/menu: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- threading/risposte: `replyToMode`
|
||||
- streaming: `streaming` (anteprima), `blockStreaming`
|
||||
- formattazione/consegna: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- media/rete: `mediaMaxMb`, `timeoutSeconds`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- azioni/capacità: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- reazioni: `reactionNotifications`, `reactionLevel`
|
||||
- errori: `errorPolicy`, `errorCooldownMs`
|
||||
@ -1073,7 +1069,7 @@ Campi Telegram specifici ad alto segnale:
|
||||
|
||||
- [Abbinamento](/it/channels/pairing)
|
||||
- [Gruppi](/it/channels/groups)
|
||||
- [Sicurezza](/gateway/security)
|
||||
- [Sicurezza](/it/gateway/security)
|
||||
- [Instradamento dei canali](/it/channels/channel-routing)
|
||||
- [Instradamento multi-agent](/concepts/multi-agent)
|
||||
- [Risoluzione dei problemi](/channels/troubleshooting)
|
||||
- [Instradamento multi-agente](/it/concepts/multi-agent)
|
||||
- [Risoluzione dei problemi](/it/channels/troubleshooting)
|
||||
|
||||
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- Il trasporto del canale risulta connesso ma le risposte non funzionano
|
||||
- Hai bisogno di controlli specifici per il canale prima di consultare la documentazione approfondita del provider
|
||||
summary: Risoluzione rapida dei problemi a livello di canale con firme di errore e correzioni per ciascun canale
|
||||
title: Risoluzione dei problemi dei canali
|
||||
- Il trasporto del canale risulta connesso ma le risposte non vengono inviate
|
||||
- Sono necessari controlli specifici del canale prima di passare alla documentazione approfondita del provider
|
||||
summary: Risoluzione rapida dei problemi a livello di canale con firme di errore e correzioni specifiche per canale
|
||||
title: Risoluzione dei problemi del canale
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T13:45:47Z"
|
||||
generated_at: "2026-04-20T08:30:51Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: d45d8220505ea420d970b20bc66e65216c2d7024b5736db1936421ffc0676e1f
|
||||
source_hash: 0aef31742cd5cc4af3fa3d3ea1acba51875ad4a1423c0e8c87372c3df31b0528
|
||||
source_path: channels/troubleshooting.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Risoluzione dei problemi dei canali
|
||||
# Risoluzione dei problemi del canale
|
||||
|
||||
Usa questa pagina quando un canale si connette ma il comportamento non è corretto.
|
||||
|
||||
## Sequenza di comandi
|
||||
|
||||
Esegui prima questi, in questo ordine:
|
||||
Esegui prima questi comandi, in questo ordine:
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -32,68 +32,69 @@ openclaw channels status --probe
|
||||
Baseline sana:
|
||||
|
||||
- `Runtime: running`
|
||||
- `RPC probe: ok`
|
||||
- La probe del canale mostra il trasporto connesso e, dove supportato, `works` o `audit ok`
|
||||
- `Connectivity probe: ok`
|
||||
- `Capability: read-only`, `write-capable` oppure `admin-capable`
|
||||
- Il probe del canale mostra il trasporto connesso e, dove supportato, `works` oppure `audit ok`
|
||||
|
||||
## WhatsApp
|
||||
|
||||
### Firme di errore di WhatsApp
|
||||
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| ------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------ |
|
||||
| Connesso ma nessuna risposta DM | `openclaw pairing list whatsapp` | Approva il mittente o cambia la policy/allowlist dei DM. |
|
||||
| Messaggi di gruppo ignorati | Controlla `requireMention` + i pattern di menzione nella config | Menziona il bot o allenta la policy di menzione per quel gruppo. |
|
||||
| Disconnessioni casuali/cicli di nuovo login | `openclaw channels status --probe` + log | Effettua di nuovo il login e verifica che la directory delle credenziali sia integra. |
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| ------------------------------- | --------------------------------------------------- | ----------------------------------------------------------- |
|
||||
| Connesso ma nessuna risposta nei DM | `openclaw pairing list whatsapp` | Approva il mittente oppure cambia il criterio DM/allowlist. |
|
||||
| I messaggi di gruppo vengono ignorati | Controlla `requireMention` + i pattern di menzione nella config | Menziona il bot oppure allenta il criterio di menzione per quel gruppo. |
|
||||
| Disconnessioni casuali/cicli di nuovo login | `openclaw channels status --probe` + log | Esegui di nuovo il login e verifica che la directory delle credenziali sia integra. |
|
||||
|
||||
Risoluzione completa dei problemi: [/channels/whatsapp#troubleshooting](/channels/whatsapp#troubleshooting)
|
||||
Risoluzione completa dei problemi: [/channels/whatsapp#troubleshooting](/it/channels/whatsapp#troubleshooting)
|
||||
|
||||
## Telegram
|
||||
|
||||
### Firme di errore di Telegram
|
||||
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| ---------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| `/start` ma nessun flusso di risposta utilizzabile | `openclaw pairing list telegram` | Approva l'associazione o modifica la policy dei DM. |
|
||||
| Bot online ma il gruppo resta silenzioso | Verifica il requisito di menzione e la modalità privacy del bot | Disabilita la modalità privacy per la visibilità nel gruppo oppure menziona il bot. |
|
||||
| Errori di invio con errori di rete | Ispeziona i log per i fallimenti delle chiamate API di Telegram | Correggi il routing DNS/IPv6/proxy verso `api.telegram.org`. |
|
||||
| `setMyCommands` rifiutato all'avvio | Ispeziona i log per `BOT_COMMANDS_TOO_MUCH` | Riduci i comandi Telegram di plugin/Skills/personalizzati oppure disabilita i menu nativi. |
|
||||
| Hai effettuato un upgrade e l'allowlist ti blocca | `openclaw security audit` e le allowlist della config | Esegui `openclaw doctor --fix` oppure sostituisci `@username` con ID numerici del mittente. |
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| ----------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| `/start` ma nessun flusso di risposta utilizzabile | `openclaw pairing list telegram` | Approva l'associazione oppure cambia il criterio DM. |
|
||||
| Bot online ma il gruppo resta silenzioso | Verifica il requisito di menzione e la modalità privacy del bot | Disattiva la modalità privacy per la visibilità nel gruppo oppure menziona il bot. |
|
||||
| Invii che falliscono con errori di rete | Ispeziona i log per gli errori delle chiamate API di Telegram | Correggi il routing DNS/IPv6/proxy verso `api.telegram.org`. |
|
||||
| `setMyCommands` rifiutato all'avvio | Ispeziona i log per `BOT_COMMANDS_TOO_MUCH` | Riduci i comandi Telegram di plugin/Skills/personalizzati oppure disabilita i menu nativi. |
|
||||
| Hai aggiornato e l'allowlist ti blocca | `openclaw security audit` e le allowlist nella config | Esegui `openclaw doctor --fix` oppure sostituisci `@username` con ID numerici del mittente. |
|
||||
|
||||
Risoluzione completa dei problemi: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
|
||||
Risoluzione completa dei problemi: [/channels/telegram#troubleshooting](/it/channels/telegram#troubleshooting)
|
||||
|
||||
## Discord
|
||||
|
||||
### Firme di errore di Discord
|
||||
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| ------------------------------ | ------------------------------------- | ------------------------------------------------------------- |
|
||||
| Bot online ma nessuna risposta nel server | `openclaw channels status --probe` | Consenti server/canale e verifica l'intento del contenuto dei messaggi. |
|
||||
| Messaggi di gruppo ignorati | Controlla nei log i blocchi dovuti alla regola di menzione | Menziona il bot o imposta `requireMention: false` per server/canale. |
|
||||
| Risposte DM mancanti | `openclaw pairing list discord` | Approva l'associazione DM o regola la policy dei DM. |
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| ------------------------------- | ----------------------------------------- | ------------------------------------------------------------- |
|
||||
| Bot online ma nessuna risposta nel server | `openclaw channels status --probe` | Consenti il server/canale e verifica l'intento message content. |
|
||||
| I messaggi di gruppo vengono ignorati | Controlla nei log gli scarti dovuti al filtro per menzione | Menziona il bot oppure imposta `requireMention: false` per server/canale. |
|
||||
| Risposte DM mancanti | `openclaw pairing list discord` | Approva l'associazione DM oppure regola il criterio DM. |
|
||||
|
||||
Risoluzione completa dei problemi: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
|
||||
Risoluzione completa dei problemi: [/channels/discord#troubleshooting](/it/channels/discord#troubleshooting)
|
||||
|
||||
## Slack
|
||||
|
||||
### Firme di errore di Slack
|
||||
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| ------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| -------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Socket mode connessa ma nessuna risposta | `openclaw channels status --probe` | Verifica app token + bot token e gli scope richiesti; controlla `botTokenStatus` / `appTokenStatus = configured_unavailable` nelle configurazioni basate su SecretRef. |
|
||||
| DM bloccati | `openclaw pairing list slack` | Approva l'associazione o allenta la policy dei DM. |
|
||||
| Messaggio del canale ignorato | Controlla `groupPolicy` e l'allowlist del canale | Consenti il canale o cambia la policy in `open`. |
|
||||
| DM bloccati | `openclaw pairing list slack` | Approva l'associazione oppure allenta il criterio DM. |
|
||||
| Messaggio del canale ignorato | Controlla `groupPolicy` e l'allowlist del canale | Consenti il canale oppure cambia il criterio in `open`. |
|
||||
|
||||
Risoluzione completa dei problemi: [/channels/slack#troubleshooting](/channels/slack#troubleshooting)
|
||||
Risoluzione completa dei problemi: [/channels/slack#troubleshooting](/it/channels/slack#troubleshooting)
|
||||
|
||||
## iMessage e BlueBubbles
|
||||
|
||||
### Firme di errore di iMessage e BlueBubbles
|
||||
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| ------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------- |
|
||||
| Nessun evento in ingresso | Verifica la raggiungibilità del webhook/server e i permessi dell'app | Correggi l'URL del webhook o lo stato del server BlueBubbles. |
|
||||
| Può inviare ma non ricevere su macOS | Controlla i permessi privacy di macOS per l'automazione di Messages | Concedi di nuovo i permessi TCC e riavvia il processo del canale. |
|
||||
| Mittente DM bloccato | `openclaw pairing list imessage` o `openclaw pairing list bluebubbles` | Approva l'associazione o aggiorna l'allowlist. |
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| -------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------- |
|
||||
| Nessun evento in ingresso | Verifica la raggiungibilità del webhook/server e i permessi dell'app | Correggi l'URL del webhook o lo stato del server BlueBubbles. |
|
||||
| Può inviare ma non riceve su macOS | Controlla i permessi privacy di macOS per l'automazione di Messaggi | Concedi di nuovo i permessi TCC e riavvia il processo del canale. |
|
||||
| Mittente DM bloccato | `openclaw pairing list imessage` o `openclaw pairing list bluebubbles` | Approva l'associazione oppure aggiorna l'allowlist. |
|
||||
|
||||
Risoluzione completa dei problemi:
|
||||
|
||||
@ -104,11 +105,11 @@ Risoluzione completa dei problemi:
|
||||
|
||||
### Firme di errore di Signal
|
||||
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| ------------------------------ | ------------------------------------------ | ------------------------------------------------------- |
|
||||
| Demone raggiungibile ma bot silenzioso | `openclaw channels status --probe` | Verifica URL/account del demone `signal-cli` e la modalità di ricezione. |
|
||||
| DM bloccato | `openclaw pairing list signal` | Approva il mittente o regola la policy dei DM. |
|
||||
| Le risposte nei gruppi non si attivano | Controlla l'allowlist del gruppo e i pattern di menzione | Aggiungi mittente/gruppo o allenta il gating. |
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| ------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| Demone raggiungibile ma bot silenzioso | `openclaw channels status --probe` | Verifica l'URL/account del demone `signal-cli` e la modalità di ricezione. |
|
||||
| DM bloccato | `openclaw pairing list signal` | Approva il mittente oppure regola il criterio DM. |
|
||||
| Le risposte nei gruppi non si attivano | Controlla l'allowlist dei gruppi e i pattern di menzione | Aggiungi mittente/gruppo oppure allenta il filtro. |
|
||||
|
||||
Risoluzione completa dei problemi: [/channels/signal#troubleshooting](/it/channels/signal#troubleshooting)
|
||||
|
||||
@ -116,12 +117,12 @@ Risoluzione completa dei problemi: [/channels/signal#troubleshooting](/it/channe
|
||||
|
||||
### Firme di errore di QQ Bot
|
||||
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| ------------------------------ | -------------------------------------------- | ------------------------------------------------------------------- |
|
||||
| Il bot risponde "gone to Mars" | Verifica `appId` e `clientSecret` nella config | Imposta le credenziali o riavvia il gateway. |
|
||||
| Nessun messaggio in ingresso | `openclaw channels status --probe` | Verifica le credenziali sulla QQ Open Platform. |
|
||||
| Voce non trascritta | Controlla la config del provider STT | Configura `channels.qqbot.stt` o `tools.media.audio`. |
|
||||
| I messaggi proattivi non arrivano | Controlla i requisiti di interazione della piattaforma QQ | QQ può bloccare i messaggi avviati dal bot senza un'interazione recente. |
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| ------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------ |
|
||||
| Il bot risponde "gone to Mars" | Verifica `appId` e `clientSecret` nella config | Imposta le credenziali oppure riavvia il Gateway. |
|
||||
| Nessun messaggio in ingresso | `openclaw channels status --probe` | Verifica le credenziali sulla QQ Open Platform. |
|
||||
| La voce non viene trascritta | Controlla la config del provider STT | Configura `channels.qqbot.stt` oppure `tools.media.audio`. |
|
||||
| I messaggi proattivi non arrivano | Controlla i requisiti di interazione della piattaforma QQ | QQ può bloccare i messaggi avviati dal bot senza una recente interazione. |
|
||||
|
||||
Risoluzione completa dei problemi: [/channels/qqbot#troubleshooting](/it/channels/qqbot#troubleshooting)
|
||||
|
||||
@ -129,12 +130,12 @@ Risoluzione completa dei problemi: [/channels/qqbot#troubleshooting](/it/channel
|
||||
|
||||
### Firme di errore di Matrix
|
||||
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| ---------------------------------- | --------------------------------------- | ------------------------------------------------------------------------- |
|
||||
| Accesso eseguito ma i messaggi della stanza vengono ignorati | `openclaw channels status --probe` | Controlla `groupPolicy`, l'allowlist delle stanze e il gating delle menzioni. |
|
||||
| I DM non vengono elaborati | `openclaw pairing list matrix` | Approva il mittente o regola la policy dei DM. |
|
||||
| Le stanze crittografate non funzionano | `openclaw matrix verify status` | Verifica di nuovo il dispositivo, poi controlla `openclaw matrix verify backup status`. |
|
||||
| Il ripristino del backup è in sospeso/non funziona | `openclaw matrix verify backup status` | Esegui `openclaw matrix verify backup restore` o ripeti l'operazione con una chiave di recupero. |
|
||||
| Cross-signing/bootstrap sembra errato | `openclaw matrix verify bootstrap` | Ripara secret storage, cross-signing e stato del backup in un solo passaggio. |
|
||||
| Sintomo | Controllo più rapido | Correzione |
|
||||
| ----------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------- |
|
||||
| Ha eseguito il login ma ignora i messaggi nella stanza | `openclaw channels status --probe` | Controlla `groupPolicy`, l'allowlist della stanza e il filtro per menzione. |
|
||||
| I DM non vengono elaborati | `openclaw pairing list matrix` | Approva il mittente oppure regola il criterio DM. |
|
||||
| Le stanze cifrate falliscono | `openclaw matrix verify status` | Verifica di nuovo il dispositivo, poi controlla `openclaw matrix verify backup status`. |
|
||||
| Il ripristino del backup è in attesa/non funziona | `openclaw matrix verify backup status` | Esegui `openclaw matrix verify backup restore` oppure riesegui con una chiave di recupero. |
|
||||
| Il bootstrap/cross-signing sembra errato | `openclaw matrix verify bootstrap` | Ripara in un solo passaggio l'archiviazione dei segreti, il cross-signing e lo stato del backup. |
|
||||
|
||||
Configurazione e setup completi: [Matrix](/channels/matrix)
|
||||
Configurazione e impostazione complete: [Matrix](/it/channels/matrix)
|
||||
|
||||
@ -1,31 +1,31 @@
|
||||
---
|
||||
read_when:
|
||||
- Estensione di qa-lab o qa-channel
|
||||
- Estendere qa-lab o qa-channel
|
||||
- Aggiunta di scenari QA supportati dal repository
|
||||
- Creazione di un'automazione QA a maggiore realismo attorno alla dashboard del Gateway
|
||||
- Creazione di automazione QA a maggiore realismo attorno alla dashboard del Gateway
|
||||
summary: Forma dell'automazione QA privata per qa-lab, qa-channel, scenari con seed e report di protocollo
|
||||
title: Automazione QA E2E
|
||||
title: Automazione QA end-to-end
|
||||
x-i18n:
|
||||
generated_at: "2026-04-18T08:05:14Z"
|
||||
generated_at: "2026-04-20T08:30:54Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: adf8c5f74e8fabdc8e9fd7ecd41afce8b60354c7dd24d92ac926d3c527927cd4
|
||||
source_hash: 34245ce871356caeab0d9e0eeeaa9fb4e408920a4a97ad27567fa365d8db17c7
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Automazione QA E2E
|
||||
# Automazione QA end-to-end
|
||||
|
||||
Lo stack QA privato è pensato per esercitare OpenClaw in modo più realistico,
|
||||
con una forma simile a quella di un canale, rispetto a quanto possa fare un singolo test unitario.
|
||||
Lo stack QA privato è pensato per esercitare OpenClaw in un modo più realistico,
|
||||
con una forma simile ai canali, rispetto a quanto possa fare un singolo test unitario.
|
||||
|
||||
Componenti attuali:
|
||||
|
||||
- `extensions/qa-channel`: canale di messaggi sintetico con superfici DM, canale, thread,
|
||||
reazione, modifica ed eliminazione.
|
||||
- `extensions/qa-lab`: interfaccia utente di debug e bus QA per osservare la trascrizione,
|
||||
- `extensions/qa-channel`: canale di messaggistica sintetico con superfici per messaggi diretti, canale, thread,
|
||||
reazioni, modifiche ed eliminazioni.
|
||||
- `extensions/qa-lab`: interfaccia debugger e bus QA per osservare la trascrizione,
|
||||
iniettare messaggi in ingresso ed esportare un report Markdown.
|
||||
- `qa/`: asset seed supportati dal repository per l'attività iniziale e gli scenari QA
|
||||
- `qa/`: risorse seed supportate dal repository per il task iniziale e gli scenari QA
|
||||
di base.
|
||||
|
||||
L'attuale flusso operativo QA è un sito QA a due pannelli:
|
||||
@ -39,13 +39,13 @@ Eseguilo con:
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
Questo compila il sito QA, avvia la lane del gateway supportata da Docker ed espone la
|
||||
pagina QA Lab dove un operatore o un loop di automazione può assegnare all'agente una
|
||||
missione QA, osservare il comportamento reale del canale e registrare ciò che ha funzionato,
|
||||
ciò che è fallito o ciò che è rimasto bloccato.
|
||||
Questo compila il sito QA, avvia la corsia gateway supportata da Docker ed espone la
|
||||
pagina QA Lab dove un operatore o un ciclo di automazione può assegnare all'agente una
|
||||
missione QA, osservare il comportamento reale del canale e registrare cosa ha funzionato, cosa è fallito o
|
||||
cosa è rimasto bloccato.
|
||||
|
||||
Per un'iterazione più rapida dell'interfaccia di QA Lab senza ricompilare ogni volta l'immagine Docker,
|
||||
avvia lo stack con un bundle QA Lab montato in bind:
|
||||
Per iterazioni più rapide dell'interfaccia di QA Lab senza ricompilare ogni volta l'immagine Docker,
|
||||
avvia lo stack con un bundle QA Lab montato tramite bind:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa docker-build-image
|
||||
@ -54,54 +54,57 @@ pnpm qa:lab:up:fast
|
||||
pnpm qa:lab:watch
|
||||
```
|
||||
|
||||
`qa:lab:up:fast` mantiene i servizi Docker su un'immagine precompilata e monta in bind
|
||||
`qa:lab:up:fast` mantiene i servizi Docker su un'immagine precompilata e monta tramite bind
|
||||
`extensions/qa-lab/web/dist` nel container `qa-lab`. `qa:lab:watch`
|
||||
ricompila quel bundle quando cambia, e il browser si ricarica automaticamente quando cambia l'hash
|
||||
degli asset di QA Lab.
|
||||
ricompila quel bundle a ogni modifica e il browser si ricarica automaticamente quando cambia l'hash
|
||||
delle risorse di QA Lab.
|
||||
|
||||
Per una lane smoke Matrix con trasporto reale, esegui:
|
||||
Per una corsia smoke Matrix con trasporto reale, esegui:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa matrix
|
||||
```
|
||||
|
||||
Questa lane effettua il provisioning di un homeserver Tuwunel temporaneo in Docker, registra
|
||||
utenti temporanei driver, SUT e osservatore, crea una stanza privata, quindi esegue il vero Plugin Matrix all'interno di un processo figlio del gateway QA. La lane con trasporto live mantiene
|
||||
la configurazione del processo figlio limitata al trasporto in test, quindi Matrix viene eseguito senza
|
||||
`qa-channel` nella configurazione del processo figlio. Scrive gli artifact del report strutturato e
|
||||
Questa corsia effettua il provisioning di un homeserver Tuwunel usa e getta in Docker, registra
|
||||
utenti temporanei driver, SUT e observer, crea una stanza privata, quindi esegue
|
||||
il vero plugin Matrix all'interno di un processo figlio QA del gateway. La corsia con trasporto live mantiene
|
||||
la configurazione figlia limitata al trasporto in test, così Matrix viene eseguito senza
|
||||
`qa-channel` nella configurazione figlia. Scrive gli artefatti di report strutturati e
|
||||
un log combinato stdout/stderr nella directory di output Matrix QA selezionata. Per
|
||||
acquisire anche l'output esterno di build/launcher di `scripts/run-node.mjs`, imposta
|
||||
`OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` su un file di log locale al repository.
|
||||
|
||||
Per una lane smoke Telegram con trasporto reale, esegui:
|
||||
Per una corsia smoke Telegram con trasporto reale, esegui:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa telegram
|
||||
```
|
||||
|
||||
Questa lane usa come destinazione un vero gruppo privato Telegram invece di effettuare il provisioning di
|
||||
un server temporaneo. Richiede `OPENCLAW_QA_TELEGRAM_GROUP_ID`,
|
||||
Questa corsia punta a un gruppo privato Telegram reale invece di effettuare il provisioning di un
|
||||
server usa e getta. Richiede `OPENCLAW_QA_TELEGRAM_GROUP_ID`,
|
||||
`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` e
|
||||
`OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`, oltre a due bot distinti nello stesso
|
||||
gruppo privato. Il bot SUT deve avere un nome utente Telegram e l'osservazione bot-to-bot
|
||||
funziona al meglio quando entrambi i bot hanno Bot-to-Bot Communication Mode
|
||||
gruppo privato. Il bot SUT deve avere un nome utente Telegram, e l'osservazione tra bot
|
||||
funziona al meglio quando entrambi i bot hanno la modalità di comunicazione Bot-to-Bot
|
||||
abilitata in `@BotFather`.
|
||||
Il comando termina con codice diverso da zero quando uno scenario fallisce. Usa `--allow-failures` quando
|
||||
vuoi ottenere gli artefatti senza un codice di uscita di errore.
|
||||
|
||||
Le lane con trasporto live ora condividono un unico contratto più piccolo invece di definire
|
||||
ognuna una propria forma dell'elenco di scenari.
|
||||
Le corsie live di trasporto ora condividono un contratto più piccolo invece di inventare
|
||||
ognuna una propria forma per l'elenco degli scenari:
|
||||
|
||||
`qa-channel` resta la suite ampia di comportamento sintetico del prodotto e non fa parte
|
||||
`qa-channel` rimane la suite ampia di comportamento di prodotto sintetico e non fa parte
|
||||
della matrice di copertura del trasporto live.
|
||||
|
||||
| Lane | Canary | Gating delle menzioni | Blocco allowlist | Risposta di primo livello | Ripresa dopo riavvio | Follow-up nel thread | Isolamento del thread | Osservazione delle reazioni | Comando help |
|
||||
| -------- | ------ | --------------------- | ---------------- | ------------------------- | -------------------- | ------------------- | --------------------- | --------------------------- | ------------ |
|
||||
| Matrix | x | x | x | x | x | x | x | x | |
|
||||
| Telegram | x | | | | | | | | x |
|
||||
| Corsia | Canary | Blocco menzioni | Blocco allowlist | Risposta di primo livello | Ripresa dopo riavvio | Follow-up del thread | Isolamento del thread | Osservazione reazioni | Comando help |
|
||||
| -------- | ------ | --------------- | ---------------- | ------------------------- | -------------------- | ------------------- | --------------------- | --------------------- | ------------ |
|
||||
| Matrix | x | x | x | x | x | x | x | x | |
|
||||
| Telegram | x | | | | | | | | x |
|
||||
|
||||
Questo mantiene `qa-channel` come suite ampia di comportamento del prodotto, mentre Matrix,
|
||||
Telegram e i futuri trasporti live condividono una checklist esplicita di contratto di trasporto.
|
||||
|
||||
Per una lane VM Linux temporanea senza portare Docker nel percorso QA, esegui:
|
||||
Per una corsia VM Linux usa e getta senza portare Docker nel percorso QA, esegui:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
@ -109,92 +112,93 @@ pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
|
||||
Questo avvia un guest Multipass pulito, installa le dipendenze, compila OpenClaw
|
||||
all'interno del guest, esegue `qa suite`, quindi copia il normale report QA e il
|
||||
riepilogo in `.artifacts/qa-e2e/...` sull'host.
|
||||
riepilogo di nuovo in `.artifacts/qa-e2e/...` sull'host.
|
||||
Riutilizza lo stesso comportamento di selezione degli scenari di `qa suite` sull'host.
|
||||
Le esecuzioni host e Multipass della suite eseguono più scenari selezionati in parallelo
|
||||
con worker del gateway isolati per impostazione predefinita, fino a 64 worker o al numero
|
||||
di scenari selezionati. Usa `--concurrency <count>` per regolare il numero di worker, oppure
|
||||
`--concurrency 1` per l'esecuzione seriale.
|
||||
Le esecuzioni host e Multipass della suite eseguono in parallelo per impostazione predefinita
|
||||
più scenari selezionati con worker gateway isolati. `qa-channel` usa come valore predefinito la concorrenza
|
||||
4, limitata dal numero di scenari selezionati. Usa `--concurrency <count>` per regolare
|
||||
il numero di worker, oppure `--concurrency 1` per l'esecuzione seriale.
|
||||
Il comando termina con codice diverso da zero quando uno scenario fallisce. Usa `--allow-failures` quando
|
||||
vuoi ottenere gli artefatti senza un codice di uscita di errore.
|
||||
Le esecuzioni live inoltrano gli input di autenticazione QA supportati che sono pratici per il
|
||||
guest: chiavi provider basate su env, percorso della configurazione del provider live QA e
|
||||
guest: chiavi provider basate su variabili d'ambiente, il percorso di configurazione del provider live QA e
|
||||
`CODEX_HOME` quando presente. Mantieni `--output-dir` sotto la root del repository in modo che il guest
|
||||
possa scrivere di nuovo attraverso il workspace montato.
|
||||
possa scrivere di ritorno attraverso il workspace montato.
|
||||
|
||||
## Seed supportati dal repository
|
||||
|
||||
Gli asset seed si trovano in `qa/`:
|
||||
Le risorse seed si trovano in `qa/`:
|
||||
|
||||
- `qa/scenarios/index.md`
|
||||
- `qa/scenarios/<theme>/*.md`
|
||||
|
||||
Sono intenzionalmente in git così che il piano QA sia visibile sia agli esseri umani sia
|
||||
Queste sono intenzionalmente in git così che il piano QA sia visibile sia agli esseri umani sia
|
||||
all'agente.
|
||||
|
||||
`qa-lab` dovrebbe restare un esecutore Markdown generico. Ogni file Markdown di scenario è
|
||||
`qa-lab` dovrebbe rimanere un runner Markdown generico. Ogni file Markdown di scenario è
|
||||
la fonte di verità per una singola esecuzione di test e dovrebbe definire:
|
||||
|
||||
- metadati dello scenario
|
||||
- metadati opzionali di categoria, capacità, lane e rischio
|
||||
- metadati facoltativi di categoria, capacità, corsia e rischio
|
||||
- riferimenti a documentazione e codice
|
||||
- requisiti opzionali del Plugin
|
||||
- patch opzionale di configurazione del gateway
|
||||
- requisiti facoltativi dei plugin
|
||||
- patch facoltativa della configurazione Gateway
|
||||
- il `qa-flow` eseguibile
|
||||
|
||||
La superficie runtime riutilizzabile che supporta `qa-flow` può restare generica
|
||||
La superficie runtime riutilizzabile che supporta `qa-flow` può rimanere generica
|
||||
e trasversale. Ad esempio, gli scenari Markdown possono combinare helper lato trasporto
|
||||
con helper lato browser che pilotano la Control UI incorporata tramite la seam
|
||||
`browser.request` del Gateway senza aggiungere un runner con casi speciali.
|
||||
con helper lato browser che guidano la Control UI incorporata tramite la seam
|
||||
Gateway `browser.request` senza aggiungere un runner con casi speciali.
|
||||
|
||||
I file di scenario dovrebbero essere raggruppati per capacità del prodotto anziché per cartella
|
||||
dell'albero sorgente. Mantieni stabili gli ID degli scenari quando i file vengono spostati; usa
|
||||
`docsRefs` e `codeRefs` per la tracciabilità dell'implementazione.
|
||||
I file di scenario dovrebbero essere raggruppati per capacità del prodotto invece che per cartella
|
||||
dell'albero sorgente. Mantieni stabili gli ID degli scenari quando i file vengono spostati; usa `docsRefs` e `codeRefs`
|
||||
per la tracciabilità dell'implementazione.
|
||||
|
||||
L'elenco di base dovrebbe restare abbastanza ampio da coprire:
|
||||
L'elenco di base dovrebbe rimanere abbastanza ampio da coprire:
|
||||
|
||||
- chat DM e di canale
|
||||
- chat in DM e canale
|
||||
- comportamento dei thread
|
||||
- ciclo di vita delle azioni sui messaggi
|
||||
- callback Cron
|
||||
- richiamo della memoria
|
||||
- cambio modello
|
||||
- handoff al sottoagente
|
||||
- handoff ai subagenti
|
||||
- lettura del repository e della documentazione
|
||||
- una piccola attività di build come Lobster Invaders
|
||||
- un piccolo task di build come Lobster Invaders
|
||||
|
||||
## Lane mock del provider
|
||||
## Corsie mock del provider
|
||||
|
||||
`qa suite` ha due lane mock locali del provider:
|
||||
`qa suite` ha due corsie mock locali del provider:
|
||||
|
||||
- `mock-openai` è il mock OpenClaw consapevole dello scenario. Resta la lane mock
|
||||
deterministica predefinita per il QA supportato dal repository e per i gate di parità.
|
||||
- `aimock` avvia un server provider supportato da AIMock per copertura sperimentale di protocollo,
|
||||
fixture, record/replay e chaos. È aggiuntivo e non sostituisce il dispatcher di scenari `mock-openai`.
|
||||
- `mock-openai` è il mock OpenClaw consapevole dello scenario. Rimane la corsia mock deterministica
|
||||
predefinita per la QA supportata dal repository e per i gate di parità.
|
||||
- `aimock` avvia un server provider basato su AIMock per copertura sperimentale di protocollo,
|
||||
fixture, record/replay e chaos. È aggiuntivo e non sostituisce il dispatcher
|
||||
di scenari `mock-openai`.
|
||||
|
||||
L'implementazione della lane del provider si trova in `extensions/qa-lab/src/providers/`.
|
||||
L'implementazione della corsia provider si trova in `extensions/qa-lab/src/providers/`.
|
||||
Ogni provider possiede i propri valori predefiniti, l'avvio del server locale, la configurazione
|
||||
del modello gateway, le esigenze di staging del profilo auth e i flag di capacità live/mock. Il codice condiviso
|
||||
di suite e gateway dovrebbe instradare attraverso il registro dei provider invece di ramificarsi in base ai
|
||||
nomi dei provider.
|
||||
del modello gateway, le esigenze di staging del profilo auth e i flag di capacità live/mock. Il codice condiviso della suite e del gateway dovrebbe instradare attraverso il registro dei provider invece di ramificare sui nomi dei provider.
|
||||
|
||||
## Adapter di trasporto
|
||||
## Adattatori di trasporto
|
||||
|
||||
`qa-lab` possiede una seam di trasporto generica per scenari QA Markdown.
|
||||
`qa-channel` è il primo adapter su questa seam, ma l'obiettivo del design è più ampio:
|
||||
i futuri canali reali o sintetici dovrebbero collegarsi alla stessa suite runner
|
||||
invece di aggiungere un runner QA specifico per trasporto.
|
||||
`qa-lab` possiede una seam di trasporto generica per gli scenari QA Markdown.
|
||||
`qa-channel` è il primo adattatore su quella seam, ma l'obiettivo di progettazione è più ampio:
|
||||
i futuri canali reali o sintetici dovrebbero collegarsi allo stesso runner di suite
|
||||
invece di aggiungere un runner QA specifico per il trasporto.
|
||||
|
||||
A livello architetturale, la suddivisione è la seguente:
|
||||
A livello di architettura, la suddivisione è:
|
||||
|
||||
- `qa-lab` possiede l'esecuzione generica degli scenari, la concorrenza dei worker, la scrittura degli artifact e il reporting.
|
||||
- l'adapter di trasporto possiede la configurazione del gateway, la readiness, l'osservazione in ingresso e in uscita, le azioni di trasporto e lo stato di trasporto normalizzato.
|
||||
- i file di scenario Markdown in `qa/scenarios/` definiscono l'esecuzione del test; `qa-lab` fornisce la superficie runtime riutilizzabile che li esegue.
|
||||
- `qa-lab` possiede l'esecuzione generica degli scenari, la concorrenza dei worker, la scrittura degli artefatti e la reportistica.
|
||||
- l'adattatore di trasporto possiede la configurazione gateway, la readiness, l'osservazione in ingresso e in uscita, le azioni di trasporto e lo stato di trasporto normalizzato.
|
||||
- i file di scenario Markdown sotto `qa/scenarios/` definiscono l'esecuzione di test; `qa-lab` fornisce la superficie runtime riutilizzabile che li esegue.
|
||||
|
||||
La guida all'adozione, rivolta ai maintainer, per i nuovi adapter di canale si trova in
|
||||
Le linee guida di adozione rivolte ai maintainer per i nuovi adattatori di canale si trovano in
|
||||
[Testing](/it/help/testing#adding-a-channel-to-qa).
|
||||
|
||||
## Reportistica
|
||||
|
||||
`qa-lab` esporta un report di protocollo Markdown dalla timeline osservata del bus.
|
||||
`qa-lab` esporta un report di protocollo Markdown dalla timeline del bus osservata.
|
||||
Il report dovrebbe rispondere a:
|
||||
|
||||
- Cosa ha funzionato
|
||||
@ -202,7 +206,7 @@ Il report dovrebbe rispondere a:
|
||||
- Cosa è rimasto bloccato
|
||||
- Quali scenari di follow-up vale la pena aggiungere
|
||||
|
||||
Per i controlli su carattere e stile, esegui lo stesso scenario su più riferimenti live del modello
|
||||
Per i controlli di carattere e stile, esegui lo stesso scenario su più riferimenti di modelli live
|
||||
e scrivi un report Markdown valutato:
|
||||
|
||||
```bash
|
||||
@ -222,31 +226,31 @@ pnpm openclaw qa character-eval \
|
||||
--judge-concurrency 16
|
||||
```
|
||||
|
||||
Il comando esegue processi figli locali del gateway QA, non Docker. Gli scenari di character eval
|
||||
Il comando esegue processi figli locali del gateway QA, non Docker. Gli scenari di valutazione del carattere
|
||||
dovrebbero impostare la persona tramite `SOUL.md`, quindi eseguire normali turni utente
|
||||
come chat, aiuto workspace e piccole attività sui file. Al modello candidato non
|
||||
dovrebbe essere detto che è in fase di valutazione. Il comando conserva ogni trascrizione
|
||||
completa, registra statistiche di base dell'esecuzione, quindi chiede ai modelli giudice in modalità fast con
|
||||
ragionamento `xhigh` di classificare le esecuzioni per naturalezza, vibe e umorismo.
|
||||
come chat, aiuto nel workspace e piccoli task sui file. Al modello candidato
|
||||
non dovrebbe essere detto che sta venendo valutato. Il comando conserva ogni trascrizione
|
||||
completa, registra statistiche di base dell'esecuzione, quindi chiede ai modelli giudici in modalità fast con
|
||||
ragionamento `xhigh` di classificare le esecuzioni per naturalezza, atmosfera e umorismo.
|
||||
Usa `--blind-judge-models` quando confronti provider: il prompt del giudice riceve comunque
|
||||
ogni trascrizione e stato di esecuzione, ma i riferimenti candidati vengono sostituiti con etichette
|
||||
neutre come `candidate-01`; il report rimappa le classifiche ai riferimenti reali dopo
|
||||
il parsing.
|
||||
Le esecuzioni candidate usano per impostazione predefinita il thinking `high`, con `xhigh` per i modelli OpenAI che
|
||||
Le esecuzioni dei candidati usano per impostazione predefinita il thinking `high`, con `xhigh` per i modelli OpenAI che
|
||||
lo supportano. Sostituisci un candidato specifico inline con
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` imposta comunque un fallback
|
||||
globale, e la vecchia forma `--model-thinking <provider/model=level>` viene
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` imposta comunque
|
||||
un fallback globale, e la vecchia forma `--model-thinking <provider/model=level>` viene
|
||||
mantenuta per compatibilità.
|
||||
I riferimenti candidati OpenAI usano per impostazione predefinita la modalità fast, così da usare l'elaborazione prioritaria dove
|
||||
I riferimenti candidati OpenAI usano per impostazione predefinita la modalità fast così da usare l'elaborazione prioritaria dove
|
||||
il provider la supporta. Aggiungi `,fast`, `,no-fast` o `,fast=false` inline quando un
|
||||
singolo candidato o giudice necessita di un override. Passa `--fast` solo quando vuoi
|
||||
forzare la modalità fast per ogni modello candidato. Le durate di candidati e giudici sono
|
||||
registrate nel report per l'analisi dei benchmark, ma i prompt dei giudici specificano esplicitamente di
|
||||
non classificare in base alla velocità.
|
||||
Le esecuzioni dei modelli candidati e giudici usano entrambe per impostazione predefinita una concorrenza di 16.
|
||||
Riduci `--concurrency` o `--judge-concurrency` quando i limiti del provider o la pressione
|
||||
sul gateway locale rendono un'esecuzione troppo rumorosa.
|
||||
Quando non viene passato alcun candidato `--model`, character eval usa per impostazione predefinita
|
||||
forzare la modalità fast per ogni modello candidato. Le durate di candidati e giudici vengono
|
||||
registrate nel report per l'analisi comparativa, ma i prompt dei giudici specificano esplicitamente
|
||||
di non classificare in base alla velocità.
|
||||
Le esecuzioni sia dei modelli candidati sia di quelli giudici usano entrambe per impostazione predefinita la concorrenza 16. Riduci
|
||||
`--concurrency` o `--judge-concurrency` quando i limiti del provider o la pressione sul gateway locale
|
||||
rendono un'esecuzione troppo rumorosa.
|
||||
Quando non viene passato alcun `--model` candidato, la valutazione del carattere usa per impostazione predefinita
|
||||
`openai/gpt-5.4`, `openai/gpt-5.2`, `openai/gpt-5`, `anthropic/claude-opus-4-6`,
|
||||
`anthropic/claude-sonnet-4-6`, `zai/glm-5.1`,
|
||||
`moonshot/kimi-k2.5` e
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,23 +1,21 @@
|
||||
---
|
||||
read_when:
|
||||
- Stai aggiungendo o modificando migrazioni di doctor
|
||||
- Stai introducendo modifiche incompatibili alla configurazione
|
||||
summary: 'Comando Doctor: controlli di integrità, migrazioni della configurazione e passaggi di riparazione'
|
||||
- Aggiunta o modifica delle migrazioni di doctor
|
||||
- Introduzione di modifiche incompatibili alla configurazione
|
||||
summary: 'Comando doctor: controlli di integrità, migrazioni della configurazione e passaggi di riparazione'
|
||||
title: Doctor
|
||||
x-i18n:
|
||||
generated_at: "2026-04-09T01:29:07Z"
|
||||
generated_at: "2026-04-20T08:30:53Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 75d321bd1ad0e16c29f2382e249c51edfc3a8d33b55bdceea39e7dbcd4901fce
|
||||
source_hash: 61a5e01a306058c49be6095f7c8082d779a55d63cf3b5f4c4096173943faf51b
|
||||
source_path: gateway/doctor.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Doctor
|
||||
|
||||
`openclaw doctor` è lo strumento di riparazione + migrazione di OpenClaw. Corregge
|
||||
configurazioni/stati obsoleti, controlla l'integrità e fornisce passaggi di
|
||||
riparazione concreti.
|
||||
`openclaw doctor` è lo strumento di riparazione + migrazione per OpenClaw. Corregge configurazione/stato obsoleti, esegue controlli di integrità e fornisce passaggi di riparazione attuabili.
|
||||
|
||||
## Avvio rapido
|
||||
|
||||
@ -31,32 +29,32 @@ openclaw doctor
|
||||
openclaw doctor --yes
|
||||
```
|
||||
|
||||
Accetta le impostazioni predefinite senza richiedere conferma (inclusi i passaggi di ripristino di riavvio/servizio/sandbox quando applicabili).
|
||||
Accetta i valori predefiniti senza chiedere conferma (inclusi i passaggi di riparazione di riavvio/servizio/sandbox quando applicabili).
|
||||
|
||||
```bash
|
||||
openclaw doctor --repair
|
||||
```
|
||||
|
||||
Applica le riparazioni consigliate senza richiedere conferma (riparazioni + riavvii dove sicuro).
|
||||
Applica le riparazioni consigliate senza chiedere conferma (riparazioni + riavvii dove sicuro).
|
||||
|
||||
```bash
|
||||
openclaw doctor --repair --force
|
||||
```
|
||||
|
||||
Applica anche riparazioni aggressive (sovrascrive configurazioni del supervisor personalizzate).
|
||||
Applica anche riparazioni aggressive (sovrascrive configurazioni supervisor personalizzate).
|
||||
|
||||
```bash
|
||||
openclaw doctor --non-interactive
|
||||
```
|
||||
|
||||
Esegue senza richieste e applica solo migrazioni sicure (normalizzazione della configurazione + spostamenti dello stato su disco). Salta le azioni di riavvio/servizio/sandbox che richiedono conferma umana.
|
||||
Esegue senza richieste e applica solo migrazioni sicure (normalizzazione della configurazione + spostamenti dello stato su disco). Salta azioni di riavvio/servizio/sandbox che richiedono conferma umana.
|
||||
Le migrazioni dello stato legacy vengono eseguite automaticamente quando rilevate.
|
||||
|
||||
```bash
|
||||
openclaw doctor --deep
|
||||
```
|
||||
|
||||
Analizza i servizi di sistema per installazioni gateway aggiuntive (launchd/systemd/schtasks).
|
||||
Analizza i servizi di sistema per installazioni Gateway aggiuntive (launchd/systemd/schtasks).
|
||||
|
||||
Se vuoi rivedere le modifiche prima di scrivere, apri prima il file di configurazione:
|
||||
|
||||
@ -66,114 +64,99 @@ cat ~/.openclaw/openclaw.json
|
||||
|
||||
## Cosa fa (riepilogo)
|
||||
|
||||
- Aggiornamento pre-flight facoltativo per installazioni git (solo interattivo).
|
||||
- Controllo dell'aggiornamento del protocollo UI (ricostruisce la Control UI quando lo schema del protocollo è più recente).
|
||||
- Aggiornamento pre-flight opzionale per installazioni git (solo interattivo).
|
||||
- Controllo di aggiornamento del protocollo UI (ricostruisce la Control UI quando lo schema del protocollo è più recente).
|
||||
- Controllo di integrità + richiesta di riavvio.
|
||||
- Riepilogo dello stato delle Skills (idonee/mancanti/bloccate) e stato dei plugin.
|
||||
- Riepilogo dello stato di Skills (idonee/mancanti/bloccate) e stato dei plugin.
|
||||
- Normalizzazione della configurazione per valori legacy.
|
||||
- Migrazione della configurazione Talk dai campi legacy piatti `talk.*` a `talk.provider` + `talk.providers.<provider>`.
|
||||
- Controlli di migrazione del browser per configurazioni legacy dell'estensione Chrome e preparazione di Chrome MCP.
|
||||
- Avvisi sulle sostituzioni del provider OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
|
||||
- Avvisi sull'oscuramento di Codex OAuth (`models.providers.openai-codex`).
|
||||
- Controllo dei prerequisiti OAuth TLS per i profili OAuth OpenAI Codex.
|
||||
- Migrazione legacy dello stato su disco (sessioni/dir agente/autenticazione WhatsApp).
|
||||
- Migrazione legacy della chiave del contratto del manifest del plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Migrazione legacy dell'archivio cron (`jobId`, `schedule.cron`, campi delivery/payload di primo livello, `provider` nel payload, semplici job di fallback webhook `notify: true`).
|
||||
- Migrazione della configurazione Talk dai campi flat legacy `talk.*` a `talk.provider` + `talk.providers.<provider>`.
|
||||
- Controlli di migrazione del browser per configurazioni legacy dell'estensione Chrome e stato di prontezza di Chrome MCP.
|
||||
- Avvisi di override del provider OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
|
||||
- Avvisi di shadowing OAuth Codex (`models.providers.openai-codex`).
|
||||
- Controllo dei prerequisiti TLS OAuth per i profili OAuth OpenAI Codex.
|
||||
- Migrazione dello stato legacy su disco (sessions/agent dir/auth WhatsApp).
|
||||
- Migrazione della chiave `contracts` del manifesto dei plugin legacy (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Migrazione dell'archivio Cron legacy (`jobId`, `schedule.cron`, campi top-level delivery/payload, `provider` del payload, job fallback Webhook semplici con `notify: true`).
|
||||
- Ispezione dei file di lock della sessione e pulizia dei lock obsoleti.
|
||||
- Controlli di integrità e permessi dello stato (sessioni, trascrizioni, directory di stato).
|
||||
- Controlli dei permessi del file di configurazione (chmod 600) quando eseguito in locale.
|
||||
- Integrità dell'autenticazione del modello: controlla la scadenza OAuth, può aggiornare token in scadenza e segnala stati di cooldown/disabilitazione del profilo auth.
|
||||
- Controlli di integrità e permessi dello stato (sessions, transcripts, directory dello stato).
|
||||
- Controlli dei permessi del file di configurazione (`chmod 600`) quando eseguito in locale.
|
||||
- Integrità dell'autenticazione del modello: controlla la scadenza OAuth, può rinnovare token in scadenza e segnala stati di cooldown/disabilitazione del profilo di autenticazione.
|
||||
- Rilevamento di directory workspace aggiuntive (`~/openclaw`).
|
||||
- Riparazione dell'immagine sandbox quando la sandbox è abilitata.
|
||||
- Migrazione di servizi legacy e rilevamento di gateway aggiuntivi.
|
||||
- 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 del runtime del gateway (servizio installato ma non in esecuzione; etichetta launchd in cache).
|
||||
- Avvisi sullo stato dei canali (rilevati dal gateway in esecuzione).
|
||||
- Audit della configurazione del supervisor (launchd/systemd/schtasks) con riparazione facoltativa.
|
||||
- Controlli delle best practice del runtime del gateway (Node vs Bun, percorsi dei version manager).
|
||||
- Diagnostica dei conflitti di porta del gateway (predefinita `18789`).
|
||||
- Controlli del runtime Gateway (servizio installato ma non in esecuzione; etichetta launchd in cache).
|
||||
- Avvisi sullo stato dei canali (sondati dal Gateway in esecuzione).
|
||||
- Audit della configurazione supervisor (launchd/systemd/schtasks) con riparazione opzionale.
|
||||
- Controlli delle best practice del runtime Gateway (Node vs Bun, percorsi del gestore versioni).
|
||||
- Diagnostica dei conflitti di porta Gateway (predefinita `18789`).
|
||||
- Avvisi di sicurezza per policy DM aperte.
|
||||
- Controlli di autenticazione del gateway per la modalità token locale (offre la generazione del token quando non esiste una sorgente token; non sovrascrive configurazioni token SecretRef).
|
||||
- Controllo di `linger` per systemd su Linux.
|
||||
- Controllo della dimensione dei file bootstrap del workspace (avvisi per troncamento/quasi limite dei file di contesto).
|
||||
- Controlli di autenticazione Gateway per la modalità token locale (offre la generazione del token quando non esiste alcuna sorgente di token; non sovrascrive configurazioni token SecretRef).
|
||||
- Rilevamento dei problemi di associazione dei dispositivi (richieste di prima associazione in sospeso, aggiornamenti di ruolo/ambito in sospeso, deriva della cache locale obsoleta del token del dispositivo e deriva di autenticazione dei record associati).
|
||||
- Controllo di linger systemd su Linux.
|
||||
- Controllo della dimensione dei file di bootstrap del workspace (avvisi di troncamento/quasi limite per i file di contesto).
|
||||
- Controllo dello stato del completamento della shell e installazione/aggiornamento automatici.
|
||||
- Controllo di preparazione del provider di embedding per la ricerca nella memoria (modello locale, chiave API remota o binario QMD).
|
||||
- Controlli dell'installazione da sorgente (mismatch del workspace pnpm, asset UI mancanti, binario tsx mancante).
|
||||
- Controllo della prontezza del provider di embedding per la ricerca in memoria (modello locale, chiave API remota o binario QMD).
|
||||
- Controlli dell'installazione da sorgente (mismatch del workspace pnpm, risorse UI mancanti, binario tsx mancante).
|
||||
- Scrive la configurazione aggiornata + i metadati del wizard.
|
||||
|
||||
## Backfill e reset Dreams UI
|
||||
## Backfill e reset della UI Dreams
|
||||
|
||||
La scena Dreams della Control UI include le azioni **Backfill**, **Reset** e **Clear Grounded**
|
||||
per il flusso di lavoro di grounded dreaming. Queste azioni usano metodi RPC
|
||||
in stile doctor del gateway, ma **non** fanno parte della riparazione/migrazione
|
||||
della CLI `openclaw doctor`.
|
||||
La scena Dreams della Control UI include le azioni **Backfill**, **Reset** e **Clear Grounded** per il flusso di dreaming grounded. Queste azioni usano metodi RPC in stile doctor del Gateway, ma **non** fanno parte della riparazione/migrazione della CLI `openclaw doctor`.
|
||||
|
||||
Cosa fanno:
|
||||
|
||||
- **Backfill** analizza i file storici `memory/YYYY-MM-DD.md` nel workspace
|
||||
attivo, esegue il passaggio grounded REM diary e scrive voci di backfill
|
||||
reversibili in `DREAMS.md`.
|
||||
- **Reset** rimuove da `DREAMS.md` solo le voci del diario di backfill contrassegnate.
|
||||
- **Clear Grounded** rimuove solo le voci staged grounded-only a breve termine
|
||||
provenienti dal replay storico e che non hanno ancora accumulato richiamo live
|
||||
o supporto giornaliero.
|
||||
- **Backfill** analizza i file storici `memory/YYYY-MM-DD.md` nel workspace attivo, esegue il passaggio grounded REM diary e scrive voci di backfill reversibili in `DREAMS.md`.
|
||||
- **Reset** rimuove solo quelle voci di diario di backfill contrassegnate da `DREAMS.md`.
|
||||
- **Clear Grounded** rimuove solo le voci staged grounded-only a breve termine provenienti dal replay storico e che non hanno ancora accumulato richiamo live o supporto giornaliero.
|
||||
|
||||
Cosa **non** fanno da sole:
|
||||
|
||||
- non modificano `MEMORY.md`
|
||||
- non eseguono migrazioni complete di doctor
|
||||
- non mettono automaticamente in staging i candidati grounded nell'archivio live
|
||||
di promozione a breve termine, a meno che tu non esegua prima esplicitamente il percorso CLI staged
|
||||
- non eseguono migrazioni doctor complete
|
||||
- non mettono automaticamente in staging i candidati grounded nel live short-term promotion store a meno che tu non esegua prima esplicitamente il percorso CLI staged
|
||||
|
||||
Se vuoi che il replay storico grounded influenzi il normale percorso di
|
||||
promozione profonda, usa invece il flusso CLI:
|
||||
Se vuoi che il replay storico grounded influenzi il normale percorso di deep promotion, usa invece il flusso CLI:
|
||||
|
||||
```bash
|
||||
openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
```
|
||||
|
||||
Questo mette in staging i candidati durevoli grounded nell'archivio di dreaming a breve termine mantenendo `DREAMS.md` come superficie di revisione.
|
||||
Questo mette in staging i candidati grounded durevoli nel dreaming store a breve termine mantenendo `DREAMS.md` come superficie di revisione.
|
||||
|
||||
## Comportamento dettagliato e motivazione
|
||||
|
||||
### 0) Aggiornamento facoltativo (installazioni git)
|
||||
### 0) Aggiornamento opzionale (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.
|
||||
Se si tratta di un checkout git e doctor è in esecuzione in modalità interattiva, offre la possibilità di aggiornare (fetch/rebase/build) prima di eseguire doctor.
|
||||
|
||||
### 1) Normalizzazione della configurazione
|
||||
|
||||
Se la configurazione contiene forme di valori legacy (ad esempio `messages.ackReaction`
|
||||
senza una sostituzione specifica per canale), doctor le normalizza nello schema attuale.
|
||||
Se la configurazione contiene forme di valore legacy (per esempio `messages.ackReaction` senza un override specifico per canale), doctor le normalizza nello schema corrente.
|
||||
|
||||
Questo include i campi legacy piatti di Talk. La configurazione pubblica attuale di Talk è
|
||||
`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 flat legacy di Talk. La configurazione pubblica corrente di Talk è `talk.provider` + `talk.providers.<provider>`. Doctor riscrive le vecchie forme `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` nella mappa provider.
|
||||
|
||||
### 2) Migrazioni delle chiavi di configurazione legacy
|
||||
|
||||
Quando la configurazione contiene chiavi deprecate, gli altri comandi si 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 eseguirà queste operazioni:
|
||||
Doctor eseguirà quanto segue:
|
||||
|
||||
- Spiegare quali chiavi legacy sono state trovate.
|
||||
- Mostrare la migrazione applicata.
|
||||
- Riscrivere `~/.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 dell'archivio dei job cron sono gestite da `openclaw doctor --fix`.
|
||||
Il Gateway esegue inoltre automaticamente le migrazioni doctor all'avvio quando rileva un formato di configurazione legacy, così le configurazioni obsolete vengono riparate senza intervento manuale.
|
||||
Le migrazioni dell'archivio dei job Cron sono gestite da `openclaw doctor --fix`.
|
||||
|
||||
Migrazioni attuali:
|
||||
Migrazioni correnti:
|
||||
|
||||
- `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`
|
||||
- `routing.queue` → `messages.queue`
|
||||
- `routing.bindings` → `bindings` di primo livello
|
||||
- `routing.bindings` → top-level `bindings`
|
||||
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
|
||||
- legacy `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.<provider>`
|
||||
- `routing.agentToAgent` → `tools.agentToAgent`
|
||||
@ -188,7 +171,7 @@ Migrazioni attuali:
|
||||
- `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` nominati ma con ancora valori di canale di primo livello per account singolo, sposta quei valori con ambito account nell'account promosso scelto per quel canale (`accounts.default` per la maggior parte dei canali; Matrix può preservare un target nominato/predefinito corrispondente esistente)
|
||||
- Per i canali con `accounts` nominati ma con valori top-level del canale single-account 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 un target nominato/predefinito esistente corrispondente)
|
||||
- `identity` → `agents.list[].identity`
|
||||
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
|
||||
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
|
||||
@ -197,22 +180,19 @@ Migrazioni attuali:
|
||||
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
|
||||
- rimuove `browser.relayBindHost` (impostazione legacy del relay dell'estensione)
|
||||
|
||||
Gli avvisi di doctor includono anche indicazioni sul default account per i canali multi-account:
|
||||
Gli avvisi di doctor includono anche indicazioni sui predefiniti degli account per i canali multi-account:
|
||||
|
||||
- Se sono configurate due o più voci `channels.<channel>.accounts` senza `channels.<channel>.defaultAccount` o `accounts.default`, doctor avvisa che il routing di fallback può selezionare un account imprevisto.
|
||||
- Se due o più voci `channels.<channel>.accounts` sono configurate senza `channels.<channel>.defaultAccount` o `accounts.default`, doctor avvisa che il routing di fallback può scegliere un account imprevisto.
|
||||
- Se `channels.<channel>.defaultAccount` è impostato su un ID account sconosciuto, doctor avvisa ed elenca gli ID account configurati.
|
||||
|
||||
### 2b) Sostituzioni del provider OpenCode
|
||||
### 2b) Override del provider OpenCode
|
||||
|
||||
Se hai aggiunto manualmente `models.providers.opencode`, `opencode-zen` o `opencode-go`,
|
||||
questo sostituisce il catalogo OpenCode integrato da `@mariozechner/pi-ai`.
|
||||
Può forzare i modelli sull'API sbagliata o azzerare i costi. Doctor avvisa in modo che tu
|
||||
possa rimuovere la sostituzione e ripristinare il routing API + i costi per modello.
|
||||
Se hai aggiunto manualmente `models.providers.opencode`, `opencode-zen` o `opencode-go`, questo 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 il routing API per modello + i costi.
|
||||
|
||||
### 2c) Migrazione del browser e preparazione di Chrome MCP
|
||||
### 2c) Migrazione del browser e prontezza di Chrome MCP
|
||||
|
||||
Se la tua configurazione del browser punta ancora al percorso rimosso dell'estensione Chrome, doctor
|
||||
la normalizza nell'attuale modello di collegamento Chrome MCP host-local:
|
||||
Se la configurazione del browser punta ancora al percorso rimosso dell'estensione Chrome, doctor la normalizza all'attuale modello di collegamento Chrome MCP host-local:
|
||||
|
||||
- `browser.profiles.*.driver: "extension"` diventa `"existing-session"`
|
||||
- `browser.relayBindHost` viene rimosso
|
||||
@ -220,157 +200,143 @@ la normalizza nell'attuale modello di collegamento Chrome MCP host-local:
|
||||
Doctor controlla anche il percorso Chrome MCP host-local quando usi `defaultProfile:
|
||||
"user"` o un profilo `existing-session` configurato:
|
||||
|
||||
- verifica se Google Chrome è installato sullo stesso host per i profili di
|
||||
connessione automatica predefiniti
|
||||
- controlla la versione di Chrome rilevata e avvisa quando è inferiore a Chrome 144
|
||||
- ricorda di abilitare il debug remoto nella pagina inspect 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 di connessione automatica predefiniti
|
||||
- controlla la versione rilevata di Chrome e avvisa quando è inferiore a Chrome 144
|
||||
- ricorda di abilitare il remote debugging nella pagina inspect del browser (per esempio `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`, o `edge://inspect/#remote-debugging`)
|
||||
|
||||
Doctor non può abilitare per te l'impostazione lato Chrome. Chrome MCP host-local
|
||||
richiede comunque:
|
||||
Doctor non può abilitare per te l'impostazione lato Chrome. Chrome MCP host-local richiede comunque:
|
||||
|
||||
- un browser basato su Chromium 144+ sull'host gateway/node
|
||||
- il browser in esecuzione localmente
|
||||
- il debug remoto abilitato in quel browser
|
||||
- l'approvazione del primo prompt di consenso al collegamento nel browser
|
||||
- il remote debugging abilitato in quel browser
|
||||
- l'approvazione del primo prompt di consenso per il collegamento nel browser
|
||||
|
||||
La preparazione qui riguarda solo i prerequisiti per il collegamento locale. Existing-session mantiene
|
||||
gli attuali limiti di routing di Chrome MCP; percorsi avanzati come `responsebody`, esportazione PDF,
|
||||
intercettazione dei download e azioni batch richiedono ancora un browser gestito
|
||||
o un profilo CDP raw.
|
||||
La prontezza qui riguarda solo i prerequisiti di collegamento locale. Existing-session mantiene gli attuali limiti di instradamento di Chrome MCP; instradamenti avanzati 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 raw CDP.
|
||||
Questo controllo **non** si applica a Docker, sandbox, remote-browser o altri flussi headless. Questi continuano a usare CDP raw.
|
||||
|
||||
### 2d) Prerequisiti OAuth TLS
|
||||
### 2d) Prerequisiti TLS OAuth
|
||||
|
||||
Quando è configurato un profilo OAuth OpenAI Codex, doctor verifica l'endpoint di
|
||||
autorizzazione OpenAI per controllare che lo stack TLS locale Node/OpenSSL possa
|
||||
validare la catena di certificati. Se la verifica 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 piattaforma. Su macOS con un Node Homebrew, la
|
||||
correzione è di solito `brew postinstall ca-certificates`. Con `--deep`, la verifica viene eseguita
|
||||
anche se il gateway è integro.
|
||||
Quando è configurato un profilo OAuth OpenAI Codex, doctor interroga l'endpoint di autorizzazione OpenAI per verificare che lo stack TLS Node/OpenSSL locale possa validare la catena di certificati. Se la verifica fallisce con un errore di certificato (per esempio `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, certificato scaduto o certificato self-signed), doctor stampa indicazioni di correzione specifiche per piattaforma. Su macOS con un Node Homebrew, la correzione di solito è `brew postinstall ca-certificates`. Con `--deep`, la verifica viene eseguita anche se il Gateway è integro.
|
||||
|
||||
### 2c) Sostituzioni del provider Codex OAuth
|
||||
### 2c) Override del provider OAuth Codex
|
||||
|
||||
Se in precedenza hai aggiunto impostazioni legacy del trasporto OpenAI sotto
|
||||
`models.providers.openai-codex`, queste possono oscurare il percorso del
|
||||
provider Codex OAuth integrato che le versioni più recenti usano automaticamente. Doctor avvisa quando vede
|
||||
quelle vecchie impostazioni di trasporto insieme a Codex OAuth in modo che tu possa rimuovere o riscrivere
|
||||
la sostituzione del trasporto obsoleta e recuperare il comportamento integrato di routing/fallback.
|
||||
I proxy personalizzati e le sostituzioni solo-header sono ancora supportati e non
|
||||
attivano questo avviso.
|
||||
`models.providers.openai-codex`, possono oscurare il percorso del provider
|
||||
OAuth Codex integrato che le versioni più recenti usano automaticamente. Doctor
|
||||
avvisa quando rileva queste vecchie impostazioni di trasporto insieme a Codex OAuth,
|
||||
così puoi rimuovere o riscrivere l'override di trasporto obsoleto e ripristinare
|
||||
il comportamento integrato di routing/fallback. I proxy personalizzati e gli override
|
||||
solo intestazione sono ancora supportati e non attivano questo avviso.
|
||||
|
||||
### 3) Migrazioni dello stato legacy (layout su disco)
|
||||
|
||||
Doctor può migrare vecchi layout su disco nella struttura attuale:
|
||||
Doctor può migrare layout su disco più vecchi nella struttura corrente:
|
||||
|
||||
- Archivio sessioni + trascrizioni:
|
||||
- Archivio delle sessioni + transcript:
|
||||
- da `~/.openclaw/sessions/` a `~/.openclaw/agents/<agentId>/sessions/`
|
||||
- Directory agente:
|
||||
- Directory dell'agente:
|
||||
- da `~/.openclaw/agent/` a `~/.openclaw/agents/<agentId>/agent/`
|
||||
- Stato auth WhatsApp (Baileys):
|
||||
- da `~/.openclaw/credentials/*.json` legacy (eccetto `oauth.json`)
|
||||
- Stato di autenticazione WhatsApp (Baileys):
|
||||
- dal legacy `~/.openclaw/credentials/*.json` (eccetto `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 migrano automaticamente
|
||||
all'avvio le sessioni legacy + la directory agente, quindi cronologia/auth/modelli finiscono nel
|
||||
percorso per agente senza eseguire manualmente doctor. L'auth WhatsApp viene intenzionalmente
|
||||
migrata solo tramite `openclaw doctor`. La normalizzazione di provider/mappa provider di Talk ora
|
||||
confronta per uguaglianza strutturale, quindi differenze solo nell'ordine delle chiavi non attivano più
|
||||
modifiche ripetute e inutili di `doctor --fix`.
|
||||
lascia cartelle legacy come backup. Anche il Gateway/la CLI eseguono automaticamente
|
||||
la migrazione delle sessioni legacy + della directory dell'agente all'avvio, così cronologia/autenticazione/modelli finiscono nel
|
||||
percorso per agente senza una esecuzione manuale di doctor. L'autenticazione WhatsApp viene intenzionalmente
|
||||
migrata solo tramite `openclaw doctor`. La normalizzazione del provider/mappa provider di Talk ora
|
||||
confronta per uguaglianza strutturale, quindi differenze dovute solo all'ordine delle chiavi non attivano più
|
||||
modifiche ripetute senza effetto di `doctor --fix`.
|
||||
|
||||
### 3a) Migrazioni legacy del manifest dei plugin
|
||||
### 3a) Migrazioni legacy del manifesto dei plugin
|
||||
|
||||
Doctor analizza tutti i manifest dei plugin installati per trovare chiavi di capability
|
||||
di primo livello deprecate (`speechProviders`, `realtimeTranscriptionProviders`,
|
||||
Doctor analizza tutti i manifesti dei plugin installati alla ricerca di chiavi di capacità
|
||||
top-level deprecate (`speechProviders`, `realtimeTranscriptionProviders`,
|
||||
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
|
||||
`imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`,
|
||||
`webSearchProviders`). Quando le trova, propone di spostarle nell'oggetto `contracts`
|
||||
e di riscrivere il file del manifest sul posto. Questa migrazione è idempotente;
|
||||
e di riscrivere il file del manifesto in-place. Questa migrazione è idempotente;
|
||||
se la chiave `contracts` contiene già gli stessi valori, la chiave legacy viene rimossa
|
||||
senza duplicare i dati.
|
||||
|
||||
### 3b) Migrazioni legacy dell'archivio cron
|
||||
### 3b) Migrazioni legacy dell'archivio Cron
|
||||
|
||||
Doctor controlla anche l'archivio dei job cron (`~/.openclaw/cron/jobs.json` per impostazione predefinita,
|
||||
o `cron.store` quando sostituito) per trovare forme di job vecchie che lo scheduler accetta ancora
|
||||
per compatibilità.
|
||||
Doctor controlla anche l'archivio dei job Cron (`~/.openclaw/cron/jobs.json` per impostazione predefinita,
|
||||
oppure `cron.store` se sovrascritto) per vecchie forme di job che lo scheduler continua
|
||||
ad accettare 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 delivery di primo livello (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- alias delivery `provider` nel payload → `delivery.channel` esplicito
|
||||
- semplici job legacy di fallback webhook `notify: true` → `delivery.mode="webhook"` esplicito con `delivery.to=cron.webhook`
|
||||
- campi payload top-level (`message`, `model`, `thinking`, ...) → `payload`
|
||||
- campi delivery top-level (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- alias di delivery `provider` del payload → `delivery.channel` esplicito
|
||||
- semplici job fallback Webhook 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 legacy di notify con una modalità
|
||||
delivery non-webhook esistente, doctor avvisa e lascia quel job per una revisione manuale.
|
||||
cambiare il comportamento. Se un job combina il fallback notify legacy con una modalità
|
||||
di delivery non webhook già esistente, doctor avvisa e lascia quel job alla revisione manuale.
|
||||
|
||||
### 3c) Pulizia dei lock di sessione
|
||||
|
||||
Doctor analizza ogni directory di sessione dell'agente per trovare file di lock di scrittura obsoleti — file lasciati
|
||||
indietro quando una sessione è terminata in modo anomalo. Per ogni file di lock trovato segnala:
|
||||
Doctor analizza ogni directory di sessione dell'agente alla ricerca di file di lock di scrittura obsoleti —
|
||||
file lasciati indietro quando una sessione è terminata in modo anomalo. Per ogni file di lock trovato riporta:
|
||||
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
|
||||
ti dice di rieseguire con `--fix`.
|
||||
ti istruisce a eseguire di nuovo con `--fix`.
|
||||
|
||||
### 4) Controlli di integrità dello stato (persistenza della sessione, routing e sicurezza)
|
||||
|
||||
La directory di stato è il tronco encefalico operativo. Se scompare, perdi
|
||||
La directory dello stato è il tronco encefalico operativo. 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
|
||||
- **Directory dello stato mancante**: avvisa di una 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 rileva una mancata corrispondenza tra proprietario/gruppo).
|
||||
- **Directory di stato macOS sincronizzata con il cloud**: avvisa quando lo stato si risolve sotto iCloud Drive
|
||||
- **Permessi della directory dello stato**: verifica la scrivibilità; offre di riparare i permessi
|
||||
(ed emette un suggerimento `chown` quando viene rilevata una discrepanza di proprietario/gruppo).
|
||||
- **Directory dello stato sincronizzata nel cloud su macOS**: avvisa quando lo stato si risolve sotto iCloud Drive
|
||||
(`~/Library/Mobile Documents/com~apple~CloudDocs/...`) o
|
||||
`~/Library/CloudStorage/...` perché i percorsi supportati dalla sincronizzazione possono causare I/O più lenti
|
||||
`~/Library/CloudStorage/...` perché i percorsi supportati dalla 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 supportato da SD o eMMC può essere più lento e usurarsi più
|
||||
rapidamente con scritture di sessione e credenziali.
|
||||
- **Directory di sessione mancanti**: `sessions/` e la directory dell'archivio sessioni sono
|
||||
- **Directory dello stato su SD o eMMC su Linux**: avvisa quando lo stato si risolve su una sorgente di mount `mmcblk*`,
|
||||
perché l'I/O casuale supportato da SD o eMMC può essere più lento e usurarsi
|
||||
più velocemente con le scritture di sessioni e credenziali.
|
||||
- **Directory delle sessioni mancanti**: `sessions/` e la directory dell'archivio delle sessioni sono
|
||||
necessarie per mantenere la cronologia ed evitare crash `ENOENT`.
|
||||
- **Mismatch 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
|
||||
- **Mancata corrispondenza dei transcript**: avvisa quando voci di sessione recenti hanno
|
||||
file transcript mancanti.
|
||||
- **Sessione principale “JSONL a 1 riga”**: segnala quando il transcript 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ò
|
||||
- **Più directory dello stato**: avvisa quando esistono più cartelle `~/.openclaw` in
|
||||
directory home diverse 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 si trova lì).
|
||||
- **Permessi del file di configurazione**: avvisa se `~/.openclaw/openclaw.json` è
|
||||
leggibile da gruppo/altri e offre di restringerlo a `600`.
|
||||
leggibile da gruppo/altri e offre di restringerli a `600`.
|
||||
|
||||
### 5) Integrità auth del modello (scadenza OAuth)
|
||||
### 5) Integrità dell'autenticazione del modello (scadenza OAuth)
|
||||
|
||||
Doctor ispeziona i profili OAuth nell'archivio auth, 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 Anthropic.
|
||||
Le richieste di refresh compaiono solo in esecuzione interattiva (TTY); `--non-interactive`
|
||||
salta i tentativi di refresh.
|
||||
Doctor ispeziona i profili OAuth nell'archivio auth, avvisa quando i token stanno
|
||||
per scadere/sono scaduti e può aggiornarli quando è sicuro. Se il
|
||||
profilo OAuth/token Anthropic è obsoleto, suggerisce una chiave API Anthropic o il
|
||||
percorso del setup-token Anthropic.
|
||||
Le richieste di aggiornamento compaiono solo in esecuzione interattiva (TTY); `--non-interactive`
|
||||
salta i tentativi di aggiornamento.
|
||||
|
||||
Quando un refresh OAuth fallisce in modo permanente (ad esempio `refresh_token_reused`,
|
||||
Quando un aggiornamento OAuth fallisce in modo permanente (per esempio `refresh_token_reused`,
|
||||
`invalid_grant`, o un provider che ti dice di accedere di nuovo), doctor segnala
|
||||
che è richiesta una nuova autenticazione e stampa il comando esatto `openclaw models auth login --provider ...`
|
||||
che è necessaria una nuova autenticazione e stampa l'esatto comando `openclaw models auth login --provider ...`
|
||||
da eseguire.
|
||||
|
||||
Doctor segnala anche i profili auth temporaneamente inutilizzabili a causa di:
|
||||
|
||||
- brevi cooldown (limiti di frequenza/timeout/errori auth)
|
||||
- cooldown brevi (rate limit/timeout/errori di autenticazione)
|
||||
- disabilitazioni più lunghe (errori di fatturazione/credito)
|
||||
|
||||
### 6) Validazione del modello Hooks
|
||||
@ -380,170 +346,198 @@ catalogo e alla allowlist e avvisa quando non verrà risolto o non è consentito
|
||||
|
||||
### 7) Riparazione dell'immagine sandbox
|
||||
|
||||
Quando la sandbox è abilitata, doctor controlla le immagini Docker e offre di compilare o
|
||||
passare a nomi legacy se l'immagine attuale manca.
|
||||
Quando il sandboxing è abilitato, doctor controlla le immagini Docker e offre di compilare o
|
||||
passare a nomi legacy se l'immagine corrente è mancante.
|
||||
|
||||
### 7b) Dipendenze runtime dei plugin integrati
|
||||
### 7b) Dipendenze runtime dei plugin inclusi
|
||||
|
||||
Doctor verifica che le dipendenze runtime dei plugin integrati (ad esempio i
|
||||
Doctor verifica che le dipendenze runtime dei plugin inclusi (per esempio i
|
||||
pacchetti runtime del plugin Discord) siano presenti nella root di installazione di OpenClaw.
|
||||
Se ne manca qualcuna, doctor segnala i pacchetti e li installa in modalità
|
||||
`openclaw doctor --fix` / `openclaw doctor --repair`.
|
||||
Se ne manca qualcuna, doctor segnala i pacchetti e li installa in
|
||||
modalità `openclaw doctor --fix` / `openclaw doctor --repair`.
|
||||
|
||||
### 8) Migrazioni del servizio gateway e suggerimenti di pulizia
|
||||
### 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 attuale.
|
||||
Può anche cercare servizi aggiuntivi simili a gateway e stampare suggerimenti di pulizia.
|
||||
I servizi gateway OpenClaw con nome del profilo sono considerati di prima classe e non vengono
|
||||
contrassegnati come "aggiuntivi".
|
||||
Doctor rileva servizi Gateway legacy (launchd/systemd/schtasks) e
|
||||
offre di rimuoverli e installare il servizio OpenClaw usando l'attuale porta del Gateway.
|
||||
Può anche cercare 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 "aggiuntivi".
|
||||
|
||||
### 8b) Migrazione Matrix all'avvio
|
||||
|
||||
Quando un account del canale Matrix ha una migrazione dello stato legacy in sospeso o applicabile,
|
||||
Quando un account del canale Matrix ha una migrazione dello stato legacy in sospeso o attuabile,
|
||||
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
|
||||
legacy dello stato cifrato. Entrambi i passaggi non sono fatali; gli errori vengono registrati e
|
||||
l'avvio continua. In modalità sola lettura (`openclaw doctor` senza `--fix`) questo controllo
|
||||
dello stato cifrato legacy. Entrambi i passaggi non sono fatali; gli errori vengono registrati e
|
||||
l'avvio continua. In modalità di sola lettura (`openclaw doctor` senza `--fix`) questo controllo
|
||||
viene saltato completamente.
|
||||
|
||||
### 8c) Associazione del dispositivo e deriva dell'autenticazione
|
||||
|
||||
Doctor ora ispeziona lo stato di associazione del dispositivo come parte del normale controllo di integrità.
|
||||
|
||||
Cosa riporta:
|
||||
|
||||
- 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 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 divergono dalla baseline di associazione approvata
|
||||
- voci della cache locale del token del dispositivo per la macchina corrente che precedono una
|
||||
rotazione del token lato gateway o che riportano metadati di ambito obsoleti
|
||||
|
||||
Doctor non approva automaticamente richieste di associazione né ruota automaticamente i token del dispositivo. Invece
|
||||
stampa i passaggi successivi esatti:
|
||||
|
||||
- ispeziona le richieste in sospeso con `openclaw devices list`
|
||||
- approva la richiesta esatta con `openclaw devices approve <requestId>`
|
||||
- ruota un nuovo token con `openclaw devices rotate --device <deviceId> --role <role>`
|
||||
- rimuovi e riapprova un record obsoleto con `openclaw devices remove <deviceId>`
|
||||
|
||||
Questo chiude il comune problema "già associato ma ricevo ancora pairing required":
|
||||
doctor ora distingue la prima associazione dagli aggiornamenti di ruolo/ambito in sospeso
|
||||
e dalla deriva obsoleta del token/dell'identità del dispositivo.
|
||||
|
||||
### 9) Avvisi di sicurezza
|
||||
|
||||
Doctor emette avvisi quando un provider è aperto ai DM senza una allowlist, o
|
||||
Doctor emette avvisi quando un provider è aperto ai DM senza una allowlist, oppure
|
||||
quando una policy è configurata in modo pericoloso.
|
||||
|
||||
### 10) systemd linger (Linux)
|
||||
|
||||
Se è in esecuzione come servizio utente systemd, doctor assicura che lingering sia abilitato in modo che il
|
||||
gateway resti attivo dopo il logout.
|
||||
Se è in esecuzione come servizio utente systemd, doctor garantisce che lingering sia abilitato affinché il
|
||||
Gateway resti attivo dopo il logout.
|
||||
|
||||
### 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 le Skills idonee, con requisiti mancanti e bloccate dalla allowlist.
|
||||
- **Stato di Skills**: conta le Skills idonee, con requisiti mancanti e bloccate dalla allowlist.
|
||||
- **Directory workspace legacy**: avvisa quando `~/openclaw` o altre directory workspace legacy
|
||||
esistono accanto al workspace attuale.
|
||||
esistono insieme al workspace corrente.
|
||||
- **Stato dei plugin**: conta i plugin caricati/disabilitati/in errore; elenca gli ID plugin per eventuali
|
||||
errori; segnala le capability dei plugin bundle.
|
||||
errori; riporta le capacità dei plugin bundle.
|
||||
- **Avvisi di compatibilità dei plugin**: segnala i plugin che hanno problemi di compatibilità con
|
||||
il runtime attuale.
|
||||
il runtime corrente.
|
||||
- **Diagnostica dei plugin**: mostra eventuali avvisi o errori di caricamento emessi dal
|
||||
registro plugin.
|
||||
registro dei plugin.
|
||||
|
||||
### 11b) Dimensione del file bootstrap
|
||||
### 11b) Dimensione del file di bootstrap
|
||||
|
||||
Doctor controlla se i file bootstrap del workspace (ad esempio `AGENTS.md`,
|
||||
`CLAUDE.md` o altri file di contesto iniettati) sono vicini o oltre il budget
|
||||
di caratteri configurato. Riporta per file il numero di caratteri raw 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 sono troncati o vicini
|
||||
Doctor controlla se i file bootstrap del workspace (per esempio `AGENTS.md`,
|
||||
`CLAUDE.md` o altri file di contesto iniettati) sono vicini o oltre il budget di
|
||||
caratteri configurato. Riporta per file il numero di 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`.
|
||||
|
||||
### 11c) Completamento della shell
|
||||
|
||||
Doctor controlla se il completamento tramite tab è installato per la shell attuale
|
||||
Doctor controlla se il completamento con tabulazione è installato per la shell corrente
|
||||
(zsh, bash, fish o PowerShell):
|
||||
|
||||
- Se il profilo della shell usa un pattern di completamento dinamico lento
|
||||
(`source <(openclaw completion ...)`), doctor lo aggiorna alla variante più veloce
|
||||
con file in cache.
|
||||
- Se il completamento è configurato nel profilo ma il file cache manca,
|
||||
- Se il completamento è configurato nel profilo ma il file di cache manca,
|
||||
doctor rigenera automaticamente la cache.
|
||||
- Se non è configurato alcun completamento, doctor propone di installarlo
|
||||
(solo modalità interattiva; saltato con `--non-interactive`).
|
||||
|
||||
Esegui `openclaw completion --write-state` per rigenerare manualmente la cache.
|
||||
|
||||
### 12) Controlli auth del gateway (token locale)
|
||||
### 12) Controlli di autenticazione Gateway (token locale)
|
||||
|
||||
Doctor controlla la preparazione dell'autenticazione token del gateway locale.
|
||||
Doctor controlla lo stato di prontezza dell'autenticazione del token Gateway locale.
|
||||
|
||||
- Se la modalità token richiede un token e non esiste alcuna sorgente token, doctor propone di generarne uno.
|
||||
- Se la modalità token richiede un token e non esiste alcuna sorgente di 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.
|
||||
|
||||
### 12b) Riparazioni in sola lettura consapevoli di SecretRef
|
||||
|
||||
Alcuni flussi di riparazione devono ispezionare le credenziali configurate senza indebolire il comportamento runtime fail-fast.
|
||||
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 riassuntivo SecretRef in sola lettura dei comandi della famiglia status per riparazioni di configurazione mirate.
|
||||
- Esempio: la riparazione Telegram `allowFrom` / `groupAllowFrom` con `@username` prova a usare le credenziali del bot configurate quando disponibili.
|
||||
- Se il token del 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 che il token manca.
|
||||
- `openclaw doctor --fix` ora usa lo stesso modello di riepilogo SecretRef in sola lettura dei comandi della famiglia status per riparazioni mirate della configurazione.
|
||||
- Esempio: la riparazione di Telegram `allowFrom` / `groupAllowFrom` `@username` prova a usare le credenziali del bot configurate quando disponibili.
|
||||
- Se il token del 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.
|
||||
|
||||
### 13) Controllo di integrità del gateway + riavvio
|
||||
### 13) Controllo di integrità Gateway + riavvio
|
||||
|
||||
Doctor esegue un controllo di integrità e offre di riavviare il gateway quando
|
||||
Doctor esegue un controllo di integrità e propone di riavviare il Gateway quando
|
||||
sembra non integro.
|
||||
|
||||
### 13b) Preparazione della ricerca nella memoria
|
||||
### 13b) Prontezza della ricerca in memoria
|
||||
|
||||
Doctor controlla se il provider di embedding configurato per la ricerca nella memoria è pronto
|
||||
Doctor controlla se il provider di embedding configurato per la ricerca in memoria è 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 incluse il pacchetto npm e un'opzione manuale per il percorso del binario.
|
||||
- **Provider locale esplicito**: controlla la presenza di un file modello locale o di un URL modello remoto/scaricabile riconosciuto. Se manca, suggerisce di passare a un provider remoto.
|
||||
In caso contrario, stampa indicazioni per la correzione, incluso il pacchetto npm e un'opzione manuale per il percorso 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 auth. Stampa suggerimenti di correzione concreti se manca.
|
||||
- **Provider automatico**: controlla prima la disponibilità del modello locale, poi prova ciascun provider remoto
|
||||
presente nell'ambiente o nell'archivio auth. Se manca, stampa suggerimenti di correzione attuabili.
|
||||
- **Provider automatico**: controlla prima la disponibilità del modello locale, poi prova ogni provider remoto
|
||||
nell'ordine di selezione automatica.
|
||||
|
||||
Quando è disponibile un risultato della verifica del gateway (il gateway era integro al momento del
|
||||
controllo), doctor lo confronta con la configurazione visibile dalla CLI e annota
|
||||
Quando è disponibile il risultato di una verifica del Gateway (il Gateway era integro al momento del
|
||||
controllo), doctor confronta il suo risultato con la configurazione visibile dalla CLI e segnala
|
||||
qualsiasi discrepanza.
|
||||
|
||||
Usa `openclaw memory status --deep` per verificare la preparazione dell'embedding a runtime.
|
||||
Usa `openclaw memory status --deep` per verificare la prontezza degli embedding a runtime.
|
||||
|
||||
### 14) Avvisi sullo stato dei canali
|
||||
|
||||
Se il gateway è integro, doctor esegue una verifica dello stato dei canali e segnala
|
||||
avvisi con le correzioni suggerite.
|
||||
Se il Gateway è integro, doctor esegue una verifica dello stato dei canali e riporta
|
||||
avvisi con correzioni suggerite.
|
||||
|
||||
### 15) Audit + riparazione della configurazione del supervisor
|
||||
### 15) Audit + riparazione della configurazione supervisor
|
||||
|
||||
Doctor controlla la configurazione del supervisor 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/task con i valori predefiniti attuali.
|
||||
Doctor controlla la configurazione supervisor installata (launchd/systemd/schtasks) per
|
||||
valori predefiniti mancanti o obsoleti (ad esempio dipendenze systemd `network-online` e
|
||||
ritardo di riavvio). Quando trova una discrepanza, consiglia un aggiornamento e può
|
||||
riscrivere il file del servizio/task ai valori predefiniti correnti.
|
||||
|
||||
Note:
|
||||
|
||||
- `openclaw doctor` richiede conferma prima di riscrivere la configurazione del supervisor.
|
||||
- `openclaw doctor` chiede conferma prima di riscrivere la configurazione supervisor.
|
||||
- `openclaw doctor --yes` accetta le richieste di riparazione predefinite.
|
||||
- `openclaw doctor --repair` applica le correzioni consigliate senza richieste.
|
||||
- `openclaw doctor --repair --force` sovrascrive configurazioni del supervisor personalizzate.
|
||||
- Se l'autenticazione token richiede un token e `gateway.auth.token` è gestito da SecretRef, doctor durante installazione/riparazione del servizio valida il SecretRef ma non rende persistenti i valori del token risolti in chiaro nei metadati dell'ambiente del servizio supervisor.
|
||||
- Se l'autenticazione token richiede un token e il token SecretRef configurato non è risolto, doctor blocca il percorso di installazione/riparazione con indicazioni concrete.
|
||||
- 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.
|
||||
- `openclaw doctor --repair --force` sovrascrive le configurazioni supervisor personalizzate.
|
||||
- Se l'autenticazione token richiede un token e `gateway.auth.token` è gestito da SecretRef, l'installazione/riparazione del servizio doctor convalida il SecretRef ma non rende persistenti i valori del token in chiaro risolti nei metadati dell'ambiente del servizio supervisor.
|
||||
- Se l'autenticazione token richiede un token e il token SecretRef configurato non è risolto, doctor blocca il percorso di installazione/riparazione con indicazioni attuabili.
|
||||
- Se sono configurati sia `gateway.auth.token` sia `gateway.auth.password` e `gateway.auth.mode` non è impostato, doctor blocca l'installazione/riparazione finché la modalità non viene impostata esplicitamente.
|
||||
- Per le unità user-systemd Linux, i controlli di deriva del token di doctor ora includono sia le sorgenti `Environment=` sia `EnvironmentFile=` quando confrontano i metadati auth del servizio.
|
||||
- Puoi sempre forzare una riscrittura completa tramite `openclaw gateway install --force`.
|
||||
|
||||
### 16) Diagnostica del runtime gateway + della porta
|
||||
### 16) Runtime Gateway + diagnostica della porta
|
||||
|
||||
Doctor ispeziona il runtime del servizio (PID, ultimo stato di uscita) e avvisa quando il
|
||||
servizio è installato ma non è realmente in esecuzione. Controlla anche i conflitti
|
||||
sulla porta gateway (predefinita `18789`) e riporta le cause probabili (gateway già
|
||||
servizio è installato ma non è effettivamente in esecuzione. Controlla anche eventuali conflitti
|
||||
di porta sulla porta del Gateway (predefinita `18789`) e riporta le cause probabili (Gateway già
|
||||
in esecuzione, tunnel SSH).
|
||||
|
||||
### 17) Best practice del runtime gateway
|
||||
### 17) Best practice del runtime Gateway
|
||||
|
||||
Doctor avvisa quando il servizio gateway viene eseguito su Bun o su un percorso Node gestito da version manager
|
||||
Doctor avvisa quando il servizio Gateway viene eseguito su Bun o su un percorso Node gestito da un gestore di versioni
|
||||
(`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 tua shell. Doctor propone di migrare a un'installazione Node di sistema quando
|
||||
e i percorsi dei gestori di versioni possono rompersi 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).
|
||||
|
||||
### 18) Scrittura della configurazione + metadati wizard
|
||||
### 18) Scrittura della configurazione + metadati del wizard
|
||||
|
||||
Doctor rende persistenti eventuali modifiche alla configurazione e appone i metadati wizard per registrare
|
||||
Doctor rende persistenti eventuali modifiche alla configurazione e registra i metadati del wizard per annotare
|
||||
l'esecuzione di doctor.
|
||||
|
||||
### 19) Suggerimenti per il workspace (backup + sistema di memoria)
|
||||
|
||||
Doctor suggerisce un sistema di memoria del workspace quando manca e stampa un suggerimento sul backup
|
||||
Doctor suggerisce un sistema di memoria del workspace quando manca e stampa un suggerimento per il backup
|
||||
se il workspace non è già sotto git.
|
||||
|
||||
Vedi [/concepts/agent-workspace](/it/concepts/agent-workspace) per una guida completa alla
|
||||
struttura del workspace e al backup git (consigliati GitHub o GitLab privati).
|
||||
struttura del workspace e al backup git (GitHub o GitLab privato consigliati).
|
||||
|
||||
@ -1,24 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- Esecuzione o debug del processo gateway
|
||||
- Eseguire o eseguire il debug del processo Gateway
|
||||
summary: Runbook per il servizio Gateway, il ciclo di vita e le operazioni
|
||||
title: Runbook del Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-04-07T08:13:17Z"
|
||||
generated_at: "2026-04-20T08:30:50Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fd2c21036e88612861ef2195b8ff7205aca31386bb11558614ade8d1a54fdebd
|
||||
source_hash: e1004cdd43b1db6794f3ca83da38dbdb231a1976329d9d6d851e2b02405278d8
|
||||
source_path: gateway/index.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Runbook del gateway
|
||||
# Runbook del Gateway
|
||||
|
||||
Usa questa pagina per l'avvio del servizio Gateway il primo giorno e per le operazioni dal secondo giorno in poi.
|
||||
Usa questa pagina per l'avvio del primo giorno e le operazioni del secondo giorno del servizio Gateway.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Risoluzione avanzata dei problemi" icon="siren" href="/it/gateway/troubleshooting">
|
||||
Diagnostica orientata ai sintomi con sequenze di comandi esatte e firme nei log.
|
||||
Diagnostica orientata ai sintomi con sequenze di comandi esatte e firme dei log.
|
||||
</Card>
|
||||
<Card title="Configurazione" icon="sliders" href="/it/gateway/configuration">
|
||||
Guida di configurazione orientata alle attività + riferimento completo della configurazione.
|
||||
@ -27,7 +27,7 @@ Usa questa pagina per l'avvio del servizio Gateway il primo giorno e per le oper
|
||||
Contratto SecretRef, comportamento degli snapshot a runtime e operazioni di migrazione/ricarica.
|
||||
</Card>
|
||||
<Card title="Contratto del piano dei segreti" icon="shield-check" href="/it/gateway/secrets-plan-contract">
|
||||
Regole esatte per target/path di `secrets apply` e comportamento dei profili di autenticazione solo-ref.
|
||||
Regole esatte di target/percorso per `secrets apply` e comportamento dei profili auth solo-ref.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -40,13 +40,13 @@ Usa questa pagina per l'avvio del servizio Gateway il primo giorno e per le oper
|
||||
openclaw gateway --port 18789
|
||||
# debug/trace rispecchiati su stdio
|
||||
openclaw gateway --port 18789 --verbose
|
||||
# termina forzatamente il listener sulla porta selezionata, quindi avvia
|
||||
# forza la terminazione del listener sulla porta selezionata, poi avvia
|
||||
openclaw gateway --force
|
||||
```
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Verifica lo stato del servizio">
|
||||
<Step title="Verifica lo stato di salute del servizio">
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -54,7 +54,7 @@ openclaw status
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Baseline di stato corretto: `Runtime: running` e `RPC probe: ok`.
|
||||
Riferimento di stato corretto: `Runtime: running`, `Connectivity probe: ok` e `Capability: ...` corrispondente a ciò che ti aspetti. Usa `openclaw gateway status --require-rpc` quando ti serve una prova RPC con ambito di lettura, non solo la raggiungibilità.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -64,31 +64,31 @@ Baseline di stato corretto: `Runtime: running` e `RPC probe: ok`.
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Con un gateway raggiungibile, questo esegue probe live per account dei canali e audit opzionali.
|
||||
Se il gateway non è raggiungibile, la CLI torna a riepiloghi dei canali basati solo sulla configurazione invece
|
||||
dell'output dei probe live.
|
||||
Con un gateway raggiungibile questo esegue probe live dei canali per account e audit facoltativi.
|
||||
Se il gateway non è raggiungibile, la CLI torna a riepiloghi dei canali basati solo sulla configurazione
|
||||
invece dell'output dei probe live.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
La ricarica della configurazione del Gateway osserva il percorso del file di configurazione attivo (risolto dai valori predefiniti del profilo/dello stato, oppure da `OPENCLAW_CONFIG_PATH` se impostato).
|
||||
La ricarica della configurazione del Gateway osserva il percorso del file di configurazione attivo (risolto dai valori predefiniti di profilo/stato, o da `OPENCLAW_CONFIG_PATH` se impostato).
|
||||
La modalità predefinita è `gateway.reload.mode="hybrid"`.
|
||||
Dopo il primo caricamento riuscito, il processo in esecuzione serve lo snapshot di configurazione attivo in memoria; una ricarica riuscita sostituisce atomicamente quello snapshot.
|
||||
Dopo il primo caricamento riuscito, il processo in esecuzione serve lo snapshot della configurazione attiva in memoria; una ricarica riuscita sostituisce quello snapshot in modo atomico.
|
||||
</Note>
|
||||
|
||||
## Modello di runtime
|
||||
|
||||
- Un unico processo sempre attivo per routing, control plane e connessioni dei canali.
|
||||
- Un processo sempre attivo per routing, control plane e connessioni dei canali.
|
||||
- Una singola porta multiplexata per:
|
||||
- control/RPC WebSocket
|
||||
- WebSocket control/RPC
|
||||
- API HTTP, compatibili con OpenAI (`/v1/models`, `/v1/embeddings`, `/v1/chat/completions`, `/v1/responses`, `/tools/invoke`)
|
||||
- Control UI e hook
|
||||
- UI di controllo e hook
|
||||
- Modalità di bind predefinita: `loopback`.
|
||||
- L'autenticazione è richiesta per impostazione predefinita. Le configurazioni con segreto condiviso usano
|
||||
- L'auth è richiesta per impostazione predefinita. Le configurazioni con segreto condiviso usano
|
||||
`gateway.auth.token` / `gateway.auth.password` (oppure
|
||||
`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`), e le configurazioni con reverse proxy
|
||||
non-loopback possono usare `gateway.auth.mode: "trusted-proxy"`.
|
||||
`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`), e le configurazioni non-loopback
|
||||
con reverse proxy possono usare `gateway.auth.mode: "trusted-proxy"`.
|
||||
|
||||
## Endpoint compatibili con OpenAI
|
||||
|
||||
@ -102,7 +102,7 @@ La superficie di compatibilità a più alto impatto di OpenClaw ora è:
|
||||
|
||||
Perché questo insieme è importante:
|
||||
|
||||
- La maggior parte delle integrazioni con Open WebUI, LobeChat e LibreChat esegue prima probe su `/v1/models`.
|
||||
- La maggior parte delle integrazioni Open WebUI, LobeChat e LibreChat interroga prima `/v1/models`.
|
||||
- Molte pipeline RAG e di memoria si aspettano `/v1/embeddings`.
|
||||
- I client nativi per agenti preferiscono sempre più spesso `/v1/responses`.
|
||||
|
||||
@ -110,27 +110,27 @@ Nota di pianificazione:
|
||||
|
||||
- `/v1/models` è agent-first: restituisce `openclaw`, `openclaw/default` e `openclaw/<agentId>`.
|
||||
- `openclaw/default` è l'alias stabile che mappa sempre all'agente predefinito configurato.
|
||||
- Usa `x-openclaw-model` quando vuoi un override del provider/modello di backend; altrimenti il normale modello e la configurazione degli embedding dell'agente selezionato restano in controllo.
|
||||
- Usa `x-openclaw-model` quando vuoi una sostituzione del provider/modello backend; altrimenti il normale modello e la configurazione degli embedding dell'agente selezionato restano in controllo.
|
||||
|
||||
Tutti questi endpoint vengono eseguiti sulla porta principale del Gateway e usano lo stesso confine di autenticazione dell'operatore attendibile del resto dell'API HTTP del Gateway.
|
||||
Tutti questi endpoint vengono eseguiti sulla porta principale del Gateway e usano lo stesso confine di auth per operatore fidato del resto dell'API HTTP del Gateway.
|
||||
|
||||
### Precedenza di porta e bind
|
||||
|
||||
| Impostazione | Ordine di risoluzione |
|
||||
| ---------------- | ------------------------------------------------------------- |
|
||||
| Porta del Gateway | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` |
|
||||
| Modalità bind | CLI/override → `gateway.bind` → `loopback` |
|
||||
| Impostazione | Ordine di risoluzione |
|
||||
| ------------ | ------------------------------------------------------------- |
|
||||
| Porta Gateway | `--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789` |
|
||||
| Modalità bind | CLI/override → `gateway.bind` → `loopback` |
|
||||
|
||||
### Modalità di hot reload
|
||||
|
||||
| `gateway.reload.mode` | Comportamento |
|
||||
| --------------------- | ------------------------------------------ |
|
||||
| `off` | Nessuna ricarica della configurazione |
|
||||
| `hot` | Applica solo modifiche sicure a caldo |
|
||||
| `restart` | Riavvia quando le modifiche richiedono reload |
|
||||
| `hybrid` (predefinita) | Applica a caldo quando sicuro, riavvia quando richiesto |
|
||||
| `gateway.reload.mode` | Comportamento |
|
||||
| --------------------- | ----------------------------------------- |
|
||||
| `off` | Nessuna ricarica della configurazione |
|
||||
| `hot` | Applica solo modifiche sicure a caldo |
|
||||
| `restart` | Riavvia per modifiche che richiedono reload |
|
||||
| `hybrid` (predefinito) | Applica a caldo quando sicuro, riavvia quando richiesto |
|
||||
|
||||
## Set di comandi per operatori
|
||||
## Set di comandi per operatore
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -144,14 +144,14 @@ openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
`gateway status --deep` serve per discovery aggiuntiva dei servizi (unità di sistema LaunchDaemons/systemd/schtasks), non per un probe RPC di stato più approfondito.
|
||||
`gateway status --deep` serve per il rilevamento aggiuntivo dei servizi (unità di sistema LaunchDaemons/systemd/schtasks), non per un probe di salute RPC più approfondito.
|
||||
|
||||
## Più gateway (stesso host)
|
||||
## Gateway multipli (stesso host)
|
||||
|
||||
La maggior parte delle installazioni dovrebbe eseguire un gateway per macchina. Un singolo gateway può ospitare più
|
||||
agenti e canali.
|
||||
|
||||
Ti servono più gateway solo quando vuoi intenzionalmente isolamento oppure un bot di emergenza.
|
||||
Hai bisogno di più gateway solo quando vuoi intenzionalmente isolamento o un bot di emergenza.
|
||||
|
||||
Controlli utili:
|
||||
|
||||
@ -163,9 +163,10 @@ openclaw gateway probe
|
||||
Cosa aspettarsi:
|
||||
|
||||
- `gateway status --deep` può segnalare `Other gateway-like services detected (best effort)`
|
||||
e stampare suggerimenti di pulizia quando sono ancora presenti installazioni stale di launchd/systemd/schtasks.
|
||||
- `gateway probe` può avvisare con `multiple reachable gateways` quando risponde più di una destinazione.
|
||||
- Se ciò è intenzionale, isola porte, config/stato e root del workspace per ciascun gateway.
|
||||
e stampare suggerimenti di pulizia quando sono ancora presenti installazioni launchd/systemd/schtasks obsolete.
|
||||
- `gateway probe` può avvisare con `multiple reachable gateways` quando più di un target
|
||||
risponde.
|
||||
- Se è intenzionale, isola porte, configurazione/stato e radici del workspace per ciascun gateway.
|
||||
|
||||
Configurazione dettagliata: [/gateway/multiple-gateways](/it/gateway/multiple-gateways).
|
||||
|
||||
@ -181,16 +182,16 @@ ssh -N -L 18789:127.0.0.1:18789 user@host
|
||||
Poi collega i client localmente a `ws://127.0.0.1:18789`.
|
||||
|
||||
<Warning>
|
||||
I tunnel SSH non aggirano l'autenticazione del gateway. Per l'autenticazione con segreto condiviso, i client devono comunque
|
||||
inviare `token`/`password` anche attraverso il tunnel. Per le modalità con identità incorporata,
|
||||
la richiesta deve comunque soddisfare quel percorso di autenticazione.
|
||||
I tunnel SSH non aggirano l'auth del gateway. Per l'auth con segreto condiviso, i client
|
||||
devono comunque inviare `token`/`password` anche attraverso il tunnel. Per le modalità
|
||||
con identità, la richiesta deve comunque soddisfare quel percorso di auth.
|
||||
</Warning>
|
||||
|
||||
Vedi: [Gateway remoto](/it/gateway/remote), [Autenticazione](/it/gateway/authentication), [Tailscale](/it/gateway/tailscale).
|
||||
|
||||
## Supervisione e ciclo di vita del servizio
|
||||
|
||||
Usa esecuzioni supervisionate per un'affidabilità di tipo produzione.
|
||||
Usa esecuzioni supervisionate per un'affidabilità di livello produzione.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="macOS (launchd)">
|
||||
@ -202,7 +203,7 @@ openclaw gateway restart
|
||||
openclaw gateway stop
|
||||
```
|
||||
|
||||
Le etichette LaunchAgent sono `ai.openclaw.gateway` (predefinita) oppure `ai.openclaw.<profile>` (profilo con nome). `openclaw doctor` verifica e ripara la deriva della configurazione del servizio.
|
||||
Le etichette LaunchAgent sono `ai.openclaw.gateway` (predefinita) o `ai.openclaw.<profile>` (profilo con nome). `openclaw doctor` controlla e ripara la deriva della configurazione del servizio.
|
||||
|
||||
</Tab>
|
||||
|
||||
@ -220,7 +221,7 @@ Per la persistenza dopo il logout, abilita lingering:
|
||||
sudo loginctl enable-linger <user>
|
||||
```
|
||||
|
||||
Esempio manuale di unità utente quando ti serve un percorso di installazione personalizzato:
|
||||
Esempio manuale di unità utente quando hai bisogno di un percorso di installazione personalizzato:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
@ -253,8 +254,8 @@ openclaw gateway stop
|
||||
```
|
||||
|
||||
L'avvio gestito nativo di Windows usa un'Attività pianificata chiamata `OpenClaw Gateway`
|
||||
(o `OpenClaw Gateway (<profile>)` per i profili con nome). Se la creazione dell'Attività pianificata
|
||||
viene negata, OpenClaw torna a un launcher per utente nella cartella Esecuzione automatica
|
||||
(oppure `OpenClaw Gateway (<profile>)` per i profili con nome). Se la creazione
|
||||
dell'Attività pianificata viene negata, OpenClaw ripiega su un launcher per utente nella cartella Startup
|
||||
che punta a `gateway.cmd` all'interno della directory di stato.
|
||||
|
||||
</Tab>
|
||||
@ -268,21 +269,21 @@ sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now openclaw-gateway[-<profile>].service
|
||||
```
|
||||
|
||||
Usa lo stesso corpo del servizio dell'unità utente, ma installalo sotto
|
||||
Usa lo stesso corpo del servizio dell'unità utente, ma installalo in
|
||||
`/etc/systemd/system/openclaw-gateway[-<profile>].service` e regola
|
||||
`ExecStart=` se il tuo binario `openclaw` si trova altrove.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Più gateway su un host
|
||||
## Gateway multipli su un host
|
||||
|
||||
La maggior parte delle configurazioni dovrebbe eseguire **un** solo Gateway.
|
||||
Usane più di uno solo per isolamento/ridondanza rigorosi (ad esempio un profilo di emergenza).
|
||||
La maggior parte delle configurazioni dovrebbe eseguire **un solo** Gateway.
|
||||
Usane più di uno solo per isolamento/ridondanza rigorosi (per esempio un profilo di emergenza).
|
||||
|
||||
Checklist per istanza:
|
||||
|
||||
- `gateway.port` univoco
|
||||
- `gateway.port` univoca
|
||||
- `OPENCLAW_CONFIG_PATH` univoco
|
||||
- `OPENCLAW_STATE_DIR` univoco
|
||||
- `agents.defaults.workspace` univoco
|
||||
@ -294,9 +295,9 @@ OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a opencla
|
||||
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
|
||||
```
|
||||
|
||||
Vedi: [Più gateway](/it/gateway/multiple-gateways).
|
||||
Vedi: [Gateway multipli](/it/gateway/multiple-gateways).
|
||||
|
||||
### Percorso rapido del profilo dev
|
||||
### Percorso rapido per il profilo dev
|
||||
|
||||
```bash
|
||||
openclaw --dev setup
|
||||
@ -304,13 +305,13 @@ openclaw --dev gateway --allow-unconfigured
|
||||
openclaw --dev status
|
||||
```
|
||||
|
||||
I valori predefiniti includono stato/config isolati e porta base del gateway `19001`.
|
||||
I valori predefiniti includono stato/configurazione isolati e una porta Gateway di base `19001`.
|
||||
|
||||
## Riferimento rapido del protocollo (vista operatore)
|
||||
|
||||
- Il primo frame del client deve essere `connect`.
|
||||
- Il Gateway restituisce uno snapshot `hello-ok` (`presence`, `health`, `stateVersion`, `uptimeMs`, limiti/policy).
|
||||
- `hello-ok.features.methods` / `events` sono un elenco di discovery prudente, non
|
||||
- `hello-ok.features.methods` / `events` sono un elenco di rilevamento conservativo, non
|
||||
un dump generato di ogni route helper richiamabile.
|
||||
- Richieste: `req(method, params)` → `res(ok/payload|error)`.
|
||||
- Gli eventi comuni includono `connect.challenge`, `agent`, `chat`,
|
||||
@ -319,7 +320,7 @@ I valori predefiniti includono stato/config isolati e porta base del gateway `19
|
||||
|
||||
Le esecuzioni degli agenti sono in due fasi:
|
||||
|
||||
1. Ack di accettazione immediata (`status:"accepted"`)
|
||||
1. Ack di accettazione immediato (`status:"accepted"`)
|
||||
2. Risposta finale di completamento (`status:"ok"|"error"`), con eventi `agent` in streaming nel mezzo.
|
||||
|
||||
Vedi la documentazione completa del protocollo: [Protocollo Gateway](/it/gateway/protocol).
|
||||
@ -329,7 +330,7 @@ Vedi la documentazione completa del protocollo: [Protocollo Gateway](/it/gateway
|
||||
### Liveness
|
||||
|
||||
- Apri WS e invia `connect`.
|
||||
- Attendi una risposta `hello-ok` con snapshot.
|
||||
- Aspettati una risposta `hello-ok` con snapshot.
|
||||
|
||||
### Readiness
|
||||
|
||||
@ -343,22 +344,22 @@ openclaw health
|
||||
|
||||
Gli eventi non vengono riprodotti. In caso di gap di sequenza, aggiorna lo stato (`health`, `system-presence`) prima di continuare.
|
||||
|
||||
## Firme di errore comuni
|
||||
## Firme comuni di errore
|
||||
|
||||
| Firma | Problema probabile |
|
||||
| ------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
||||
| `refusing to bind gateway ... without auth` | Bind non-loopback senza un percorso di autenticazione del gateway valido |
|
||||
| `another gateway instance is already listening` / `EADDRINUSE` | Conflitto di porta |
|
||||
| `Gateway start blocked: set gateway.mode=local` | Config impostata in modalità remota, oppure stamp di modalità locale mancante in una config danneggiata |
|
||||
| `unauthorized` during connect | Mancata corrispondenza dell'autenticazione tra client e gateway |
|
||||
| Firma | Problema probabile |
|
||||
| -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
|
||||
| `refusing to bind gateway ... without auth` | Bind non-loopback senza un percorso di auth del gateway valido |
|
||||
| `another gateway instance is already listening` / `EADDRINUSE` | Conflitto di porta |
|
||||
| `Gateway start blocked: set gateway.mode=local` | Configurazione impostata in modalità remota, oppure manca il marker local-mode da una configurazione danneggiata |
|
||||
| `unauthorized` during connect | Mancata corrispondenza auth tra client e gateway |
|
||||
|
||||
Per sequenze complete di diagnosi, usa [Risoluzione dei problemi del Gateway](/it/gateway/troubleshooting).
|
||||
|
||||
## Garanzie di sicurezza
|
||||
|
||||
- I client del protocollo Gateway falliscono rapidamente quando il Gateway non è disponibile (nessun fallback implicito diretto al canale).
|
||||
- I first frame non validi/non-connect vengono rifiutati e la connessione viene chiusa.
|
||||
- Lo shutdown ordinato emette l'evento `shutdown` prima della chiusura del socket.
|
||||
- I primi frame non validi/non-connect vengono rifiutati e la connessione viene chiusa.
|
||||
- Lo spegnimento ordinato emette l'evento `shutdown` prima della chiusura del socket.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- L'hub di risoluzione dei problemi ti ha indirizzato qui per una diagnosi più approfondita
|
||||
- Hai bisogno di sezioni di runbook stabili basate sui sintomi con comandi esatti
|
||||
summary: Runbook di risoluzione avanzata dei problemi per gateway, canali, automazione, nodi e browser
|
||||
- Hai bisogno di sezioni del runbook stabili e basate sui sintomi con comandi esatti
|
||||
summary: Runbook di troubleshooting approfondito per Gateway, canali, automazione, Node e browser
|
||||
title: Risoluzione dei problemi
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:45:10Z"
|
||||
generated_at: "2026-04-20T08:30:49Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 7ef2faccba26ede307861504043a6415bc1f12dc64407771106f63ddc5b107f5
|
||||
source_hash: d93a82407dbb1314b91a809ff9433114e1e9a3b56d46547ef53a8196bac06260
|
||||
source_path: gateway/troubleshooting.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -32,12 +32,12 @@ openclaw channels status --probe
|
||||
|
||||
Segnali attesi di stato sano:
|
||||
|
||||
- `openclaw gateway status` mostra `Runtime: running` e `RPC probe: ok`.
|
||||
- `openclaw doctor` non segnala problemi bloccanti di configurazione o servizio.
|
||||
- `openclaw channels status --probe` mostra lo stato live del trasporto per account e,
|
||||
- `openclaw gateway status` mostra `Runtime: running`, `Connectivity probe: ok` e una riga `Capability: ...`.
|
||||
- `openclaw doctor` non segnala problemi bloccanti di configurazione/servizio.
|
||||
- `openclaw channels status --probe` mostra lo stato di trasporto live per account e,
|
||||
dove supportato, risultati di probe/audit come `works` o `audit ok`.
|
||||
|
||||
## Anthropic 429 richiede utilizzo extra per contesto lungo
|
||||
## Anthropic 429: utilizzo extra richiesto per contesto lungo
|
||||
|
||||
Usa questa sezione quando i log/errori includono:
|
||||
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
|
||||
@ -51,14 +51,14 @@ openclaw config get agents.defaults.models
|
||||
Cerca:
|
||||
|
||||
- Il modello Anthropic Opus/Sonnet selezionato ha `params.context1m: true`.
|
||||
- La credenziale Anthropic corrente non è idonea per l'uso con contesto lungo.
|
||||
- Le richieste falliscono solo su sessioni lunghe/esecuzioni del modello che richiedono il percorso beta 1M.
|
||||
- La credenziale Anthropic corrente non è idonea per l'uso del contesto lungo.
|
||||
- Le richieste falliscono solo su sessioni lunghe/esecuzioni del modello che richiedono il percorso beta da 1M.
|
||||
|
||||
Opzioni di correzione:
|
||||
|
||||
1. Disabilita `context1m` per quel modello per tornare alla normale finestra di contesto.
|
||||
2. Usa una credenziale Anthropic idonea per richieste con contesto lungo, oppure passa a una chiave API Anthropic.
|
||||
3. Configura modelli di fallback in modo che le esecuzioni continuino quando le richieste Anthropic con contesto lungo vengono rifiutate.
|
||||
1. Disabilita `context1m` per quel modello in modo da tornare alla finestra di contesto normale.
|
||||
2. Usa una credenziale Anthropic idonea per le richieste a contesto lungo, oppure passa a una chiave API Anthropic.
|
||||
3. Configura modelli di fallback in modo che le esecuzioni continuino quando le richieste Anthropic a contesto lungo vengono rifiutate.
|
||||
|
||||
Correlati:
|
||||
|
||||
@ -66,13 +66,13 @@ Correlati:
|
||||
- [/reference/token-use](/it/reference/token-use)
|
||||
- [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/it/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)
|
||||
|
||||
## Un backend locale compatibile con OpenAI supera le probe dirette ma le esecuzioni dell'agente falliscono
|
||||
## Il backend locale compatibile con OpenAI supera i probe diretti ma le esecuzioni dell'agente falliscono
|
||||
|
||||
Usa questa sezione quando:
|
||||
|
||||
- `curl ... /v1/models` funziona
|
||||
- piccole chiamate dirette a `/v1/chat/completions` funzionano
|
||||
- le esecuzioni del modello OpenClaw falliscono solo durante i normali turni dell'agente
|
||||
- le esecuzioni del modello OpenClaw falliscono solo nei normali turni dell'agente
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:1234/v1/models
|
||||
@ -85,22 +85,34 @@ openclaw logs --follow
|
||||
|
||||
Cerca:
|
||||
|
||||
- le piccole chiamate dirette riescono, ma le esecuzioni OpenClaw falliscono solo con prompt più grandi
|
||||
- le piccole chiamate dirette hanno esito positivo, ma le esecuzioni OpenClaw falliscono solo con prompt più grandi
|
||||
- errori del backend su `messages[].content` che si aspetta una stringa
|
||||
- crash del backend che compaiono solo con conteggi più alti di token nel prompt o con prompt completi del runtime dell'agente
|
||||
- crash del backend che compaiono solo con conteggi di token del prompt più elevati o con i prompt completi del runtime dell'agente
|
||||
|
||||
Firme comuni:
|
||||
|
||||
- `messages[...].content: invalid type: sequence, expected a string` → il backend rifiuta parti di contenuto strutturato in Chat Completions. Correzione: imposta `models.providers.<provider>.models[].compat.requiresStringContent: true`.
|
||||
- le piccole richieste dirette riescono, ma i turni dell'agente OpenClaw falliscono con crash del backend/modello (per esempio Gemma su alcune build `inferrs`) → il trasporto OpenClaw è probabilmente già corretto; è il backend che fallisce sulla forma più ampia del prompt del runtime dell'agente.
|
||||
- i fallimenti si riducono dopo aver disabilitato gli strumenti ma non scompaiono → gli schemi degli strumenti contribuivano al carico, ma il problema rimanente è ancora a monte: capacità del modello/server o un bug del backend.
|
||||
- `messages[...].content: invalid type: sequence, expected a string` → il backend
|
||||
rifiuta le parti strutturate del contenuto di Chat Completions. Correzione: imposta
|
||||
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
|
||||
- le piccole richieste dirette hanno esito positivo, ma i turni dell'agente OpenClaw falliscono con
|
||||
crash del backend/modello (per esempio Gemma su alcune build `inferrs`) → il trasporto OpenClaw è
|
||||
probabilmente già corretto; è il backend che fallisce sulla forma più ampia del prompt
|
||||
del runtime dell'agente.
|
||||
- i fallimenti si riducono dopo aver disabilitato i tool ma non scompaiono → gli schemi dei tool erano
|
||||
parte della pressione, ma il problema residuo è comunque a monte: capacità del modello/server
|
||||
o un bug del backend.
|
||||
|
||||
Opzioni di correzione:
|
||||
|
||||
1. Imposta `compat.requiresStringContent: true` per i backend Chat Completions che accettano solo stringhe.
|
||||
2. Imposta `compat.supportsTools: false` per modelli/backend che non riescono a gestire in modo affidabile la superficie di schema degli strumenti di OpenClaw.
|
||||
3. Riduci il carico del prompt dove possibile: bootstrap del workspace più piccolo, cronologia della sessione più breve, modello locale più leggero o backend con supporto più robusto per contesti lunghi.
|
||||
4. Se le piccole richieste dirette continuano a funzionare mentre i turni dell'agente OpenClaw continuano a crashare nel backend, trattalo come un limite del server/modello a monte e apri lì un repro con la forma di payload accettata.
|
||||
2. Imposta `compat.supportsTools: false` per modelli/backend che non riescono a gestire
|
||||
in modo affidabile la superficie dello schema dei tool di OpenClaw.
|
||||
3. Riduci la pressione del prompt dove possibile: bootstrap dello workspace più piccolo, cronologia
|
||||
della sessione più corta, modello locale più leggero o un backend con supporto più solido
|
||||
per il contesto lungo.
|
||||
4. Se le piccole richieste dirette continuano a funzionare mentre i turni dell'agente OpenClaw continuano a bloccarsi
|
||||
nel backend, trattalo come un limite del server/modello a monte e apri lì
|
||||
un repro con la forma del payload accettata.
|
||||
|
||||
Correlati:
|
||||
|
||||
@ -110,7 +122,7 @@ Correlati:
|
||||
|
||||
## Nessuna risposta
|
||||
|
||||
Se i canali sono attivi ma non arriva nessuna risposta, controlla instradamento e policy prima di ricollegare qualsiasi cosa.
|
||||
Se i canali sono attivi ma non arriva alcuna risposta, controlla instradamento e policy prima di riconnettere qualsiasi cosa.
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -122,14 +134,14 @@ openclaw logs --follow
|
||||
|
||||
Cerca:
|
||||
|
||||
- Pairing in sospeso per i mittenti di messaggi diretti.
|
||||
- Blocco delle menzioni nei gruppi (`requireMention`, `mentionPatterns`).
|
||||
- Mancata corrispondenza nelle allowlist di canale/gruppo.
|
||||
- Pairing in sospeso per i mittenti DM.
|
||||
- Blocco per menzione nei gruppi (`requireMention`, `mentionPatterns`).
|
||||
- Mancate corrispondenze nelle allowlist di canale/gruppo.
|
||||
|
||||
Firme comuni:
|
||||
|
||||
- `drop guild message (mention required` → messaggio di gruppo ignorato finché non viene menzionato.
|
||||
- `pairing request` → il mittente richiede approvazione.
|
||||
- `drop guild message (mention required` → messaggio di gruppo ignorato fino a menzione.
|
||||
- `pairing request` → il mittente necessita approvazione.
|
||||
- `blocked` / `allowlist` → mittente/canale filtrato dalla policy.
|
||||
|
||||
Correlati:
|
||||
@ -138,9 +150,9 @@ Correlati:
|
||||
- [/channels/pairing](/it/channels/pairing)
|
||||
- [/channels/groups](/it/channels/groups)
|
||||
|
||||
## Connettività del dashboard Control UI
|
||||
## Connettività della control UI della dashboard
|
||||
|
||||
Quando il dashboard/Control UI non si connette, verifica URL, modalità di autenticazione e presupposti di contesto sicuro.
|
||||
Quando la dashboard/control UI non si connette, verifica URL, modalità di autenticazione e presupposti di contesto sicuro.
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -152,37 +164,47 @@ openclaw gateway status --json
|
||||
|
||||
Cerca:
|
||||
|
||||
- URL di probe e URL del dashboard corretti.
|
||||
- Mancata corrispondenza della modalità/token di autenticazione tra client e gateway.
|
||||
- URL del probe e URL della dashboard corretti.
|
||||
- Mancata corrispondenza della modalità/token di autenticazione tra client e Gateway.
|
||||
- Uso di HTTP dove è richiesta l'identità del dispositivo.
|
||||
|
||||
Firme comuni:
|
||||
|
||||
- `device identity required` → contesto non sicuro o autenticazione del dispositivo mancante.
|
||||
- `origin not allowed` → `Origin` del browser non è in `gateway.controlUi.allowedOrigins`
|
||||
(oppure ti stai connettendo da un'origine browser non loopback senza una allowlist esplicita).
|
||||
- `device nonce required` / `device nonce mismatch` → il client non sta completando il flusso di autenticazione del dispositivo basato su challenge (`connect.challenge` + `device.nonce`).
|
||||
- `device signature invalid` / `device signature expired` → il client ha firmato il payload sbagliato (o con timestamp scaduto) per l'handshake corrente.
|
||||
- `AUTH_TOKEN_MISMATCH` con `canRetryWithDeviceToken=true` → il client può eseguire un retry trusted con token del dispositivo memorizzato in cache.
|
||||
- Quel retry con token in cache riutilizza l'insieme di scope memorizzato con il token del dispositivo associato. I chiamanti con `deviceToken` esplicito / `scopes` espliciti mantengono invece l'insieme di scope richiesto.
|
||||
- Al di fuori di quel percorso di retry, la precedenza dell'autenticazione di connessione è: token/password condivisi espliciti, poi `deviceToken` esplicito, poi token del dispositivo memorizzato, poi bootstrap token.
|
||||
- Nel percorso asincrono Tailscale Serve Control UI, i tentativi falliti per lo stesso `{scope, ip}` vengono serializzati prima che il limitatore registri il fallimento. Due retry concorrenti errati dallo stesso client possono quindi mostrare `retry later` sul secondo tentativo invece di due semplici mismatch.
|
||||
- `too many failed authentication attempts (retry later)` da un client loopback con origine browser → fallimenti ripetuti dalla stessa `Origin` normalizzata vengono temporaneamente bloccati; un'altra origine localhost usa un bucket separato.
|
||||
- `unauthorized` ripetuti dopo quel retry → deriva tra token condiviso e token del dispositivo; aggiorna la configurazione del token e riapprova/ruota il token del dispositivo se necessario.
|
||||
- `gateway connect failed:` → host/porta/target URL errato.
|
||||
- `origin not allowed` → l'`Origin` del browser non è in `gateway.controlUi.allowedOrigins`
|
||||
(oppure stai effettuando la connessione da un'origine browser non loopback senza una
|
||||
allowlist esplicita).
|
||||
- `device nonce required` / `device nonce mismatch` → il client non completa il
|
||||
flusso di autenticazione del dispositivo basato su challenge (`connect.challenge` + `device.nonce`).
|
||||
- `device signature invalid` / `device signature expired` → il client ha firmato il payload sbagliato
|
||||
(o con timestamp obsoleto) per l'handshake corrente.
|
||||
- `AUTH_TOKEN_MISMATCH` con `canRetryWithDeviceToken=true` → il client può eseguire un solo retry affidabile con il token dispositivo in cache.
|
||||
- Quel retry con token in cache riutilizza l'insieme di scope in cache memorizzato con il
|
||||
token del dispositivo associato. I chiamanti con `deviceToken` esplicito / `scopes` espliciti mantengono invece
|
||||
l'insieme di scope richiesto.
|
||||
- Al di fuori di quel percorso di retry, la precedenza dell'autenticazione in connessione è
|
||||
prima token/password condivisi espliciti, poi `deviceToken` esplicito, poi token dispositivo memorizzato,
|
||||
quindi token bootstrap.
|
||||
- Nel percorso asincrono della Control UI Tailscale Serve, i tentativi falliti per lo stesso
|
||||
`{scope, ip}` vengono serializzati prima che il limitatore registri il fallimento. Due retry concorrenti errati dello stesso client possono quindi mostrare `retry later`
|
||||
al secondo tentativo invece di due semplici mismatch.
|
||||
- `too many failed authentication attempts (retry later)` da un client loopback con origine browser
|
||||
→ i fallimenti ripetuti da quello stesso `Origin` normalizzato vengono bloccati temporaneamente; un'altra origine localhost usa un bucket separato.
|
||||
- `unauthorized` ripetuti dopo quel retry → deriva di token condiviso/token dispositivo; aggiorna la configurazione del token e riapprova/ruota il token dispositivo se necessario.
|
||||
- `gateway connect failed:` → host/porta/URL di destinazione errati.
|
||||
|
||||
### Mappa rapida dei codici di dettaglio auth
|
||||
|
||||
Usa `error.details.code` dalla risposta `connect` fallita per scegliere l'azione successiva:
|
||||
|
||||
| Codice di dettaglio | Significato | Azione consigliata |
|
||||
| ---------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `AUTH_TOKEN_MISSING` | Il client non ha inviato un token condiviso richiesto. | Incolla/imposta il token nel client e riprova. Per i percorsi dashboard: `openclaw config get gateway.auth.token` poi incollalo nelle impostazioni di Control UI. |
|
||||
| `AUTH_TOKEN_MISMATCH` | Il token condiviso non corrisponde al token auth del gateway. | Se `canRetryWithDeviceToken=true`, consenti un retry trusted. I retry con token in cache riutilizzano gli scope approvati memorizzati; i chiamanti con `deviceToken` / `scopes` espliciti mantengono gli scope richiesti. Se continua a fallire, esegui la [checklist di ripristino della deriva del token](/cli/devices#token-drift-recovery-checklist). |
|
||||
| `AUTH_DEVICE_TOKEN_MISMATCH` | Il token per dispositivo memorizzato è obsoleto o revocato. | Ruota/riapprova il token del dispositivo usando la [CLI devices](/cli/devices), poi riconnettiti. |
|
||||
| `PAIRING_REQUIRED` | L'identità del dispositivo è nota ma non approvata per questo ruolo. | Approva la richiesta in sospeso: `openclaw devices list` poi `openclaw devices approve <requestId>`. |
|
||||
| Detail code | Meaning | Recommended action |
|
||||
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `AUTH_TOKEN_MISSING` | Il client non ha inviato un token condiviso richiesto. | Incolla/imposta il token nel client e riprova. Per i percorsi dashboard: `openclaw config get gateway.auth.token` poi incollalo nelle impostazioni della Control UI. |
|
||||
| `AUTH_TOKEN_MISMATCH` | Il token condiviso non corrisponde al token auth del Gateway. | Se `canRetryWithDeviceToken=true`, consenti un retry affidabile. I retry con token in cache riutilizzano gli scope approvati memorizzati; i chiamanti con `deviceToken` / `scopes` espliciti mantengono gli scope richiesti. Se continua a fallire, esegui la [checklist di ripristino deriva token](/cli/devices#token-drift-recovery-checklist). |
|
||||
| `AUTH_DEVICE_TOKEN_MISMATCH` | Il token per-dispositivo in cache è obsoleto o revocato. | Ruota/riapprova il token dispositivo usando la [CLI dei dispositivi](/cli/devices), poi riconnettiti. |
|
||||
| `PAIRING_REQUIRED` | L'identità del dispositivo richiede approvazione. Controlla `error.details.reason` per `not-paired`, `scope-upgrade`, `role-upgrade` o `metadata-upgrade`, e usa `requestId` / `remediationHint` quando presenti. | Approva la richiesta in sospeso: `openclaw devices list` poi `openclaw devices approve <requestId>`. Gli upgrade di scope/ruolo usano lo stesso flusso dopo aver esaminato l'accesso richiesto. |
|
||||
|
||||
Controllo della migrazione ad auth dispositivo v2:
|
||||
Controllo della migrazione auth dispositivo v2:
|
||||
|
||||
```bash
|
||||
openclaw --version
|
||||
@ -193,25 +215,27 @@ openclaw gateway status
|
||||
Se i log mostrano errori di nonce/firma, aggiorna il client che si connette e verifica che:
|
||||
|
||||
1. attenda `connect.challenge`
|
||||
2. firmi il payload vincolato alla challenge
|
||||
2. firmi il payload associato alla challenge
|
||||
3. invii `connect.params.device.nonce` con lo stesso nonce della challenge
|
||||
|
||||
Se `openclaw devices rotate` / `revoke` / `remove` viene negato in modo inatteso:
|
||||
Se `openclaw devices rotate` / `revoke` / `remove` viene negato in modo imprevisto:
|
||||
|
||||
- le sessioni con token di dispositivo associato possono gestire solo **il proprio** dispositivo, a meno che il chiamante non abbia anche `operator.admin`
|
||||
- `openclaw devices rotate --scope ...` può richiedere solo scope operatore che la sessione chiamante già possiede
|
||||
- le sessioni con token di dispositivo associato possono gestire solo **il proprio**
|
||||
dispositivo a meno che il chiamante non abbia anche `operator.admin`
|
||||
- `openclaw devices rotate --scope ...` può richiedere solo scope operatore che
|
||||
la sessione chiamante possiede già
|
||||
|
||||
Correlati:
|
||||
|
||||
- [/web/control-ui](/web/control-ui)
|
||||
- [/gateway/configuration](/it/gateway/configuration) (modalità auth del gateway)
|
||||
- [/gateway/configuration](/it/gateway/configuration) (modalità auth del Gateway)
|
||||
- [/gateway/trusted-proxy-auth](/it/gateway/trusted-proxy-auth)
|
||||
- [/gateway/remote](/it/gateway/remote)
|
||||
- [/cli/devices](/cli/devices)
|
||||
|
||||
## Servizio gateway non in esecuzione
|
||||
## Servizio Gateway non in esecuzione
|
||||
|
||||
Usa questa sezione quando il servizio è installato ma il processo non resta attivo.
|
||||
Usa questa sezione quando il servizio è installato ma il processo non rimane attivo.
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
@ -223,18 +247,18 @@ openclaw gateway status --deep # esegue anche la scansione dei servizi a livel
|
||||
|
||||
Cerca:
|
||||
|
||||
- `Runtime: stopped` con indizi sull'uscita.
|
||||
- `Runtime: stopped` con indicazioni sull'uscita.
|
||||
- Mancata corrispondenza della configurazione del servizio (`Config (cli)` vs `Config (service)`).
|
||||
- Conflitti di porta/listener.
|
||||
- Installazioni launchd/systemd/schtasks aggiuntive quando si usa `--deep`.
|
||||
- Suggerimenti di pulizia `Other gateway-like services detected (best effort)`.
|
||||
- Installazioni launchd/systemd/schtasks aggiuntive quando viene usato `--deep`.
|
||||
- Indicazioni di pulizia `Other gateway-like services detected (best effort)`.
|
||||
|
||||
Firme comuni:
|
||||
|
||||
- `Gateway start blocked: set gateway.mode=local` o `existing config is missing gateway.mode` → la modalità gateway locale non è abilitata, oppure il file di configurazione è stato sovrascritto e ha perso `gateway.mode`. Correzione: imposta `gateway.mode="local"` nella tua configurazione, oppure esegui di nuovo `openclaw onboard --mode local` / `openclaw setup` per ripristinare la configurazione attesa in modalità locale. Se stai eseguendo OpenClaw tramite Podman, il percorso predefinito della configurazione è `~/.openclaw/openclaw.json`.
|
||||
- `refusing to bind gateway ... without auth` → bind non loopback senza un percorso auth valido per il gateway (token/password, oppure trusted-proxy dove configurato).
|
||||
- `Gateway start blocked: set gateway.mode=local` o `existing config is missing gateway.mode` → la modalità Gateway locale non è abilitata, oppure il file di configurazione è stato sovrascritto e ha perso `gateway.mode`. Correzione: imposta `gateway.mode="local"` nella tua configurazione, oppure esegui di nuovo `openclaw onboard --mode local` / `openclaw setup` per ripristinare la configurazione prevista per la modalità locale. Se stai eseguendo OpenClaw tramite Podman, il percorso di configurazione predefinito è `~/.openclaw/openclaw.json`.
|
||||
- `refusing to bind gateway ... without auth` → bind non loopback senza un percorso auth Gateway valido (token/password, oppure trusted-proxy dove configurato).
|
||||
- `another gateway instance is already listening` / `EADDRINUSE` → conflitto di porta.
|
||||
- `Other gateway-like services detected (best effort)` → esistono unità launchd/systemd/schtasks obsolete o parallele. Nella maggior parte delle configurazioni è opportuno mantenere un solo gateway per macchina; se davvero ne servono più di uno, isola porte + configurazione/stato/workspace. Vedi [/gateway#multiple-gateways-same-host](/it/gateway#multiple-gateways-same-host).
|
||||
- `Other gateway-like services detected (best effort)` → esistono unità launchd/systemd/schtasks obsolete o parallele. La maggior parte delle configurazioni dovrebbe mantenere un solo Gateway per macchina; se te ne serve più di uno, isola porte + configurazione/stato/workspace. Vedi [/gateway#multiple-gateways-same-host](/it/gateway#multiple-gateways-same-host).
|
||||
|
||||
Correlati:
|
||||
|
||||
@ -242,7 +266,7 @@ Correlati:
|
||||
- [/gateway/configuration](/it/gateway/configuration)
|
||||
- [/gateway/doctor](/it/gateway/doctor)
|
||||
|
||||
## Avvisi della probe del gateway
|
||||
## Avvisi del probe del Gateway
|
||||
|
||||
Usa questa sezione quando `openclaw gateway probe` raggiunge qualcosa, ma stampa comunque un blocco di avviso.
|
||||
|
||||
@ -255,14 +279,15 @@ openclaw gateway probe --ssh user@gateway-host
|
||||
Cerca:
|
||||
|
||||
- `warnings[].code` e `primaryTargetId` nell'output JSON.
|
||||
- Se l'avviso riguarda fallback SSH, gateway multipli, scope mancanti o SecretRef auth non risolti.
|
||||
- Se l'avviso riguarda fallback SSH, più Gateway, scope mancanti o riferimenti auth non risolti.
|
||||
|
||||
Firme comuni:
|
||||
|
||||
- `SSH tunnel failed to start; falling back to direct probes.` → la configurazione SSH non è riuscita, ma il comando ha comunque provato i target diretti configurati/loopback.
|
||||
- `multiple reachable gateways detected` → ha risposto più di un target. Di solito questo indica una configurazione multi-gateway intenzionale oppure listener obsoleti/duplicati.
|
||||
- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → la connessione è riuscita, ma il dettaglio RPC è limitato dagli scope; associa l'identità del dispositivo oppure usa credenziali con `operator.read`.
|
||||
- testo di avviso SecretRef non risolto per `gateway.auth.*` / `gateway.remote.*` → il materiale auth non era disponibile in questo percorso di comando per il target fallito.
|
||||
- `multiple reachable gateways detected` → ha risposto più di un target. Di solito questo indica una configurazione multi-Gateway intenzionale o listener obsoleti/duplicati.
|
||||
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → la connessione ha funzionato, ma il dettaglio RPC è limitato dagli scope; associa l'identità del dispositivo o usa credenziali con `operator.read`.
|
||||
- `Capability: pairing-pending` o `gateway closed (1008): pairing required` → il Gateway ha risposto, ma questo client necessita ancora di pairing/approvazione prima del normale accesso operatore.
|
||||
- testo di avviso SecretRef `gateway.auth.*` / `gateway.remote.*` non risolto → il materiale auth non era disponibile in questo percorso di comando per il target non riuscito.
|
||||
|
||||
Correlati:
|
||||
|
||||
@ -270,7 +295,7 @@ Correlati:
|
||||
- [/gateway#multiple-gateways-same-host](/it/gateway#multiple-gateways-same-host)
|
||||
- [/gateway/remote](/it/gateway/remote)
|
||||
|
||||
## Canale connesso ma flusso dei messaggi bloccato
|
||||
## Il canale è connesso ma i messaggi non fluiscono
|
||||
|
||||
Se lo stato del canale è connesso ma il flusso dei messaggi è fermo, concentrati su policy, permessi e regole di consegna specifiche del canale.
|
||||
|
||||
@ -285,7 +310,7 @@ openclaw config get channels
|
||||
Cerca:
|
||||
|
||||
- Policy DM (`pairing`, `allowlist`, `open`, `disabled`).
|
||||
- Allowlist di gruppo e requisiti di menzione.
|
||||
- Allowlist dei gruppi e requisiti di menzione.
|
||||
- Permessi/scope API del canale mancanti.
|
||||
|
||||
Firme comuni:
|
||||
@ -301,9 +326,9 @@ Correlati:
|
||||
- [/channels/telegram](/it/channels/telegram)
|
||||
- [/channels/discord](/it/channels/discord)
|
||||
|
||||
## Consegna di cron e heartbeat
|
||||
## Consegna di Cron e Heartbeat
|
||||
|
||||
Se cron o heartbeat non sono stati eseguiti o non sono stati consegnati, verifica prima lo stato dello scheduler, poi il target di consegna.
|
||||
Se Cron o Heartbeat non sono stati eseguiti o non hanno recapitato nulla, verifica prima lo stato dello scheduler, poi la destinazione della consegna.
|
||||
|
||||
```bash
|
||||
openclaw cron status
|
||||
@ -315,19 +340,19 @@ openclaw logs --follow
|
||||
|
||||
Cerca:
|
||||
|
||||
- Cron abilitato e prossimo risveglio presente.
|
||||
- Cron abilitato e prossima attivazione presente.
|
||||
- Stato della cronologia delle esecuzioni del job (`ok`, `skipped`, `error`).
|
||||
- Motivi di salto dell'heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
|
||||
- Motivi di salto di Heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).
|
||||
|
||||
Firme comuni:
|
||||
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → cron disabilitato.
|
||||
- `cron: timer tick failed` → tick dello scheduler fallito; controlla errori di file/log/runtime.
|
||||
- `heartbeat skipped` con `reason=quiet-hours` → fuori dalla finestra di orario attivo.
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → Cron disabilitato.
|
||||
- `cron: timer tick failed` → tick dello scheduler non riuscito; controlla errori di file/log/runtime.
|
||||
- `heartbeat skipped` con `reason=quiet-hours` → fuori dalla finestra di ore attive.
|
||||
- `heartbeat skipped` con `reason=empty-heartbeat-file` → `HEARTBEAT.md` esiste ma contiene solo righe vuote / intestazioni markdown, quindi OpenClaw salta la chiamata al modello.
|
||||
- `heartbeat skipped` con `reason=no-tasks-due` → `HEARTBEAT.md` contiene un blocco `tasks:`, ma nessuna delle attività è prevista in questo tick.
|
||||
- `heartbeat: unknown accountId` → account id non valido per il target di consegna dell'heartbeat.
|
||||
- `heartbeat skipped` con `reason=dm-blocked` → il target dell'heartbeat è stato risolto come destinazione in stile DM mentre `agents.defaults.heartbeat.directPolicy` (o l'override per agente) è impostato su `block`.
|
||||
- `heartbeat skipped` con `reason=no-tasks-due` → `HEARTBEAT.md` contiene un blocco `tasks:`, ma nessuna attività è in scadenza in questo tick.
|
||||
- `heartbeat: unknown accountId` → account id non valido per la destinazione di consegna di Heartbeat.
|
||||
- `heartbeat skipped` con `reason=dm-blocked` → la destinazione di Heartbeat è stata risolta in una destinazione di tipo DM mentre `agents.defaults.heartbeat.directPolicy` (o l'override per agente) è impostato su `block`.
|
||||
|
||||
Correlati:
|
||||
|
||||
@ -335,9 +360,9 @@ Correlati:
|
||||
- [/automation/cron-jobs](/it/automation/cron-jobs)
|
||||
- [/gateway/heartbeat](/it/gateway/heartbeat)
|
||||
|
||||
## Strumento del nodo associato non funzionante
|
||||
## Il tool del Node associato fallisce
|
||||
|
||||
Se un nodo è associato ma gli strumenti non funzionano, isola stato in primo piano, permessi e approvazione.
|
||||
Se un Node è associato ma i tool falliscono, isola lo stato di foreground, permessi e approvazione.
|
||||
|
||||
```bash
|
||||
openclaw nodes status
|
||||
@ -349,16 +374,16 @@ openclaw status
|
||||
|
||||
Cerca:
|
||||
|
||||
- Nodo online con le capacità previste.
|
||||
- Permessi del sistema operativo per fotocamera/microfono/posizione/schermo.
|
||||
- Stato di approvazioni exec e allowlist.
|
||||
- Node online con le capability previste.
|
||||
- Permessi OS concessi per fotocamera/microfono/posizione/schermo.
|
||||
- Stato delle approvazioni exec e dell'allowlist.
|
||||
|
||||
Firme comuni:
|
||||
|
||||
- `NODE_BACKGROUND_UNAVAILABLE` → l'app del nodo deve essere in primo piano.
|
||||
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → permesso del sistema operativo mancante.
|
||||
- `NODE_BACKGROUND_UNAVAILABLE` → l'app del Node deve essere in foreground.
|
||||
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → permesso OS mancante.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → approvazione exec in sospeso.
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → comando bloccato dalla allowlist.
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → comando bloccato dall'allowlist.
|
||||
|
||||
Correlati:
|
||||
|
||||
@ -366,9 +391,9 @@ Correlati:
|
||||
- [/nodes/index](/it/nodes/index)
|
||||
- [/tools/exec-approvals](/it/tools/exec-approvals)
|
||||
|
||||
## Strumento browser non funzionante
|
||||
## Il tool browser fallisce
|
||||
|
||||
Usa questa sezione quando le azioni dello strumento browser falliscono anche se il gateway stesso è sano.
|
||||
Usa questa sezione quando le azioni del tool browser falliscono anche se il Gateway stesso è sano.
|
||||
|
||||
```bash
|
||||
openclaw browser status
|
||||
@ -381,38 +406,38 @@ openclaw doctor
|
||||
Cerca:
|
||||
|
||||
- Se `plugins.allow` è impostato e include `browser`.
|
||||
- Percorso valido dell'eseguibile del browser.
|
||||
- Percorso eseguibile del browser valido.
|
||||
- Raggiungibilità del profilo CDP.
|
||||
- Disponibilità di Chrome locale per i profili `existing-session` / `user`.
|
||||
|
||||
Firme comuni:
|
||||
|
||||
- `unknown command "browser"` o `unknown command 'browser'` → il plugin browser incluso è escluso da `plugins.allow`.
|
||||
- browser tool mancante / non disponibile mentre `browser.enabled=true` → `plugins.allow` esclude `browser`, quindi il plugin non è mai stato caricato.
|
||||
- `unknown command "browser"` o `unknown command 'browser'` → il Plugin browser integrato è escluso da `plugins.allow`.
|
||||
- tool browser mancante / non disponibile mentre `browser.enabled=true` → `plugins.allow` esclude `browser`, quindi il Plugin non è mai stato caricato.
|
||||
- `Failed to start Chrome CDP on port` → il processo del browser non è riuscito ad avviarsi.
|
||||
- `browser.executablePath not found` → il percorso configurato non è valido.
|
||||
- `browser.cdpUrl must be http(s) or ws(s)` → l'URL CDP configurato usa uno schema non supportato come `file:` o `ftp:`.
|
||||
- `browser.cdpUrl has invalid port` → l'URL CDP configurato ha una porta non valida o fuori intervallo.
|
||||
- `browser.cdpUrl has invalid port` → l'URL CDP configurato ha una porta errata o fuori intervallo.
|
||||
- `No Chrome tabs found for profile="user"` → il profilo di collegamento Chrome MCP non ha schede Chrome locali aperte.
|
||||
- `Remote CDP for profile "<name>" is not reachable` → l'endpoint CDP remoto configurato non è raggiungibile dall'host del gateway.
|
||||
- `Browser attachOnly is enabled ... not reachable` o `Browser attachOnly is enabled and CDP websocket ... is not reachable` → il profilo solo-attach non ha un target raggiungibile, oppure l'endpoint HTTP ha risposto ma il WebSocket CDP non è comunque stato aperto.
|
||||
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → l'installazione corrente del gateway non include il pacchetto completo Playwright; snapshot ARIA e screenshot di base della pagina possono comunque funzionare, ma navigazione, snapshot AI, screenshot di elementi con selettori CSS ed esportazione PDF restano non disponibili.
|
||||
- `fullPage is not supported for element screenshots` → la richiesta di screenshot ha mescolato `--full-page` con `--ref` o `--element`.
|
||||
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → le chiamate di screenshot Chrome MCP / `existing-session` devono usare la cattura della pagina o un `--ref` da snapshot, non `--element` CSS.
|
||||
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → gli hook di upload file in Chrome MCP richiedono riferimenti snapshot, non selettori CSS.
|
||||
- `existing-session file uploads currently support one file at a time.` → invia un solo upload per chiamata nei profili Chrome MCP.
|
||||
- `existing-session dialog handling does not support timeoutMs.` → gli hook di dialogo nei profili Chrome MCP non supportano override di timeout.
|
||||
- `Remote CDP for profile "<name>" is not reachable` → l'endpoint CDP remoto configurato non è raggiungibile dall'host Gateway.
|
||||
- `Browser attachOnly is enabled ... not reachable` o `Browser attachOnly is enabled and CDP websocket ... is not reachable` → il profilo solo attach non ha un target raggiungibile, oppure l'endpoint HTTP ha risposto ma il WebSocket CDP non può comunque essere aperto.
|
||||
- `Playwright is not available in this gateway build; '<feature>' is unsupported.` → l'installazione corrente del Gateway non include il pacchetto completo di Playwright; gli snapshot ARIA e gli screenshot di pagina di base possono comunque funzionare, ma navigazione, snapshot AI, screenshot di elementi con selettori CSS ed esportazione PDF restano non disponibili.
|
||||
- `fullPage is not supported for element screenshots` → la richiesta di screenshot ha combinato `--full-page` con `--ref` o `--element`.
|
||||
- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → le chiamate di screenshot Chrome MCP / `existing-session` devono usare l'acquisizione della pagina o un `--ref` da snapshot, non `--element` CSS.
|
||||
- `existing-session file uploads do not support element selectors; use ref/inputRef.` → gli hook di upload file di Chrome MCP richiedono riferimenti snapshot, non selettori CSS.
|
||||
- `existing-session file uploads currently support one file at a time.` → invia un upload per chiamata sui profili Chrome MCP.
|
||||
- `existing-session dialog handling does not support timeoutMs.` → gli hook di dialogo sui profili Chrome MCP non supportano override di timeout.
|
||||
- `response body is not supported for existing-session profiles yet.` → `responsebody` richiede ancora un browser gestito o un profilo CDP raw.
|
||||
- override obsoleti di viewport / dark-mode / locale / offline nei profili solo-attach o CDP remoti → esegui `openclaw browser stop --browser-profile <name>` per chiudere la sessione di controllo attiva e rilasciare lo stato di emulazione Playwright/CDP senza riavviare l'intero gateway.
|
||||
- override obsoleti di viewport / dark mode / locale / offline su profili solo attach o CDP remoti → esegui `openclaw browser stop --browser-profile <name>` per chiudere la sessione di controllo attiva e rilasciare lo stato di emulazione Playwright/CDP senza riavviare l'intero Gateway.
|
||||
|
||||
Correlati:
|
||||
|
||||
- [/tools/browser-linux-troubleshooting](/it/tools/browser-linux-troubleshooting)
|
||||
- [/tools/browser](/it/tools/browser)
|
||||
|
||||
## Se hai aggiornato e qualcosa si è improvvisamente rotto
|
||||
## Se hai aggiornato e qualcosa si è rotto improvvisamente
|
||||
|
||||
La maggior parte dei problemi dopo un aggiornamento dipende da derive di configurazione o da impostazioni predefinite più rigide che ora vengono applicate.
|
||||
La maggior parte dei problemi dopo un aggiornamento è dovuta a deriva della configurazione o a impostazioni predefinite più rigide ora applicate.
|
||||
|
||||
### 1) Il comportamento di auth e override URL è cambiato
|
||||
|
||||
@ -426,14 +451,14 @@ openclaw config get gateway.auth.mode
|
||||
Cosa controllare:
|
||||
|
||||
- Se `gateway.mode=remote`, le chiamate CLI potrebbero puntare al remoto mentre il tuo servizio locale funziona correttamente.
|
||||
- Le chiamate esplicite con `--url` non fanno fallback sulle credenziali memorizzate.
|
||||
- Le chiamate esplicite con `--url` non usano fallback alle credenziali memorizzate.
|
||||
|
||||
Firme comuni:
|
||||
|
||||
- `gateway connect failed:` → target URL errato.
|
||||
- `unauthorized` → endpoint raggiungibile ma auth errata.
|
||||
|
||||
### 2) I guardrail su bind e auth sono più rigidi
|
||||
### 2) I guardrail di bind e auth sono più rigidi
|
||||
|
||||
```bash
|
||||
openclaw config get gateway.bind
|
||||
@ -445,13 +470,13 @@ openclaw logs --follow
|
||||
|
||||
Cosa controllare:
|
||||
|
||||
- I bind non loopback (`lan`, `tailnet`, `custom`) richiedono un percorso auth valido per il gateway: auth con token/password condivisi, oppure un deployment `trusted-proxy` non loopback configurato correttamente.
|
||||
- Vecchie chiavi come `gateway.token` non sostituiscono `gateway.auth.token`.
|
||||
- I bind non loopback (`lan`, `tailnet`, `custom`) richiedono un percorso auth Gateway valido: auth con token/password condivisi, oppure un deployment `trusted-proxy` non loopback configurato correttamente.
|
||||
- Chiavi vecchie come `gateway.token` non sostituiscono `gateway.auth.token`.
|
||||
|
||||
Firme comuni:
|
||||
|
||||
- `refusing to bind gateway ... without auth` → bind non loopback senza un percorso auth valido per il gateway.
|
||||
- `RPC probe: failed` mentre il runtime è in esecuzione → gateway attivo ma inaccessibile con l'auth/url attuale.
|
||||
- `refusing to bind gateway ... without auth` → bind non loopback senza un percorso auth Gateway valido.
|
||||
- `Connectivity probe: failed` mentre il runtime è in esecuzione → Gateway attivo ma inaccessibile con auth/URL correnti.
|
||||
|
||||
### 3) Lo stato di pairing e identità del dispositivo è cambiato
|
||||
|
||||
@ -464,15 +489,15 @@ openclaw doctor
|
||||
|
||||
Cosa controllare:
|
||||
|
||||
- Approvazioni dispositivo in sospeso per dashboard/nodi.
|
||||
- Approvazioni di pairing DM in sospeso dopo modifiche a policy o identità.
|
||||
- Approvazioni dispositivo in sospeso per dashboard/Node.
|
||||
- Approvazioni pairing DM in sospeso dopo modifiche di policy o identità.
|
||||
|
||||
Firme comuni:
|
||||
|
||||
- `device identity required` → auth del dispositivo non soddisfatta.
|
||||
- `device identity required` → auth dispositivo non soddisfatta.
|
||||
- `pairing required` → mittente/dispositivo deve essere approvato.
|
||||
|
||||
Se la configurazione del servizio e il runtime continuano a non corrispondere dopo i controlli, reinstalla i metadati del servizio dallo stesso profilo/directory di stato:
|
||||
Se la configurazione del servizio e il runtime continuano a non corrispondere dopo i controlli, reinstalla i metadati del servizio dalla stessa directory di profilo/stato:
|
||||
|
||||
```bash
|
||||
openclaw gateway install --force
|
||||
|
||||
1518
docs/it/help/faq.md
1518
docs/it/help/faq.md
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- OpenClaw non funziona e hai bisogno del percorso più rapido per una soluzione
|
||||
- Vuoi un flusso di triage prima di approfondire con runbook dettagliati
|
||||
summary: Hub di risoluzione dei problemi di OpenClaw orientato ai sintomi
|
||||
- Vuoi un flusso di triage prima di entrare nei runbook di approfondimento
|
||||
summary: Hub di risoluzione dei problemi orientato ai sintomi per OpenClaw
|
||||
title: Risoluzione generale dei problemi
|
||||
x-i18n:
|
||||
generated_at: "2026-04-11T02:45:17Z"
|
||||
generated_at: "2026-04-20T08:31:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 16b38920dbfdc8d4a79bbb5d6fab2c67c9f218a97c36bb4695310d7db9c4614a
|
||||
source_hash: cc5d8c9f804084985c672c5a003ce866e8142ab99fe81abb7a0d38e22aea4b88
|
||||
source_path: help/troubleshooting.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -19,7 +19,7 @@ Se hai solo 2 minuti, usa questa pagina come punto di ingresso per il triage.
|
||||
|
||||
## Primi 60 secondi
|
||||
|
||||
Esegui esattamente questa sequenza nell'ordine indicato:
|
||||
Esegui questa sequenza esatta nell'ordine indicato:
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -35,10 +35,12 @@ Output corretto in una riga:
|
||||
|
||||
- `openclaw status` → mostra i canali configurati e nessun errore auth evidente.
|
||||
- `openclaw status --all` → il report completo è presente e condivisibile.
|
||||
- `openclaw gateway probe` → la destinazione gateway prevista è raggiungibile (`Reachable: yes`). `RPC: limited - missing scope: operator.read` indica diagnostica degradata, non un errore di connessione.
|
||||
- `openclaw gateway status` → `Runtime: running` e `RPC probe: ok`.
|
||||
- `openclaw gateway probe` → il target Gateway previsto è raggiungibile (`Reachable: yes`). `Capability: ...` indica quale livello di auth il probe ha potuto dimostrare, e `Read probe: limited - missing scope: operator.read` indica una diagnostica degradata, non un errore di connessione.
|
||||
- `openclaw gateway status` → `Runtime: running`, `Connectivity probe: ok` e una riga `Capability: ...` plausibile. Usa `--require-rpc` se ti serve anche la prova RPC con ambito di lettura.
|
||||
- `openclaw doctor` → nessun errore bloccante di configurazione/servizio.
|
||||
- `openclaw channels status --probe` → se il gateway è raggiungibile, restituisce lo stato di trasporto live per account più i risultati di probe/audit come `works` o `audit ok`; se il gateway non è raggiungibile, il comando torna a riepiloghi basati solo sulla configurazione.
|
||||
- `openclaw channels status --probe` → con un gateway raggiungibile restituisce
|
||||
stato live del trasporto per account più risultati di probe/audit come `works` o `audit ok`; se il
|
||||
gateway non è raggiungibile, il comando ripiega su riepiloghi basati solo sulla configurazione.
|
||||
- `openclaw logs --follow` → attività costante, nessun errore fatale ripetuto.
|
||||
|
||||
## Anthropic long context 429
|
||||
@ -49,29 +51,29 @@ vai a [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-cont
|
||||
|
||||
## Il backend locale compatibile con OpenAI funziona direttamente ma fallisce in OpenClaw
|
||||
|
||||
Se il tuo backend locale o self-hosted `/v1` risponde a piccole probe dirette
|
||||
Se il tuo backend locale o self-hosted `/v1` risponde a piccoli probe diretti
|
||||
`/v1/chat/completions` ma fallisce su `openclaw infer model run` o nei normali
|
||||
turni dell'agente:
|
||||
turni agente:
|
||||
|
||||
1. Se l'errore menziona `messages[].content` che si aspetta una stringa, imposta
|
||||
`models.providers.<provider>.models[].compat.requiresStringContent: true`.
|
||||
2. Se il backend continua a fallire solo nei turni agente di OpenClaw, imposta
|
||||
`models.providers.<provider>.models[].compat.supportsTools: false` e riprova.
|
||||
3. Se le chiamate dirette minime continuano a funzionare ma i prompt OpenClaw più grandi mandano in crash il
|
||||
backend, tratta il problema residuo come una limitazione upstream del modello/server e
|
||||
continua nel runbook approfondito:
|
||||
backend, tratta il problema rimanente come una limitazione del modello/server upstream e
|
||||
continua nel runbook di approfondimento:
|
||||
[/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/it/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail)
|
||||
|
||||
## L'installazione del plugin fallisce con openclaw extensions mancanti
|
||||
## L'installazione del Plugin fallisce con estensioni openclaw mancanti
|
||||
|
||||
Se l'installazione fallisce con `package.json missing openclaw.extensions`, il pacchetto plugin
|
||||
Se l'installazione fallisce con `package.json missing openclaw.extensions`, il pacchetto Plugin
|
||||
usa una struttura vecchia che OpenClaw non accetta più.
|
||||
|
||||
Correzione nel pacchetto plugin:
|
||||
Correzione nel pacchetto Plugin:
|
||||
|
||||
1. Aggiungi `openclaw.extensions` a `package.json`.
|
||||
2. Punta le entry ai file runtime compilati (di solito `./dist/index.js`).
|
||||
3. Ripubblica il plugin ed esegui di nuovo `openclaw plugins install <package>`.
|
||||
2. Punta gli entry ai file runtime compilati (di solito `./dist/index.js`).
|
||||
3. Ripubblica il Plugin ed esegui di nuovo `openclaw plugins install <package>`.
|
||||
|
||||
Esempio:
|
||||
|
||||
@ -85,7 +87,7 @@ Esempio:
|
||||
}
|
||||
```
|
||||
|
||||
Riferimento: [Architettura dei plugin](/it/plugins/architecture)
|
||||
Riferimento: [Architettura dei Plugin](/it/plugins/architecture)
|
||||
|
||||
## Albero decisionale
|
||||
|
||||
@ -93,19 +95,19 @@ Riferimento: [Architettura dei plugin](/it/plugins/architecture)
|
||||
flowchart TD
|
||||
A[OpenClaw non funziona] --> B{Cosa si rompe per primo}
|
||||
B --> C[Nessuna risposta]
|
||||
B --> D[Dashboard o Control UI non si connette]
|
||||
B --> D[Dashboard o Control UI non si connettono]
|
||||
B --> E[Il Gateway non si avvia o il servizio non è in esecuzione]
|
||||
B --> F[Il canale si connette ma i messaggi non passano]
|
||||
B --> G[Cron o heartbeat non si è attivato o non ha consegnato]
|
||||
B --> H[Il nodo è associato ma il comando exec per camera canvas screen fallisce]
|
||||
B --> F[Il canale si connette ma i messaggi non scorrono]
|
||||
B --> G[Cron o Heartbeat non è stato eseguito o non ha consegnato]
|
||||
B --> H[Il Node è associato ma lo strumento camera canvas screen exec fallisce]
|
||||
B --> I[Lo strumento browser fallisce]
|
||||
|
||||
C --> C1[/Sezione Nessuna risposta/]
|
||||
D --> D1[/Sezione Control UI/]
|
||||
E --> E1[/Sezione Gateway/]
|
||||
F --> F1[/Sezione Flusso del canale/]
|
||||
F --> F1[/Sezione Flusso canale/]
|
||||
G --> G1[/Sezione Automazione/]
|
||||
H --> H1[/Sezione Strumenti nodo/]
|
||||
H --> H1[/Sezione Strumenti Node/]
|
||||
I --> I1[/Sezione Browser/]
|
||||
```
|
||||
|
||||
@ -119,20 +121,21 @@ flowchart TD
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Un output corretto appare così:
|
||||
Un output corretto si presenta così:
|
||||
|
||||
- `Runtime: running`
|
||||
- `RPC probe: ok`
|
||||
- `Connectivity probe: ok`
|
||||
- `Capability: read-only`, `write-capable` o `admin-capable`
|
||||
- Il tuo canale mostra il trasporto connesso e, dove supportato, `works` o `audit ok` in `channels status --probe`
|
||||
- Il mittente risulta approvato (oppure la policy DM è aperta/in allowlist)
|
||||
- Il mittente risulta approvato (oppure la policy DM è open/allowlist)
|
||||
|
||||
Firme di log comuni:
|
||||
Firme comuni nei log:
|
||||
|
||||
- `drop guild message (mention required` → il gating per mention ha bloccato il messaggio in Discord.
|
||||
- `pairing request` → il mittente non è approvato ed è in attesa di approvazione dell'associazione DM.
|
||||
- `drop guild message (mention required` → il gating per menzione ha bloccato il messaggio in Discord.
|
||||
- `pairing request` → il mittente non è approvato ed è in attesa di approvazione per l'associazione DM.
|
||||
- `blocked` / `allowlist` nei log del canale → mittente, stanza o gruppo è filtrato.
|
||||
|
||||
Pagine approfondite:
|
||||
Pagine di approfondimento:
|
||||
|
||||
- [/gateway/troubleshooting#no-replies](/it/gateway/troubleshooting#no-replies)
|
||||
- [/channels/troubleshooting](/it/channels/troubleshooting)
|
||||
@ -140,7 +143,7 @@ flowchart TD
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Dashboard o Control UI non si connette">
|
||||
<Accordion title="Dashboard o Control UI non si connettono">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
@ -149,28 +152,29 @@ flowchart TD
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Un output corretto appare così:
|
||||
Un output corretto si presenta così:
|
||||
|
||||
- `Dashboard: http://...` è mostrato in `openclaw gateway status`
|
||||
- `RPC probe: ok`
|
||||
- `Connectivity probe: ok`
|
||||
- `Capability: read-only`, `write-capable` o `admin-capable`
|
||||
- Nessun loop auth nei log
|
||||
|
||||
Firme di log comuni:
|
||||
Firme comuni nei log:
|
||||
|
||||
- `device identity required` → il contesto HTTP/non sicuro non può completare l'auth del dispositivo.
|
||||
- `origin not allowed` → l'`Origin` del browser non è consentito per la destinazione gateway della Control UI.
|
||||
- `AUTH_TOKEN_MISMATCH` con suggerimenti di tentativo (`canRetryWithDeviceToken=true`) → può verificarsi automaticamente un tentativo con device token fidato.
|
||||
- Quel tentativo con token in cache riutilizza l'insieme di scope in cache memorizzato con il paired
|
||||
device token. I chiamanti con `deviceToken` esplicito / `scopes` espliciti mantengono
|
||||
invece l'insieme di scope richiesto.
|
||||
- `device identity required` → HTTP/contesto non sicuro non può completare l'auth del dispositivo.
|
||||
- `origin not allowed` → l'`Origin` del browser non è consentito per il target Gateway della Control UI
|
||||
- `AUTH_TOKEN_MISMATCH` con suggerimenti di retry (`canRetryWithDeviceToken=true`) → un retry automatico con device token fidato può avvenire una volta.
|
||||
- Quel retry con token in cache riusa l'insieme di scope in cache memorizzato con il
|
||||
device token associato. I chiamanti con `deviceToken` esplicito / `scopes` espliciti mantengono invece il loro insieme di scope richiesto.
|
||||
- Nel percorso asincrono Tailscale Serve Control UI, i tentativi falliti per lo stesso
|
||||
`{scope, ip}` vengono serializzati prima che il limiter registri l'errore, quindi un
|
||||
secondo tentativo errato concorrente può già mostrare `retry later`.
|
||||
- `too many failed authentication attempts (retry later)` da un'origine browser localhost → i fallimenti ripetuti dalla stessa `Origin` vengono temporaneamente bloccati; un'altra origine localhost usa un bucket separato.
|
||||
- `repeated unauthorized` dopo quel tentativo → token/password errati, mancata corrispondenza della modalità auth o paired device token obsoleto.
|
||||
- `gateway connect failed:` → la UI sta puntando all'URL/porta sbagliata o a un gateway non raggiungibile.
|
||||
secondo retry errato concorrente può già mostrare `retry later`.
|
||||
- `too many failed authentication attempts (retry later)` da un'origine browser localhost → gli errori ripetuti dalla stessa `Origin` vengono temporaneamente
|
||||
bloccati; un'altra origine localhost usa un bucket separato.
|
||||
- `repeated unauthorized` dopo quel retry → token/password errati, modalità auth non corrispondente o device token associato non aggiornato.
|
||||
- `gateway connect failed:` → la UI punta a URL/porta sbagliati o a un gateway irraggiungibile.
|
||||
|
||||
Pagine approfondite:
|
||||
Pagine di approfondimento:
|
||||
|
||||
- [/gateway/troubleshooting#dashboard-control-ui-connectivity](/it/gateway/troubleshooting#dashboard-control-ui-connectivity)
|
||||
- [/web/control-ui](/web/control-ui)
|
||||
@ -187,19 +191,20 @@ flowchart TD
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Un output corretto appare così:
|
||||
Un output corretto si presenta così:
|
||||
|
||||
- `Service: ... (loaded)`
|
||||
- `Runtime: running`
|
||||
- `RPC probe: ok`
|
||||
- `Connectivity probe: ok`
|
||||
- `Capability: read-only`, `write-capable` o `admin-capable`
|
||||
|
||||
Firme di log comuni:
|
||||
Firme comuni nei log:
|
||||
|
||||
- `Gateway start blocked: set gateway.mode=local` o `existing config is missing gateway.mode` → la modalità gateway è remote, oppure nel file di configurazione manca il contrassegno local-mode e deve essere riparato.
|
||||
- `Gateway start blocked: set gateway.mode=local` o `existing config is missing gateway.mode` → la modalità gateway è remote, oppure nel file di configurazione manca il marker local-mode e deve essere riparato.
|
||||
- `refusing to bind gateway ... without auth` → bind non-loopback senza un percorso auth gateway valido (token/password, oppure trusted-proxy dove configurato).
|
||||
- `another gateway instance is already listening` o `EADDRINUSE` → porta già occupata.
|
||||
|
||||
Pagine approfondite:
|
||||
Pagine di approfondimento:
|
||||
|
||||
- [/gateway/troubleshooting#gateway-service-not-running](/it/gateway/troubleshooting#gateway-service-not-running)
|
||||
- [/gateway/background-process](/it/gateway/background-process)
|
||||
@ -207,7 +212,7 @@ flowchart TD
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Il canale si connette ma i messaggi non passano">
|
||||
<Accordion title="Il canale si connette ma i messaggi non scorrono">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
@ -216,26 +221,26 @@ flowchart TD
|
||||
openclaw channels status --probe
|
||||
```
|
||||
|
||||
Un output corretto appare così:
|
||||
Un output corretto si presenta così:
|
||||
|
||||
- Il trasporto del canale è connesso.
|
||||
- I controlli pairing/allowlist passano.
|
||||
- Le mention vengono rilevate dove richiesto.
|
||||
- Le menzioni vengono rilevate dove richiesto.
|
||||
|
||||
Firme di log comuni:
|
||||
Firme comuni nei log:
|
||||
|
||||
- `mention required` → il gating per mention nel gruppo ha bloccato l'elaborazione.
|
||||
- `mention required` → il gating della menzione nel gruppo ha bloccato l'elaborazione.
|
||||
- `pairing` / `pending` → il mittente DM non è ancora approvato.
|
||||
- `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → problema di token o permessi del canale.
|
||||
|
||||
Pagine approfondite:
|
||||
Pagine di approfondimento:
|
||||
|
||||
- [/gateway/troubleshooting#channel-connected-messages-not-flowing](/it/gateway/troubleshooting#channel-connected-messages-not-flowing)
|
||||
- [/channels/troubleshooting](/it/channels/troubleshooting)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Cron o heartbeat non si è attivato o non ha consegnato">
|
||||
<Accordion title="Cron o Heartbeat non è stato eseguito o non ha consegnato">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
@ -245,23 +250,23 @@ flowchart TD
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Un output corretto appare così:
|
||||
Un output corretto si presenta così:
|
||||
|
||||
- `cron.status` mostra che è abilitato con una prossima riattivazione.
|
||||
- `cron runs` mostra voci `ok` recenti.
|
||||
- `cron.status` mostra abilitato con un prossimo risveglio.
|
||||
- `cron runs` mostra recenti voci `ok`.
|
||||
- Heartbeat è abilitato e non è fuori dalle ore attive.
|
||||
|
||||
Firme di log comuni:
|
||||
Firme comuni nei log:
|
||||
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → cron è disabilitato.
|
||||
- `cron: scheduler disabled; jobs will not run automatically` → Cron è disabilitato.
|
||||
- `heartbeat skipped` con `reason=quiet-hours` → fuori dalle ore attive configurate.
|
||||
- `heartbeat skipped` con `reason=empty-heartbeat-file` → `HEARTBEAT.md` esiste ma contiene solo struttura vuota o solo intestazioni.
|
||||
- `heartbeat skipped` con `reason=no-tasks-due` → la modalità attività di `HEARTBEAT.md` è attiva ma nessuno degli intervalli delle attività è ancora scaduto.
|
||||
- `heartbeat skipped` con `reason=alerts-disabled` → tutta la visibilità heartbeat è disabilitata (`showOk`, `showAlerts` e `useIndicator` sono tutti disattivati).
|
||||
- `requests-in-flight` → corsia principale occupata; la riattivazione heartbeat è stata rinviata.
|
||||
- `unknown accountId` → l'account di destinazione della consegna heartbeat non esiste.
|
||||
- `heartbeat skipped` con `reason=no-tasks-due` → la modalità attività di `HEARTBEAT.md` è attiva ma nessun intervallo delle attività è ancora scaduto.
|
||||
- `heartbeat skipped` con `reason=alerts-disabled` → tutta la visibilità Heartbeat è disabilitata (`showOk`, `showAlerts` e `useIndicator` sono tutti disattivati).
|
||||
- `requests-in-flight` → corsia principale occupata; il risveglio Heartbeat è stato rinviato.
|
||||
- `unknown accountId` → il target di consegna Heartbeat non esiste.
|
||||
|
||||
Pagine approfondite:
|
||||
Pagine di approfondimento:
|
||||
|
||||
- [/gateway/troubleshooting#cron-and-heartbeat-delivery](/it/gateway/troubleshooting#cron-and-heartbeat-delivery)
|
||||
- [/automation/cron-jobs#troubleshooting](/it/automation/cron-jobs#troubleshooting)
|
||||
@ -269,7 +274,7 @@ flowchart TD
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Il nodo è associato ma lo strumento fallisce per camera canvas screen exec">
|
||||
<Accordion title="Il Node è associato ma lo strumento fallisce camera canvas screen exec">
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw gateway status
|
||||
@ -278,20 +283,20 @@ flowchart TD
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Un output corretto appare così:
|
||||
Un output corretto si presenta così:
|
||||
|
||||
- Il nodo è elencato come connesso e associato per il ruolo `node`.
|
||||
- Il Node è elencato come connesso e associato per il ruolo `node`.
|
||||
- La capability esiste per il comando che stai invocando.
|
||||
- Lo stato del permesso è concesso per lo strumento.
|
||||
- Lo stato dei permessi è concesso per lo strumento.
|
||||
|
||||
Firme di log comuni:
|
||||
Firme comuni nei log:
|
||||
|
||||
- `NODE_BACKGROUND_UNAVAILABLE` → porta l'app del nodo in primo piano.
|
||||
- `NODE_BACKGROUND_UNAVAILABLE` → porta l'app Node in primo piano.
|
||||
- `*_PERMISSION_REQUIRED` → il permesso del sistema operativo è stato negato o manca.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → l'approvazione exec è in sospeso.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → l'approvazione exec è in attesa.
|
||||
- `SYSTEM_RUN_DENIED: allowlist miss` → il comando non è nella allowlist exec.
|
||||
|
||||
Pagine approfondite:
|
||||
Pagine di approfondimento:
|
||||
|
||||
- [/gateway/troubleshooting#node-paired-tool-fails](/it/gateway/troubleshooting#node-paired-tool-fails)
|
||||
- [/nodes/troubleshooting](/it/nodes/troubleshooting)
|
||||
@ -299,7 +304,7 @@ flowchart TD
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Exec chiede improvvisamente l'approvazione">
|
||||
<Accordion title="Exec improvvisamente richiede approvazione">
|
||||
```bash
|
||||
openclaw config get tools.exec.host
|
||||
openclaw config get tools.exec.security
|
||||
@ -312,9 +317,9 @@ flowchart TD
|
||||
- Se `tools.exec.host` non è impostato, il valore predefinito è `auto`.
|
||||
- `host=auto` viene risolto in `sandbox` quando è attivo un runtime sandbox, altrimenti in `gateway`.
|
||||
- `host=auto` riguarda solo il routing; il comportamento "YOLO" senza prompt deriva da `security=full` più `ask=off` su gateway/node.
|
||||
- Su `gateway` e `node`, `tools.exec.security` non impostato usa come predefinito `full`.
|
||||
- `tools.exec.ask` non impostato usa come predefinito `off`.
|
||||
- Risultato: se stai vedendo richieste di approvazione, qualche policy locale dell'host o per sessione ha reso exec più restrittivo rispetto ai valori predefiniti attuali.
|
||||
- Su `gateway` e `node`, `tools.exec.security` non impostato ha come predefinito `full`.
|
||||
- `tools.exec.ask` non impostato ha come predefinito `off`.
|
||||
- Risultato: se stai vedendo richieste di approvazione, qualche policy locale dell'host o per sessione ha irrigidito exec rispetto ai valori predefiniti attuali.
|
||||
|
||||
Ripristina l'attuale comportamento predefinito senza approvazione:
|
||||
|
||||
@ -327,17 +332,17 @@ flowchart TD
|
||||
|
||||
Alternative più sicure:
|
||||
|
||||
- Imposta solo `tools.exec.host=gateway` se vuoi semplicemente un instradamento host stabile.
|
||||
- Usa `security=allowlist` con `ask=on-miss` se vuoi exec sull'host ma desideri comunque una revisione in caso di mancata corrispondenza con la allowlist.
|
||||
- Abilita la modalità sandbox se vuoi che `host=auto` torni a risolversi in `sandbox`.
|
||||
- Imposta solo `tools.exec.host=gateway` se vuoi soltanto un routing host stabile.
|
||||
- Usa `security=allowlist` con `ask=on-miss` se vuoi exec sull'host ma desideri comunque una revisione per le mancate corrispondenze nella allowlist.
|
||||
- Abilita la modalità sandbox se vuoi che `host=auto` venga risolto di nuovo in `sandbox`.
|
||||
|
||||
Firme di log comuni:
|
||||
Firme comuni nei log:
|
||||
|
||||
- `Approval required.` → il comando è in attesa su `/approve ...`.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → l'approvazione exec dell'host del nodo è in sospeso.
|
||||
- `exec host=sandbox requires a sandbox runtime for this session` → selezione sandbox implicita/esplicita ma la modalità sandbox è disattivata.
|
||||
- `Approval required.` → il comando è in attesa di `/approve ...`.
|
||||
- `SYSTEM_RUN_DENIED: approval required` → l'approvazione exec su host-node è in attesa.
|
||||
- `exec host=sandbox requires a sandbox runtime for this session` → selezione sandbox implicita/esplicita ma modalità sandbox disattivata.
|
||||
|
||||
Pagine approfondite:
|
||||
Pagine di approfondimento:
|
||||
|
||||
- [/tools/exec](/it/tools/exec)
|
||||
- [/tools/exec-approvals](/it/tools/exec-approvals)
|
||||
@ -354,24 +359,24 @@ flowchart TD
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
Un output corretto appare così:
|
||||
Un output corretto si presenta così:
|
||||
|
||||
- Lo stato del browser mostra `running: true` e un browser/profilo selezionato.
|
||||
- `openclaw` si avvia, oppure `user` può vedere le schede Chrome locali.
|
||||
|
||||
Firme di log comuni:
|
||||
Firme comuni nei log:
|
||||
|
||||
- `unknown command "browser"` o `unknown command 'browser'` → `plugins.allow` è impostato e non include `browser`.
|
||||
- `Failed to start Chrome CDP on port` → l'avvio del browser locale non è riuscito.
|
||||
- `browser.executablePath not found` → il percorso del binario configurato è errato.
|
||||
- `browser.cdpUrl must be http(s) or ws(s)` → l'URL CDP configurato usa uno schema non supportato.
|
||||
- `browser.cdpUrl has invalid port` → l'URL CDP configurato ha una porta non valida o fuori intervallo.
|
||||
- `No Chrome tabs found for profile="user"` → il profilo di collegamento Chrome MCP non ha schede Chrome locali aperte.
|
||||
- `No Chrome tabs found for profile="user"` → il profilo attach di Chrome MCP non ha schede Chrome locali aperte.
|
||||
- `Remote CDP for profile "<name>" is not reachable` → l'endpoint CDP remoto configurato non è raggiungibile da questo host.
|
||||
- `Browser attachOnly is enabled ... not reachable` o `Browser attachOnly is enabled and CDP websocket ... is not reachable` → il profilo solo collegamento non ha una destinazione CDP live.
|
||||
- override obsoleti di viewport / dark mode / locale / offline su profili solo collegamento o CDP remoti → esegui `openclaw browser stop --browser-profile <name>` per chiudere la sessione di controllo attiva e rilasciare lo stato di emulazione senza riavviare il gateway.
|
||||
- `Browser attachOnly is enabled ... not reachable` o `Browser attachOnly is enabled and CDP websocket ... is not reachable` → il profilo solo-attach non ha alcun target CDP live.
|
||||
- override obsoleti di viewport / dark-mode / locale / offline su profili solo-attach o CDP remoto → esegui `openclaw browser stop --browser-profile <name>` per chiudere la sessione di controllo attiva e rilasciare lo stato di emulazione senza riavviare il gateway.
|
||||
|
||||
Pagine approfondite:
|
||||
Pagine di approfondimento:
|
||||
|
||||
- [/gateway/troubleshooting#browser-tool-fails](/it/gateway/troubleshooting#browser-tool-fails)
|
||||
- [/tools/browser#missing-browser-command-or-tool](/it/tools/browser#missing-browser-command-or-tool)
|
||||
@ -385,7 +390,7 @@ flowchart TD
|
||||
## Correlati
|
||||
|
||||
- [FAQ](/it/help/faq) — domande frequenti
|
||||
- [Risoluzione dei problemi del Gateway](/it/gateway/troubleshooting) — problemi specifici del gateway
|
||||
- [Doctor](/it/gateway/doctor) — controlli di integrità automatizzati e riparazioni
|
||||
- [Risoluzione dei problemi del Gateway](/it/gateway/troubleshooting) — problemi specifici del Gateway
|
||||
- [Doctor](/it/gateway/doctor) — controlli di salute automatizzati e riparazioni
|
||||
- [Risoluzione dei problemi dei canali](/it/channels/troubleshooting) — problemi di connettività dei canali
|
||||
- [Risoluzione dei problemi di automazione](/it/automation/cron-jobs#troubleshooting) — problemi di cron e heartbeat
|
||||
- [Risoluzione dei problemi dell'automazione](/it/automation/cron-jobs#troubleshooting) — problemi di Cron e Heartbeat
|
||||
|
||||
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Aggiunta dell'automazione del browser controllata dall'agente
|
||||
- Debug di come openclaw stia interferendo con il tuo Chrome
|
||||
- Implementazione delle impostazioni del browser + del ciclo di vita nell'app macOS
|
||||
summary: Servizio di controllo del browser integrato + comandi di azione
|
||||
- Aggiunta di automazione del browser controllata dall'agente
|
||||
- Debug di perché openclaw sta interferendo con il tuo Chrome
|
||||
- Implementazione delle impostazioni del browser e del ciclo di vita nell'app macOS
|
||||
summary: Servizio di controllo browser integrato + comandi di azione
|
||||
title: Browser (gestito da OpenClaw)
|
||||
x-i18n:
|
||||
generated_at: "2026-04-14T13:04:29Z"
|
||||
generated_at: "2026-04-20T08:31:51Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: ae9ef725f544d4236d229f498c7187871c69bd18d31069b30a7e67fac53166a2
|
||||
source_hash: 3f7d37b34ba48dc7c38f8c2e77f8bb97af987eac6a874ebfc921f950fb59de4b
|
||||
source_path: tools/browser.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Browser (gestito da openclaw)
|
||||
|
||||
OpenClaw può eseguire un **profilo Chrome/Brave/Edge/Chromium dedicato** controllato dall'agente.
|
||||
È isolato dal tuo browser personale ed è gestito tramite un piccolo
|
||||
servizio di controllo locale all'interno del Gateway (solo loopback).
|
||||
OpenClaw può eseguire un **profilo dedicato Chrome/Brave/Edge/Chromium** controllato dall'agente.
|
||||
È isolato dal tuo browser personale ed è gestito tramite un piccolo servizio di
|
||||
controllo locale all'interno del Gateway (solo loopback).
|
||||
|
||||
Vista per principianti:
|
||||
|
||||
- Consideralo come un **browser separato, solo per l'agente**.
|
||||
- Il profilo `openclaw` **non** tocca il profilo del tuo browser personale.
|
||||
- L'agente può **aprire schede, leggere pagine, fare clic e digitare** in un percorso sicuro.
|
||||
- Il profilo `user` integrato si collega alla tua sessione Chrome reale con accesso effettuato tramite Chrome MCP.
|
||||
- L'agente può **aprire schede, leggere pagine, fare clic e digitare** in una corsia sicura.
|
||||
- Il profilo integrato `user` si collega alla tua sessione Chrome reale autenticata tramite Chrome MCP.
|
||||
|
||||
## Cosa ottieni
|
||||
|
||||
- Un profilo browser separato chiamato **openclaw** (accento arancione per impostazione predefinita).
|
||||
- Controllo deterministico delle schede (elenca/apri/metti a fuoco/chiudi).
|
||||
- Azioni dell'agente (clic/digita/trascina/seleziona), snapshot, screenshot, PDF.
|
||||
- Supporto opzionale per più profili (`openclaw`, `work`, `remote`, ...).
|
||||
- Azioni dell'agente (clic/digitazione/trascinamento/selezione), snapshot, screenshot, PDF.
|
||||
- Supporto facoltativo per più profili (`openclaw`, `work`, `remote`, ...).
|
||||
|
||||
Questo browser **non** è il tuo browser principale per tutti i giorni. È una superficie sicura e isolata per
|
||||
Questo browser **non** è il tuo browser quotidiano. È una superficie sicura e isolata per
|
||||
l'automazione e la verifica da parte dell'agente.
|
||||
|
||||
## Avvio rapido
|
||||
@ -46,16 +46,16 @@ openclaw browser --browser-profile openclaw open https://example.com
|
||||
openclaw browser --browser-profile openclaw snapshot
|
||||
```
|
||||
|
||||
Se ricevi “Browser disabled”, abilitalo nella configurazione (vedi sotto) e riavvia il
|
||||
Se ottieni “Browser disabled”, abilitalo nella configurazione (vedi sotto) e riavvia il
|
||||
Gateway.
|
||||
|
||||
Se `openclaw browser` manca del tutto, oppure l'agente dice che lo strumento browser
|
||||
Se `openclaw browser` manca completamente, oppure l'agente dice che lo strumento browser
|
||||
non è disponibile, vai a [Comando o strumento browser mancante](/it/tools/browser#missing-browser-command-or-tool).
|
||||
|
||||
## Controllo del Plugin
|
||||
|
||||
Lo strumento `browser` predefinito ora è un Plugin incluso che viene distribuito abilitato per
|
||||
impostazione predefinita. Questo significa che puoi disabilitarlo o sostituirlo senza rimuovere il resto del
|
||||
Lo strumento `browser` predefinito è ora un Plugin integrato che viene distribuito abilitato per
|
||||
impostazione predefinita. Ciò significa che puoi disabilitarlo o sostituirlo senza rimuovere il resto del
|
||||
sistema di Plugin di OpenClaw:
|
||||
|
||||
```json5
|
||||
@ -70,33 +70,33 @@ sistema di Plugin di OpenClaw:
|
||||
}
|
||||
```
|
||||
|
||||
Disabilita il Plugin incluso prima di installare un altro plugin che fornisce lo
|
||||
stesso nome strumento `browser`. L'esperienza browser predefinita richiede entrambi:
|
||||
Disabilita il Plugin integrato prima di installare un altro plugin che fornisce lo
|
||||
stesso nome di strumento `browser`. L'esperienza browser predefinita richiede entrambi:
|
||||
|
||||
- `plugins.entries.browser.enabled` non disabilitato
|
||||
- `browser.enabled=true`
|
||||
|
||||
Se disattivi solo il Plugin, la CLI browser inclusa (`openclaw browser`),
|
||||
il metodo Gateway (`browser.request`), lo strumento agente e il servizio di controllo browser
|
||||
predefinito scompaiono tutti insieme. La tua configurazione `browser.*` rimane intatta per essere riutilizzata da
|
||||
un Plugin sostitutivo.
|
||||
Se disattivi solo il Plugin, la CLI browser integrata (`openclaw browser`),
|
||||
il metodo gateway (`browser.request`), lo strumento agente e il servizio di controllo browser
|
||||
predefinito scompaiono tutti insieme. La tua configurazione `browser.*` resta intatta affinché un
|
||||
plugin sostitutivo possa riutilizzarla.
|
||||
|
||||
Il Plugin browser incluso ora possiede anche l'implementazione runtime del browser.
|
||||
Il core mantiene solo gli helper condivisi del Plugin SDK più le riesportazioni di compatibilità per
|
||||
i vecchi percorsi di importazione interni. In pratica, rimuovere o sostituire il pacchetto del Plugin browser
|
||||
rimuove l'insieme di funzionalità del browser invece di lasciare dietro un secondo runtime
|
||||
di proprietà del core.
|
||||
Il Plugin browser integrato possiede ora anche l'implementazione runtime del browser.
|
||||
Il core mantiene solo helper condivisi del Plugin SDK più re-export di compatibilità per
|
||||
vecchi percorsi di import interni. In pratica, rimuovere o sostituire il pacchetto plugin browser
|
||||
rimuove il set di funzionalità del browser invece di lasciare dietro un secondo runtime
|
||||
posseduto dal core.
|
||||
|
||||
Le modifiche alla configurazione del browser richiedono comunque un riavvio del Gateway affinché il Plugin incluso
|
||||
possa registrare nuovamente il suo servizio browser con le nuove impostazioni.
|
||||
Le modifiche alla configurazione del browser richiedono comunque un riavvio del Gateway affinché il Plugin integrato
|
||||
possa registrare di nuovo il proprio servizio browser con le nuove impostazioni.
|
||||
|
||||
## Comando o strumento browser mancante
|
||||
|
||||
Se `openclaw browser` diventa improvvisamente un comando sconosciuto dopo un aggiornamento, oppure
|
||||
l'agente segnala che manca lo strumento browser, la causa più comune è una lista `plugins.allow`
|
||||
restrittiva che non include `browser`.
|
||||
l'agente segnala che lo strumento browser è mancante, la causa più comune è una
|
||||
lista `plugins.allow` restrittiva che non include `browser`.
|
||||
|
||||
Esempio di configurazione non funzionante:
|
||||
Esempio di configurazione errata:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -118,26 +118,26 @@ Correggila aggiungendo `browser` alla allowlist dei plugin:
|
||||
|
||||
Note importanti:
|
||||
|
||||
- `browser.enabled=true` da solo non è sufficiente quando `plugins.allow` è impostato.
|
||||
- Anche `plugins.entries.browser.enabled=true` da solo non è sufficiente quando `plugins.allow` è impostato.
|
||||
- `tools.alsoAllow: ["browser"]` **non** carica il Plugin browser incluso. Regola solo la policy degli strumenti dopo che il Plugin è già stato caricato.
|
||||
- Se non hai bisogno di una allowlist dei plugin restrittiva, rimuovere `plugins.allow` ripristina anche il comportamento browser incluso predefinito.
|
||||
- `browser.enabled=true` da solo non basta quando è impostato `plugins.allow`.
|
||||
- Anche `plugins.entries.browser.enabled=true` da solo non basta quando è impostato `plugins.allow`.
|
||||
- `tools.alsoAllow: ["browser"]` **non** carica il Plugin browser integrato. Regola solo la policy degli strumenti dopo che il plugin è già stato caricato.
|
||||
- Se non hai bisogno di una allowlist dei plugin restrittiva, rimuovere `plugins.allow` ripristina anche il comportamento predefinito del browser integrato.
|
||||
|
||||
Sintomi tipici:
|
||||
|
||||
- `openclaw browser` è un comando sconosciuto.
|
||||
- `browser.request` è mancante.
|
||||
- L'agente segnala che lo strumento browser non è disponibile o manca.
|
||||
- `browser.request` manca.
|
||||
- L'agente segnala che lo strumento browser non è disponibile o è mancante.
|
||||
|
||||
## Profili: `openclaw` vs `user`
|
||||
|
||||
- `openclaw`: browser gestito e isolato (non richiede estensioni).
|
||||
- `user`: profilo integrato di collegamento Chrome MCP alla tua **vera sessione Chrome con accesso effettuato**.
|
||||
- `openclaw`: browser gestito e isolato (nessuna estensione richiesta).
|
||||
- `user`: profilo integrato di collegamento Chrome MCP alla tua **vera sessione Chrome autenticata**.
|
||||
|
||||
Per le chiamate allo strumento browser dell'agente:
|
||||
Per le chiamate dello strumento browser da parte dell'agente:
|
||||
|
||||
- Predefinito: usa il browser isolato `openclaw`.
|
||||
- Preferisci `profile="user"` quando contano le sessioni già con accesso effettuato e l'utente
|
||||
- Preferisci `profile="user"` quando contano le sessioni già autenticate e l'utente
|
||||
è al computer per fare clic/approvare eventuali prompt di collegamento.
|
||||
- `profile` è l'override esplicito quando vuoi una modalità browser specifica.
|
||||
|
||||
@ -188,30 +188,30 @@ Le impostazioni del browser si trovano in `~/.openclaw/openclaw.json`.
|
||||
|
||||
Note:
|
||||
|
||||
- Il servizio di controllo browser si associa al loopback su una porta derivata da `gateway.port`
|
||||
(predefinito: `18791`, cioè gateway + 2).
|
||||
- Il servizio di controllo browser si collega al loopback su una porta derivata da `gateway.port`
|
||||
(predefinita: `18791`, cioè gateway + 2).
|
||||
- Se sovrascrivi la porta del Gateway (`gateway.port` o `OPENCLAW_GATEWAY_PORT`),
|
||||
le porte browser derivate cambiano per restare nella stessa “famiglia”.
|
||||
le porte browser derivate si spostano per rimanere nella stessa “famiglia”.
|
||||
- `cdpUrl` usa per impostazione predefinita la porta CDP locale gestita quando non è impostato.
|
||||
- `remoteCdpTimeoutMs` si applica ai controlli di raggiungibilità CDP remoti (non loopback).
|
||||
- `remoteCdpHandshakeTimeoutMs` si applica ai controlli di raggiungibilità WebSocket CDP remoti.
|
||||
- La navigazione/apertura scheda del browser è protetta da SSRF prima della navigazione e ricontrollata al meglio sull'URL finale `http(s)` dopo la navigazione.
|
||||
- In modalità SSRF rigorosa, vengono controllati anche individuazione/sonde degli endpoint CDP remoti (`cdpUrl`, incluse le ricerche `/json/version`).
|
||||
- La navigazione/apertura scheda del browser è protetta da SSRF prima della navigazione e ricontrollata, nei limiti del possibile, sull'URL finale `http(s)` dopo la navigazione.
|
||||
- In modalità SSRF rigorosa, vengono controllati anche discovery/sonde degli endpoint CDP remoti (`cdpUrl`, incluse le ricerche `/json/version`).
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` è disabilitato per impostazione predefinita. Impostalo su `true` solo quando ti fidi intenzionalmente dell'accesso browser alla rete privata.
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` resta supportato come alias legacy per compatibilità.
|
||||
- `attachOnly: true` significa “non avviare mai un browser locale; collegarsi solo se è già in esecuzione.”
|
||||
- `attachOnly: true` significa “non avviare mai un browser locale; collegati solo se è già in esecuzione.”
|
||||
- `color` + `color` per profilo colorano l'interfaccia del browser così puoi vedere quale profilo è attivo.
|
||||
- Il profilo predefinito è `openclaw` (browser standalone gestito da OpenClaw). Usa `defaultProfile: "user"` per scegliere il browser utente con accesso effettuato.
|
||||
- Ordine di rilevamento automatico: browser di sistema predefinito se basato su Chromium; altrimenti Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
- Il profilo predefinito è `openclaw` (browser standalone gestito da OpenClaw). Usa `defaultProfile: "user"` per optare per il browser utente autenticato.
|
||||
- Ordine di rilevamento automatico: browser predefinito del sistema se basato su Chromium; altrimenti Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
- I profili `openclaw` locali assegnano automaticamente `cdpPort`/`cdpUrl` — impostali solo per CDP remoto.
|
||||
- `driver: "existing-session"` usa Chrome DevTools MCP invece di CDP grezzo. Non
|
||||
- `driver: "existing-session"` usa Chrome DevTools MCP invece del CDP grezzo. Non
|
||||
impostare `cdpUrl` per quel driver.
|
||||
- Imposta `browser.profiles.<name>.userDataDir` quando un profilo existing-session
|
||||
deve collegarsi a un profilo utente Chromium non predefinito come Brave o Edge.
|
||||
|
||||
## Usa Brave (o un altro browser basato su Chromium)
|
||||
## Usare Brave (o un altro browser basato su Chromium)
|
||||
|
||||
Se il tuo browser **di sistema predefinito** è basato su Chromium (Chrome/Brave/Edge/ecc.),
|
||||
Se il tuo browser **predefinito di sistema** è basato su Chromium (Chrome/Brave/Edge/ecc),
|
||||
OpenClaw lo usa automaticamente. Imposta `browser.executablePath` per sovrascrivere
|
||||
il rilevamento automatico:
|
||||
|
||||
@ -246,41 +246,41 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome"
|
||||
|
||||
## Controllo locale vs remoto
|
||||
|
||||
- **Controllo locale (predefinito):** il Gateway avvia il servizio di controllo loopback e può avviare un browser locale.
|
||||
- **Controllo locale (predefinito):** il Gateway avvia il servizio di controllo loopback e può lanciare un browser locale.
|
||||
- **Controllo remoto (host node):** esegui un host node sulla macchina che ha il browser; il Gateway inoltra a esso le azioni del browser.
|
||||
- **CDP remoto:** imposta `browser.profiles.<name>.cdpUrl` (o `browser.cdpUrl`) per
|
||||
- **CDP remoto:** imposta `browser.profiles.<name>.cdpUrl` (oppure `browser.cdpUrl`) per
|
||||
collegarti a un browser remoto basato su Chromium. In questo caso, OpenClaw non avvierà un browser locale.
|
||||
|
||||
Il comportamento di arresto varia in base alla modalità del profilo:
|
||||
|
||||
- profili locali gestiti: `openclaw browser stop` arresta il processo browser che
|
||||
OpenClaw ha avviato
|
||||
- profili attach-only e CDP remoti: `openclaw browser stop` chiude la sessione di
|
||||
- profili attach-only e CDP remoto: `openclaw browser stop` chiude la sessione di
|
||||
controllo attiva e rilascia gli override di emulazione Playwright/CDP (viewport,
|
||||
schema colori, impostazioni locali, fuso orario, modalità offline e stato simile), anche
|
||||
schema colori, locale, fuso orario, modalità offline e stato simile), anche
|
||||
se nessun processo browser è stato avviato da OpenClaw
|
||||
|
||||
Gli URL CDP remoti possono includere autenticazione:
|
||||
|
||||
- Token di query (ad esempio, `https://provider.example?token=<token>`)
|
||||
- Autenticazione HTTP Basic (ad esempio, `https://user:pass@provider.example`)
|
||||
- Token di query (ad es. `https://provider.example?token=<token>`)
|
||||
- Autenticazione HTTP Basic (ad es. `https://user:pass@provider.example`)
|
||||
|
||||
OpenClaw preserva l'autenticazione quando chiama gli endpoint `/json/*` e quando si connette
|
||||
al WebSocket CDP. Preferisci variabili d'ambiente o secret manager per i
|
||||
token invece di salvarli nei file di configurazione.
|
||||
OpenClaw preserva l'autenticazione quando chiama gli endpoint `/json/*` e quando si collega
|
||||
al WebSocket CDP. Preferisci variabili d'ambiente o gestori di segreti per i
|
||||
token invece di inserirli nei file di configurazione.
|
||||
|
||||
## Proxy browser node (predefinito a configurazione zero)
|
||||
## Proxy browser del Node (predefinito zero-config)
|
||||
|
||||
Se esegui un **host node** sulla macchina che ha il tuo browser, OpenClaw può
|
||||
instradare automaticamente le chiamate allo strumento browser verso quel node senza alcuna configurazione browser aggiuntiva.
|
||||
Questo è il percorso predefinito per i Gateway remoti.
|
||||
instradare automaticamente a quel node le chiamate dello strumento browser senza configurazione browser aggiuntiva.
|
||||
Questo è il percorso predefinito per i gateway remoti.
|
||||
|
||||
Note:
|
||||
|
||||
- L'host node espone il proprio server di controllo browser locale tramite un **comando proxy**.
|
||||
- I profili provengono dalla configurazione `browser.profiles` del node stesso (uguale a quella locale).
|
||||
- `nodeHost.browserProxy.allowProfiles` è opzionale. Lascialo vuoto per il comportamento legacy/predefinito: tutti i profili configurati restano raggiungibili tramite il proxy, incluse le route di creazione/eliminazione profilo.
|
||||
- Se imposti `nodeHost.browserProxy.allowProfiles`, OpenClaw lo tratta come un confine di privilegio minimo: solo i profili nella allowlist possono essere destinati e le route di creazione/eliminazione dei profili persistenti vengono bloccate sulla superficie del proxy.
|
||||
- L'host node espone il proprio server locale di controllo browser tramite un **comando proxy**.
|
||||
- I profili provengono dalla configurazione `browser.profiles` del node stesso (uguale al locale).
|
||||
- `nodeHost.browserProxy.allowProfiles` è facoltativo. Lascialo vuoto per il comportamento legacy/predefinito: tutti i profili configurati restano raggiungibili tramite il proxy, incluse le route di creazione/eliminazione dei profili.
|
||||
- Se imposti `nodeHost.browserProxy.allowProfiles`, OpenClaw lo tratta come un confine a privilegi minimi: solo i profili in allowlist possono essere usati come target e le route di creazione/eliminazione dei profili persistenti vengono bloccate sulla superficie proxy.
|
||||
- Disabilitalo se non lo vuoi:
|
||||
- Sul node: `nodeHost.browserProxy.enabled=false`
|
||||
- Sul gateway: `gateway.nodes.browser.mode="off"`
|
||||
@ -313,24 +313,38 @@ Esempio:
|
||||
|
||||
Note:
|
||||
|
||||
- Sostituisci `<BROWSERLESS_API_KEY>` con il tuo token Browserless reale.
|
||||
- Sostituisci `<BROWSERLESS_API_KEY>` con il tuo vero token Browserless.
|
||||
- Scegli l'endpoint regionale che corrisponde al tuo account Browserless (vedi la loro documentazione).
|
||||
- Se Browserless ti fornisce un URL base HTTPS, puoi convertirlo in
|
||||
`wss://` per una connessione CDP diretta oppure mantenere l'URL HTTPS e lasciare che OpenClaw
|
||||
individui `/json/version`.
|
||||
scopra `/json/version`.
|
||||
|
||||
## Provider CDP WebSocket diretti
|
||||
|
||||
Alcuni servizi browser ospitati espongono un endpoint **WebSocket diretto** invece
|
||||
del rilevamento CDP standard basato su HTTP (`/json/version`). OpenClaw supporta entrambi:
|
||||
dello standard di discovery CDP basato su HTTP (`/json/version`). OpenClaw accetta tre
|
||||
forme di URL CDP e sceglie automaticamente la strategia di connessione corretta:
|
||||
|
||||
- **Endpoint HTTP(S)** — OpenClaw chiama `/json/version` per individuare l'URL del debugger
|
||||
WebSocket, quindi si connette.
|
||||
- **Endpoint WebSocket** (`ws://` / `wss://`) — OpenClaw si connette direttamente,
|
||||
saltando `/json/version`. Usa questa modalità per servizi come
|
||||
[Browserless](https://browserless.io),
|
||||
[Browserbase](https://www.browserbase.com), o qualsiasi provider che ti fornisca un
|
||||
URL WebSocket.
|
||||
- **Discovery HTTP(S)** — `http://host[:port]` oppure `https://host[:port]`.
|
||||
OpenClaw chiama `/json/version` per scoprire l'URL del debugger WebSocket, quindi
|
||||
si collega. Nessun fallback WebSocket.
|
||||
- **Endpoint WebSocket diretti** — `ws://host[:port]/devtools/<kind>/<id>` oppure
|
||||
`wss://...` con un percorso `/devtools/browser|page|worker|shared_worker|service_worker/<id>`.
|
||||
OpenClaw si collega direttamente tramite un handshake WebSocket e salta
|
||||
completamente `/json/version`.
|
||||
- **Radici WebSocket bare** — `ws://host[:port]` oppure `wss://host[:port]` senza
|
||||
un percorso `/devtools/...` (ad es. [Browserless](https://browserless.io),
|
||||
[Browserbase](https://www.browserbase.com)). OpenClaw prova prima la discovery HTTP
|
||||
`/json/version` (normalizzando lo schema in `http`/`https`);
|
||||
se la discovery restituisce un `webSocketDebuggerUrl`, viene usato, altrimenti OpenClaw
|
||||
ripiega su un handshake WebSocket diretto alla radice bare. Questo copre
|
||||
sia le porte di debug remoto in stile Chrome sia i provider solo WebSocket.
|
||||
|
||||
`ws://host:port` / `wss://host:port` semplice senza un percorso `/devtools/...`
|
||||
puntato a un'istanza Chrome locale è supportato tramite il fallback
|
||||
discovery-first — Chrome accetta upgrade WebSocket solo sul percorso specifico per browser
|
||||
o target restituito da `/json/version`, quindi un handshake alla sola radice bare
|
||||
fallirebbe.
|
||||
|
||||
### Browserbase
|
||||
|
||||
@ -359,10 +373,10 @@ Note:
|
||||
|
||||
- [Registrati](https://www.browserbase.com/sign-up) e copia la tua **API Key**
|
||||
dalla [dashboard Overview](https://www.browserbase.com/overview).
|
||||
- Sostituisci `<BROWSERBASE_API_KEY>` con la tua vera API key Browserbase.
|
||||
- Sostituisci `<BROWSERBASE_API_KEY>` con la tua vera chiave API Browserbase.
|
||||
- Browserbase crea automaticamente una sessione browser alla connessione WebSocket, quindi
|
||||
non è necessario alcun passaggio manuale di creazione della sessione.
|
||||
- Il piano gratuito consente una sessione concorrente e un'ora di browser al mese.
|
||||
- Il piano gratuito consente una sessione concorrente e un'ora browser al mese.
|
||||
Vedi i [prezzi](https://www.browserbase.com/pricing) per i limiti dei piani a pagamento.
|
||||
- Consulta la [documentazione Browserbase](https://docs.browserbase.com) per il riferimento API
|
||||
completo, le guide SDK e gli esempi di integrazione.
|
||||
@ -372,36 +386,36 @@ Note:
|
||||
Concetti chiave:
|
||||
|
||||
- Il controllo del browser è solo loopback; l'accesso passa tramite l'autenticazione del Gateway o l'associazione del node.
|
||||
- L'API HTTP browser standalone su loopback usa **solo autenticazione con segreto condiviso**:
|
||||
autenticazione bearer con token del gateway, `x-openclaw-password`, oppure autenticazione HTTP Basic con la
|
||||
password del gateway configurata.
|
||||
- L'API HTTP browser standalone in loopback usa **solo autenticazione con segreto condiviso**:
|
||||
auth bearer con token gateway, `x-openclaw-password` oppure autenticazione HTTP Basic con la
|
||||
password gateway configurata.
|
||||
- Gli header di identità Tailscale Serve e `gateway.auth.mode: "trusted-proxy"` **non**
|
||||
autenticano questa API browser standalone su loopback.
|
||||
- Se il controllo del browser è abilitato e non è configurata alcuna autenticazione con segreto condiviso, OpenClaw
|
||||
genera automaticamente `gateway.auth.token` all'avvio e lo salva nella configurazione.
|
||||
- OpenClaw **non** genera automaticamente quel token quando `gateway.auth.mode` è
|
||||
già `password`, `none`, o `trusted-proxy`.
|
||||
autenticano questa API browser standalone in loopback.
|
||||
- Se il controllo browser è abilitato e non è configurata alcuna autenticazione con segreto condiviso, OpenClaw
|
||||
genera automaticamente `gateway.auth.token` all'avvio e lo rende persistente nella configurazione.
|
||||
- OpenClaw **non** genera automaticamente quel token quando `gateway.auth.mode` è già
|
||||
`password`, `none` oppure `trusted-proxy`.
|
||||
- Mantieni il Gateway e qualsiasi host node su una rete privata (Tailscale); evita l'esposizione pubblica.
|
||||
- Tratta gli URL/token CDP remoti come segreti; preferisci variabili d'ambiente o un secret manager.
|
||||
- Tratta gli URL/token CDP remoti come segreti; preferisci variabili d'ambiente o un gestore di segreti.
|
||||
|
||||
Suggerimenti per CDP remoto:
|
||||
|
||||
- Preferisci endpoint cifrati (HTTPS o WSS) e token a breve durata quando possibile.
|
||||
- Evita di incorporare token a lunga durata direttamente nei file di configurazione.
|
||||
- Preferisci endpoint cifrati (HTTPS o WSS) e token di breve durata quando possibile.
|
||||
- Evita di incorporare direttamente token di lunga durata nei file di configurazione.
|
||||
|
||||
## Profili (multi-browser)
|
||||
## Profili (browser multipli)
|
||||
|
||||
OpenClaw supporta più profili con nome (configurazioni di instradamento). I profili possono essere:
|
||||
OpenClaw supporta più profili con nome (configurazioni di routing). I profili possono essere:
|
||||
|
||||
- **gestiti da openclaw**: un'istanza dedicata di browser basato su Chromium con la propria directory dati utente + porta CDP
|
||||
- **gestiti da openclaw**: un'istanza browser dedicata basata su Chromium con la propria directory dati utente + porta CDP
|
||||
- **remoto**: un URL CDP esplicito (browser basato su Chromium in esecuzione altrove)
|
||||
- **sessione esistente**: il tuo profilo Chrome esistente tramite auto-connessione Chrome DevTools MCP
|
||||
- **sessione esistente**: il tuo profilo Chrome esistente tramite collegamento automatico Chrome DevTools MCP
|
||||
|
||||
Predefiniti:
|
||||
Valori predefiniti:
|
||||
|
||||
- Il profilo `openclaw` viene creato automaticamente se manca.
|
||||
- Il profilo `user` è integrato per il collegamento existing-session di Chrome MCP.
|
||||
- I profili existing-session sono opzionali oltre a `user`; creali con `--driver existing-session`.
|
||||
- I profili existing-session sono opt-in oltre a `user`; creali con `--driver existing-session`.
|
||||
- Le porte CDP locali vengono allocate da **18800–18899** per impostazione predefinita.
|
||||
- L'eliminazione di un profilo sposta la sua directory dati locale nel Cestino.
|
||||
|
||||
@ -409,11 +423,11 @@ Tutti gli endpoint di controllo accettano `?profile=<name>`; la CLI usa `--brows
|
||||
|
||||
## Existing-session tramite Chrome DevTools MCP
|
||||
|
||||
OpenClaw può anche collegarsi a un profilo browser basato su Chromium in esecuzione tramite il
|
||||
server ufficiale Chrome DevTools MCP. Questo riutilizza le schede e lo stato di accesso
|
||||
OpenClaw può anche collegarsi a un profilo browser già in esecuzione basato su Chromium tramite
|
||||
il server ufficiale Chrome DevTools MCP. Questo riutilizza le schede e lo stato di accesso
|
||||
già aperti in quel profilo browser.
|
||||
|
||||
Riferimenti ufficiali di contesto e configurazione:
|
||||
Riferimenti ufficiali per contesto e configurazione:
|
||||
|
||||
- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
|
||||
- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
|
||||
@ -422,12 +436,12 @@ Profilo integrato:
|
||||
|
||||
- `user`
|
||||
|
||||
Opzionale: crea il tuo profilo existing-session personalizzato se vuoi un
|
||||
Facoltativo: crea un tuo profilo existing-session personalizzato se vuoi un
|
||||
nome, colore o directory dati browser diversi.
|
||||
|
||||
Comportamento predefinito:
|
||||
|
||||
- Il profilo `user` integrato usa l'auto-connessione Chrome MCP, che punta al
|
||||
- Il profilo integrato `user` usa il collegamento automatico Chrome MCP, che punta al
|
||||
profilo locale predefinito di Google Chrome.
|
||||
|
||||
Usa `userDataDir` per Brave, Edge, Chromium o un profilo Chrome non predefinito:
|
||||
@ -451,7 +465,7 @@ Quindi, nel browser corrispondente:
|
||||
|
||||
1. Apri la pagina inspect di quel browser per il debug remoto.
|
||||
2. Abilita il debug remoto.
|
||||
3. Lascia il browser in esecuzione e approva il prompt di connessione quando OpenClaw si collega.
|
||||
3. Mantieni il browser in esecuzione e approva il prompt di connessione quando OpenClaw si collega.
|
||||
|
||||
Pagine inspect comuni:
|
||||
|
||||
@ -468,70 +482,71 @@ openclaw browser --browser-profile user tabs
|
||||
openclaw browser --browser-profile user snapshot --format ai
|
||||
```
|
||||
|
||||
Come appare il successo:
|
||||
Aspetto di un esito positivo:
|
||||
|
||||
- `status` mostra `driver: existing-session`
|
||||
- `status` mostra `transport: chrome-mcp`
|
||||
- `status` mostra `running: true`
|
||||
- `tabs` elenca le schede del browser già aperte
|
||||
- `tabs` elenca le schede browser già aperte
|
||||
- `snapshot` restituisce ref dalla scheda live selezionata
|
||||
|
||||
Cosa controllare se il collegamento non funziona:
|
||||
|
||||
- il browser di destinazione basato su Chromium è alla versione `144+`
|
||||
- il debug remoto è abilitato nella pagina inspect di quel browser
|
||||
- il browser ha mostrato il prompt di consenso al collegamento e tu lo hai accettato
|
||||
- `openclaw doctor` migra la vecchia configurazione browser basata su estensione e verifica che
|
||||
Chrome sia installato localmente per i profili predefiniti con auto-connessione, ma non può
|
||||
abilitare per te il debug remoto dal lato browser
|
||||
- il browser ha mostrato il prompt di consenso al collegamento e lo hai accettato
|
||||
- `openclaw doctor` migra la vecchia configurazione browser basata su estensione e controlla che
|
||||
Chrome sia installato localmente per i profili predefiniti con collegamento automatico, ma non può
|
||||
abilitare per te il debug remoto lato browser
|
||||
|
||||
Uso da parte dell'agente:
|
||||
|
||||
- Usa `profile="user"` quando hai bisogno dello stato del browser con accesso effettuato dell'utente.
|
||||
- Usa `profile="user"` quando ti serve lo stato del browser autenticato dell'utente.
|
||||
- Se usi un profilo existing-session personalizzato, passa quel nome profilo esplicito.
|
||||
- Scegli questa modalità solo quando l'utente è al computer per approvare il
|
||||
prompt di collegamento.
|
||||
- il Gateway o l'host node può eseguire `npx chrome-devtools-mcp@latest --autoConnect`
|
||||
- il Gateway o l'host node possono avviare `npx chrome-devtools-mcp@latest --autoConnect`
|
||||
|
||||
Note:
|
||||
|
||||
- Questo percorso è più rischioso del profilo `openclaw` isolato perché può
|
||||
agire all'interno della tua sessione browser con accesso effettuato.
|
||||
- Questo percorso è più rischioso del profilo isolato `openclaw` perché può
|
||||
agire all'interno della tua sessione browser autenticata.
|
||||
- OpenClaw non avvia il browser per questo driver; si collega solo a una
|
||||
sessione esistente.
|
||||
- OpenClaw usa qui il flusso ufficiale Chrome DevTools MCP `--autoConnect`. Se
|
||||
`userDataDir` è impostato, OpenClaw lo passa per puntare a quella specifica
|
||||
`userDataDir` è impostato, OpenClaw lo inoltra per puntare a quella esplicita
|
||||
directory dati utente Chromium.
|
||||
- Gli screenshot existing-session supportano acquisizioni della pagina e acquisizioni di elementi `--ref`
|
||||
dagli snapshot, ma non i selettori CSS `--element`.
|
||||
- Gli screenshot existing-session supportano acquisizioni di pagina e acquisizioni di elementi `--ref`
|
||||
da snapshot, ma non i selettori CSS `--element`.
|
||||
- Gli screenshot di pagina existing-session funzionano senza Playwright tramite Chrome MCP.
|
||||
Gli screenshot di elementi basati su ref (`--ref`) funzionano anche lì, ma `--full-page`
|
||||
Anche gli screenshot di elementi basati su ref (`--ref`) funzionano lì, ma `--full-page`
|
||||
non può essere combinato con `--ref` o `--element`.
|
||||
- Le azioni existing-session sono ancora più limitate rispetto al percorso del browser
|
||||
gestito:
|
||||
- `click`, `type`, `hover`, `scrollIntoView`, `drag`, e `select` richiedono
|
||||
ref snapshot invece dei selettori CSS
|
||||
- `click` è solo con il pulsante sinistro (nessuna sovrascrittura del pulsante o modificatore)
|
||||
- `click`, `type`, `hover`, `scrollIntoView`, `drag` e `select` richiedono
|
||||
ref di snapshot invece di selettori CSS
|
||||
- `click` è solo con pulsante sinistro (nessuna sovrascrittura del pulsante o modificatori)
|
||||
- `type` non supporta `slowly=true`; usa `fill` o `press`
|
||||
- `press` non supporta `delayMs`
|
||||
- `hover`, `scrollIntoView`, `drag`, `select`, `fill`, e `evaluate` non
|
||||
supportano override di timeout per chiamata
|
||||
- `select` al momento supporta un solo valore
|
||||
- Existing-session `wait --url` supporta pattern esatti, sottostringa e glob
|
||||
- `hover`, `scrollIntoView`, `drag`, `select`, `fill` ed `evaluate` non
|
||||
supportano override di timeout per singola chiamata
|
||||
- `select` attualmente supporta solo un singolo valore
|
||||
- Existing-session `wait --url` supporta pattern esatti, per sottostringa e glob
|
||||
come gli altri driver browser. `wait --load networkidle` non è ancora supportato.
|
||||
- Gli hook di upload existing-session richiedono `ref` o `inputRef`, supportano un file
|
||||
alla volta e non supportano il targeting CSS `element`.
|
||||
- Gli hook dialog existing-session non supportano override di timeout.
|
||||
- Alcune funzionalità richiedono ancora il percorso browser gestito, inclusi
|
||||
- Gli hook di dialog existing-session non supportano override di timeout.
|
||||
- Alcune funzionalità richiedono ancora il percorso del browser gestito, inclusi
|
||||
azioni batch, esportazione PDF, intercettazione dei download e `responsebody`.
|
||||
- Existing-session è locale all'host. Se Chrome si trova su una macchina diversa o in un
|
||||
namespace di rete diverso, usa invece CDP remoto o un host node.
|
||||
- Existing-session può collegarsi sull'host selezionato o tramite un browser node
|
||||
connesso. Se Chrome si trova altrove e non è connesso alcun browser node, usa
|
||||
CDP remoto o un host node.
|
||||
|
||||
## Garanzie di isolamento
|
||||
|
||||
- **Directory dati utente dedicata**: non tocca mai il profilo del tuo browser personale.
|
||||
- **Porte dedicate**: evita `9222` per prevenire collisioni con i flussi di lavoro di sviluppo.
|
||||
- **Controllo deterministico delle schede**: le schede di destinazione vengono identificate tramite `targetId`, non tramite “ultima scheda”.
|
||||
- **Porte dedicate**: evita `9222` per prevenire collisioni con i workflow di sviluppo.
|
||||
- **Controllo deterministico delle schede**: usa come target le schede tramite `targetId`, non “ultima scheda”.
|
||||
|
||||
## Selezione del browser
|
||||
|
||||
@ -551,7 +566,7 @@ Piattaforme:
|
||||
- Linux: cerca `google-chrome`, `brave`, `microsoft-edge`, `chromium`, ecc.
|
||||
- Windows: controlla le posizioni di installazione comuni.
|
||||
|
||||
## API di controllo (opzionale)
|
||||
## API di controllo (facoltativa)
|
||||
|
||||
Solo per integrazioni locali, il Gateway espone una piccola API HTTP loopback:
|
||||
|
||||
@ -570,71 +585,71 @@ Solo per integrazioni locali, il Gateway espone una piccola API HTTP loopback:
|
||||
|
||||
Tutti gli endpoint accettano `?profile=<name>`.
|
||||
|
||||
Se è configurata l'autenticazione gateway con segreto condiviso, anche le route HTTP browser richiedono autenticazione:
|
||||
Se è configurata l'autenticazione gateway con segreto condiviso, anche le route HTTP del browser richiedono autenticazione:
|
||||
|
||||
- `Authorization: Bearer <gateway token>`
|
||||
- `x-openclaw-password: <gateway password>` oppure autenticazione HTTP Basic con quella password
|
||||
|
||||
Note:
|
||||
|
||||
- Questa API browser standalone su loopback **non** usa trusted-proxy o
|
||||
- Questa API browser standalone in loopback **non** usa trusted-proxy né
|
||||
gli header di identità Tailscale Serve.
|
||||
- Se `gateway.auth.mode` è `none` o `trusted-proxy`, queste route browser su loopback
|
||||
non ereditano quelle modalità basate su identità; mantienile solo loopback.
|
||||
- Se `gateway.auth.mode` è `none` oppure `trusted-proxy`, queste route browser loopback
|
||||
non ereditano quelle modalità basate sull'identità; mantienile solo loopback.
|
||||
|
||||
### Contratto di errore `/act`
|
||||
|
||||
`POST /act` usa una risposta di errore strutturata per la validazione a livello di route e
|
||||
i fallimenti di policy:
|
||||
`POST /act` usa una risposta di errore strutturata per validazione a livello di route e
|
||||
fallimenti di policy:
|
||||
|
||||
```json
|
||||
{ "error": "<message>", "code": "ACT_*" }
|
||||
```
|
||||
|
||||
Valori `code` correnti:
|
||||
Valori `code` attuali:
|
||||
|
||||
- `ACT_KIND_REQUIRED` (HTTP 400): `kind` manca o non è riconosciuto.
|
||||
- `ACT_INVALID_REQUEST` (HTTP 400): il payload dell'azione ha fallito normalizzazione o validazione.
|
||||
- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): è stato usato `selector` con un tipo di azione non supportato.
|
||||
- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (o `wait --fn`) è disabilitato dalla configurazione.
|
||||
- `ACT_KIND_REQUIRED` (HTTP 400): `kind` è mancante o non riconosciuto.
|
||||
- `ACT_INVALID_REQUEST` (HTTP 400): il payload dell'azione non ha superato normalizzazione o validazione.
|
||||
- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` è stato usato con un tipo di azione non supportato.
|
||||
- `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (oppure `wait --fn`) è disabilitato dalla configurazione.
|
||||
- `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` di primo livello o batch è in conflitto con il target della richiesta.
|
||||
- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): l'azione non è supportata per i profili existing-session.
|
||||
|
||||
Altri errori di runtime possono ancora restituire `{ "error": "<message>" }` senza un
|
||||
Altri errori di runtime possono comunque restituire `{ "error": "<message>" }` senza un
|
||||
campo `code`.
|
||||
|
||||
### Requisito Playwright
|
||||
|
||||
Alcune funzionalità (navigate/act/AI snapshot/role snapshot, screenshot di elementi,
|
||||
Alcune funzionalità (`navigate`/`act`/snapshot AI/role snapshot, screenshot di elementi,
|
||||
PDF) richiedono Playwright. Se Playwright non è installato, quegli endpoint restituiscono
|
||||
un chiaro errore 501.
|
||||
|
||||
Cosa continua a funzionare senza Playwright:
|
||||
Cosa funziona ancora senza Playwright:
|
||||
|
||||
- Snapshot ARIA
|
||||
- Screenshot di pagina per il browser `openclaw` gestito quando è disponibile un WebSocket
|
||||
CDP per scheda
|
||||
- Screenshot di pagina per profili `existing-session` / Chrome MCP
|
||||
- Screenshot existing-session basati su `--ref` dall'output dello snapshot
|
||||
- snapshot ARIA
|
||||
- screenshot di pagina per il browser `openclaw` gestito quando è disponibile un
|
||||
WebSocket CDP per scheda
|
||||
- screenshot di pagina per i profili `existing-session` / Chrome MCP
|
||||
- screenshot `existing-session` basati su ref (`--ref`) dall'output di snapshot
|
||||
|
||||
Cosa richiede ancora Playwright:
|
||||
|
||||
- `navigate`
|
||||
- `act`
|
||||
- AI snapshot / role snapshot
|
||||
- Screenshot di elementi con selettore CSS (`--element`)
|
||||
- Esportazione PDF completa del browser
|
||||
- snapshot AI / role snapshot
|
||||
- screenshot di elementi con selettori CSS (`--element`)
|
||||
- esportazione PDF completa del browser
|
||||
|
||||
Anche gli screenshot di elementi rifiutano `--full-page`; la route restituisce `fullPage is
|
||||
Gli screenshot di elementi rifiutano anche `--full-page`; la route restituisce `fullPage is
|
||||
not supported for element screenshots`.
|
||||
|
||||
Se vedi `Playwright is not available in this gateway build`, installa il pacchetto
|
||||
Playwright completo (non `playwright-core`) e riavvia il gateway, oppure reinstalla
|
||||
OpenClaw con il supporto browser.
|
||||
Se vedi `Playwright is not available in this gateway build`, installa il pacchetto completo
|
||||
Playwright (non `playwright-core`) e riavvia il gateway, oppure reinstalla
|
||||
OpenClaw con supporto browser.
|
||||
|
||||
#### Installazione di Playwright in Docker
|
||||
#### Installazione Docker di Playwright
|
||||
|
||||
Se il tuo Gateway è in esecuzione in Docker, evita `npx playwright` (conflitti con gli override npm).
|
||||
Se il tuo Gateway è eseguito in Docker, evita `npx playwright` (conflitti con gli override npm).
|
||||
Usa invece la CLI inclusa:
|
||||
|
||||
```bash
|
||||
@ -643,7 +658,7 @@ docker compose run --rm openclaw-cli \
|
||||
```
|
||||
|
||||
Per rendere persistenti i download del browser, imposta `PLAYWRIGHT_BROWSERS_PATH` (ad esempio,
|
||||
`/home/node/.cache/ms-playwright`) e assicurati che `/home/node` sia persistito tramite
|
||||
`/home/node/.cache/ms-playwright`) e assicurati che `/home/node` sia persistente tramite
|
||||
`OPENCLAW_HOME_VOLUME` o un bind mount. Vedi [Docker](/it/install/docker).
|
||||
|
||||
## Come funziona (interno)
|
||||
@ -651,20 +666,20 @@ Per rendere persistenti i download del browser, imposta `PLAYWRIGHT_BROWSERS_PAT
|
||||
Flusso di alto livello:
|
||||
|
||||
- Un piccolo **server di controllo** accetta richieste HTTP.
|
||||
- Si collega ai browser basati su Chromium (Chrome/Brave/Edge/Chromium) tramite **CDP**.
|
||||
- Per le azioni avanzate (clic/digitazione/snapshot/PDF), usa **Playwright** sopra
|
||||
- Si collega a browser basati su Chromium (Chrome/Brave/Edge/Chromium) tramite **CDP**.
|
||||
- Per azioni avanzate (clic/digitazione/snapshot/PDF), usa **Playwright** sopra
|
||||
CDP.
|
||||
- Quando Playwright non è presente, sono disponibili solo le operazioni che non usano Playwright.
|
||||
- Quando Playwright manca, sono disponibili solo operazioni che non usano Playwright.
|
||||
|
||||
Questo design mantiene l'agente su un'interfaccia stabile e deterministica, permettendoti al contempo
|
||||
di cambiare browser e profili locali/remoti.
|
||||
Questo design mantiene l'agente su un'interfaccia stabile e deterministica, lasciandoti al contempo
|
||||
la possibilità di sostituire browser e profili locali/remoti.
|
||||
|
||||
## Riferimento rapido CLI
|
||||
|
||||
Tutti i comandi accettano `--browser-profile <name>` per indirizzare un profilo specifico.
|
||||
Tutti i comandi accettano `--browser-profile <name>` per puntare a un profilo specifico.
|
||||
Tutti i comandi accettano anche `--json` per output leggibile da macchina (payload stabili).
|
||||
|
||||
Nozioni di base:
|
||||
Base:
|
||||
|
||||
- `openclaw browser status`
|
||||
- `openclaw browser start`
|
||||
@ -695,7 +710,7 @@ Ispezione:
|
||||
|
||||
Nota sul ciclo di vita:
|
||||
|
||||
- Per i profili attach-only e CDP remoti, `openclaw browser stop` è comunque il
|
||||
- Per i profili attach-only e CDP remoto, `openclaw browser stop` resta comunque il
|
||||
comando di pulizia corretto dopo i test. Chiude la sessione di controllo attiva e
|
||||
cancella gli override temporanei di emulazione invece di terminare il browser
|
||||
sottostante.
|
||||
@ -749,36 +764,36 @@ Stato:
|
||||
|
||||
Note:
|
||||
|
||||
- `upload` e `dialog` sono chiamate di **preparazione**; eseguirle prima del clic/della pressione
|
||||
che attiva il selettore/la finestra di dialogo.
|
||||
- I percorsi di output di download e trace sono vincolati alle root temporanee di OpenClaw:
|
||||
- `upload` e `dialog` sono chiamate di **arming**; eseguirle prima del clic/tasto
|
||||
che attiva il chooser/dialog.
|
||||
- I percorsi di output di download e trace sono vincolati alle radici temp di OpenClaw:
|
||||
- trace: `/tmp/openclaw` (fallback: `${os.tmpdir()}/openclaw`)
|
||||
- download: `/tmp/openclaw/downloads` (fallback: `${os.tmpdir()}/openclaw/downloads`)
|
||||
- I percorsi di upload sono vincolati a una root temporanea uploads di OpenClaw:
|
||||
- uploads: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`)
|
||||
- `upload` può anche impostare direttamente input file tramite `--input-ref` o `--element`.
|
||||
- I percorsi di upload sono vincolati a una radice temp upload di OpenClaw:
|
||||
- upload: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`)
|
||||
- `upload` può anche impostare direttamente input file tramite `--input-ref` oppure `--element`.
|
||||
- `snapshot`:
|
||||
- `--format ai` (predefinito quando Playwright è installato): restituisce uno snapshot AI con ref numerici (`aria-ref="<n>"`).
|
||||
- `--format aria`: restituisce l'albero di accessibilità (senza ref; solo ispezione).
|
||||
- `--efficient` (o `--mode efficient`): preset compatto per role snapshot (interactive + compact + depth + maxChars più basso).
|
||||
- Configurazione predefinita (solo tool/CLI): imposta `browser.snapshotDefaults.mode: "efficient"` per usare snapshot efficienti quando il chiamante non passa una modalità (vedi [Configurazione Gateway](/it/gateway/configuration-reference#browser)).
|
||||
- Le opzioni del role snapshot (`--interactive`, `--compact`, `--depth`, `--selector`) forzano uno snapshot basato su ruoli con ref come `ref=e12`.
|
||||
- `--frame "<iframe selector>"` limita i role snapshot a un iframe (si abbina a role ref come `e12`).
|
||||
- `--interactive` produce un elenco piatto e facile da scegliere di elementi interattivi (ideale per guidare le azioni).
|
||||
- `--efficient` (oppure `--mode efficient`): preset compatto di role snapshot (interactive + compact + depth + maxChars più basso).
|
||||
- Configurazione predefinita (solo tool/CLI): imposta `browser.snapshotDefaults.mode: "efficient"` per usare snapshot efficient quando il chiamante non passa una modalità (vedi [Configurazione del Gateway](/it/gateway/configuration-reference#browser)).
|
||||
- Le opzioni di role snapshot (`--interactive`, `--compact`, `--depth`, `--selector`) forzano uno snapshot basato su ruoli con ref come `ref=e12`.
|
||||
- `--frame "<iframe selector>"` limita i role snapshot a un iframe (si abbina a ref di ruolo come `e12`).
|
||||
- `--interactive` produce un elenco piatto e facile da selezionare degli elementi interattivi (ideale per guidare le azioni).
|
||||
- `--labels` aggiunge uno screenshot della viewport con etichette ref sovrapposte (stampa `MEDIA:<path>`).
|
||||
- `click`/`type`/ecc. richiedono un `ref` da `snapshot` (sia numerico `12` sia role ref `e12`).
|
||||
- `click`/`type`/ecc. richiedono un `ref` da `snapshot` (sia numerico `12` sia ref di ruolo `e12`).
|
||||
I selettori CSS intenzionalmente non sono supportati per le azioni.
|
||||
|
||||
## Snapshot e ref
|
||||
|
||||
OpenClaw supporta due stili di “snapshot”:
|
||||
|
||||
- **AI snapshot (ref numerici)**: `openclaw browser snapshot` (predefinito; `--format ai`)
|
||||
- **Snapshot AI (ref numerici)**: `openclaw browser snapshot` (predefinito; `--format ai`)
|
||||
- Output: uno snapshot testuale che include ref numerici.
|
||||
- Azioni: `openclaw browser click 12`, `openclaw browser type 23 "hello"`.
|
||||
- Internamente, il ref viene risolto tramite `aria-ref` di Playwright.
|
||||
|
||||
- **Role snapshot (role ref come `e12`)**: `openclaw browser snapshot --interactive` (oppure `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- **Role snapshot (ref di ruolo come `e12`)**: `openclaw browser snapshot --interactive` (oppure `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- Output: un elenco/albero basato su ruoli con `[ref=e12]` (e facoltativamente `[nth=1]`).
|
||||
- Azioni: `openclaw browser click e12`, `openclaw browser highlight e12`.
|
||||
- Internamente, il ref viene risolto tramite `getByRole(...)` (più `nth()` per i duplicati).
|
||||
@ -786,12 +801,12 @@ OpenClaw supporta due stili di “snapshot”:
|
||||
|
||||
Comportamento dei ref:
|
||||
|
||||
- I ref **non sono stabili tra una navigazione e l'altra**; se qualcosa fallisce, esegui di nuovo `snapshot` e usa un ref aggiornato.
|
||||
- Se il role snapshot è stato acquisito con `--frame`, i role ref sono limitati a quell'iframe fino al role snapshot successivo.
|
||||
- I ref **non sono stabili tra una navigazione e l'altra**; se qualcosa fallisce, riesegui `snapshot` e usa un ref aggiornato.
|
||||
- Se il role snapshot è stato acquisito con `--frame`, i ref di ruolo sono limitati a quell'iframe fino al role snapshot successivo.
|
||||
|
||||
## Potenziamenti di wait
|
||||
|
||||
Puoi attendere più di un semplice tempo/testo:
|
||||
Puoi aspettare più di semplice tempo/testo:
|
||||
|
||||
- Attendere un URL (glob supportati da Playwright):
|
||||
- `openclaw browser wait --url "**/dash"`
|
||||
@ -812,13 +827,13 @@ openclaw browser wait "#main" \
|
||||
--timeout-ms 15000
|
||||
```
|
||||
|
||||
## Flussi di debug
|
||||
## Workflow di debug
|
||||
|
||||
Quando un'azione fallisce (ad esempio “not visible”, “strict mode violation”, “covered”):
|
||||
Quando un'azione fallisce (ad es. “not visible”, “strict mode violation”, “covered”):
|
||||
|
||||
1. `openclaw browser snapshot --interactive`
|
||||
2. Usa `click <ref>` / `type <ref>` (preferisci role ref in modalità interattiva)
|
||||
3. Se fallisce ancora: `openclaw browser highlight <ref>` per vedere cosa Playwright sta prendendo di mira
|
||||
2. Usa `click <ref>` / `type <ref>` (preferisci ref di ruolo in modalità interactive)
|
||||
3. Se fallisce ancora: `openclaw browser highlight <ref>` per vedere cosa sta puntando Playwright
|
||||
4. Se la pagina si comporta in modo strano:
|
||||
- `openclaw browser errors --clear`
|
||||
- `openclaw browser requests --filter api --clear`
|
||||
@ -829,7 +844,7 @@ Quando un'azione fallisce (ad esempio “not visible”, “strict mode violatio
|
||||
|
||||
## Output JSON
|
||||
|
||||
`--json` serve per scripting e tool strutturati.
|
||||
`--json` è per scripting e tooling strutturato.
|
||||
|
||||
Esempi:
|
||||
|
||||
@ -844,31 +859,31 @@ I role snapshot in JSON includono `refs` più un piccolo blocco `stats` (righe/c
|
||||
|
||||
## Controlli di stato e ambiente
|
||||
|
||||
Questi sono utili per flussi “fai comportare il sito come X”:
|
||||
Questi sono utili per workflow del tipo “fai comportare il sito come X”:
|
||||
|
||||
- Cookie: `cookies`, `cookies set`, `cookies clear`
|
||||
- Storage: `storage local|session get|set|clear`
|
||||
- Offline: `set offline on|off`
|
||||
- Header: `set headers --headers-json '{"X-Debug":"1"}'` (il legacy `set headers --json '{"X-Debug":"1"}'` resta supportato)
|
||||
- Autenticazione HTTP basic: `set credentials user pass` (oppure `--clear`)
|
||||
- Header: `set headers --headers-json '{"X-Debug":"1"}'` (la forma legacy `set headers --json '{"X-Debug":"1"}'` resta supportata)
|
||||
- Auth HTTP Basic: `set credentials user pass` (oppure `--clear`)
|
||||
- Geolocalizzazione: `set geo <lat> <lon> --origin "https://example.com"` (oppure `--clear`)
|
||||
- Media: `set media dark|light|no-preference|none`
|
||||
- Fuso orario / impostazioni locali: `set timezone ...`, `set locale ...`
|
||||
- Fuso orario / locale: `set timezone ...`, `set locale ...`
|
||||
- Dispositivo / viewport:
|
||||
- `set device "iPhone 14"` (preset dispositivo Playwright)
|
||||
- `set device "iPhone 14"` (preset dispositivi Playwright)
|
||||
- `set viewport 1280 720`
|
||||
|
||||
## Sicurezza e privacy
|
||||
|
||||
- Il profilo browser openclaw può contenere sessioni con accesso effettuato; trattalo come sensibile.
|
||||
- Il profilo browser openclaw può contenere sessioni autenticate; trattalo come sensibile.
|
||||
- `browser act kind=evaluate` / `openclaw browser evaluate` e `wait --fn`
|
||||
eseguono JavaScript arbitrario nel contesto della pagina. Il prompt injection può indirizzare
|
||||
eseguono JavaScript arbitrario nel contesto della pagina. Il prompt injection può orientare
|
||||
questo comportamento. Disabilitalo con `browser.evaluateEnabled=false` se non ti serve.
|
||||
- Per login e note anti-bot (X/Twitter, ecc.), vedi [Accesso browser + pubblicazione su X/Twitter](/it/tools/browser-login).
|
||||
- Mantieni privati il Gateway/l'host node (solo loopback o tailnet).
|
||||
- Gli endpoint CDP remoti sono potenti; incanalarli e proteggerli.
|
||||
- Per note su login e anti-bot (X/Twitter, ecc.), vedi [Login browser + pubblicazione su X/Twitter](/it/tools/browser-login).
|
||||
- Mantieni privato il Gateway/node host (solo loopback o tailnet).
|
||||
- Gli endpoint CDP remoti sono potenti; instradali in tunnel e proteggili.
|
||||
|
||||
Esempio di modalità rigorosa (blocca per impostazione predefinita le destinazioni private/interne):
|
||||
Esempio di modalità rigorosa (blocca per impostazione predefinita destinazioni private/interne):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -876,7 +891,7 @@ Esempio di modalità rigorosa (blocca per impostazione predefinita le destinazio
|
||||
ssrfPolicy: {
|
||||
dangerouslyAllowPrivateNetwork: false,
|
||||
hostnameAllowlist: ["*.example.com", "example.com"],
|
||||
allowedHostnames: ["localhost"], // allow esatto opzionale
|
||||
allowedHostnames: ["localhost"], // optional exact allow
|
||||
},
|
||||
},
|
||||
}
|
||||
@ -884,26 +899,26 @@ Esempio di modalità rigorosa (blocca per impostazione predefinita le destinazio
|
||||
|
||||
## Risoluzione dei problemi
|
||||
|
||||
Per problemi specifici di Linux (in particolare snap Chromium), vedi
|
||||
Per problemi specifici di Linux (soprattutto snap Chromium), vedi
|
||||
[Risoluzione dei problemi del browser](/it/tools/browser-linux-troubleshooting).
|
||||
|
||||
Per configurazioni divise host WSL2 Gateway + Chrome Windows, vedi
|
||||
Per configurazioni split-host con Gateway WSL2 + Chrome Windows, vedi
|
||||
[Risoluzione dei problemi WSL2 + Windows + CDP Chrome remoto](/it/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
|
||||
### Errore di avvio CDP vs blocco SSRF di navigazione
|
||||
|
||||
Queste sono classi di errore diverse e puntano a percorsi di codice differenti.
|
||||
Queste sono classi di errore diverse e indicano percorsi di codice diversi.
|
||||
|
||||
- **Errore di avvio o di prontezza CDP** significa che OpenClaw non riesce a confermare che il piano di controllo del browser sia integro.
|
||||
- **Blocco SSRF di navigazione** significa che il piano di controllo del browser è integro, ma una destinazione di navigazione della pagina viene rifiutata dalla policy.
|
||||
- **Errore di avvio o readiness CDP** significa che OpenClaw non riesce a confermare che il control plane del browser sia integro.
|
||||
- **Blocco SSRF di navigazione** significa che il control plane del browser è integro, ma una destinazione di navigazione di pagina viene rifiutata dalla policy.
|
||||
|
||||
Esempi comuni:
|
||||
|
||||
- Errore di avvio o di prontezza CDP:
|
||||
- Errore di avvio o readiness CDP:
|
||||
- `Chrome CDP websocket for profile "openclaw" is not reachable after start`
|
||||
- `Remote CDP for profile "<name>" is not reachable at <cdpUrl>`
|
||||
- Blocco SSRF di navigazione:
|
||||
- i flussi `open`, `navigate`, snapshot o di apertura schede falliscono con un errore di policy browser/rete mentre `start` e `tabs` continuano a funzionare
|
||||
- i flussi `open`, `navigate`, snapshot o apertura di schede falliscono con un errore di policy browser/rete mentre `start` e `tabs` continuano a funzionare
|
||||
|
||||
Usa questa sequenza minima per distinguere i due casi:
|
||||
|
||||
@ -915,39 +930,39 @@ openclaw browser --browser-profile openclaw open https://example.com
|
||||
|
||||
Come interpretare i risultati:
|
||||
|
||||
- Se `start` fallisce con `not reachable after start`, risolvi prima il problema di prontezza CDP.
|
||||
- Se `start` riesce ma `tabs` fallisce, il piano di controllo non è ancora integro. Trattalo come un problema di raggiungibilità CDP, non come un problema di navigazione della pagina.
|
||||
- Se `start` e `tabs` riescono ma `open` o `navigate` falliscono, il piano di controllo del browser è attivo e il problema riguarda la policy di navigazione o la pagina di destinazione.
|
||||
- Se `start` fallisce con `not reachable after start`, risolvi prima i problemi di readiness CDP.
|
||||
- Se `start` riesce ma `tabs` fallisce, il control plane non è ancora integro. Trattalo come un problema di raggiungibilità CDP, non come un problema di navigazione della pagina.
|
||||
- Se `start` e `tabs` riescono ma `open` o `navigate` falliscono, il control plane del browser è attivo e il problema è nella policy di navigazione o nella pagina di destinazione.
|
||||
- Se `start`, `tabs` e `open` riescono tutti, il percorso di controllo di base del browser gestito è integro.
|
||||
|
||||
Dettagli importanti sul comportamento:
|
||||
Dettagli importanti del comportamento:
|
||||
|
||||
- La configurazione del browser usa per impostazione predefinita un oggetto di policy SSRF fail-closed anche quando non configuri `browser.ssrfPolicy`.
|
||||
- Per il profilo gestito locale `openclaw` su loopback, i controlli di integrità CDP saltano intenzionalmente l'applicazione della raggiungibilità SSRF del browser per il piano di controllo locale di OpenClaw.
|
||||
- Per il profilo gestito locale `openclaw` in loopback, i controlli di integrità CDP saltano intenzionalmente l'applicazione della raggiungibilità SSRF del browser per il control plane locale di OpenClaw stesso.
|
||||
- La protezione della navigazione è separata. Un risultato positivo di `start` o `tabs` non significa che una destinazione successiva di `open` o `navigate` sia consentita.
|
||||
|
||||
Linee guida di sicurezza:
|
||||
|
||||
- **Non** allentare la policy SSRF del browser per impostazione predefinita.
|
||||
- Preferisci eccezioni host ristrette come `hostnameAllowlist` o `allowedHostnames` invece di un ampio accesso alla rete privata.
|
||||
- Usa `dangerouslyAllowPrivateNetwork: true` solo in ambienti intenzionalmente attendibili in cui l'accesso del browser alla rete privata è richiesto e revisionato.
|
||||
- Preferisci eccezioni host ristrette come `hostnameAllowlist` o `allowedHostnames` rispetto a un ampio accesso alla rete privata.
|
||||
- Usa `dangerouslyAllowPrivateNetwork: true` solo in ambienti intenzionalmente affidabili in cui l'accesso del browser alla rete privata è richiesto e revisionato.
|
||||
|
||||
Esempio: navigazione bloccata, piano di controllo integro
|
||||
Esempio: navigazione bloccata, control plane integro
|
||||
|
||||
- `start` riesce
|
||||
- `tabs` riesce
|
||||
- `open http://internal.example` fallisce
|
||||
|
||||
Questo di solito significa che l'avvio del browser è corretto e che la destinazione di navigazione richiede una revisione della policy.
|
||||
Di solito significa che l'avvio del browser è corretto e la destinazione di navigazione richiede una revisione della policy.
|
||||
|
||||
Esempio: avvio bloccato prima che la navigazione conti
|
||||
|
||||
- `start` fallisce con `not reachable after start`
|
||||
- anche `tabs` fallisce o non può essere eseguito
|
||||
- `tabs` fallisce anch'esso o non può essere eseguito
|
||||
|
||||
Questo indica un problema di avvio del browser o di raggiungibilità CDP, non un problema di allowlist URL della pagina.
|
||||
Questo indica un problema di avvio del browser o di raggiungibilità CDP, non un problema di allowlist degli URL di pagina.
|
||||
|
||||
## Strumenti dell'agente + funzionamento del controllo
|
||||
## Strumenti dell'agente + come funziona il controllo
|
||||
|
||||
L'agente riceve **uno strumento** per l'automazione del browser:
|
||||
|
||||
@ -957,18 +972,18 @@ Mappatura:
|
||||
|
||||
- `browser snapshot` restituisce un albero UI stabile (AI o ARIA).
|
||||
- `browser act` usa gli ID `ref` dello snapshot per fare clic/digitare/trascinare/selezionare.
|
||||
- `browser screenshot` acquisisce i pixel (pagina intera o elemento).
|
||||
- `browser screenshot` cattura i pixel (pagina intera o elemento).
|
||||
- `browser` accetta:
|
||||
- `profile` per scegliere un profilo browser con nome (openclaw, chrome o CDP remoto).
|
||||
- `target` (`sandbox` | `host` | `node`) per selezionare dove si trova il browser.
|
||||
- Nelle sessioni sandboxed, `target: "host"` richiede `agents.defaults.sandbox.browser.allowHostControl=true`.
|
||||
- Se `target` viene omesso: le sessioni sandboxed usano per impostazione predefinita `sandbox`, le sessioni non sandbox usano per impostazione predefinita `host`.
|
||||
- Se è connesso un node con capacità browser, lo strumento può instradarsi automaticamente a esso a meno che tu non fissi `target="host"` o `target="node"`.
|
||||
- Se è connesso un node con capacità browser, lo strumento può instradarsi automaticamente verso di esso a meno che tu non fissi `target="host"` o `target="node"`.
|
||||
|
||||
Questo mantiene l'agente deterministico ed evita selettori fragili.
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Panoramica degli strumenti](/it/tools) — tutti gli strumenti dell'agente disponibili
|
||||
- [Panoramica degli strumenti](/it/tools) — tutti gli strumenti agente disponibili
|
||||
- [Sandboxing](/it/gateway/sandboxing) — controllo del browser in ambienti sandboxed
|
||||
- [Sicurezza](/it/gateway/security) — rischi e misure di hardening del controllo del browser
|
||||
- [Sicurezza](/it/gateway/security) — rischi del controllo browser e misure di hardening
|
||||
|
||||
Loading…
Reference in New Issue
Block a user