chore(i18n): refresh it translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
6c97ed6a08
commit
37adedfa62
@ -1,42 +1,42 @@
|
||||
---
|
||||
read_when:
|
||||
- Ispezione del lavoro in background in corso o completato di recente
|
||||
- Debug degli errori di consegna per esecuzioni agent distaccate
|
||||
- Debug delle errori di consegna per esecuzioni di agenti scollegati
|
||||
- Comprendere come le esecuzioni in background si relazionano a sessioni, cron e heartbeat
|
||||
summary: Monitoraggio delle attività in background per esecuzioni ACP, subagent, processi cron isolati e operazioni CLI
|
||||
summary: Monitoraggio delle attività in background per esecuzioni ACP, subagenti, processi cron isolati e operazioni CLI
|
||||
title: Attività in background
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:06:37Z"
|
||||
generated_at: "2026-04-10T08:13:31Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2f56c1ac23237907a090c69c920c09578a2f56f5d8bf750c7f2136c603c8a8ff
|
||||
source_hash: d7b5ba41f1025e0089986342ce85698bc62f676439c3ccf03f3ed146beb1b1ac
|
||||
source_path: automation/tasks.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Attività in background
|
||||
|
||||
> **Cerchi la pianificazione?** Consulta [Automazione e attività](/it/automation) per scegliere il meccanismo corretto. Questa pagina riguarda il **monitoraggio** del lavoro in background, non la sua pianificazione.
|
||||
> **Cerchi la pianificazione?** Vedi [Automation & Tasks](/it/automation) per scegliere il meccanismo giusto. Questa pagina copre il **monitoraggio** del lavoro in background, non la sua pianificazione.
|
||||
|
||||
Le attività in background monitorano il lavoro che viene eseguito **al di fuori della sessione principale di conversazione**:
|
||||
esecuzioni ACP, avvii di subagent, esecuzioni isolate di processi cron e operazioni avviate dalla CLI.
|
||||
Le attività in background tengono traccia del lavoro che viene eseguito **al di fuori della sessione principale della conversazione**:
|
||||
esecuzioni ACP, avvii di subagenti, esecuzioni isolate di processi cron e operazioni avviate dalla CLI.
|
||||
|
||||
Le attività **non** sostituiscono sessioni, processi cron o heartbeat: sono il **registro delle attività** che annota quale lavoro distaccato è avvenuto, quando, e se è andato a buon fine.
|
||||
Le attività **non** sostituiscono sessioni, processi cron o heartbeat — sono il **registro delle attività** che annota quale lavoro scollegato è avvenuto, quando e se è andato a buon fine.
|
||||
|
||||
<Note>
|
||||
Non tutte le esecuzioni di agent creano un'attività. I turni heartbeat e la normale chat interattiva non lo fanno. Tutte le esecuzioni cron, gli avvii ACP, gli avvii di subagent e i comandi agent della CLI lo fanno.
|
||||
Non tutte le esecuzioni dell'agente creano un'attività. I turni heartbeat e la normale chat interattiva no. Tutte le esecuzioni cron, gli avvii ACP, gli avvii di subagenti e i comandi agente della CLI sì.
|
||||
</Note>
|
||||
|
||||
## In breve
|
||||
|
||||
- Le attività sono **record**, non scheduler: cron e heartbeat decidono _quando_ viene eseguito il lavoro, le attività monitorano _cosa è successo_.
|
||||
- ACP, subagent, tutti i processi cron e le operazioni CLI creano attività. I turni heartbeat no.
|
||||
- Ogni attività passa attraverso `queued → running → terminal` (succeeded, failed, timed_out, cancelled oppure lost).
|
||||
- Le attività cron restano attive finché il runtime cron continua a possedere il job; le attività CLI supportate dalla chat restano attive solo finché il relativo contesto di esecuzione è ancora attivo.
|
||||
- Il completamento è basato su push: il lavoro distaccato può notificare direttamente o risvegliare la sessione richiedente/l'heartbeat quando termina, quindi i loop di polling dello stato di solito non sono l'approccio corretto.
|
||||
- Le esecuzioni cron isolate e i completamenti dei subagent tentano, nei limiti del possibile, di ripulire le schede/processi del browser tracciati per la loro sessione figlia prima della contabilità finale di pulizia.
|
||||
- La consegna cron isolata sopprime le risposte intermedie obsolete del parent mentre il lavoro dei subagent discendenti è ancora in fase di completamento, e preferisce l'output finale del discendente quando arriva prima della consegna.
|
||||
- Le notifiche di completamento vengono consegnate direttamente a un canale o messe in coda per il prossimo heartbeat.
|
||||
- Le attività sono **record**, non scheduler — cron e heartbeat decidono _quando_ viene eseguito il lavoro, le attività tengono traccia di _cosa è successo_.
|
||||
- ACP, subagenti, tutti i processi cron e le operazioni CLI creano attività. I turni heartbeat no.
|
||||
- Ogni attività passa attraverso `queued → running → terminal` (`succeeded`, `failed`, `timed_out`, `cancelled` o `lost`).
|
||||
- Le attività cron restano attive finché il runtime cron possiede ancora il processo; le attività CLI supportate dalla chat restano attive solo finché il relativo contesto di esecuzione è ancora attivo.
|
||||
- Il completamento è guidato da push: il lavoro scollegato può notificare direttamente o risvegliare la sessione/heartbeat del richiedente quando termina, quindi i cicli di polling dello stato di solito non sono l'approccio corretto.
|
||||
- Le esecuzioni cron isolate e i completamenti dei subagenti eseguono, per quanto possibile, la pulizia delle schede/processi del browser tracciati per la loro sessione figlia prima della contabilità finale di pulizia.
|
||||
- Il recapito cron isolato sopprime le risposte intermedie obsolete del padre mentre il lavoro del subagente discendente è ancora in fase di completamento, e preferisce l'output finale discendente quando arriva prima del recapito.
|
||||
- Le notifiche di completamento vengono recapitate direttamente a un canale o accodate per il prossimo heartbeat.
|
||||
- `openclaw tasks list` mostra tutte le attività; `openclaw tasks audit` evidenzia i problemi.
|
||||
- I record terminali vengono conservati per 7 giorni, poi eliminati automaticamente.
|
||||
|
||||
@ -50,23 +50,23 @@ openclaw tasks list
|
||||
openclaw tasks list --runtime acp
|
||||
openclaw tasks list --status running
|
||||
|
||||
# Mostra i dettagli di un'attività specifica (per ID, ID esecuzione o chiave sessione)
|
||||
# Mostra i dettagli di un'attività specifica (per ID, run ID o chiave sessione)
|
||||
openclaw tasks show <lookup>
|
||||
|
||||
# Annulla un'attività in esecuzione (termina la sessione figlia)
|
||||
openclaw tasks cancel <lookup>
|
||||
|
||||
# Modifica il criterio di notifica per un'attività
|
||||
# Cambia il criterio di notifica per un'attività
|
||||
openclaw tasks notify <lookup> state_changes
|
||||
|
||||
# Esegui un controllo di integrità
|
||||
# Esegui un audit di integrità
|
||||
openclaw tasks audit
|
||||
|
||||
# Anteprima o applicazione della manutenzione
|
||||
openclaw tasks maintenance
|
||||
openclaw tasks maintenance --apply
|
||||
|
||||
# Ispeziona lo stato di Task Flow
|
||||
# Ispeziona lo stato di TaskFlow
|
||||
openclaw tasks flow list
|
||||
openclaw tasks flow show <lookup>
|
||||
openclaw tasks flow cancel <lookup>
|
||||
@ -76,82 +76,82 @@ openclaw tasks flow cancel <lookup>
|
||||
|
||||
| Origine | Tipo di runtime | Quando viene creato un record attività | Criterio di notifica predefinito |
|
||||
| ---------------------- | --------------- | ------------------------------------------------------ | -------------------------------- |
|
||||
| Esecuzioni ACP in background | `acp` | Avvio di una sessione ACP figlia | `done_only` |
|
||||
| Orchestrazione subagent | `subagent` | Avvio di un subagent tramite `sessions_spawn` | `done_only` |
|
||||
| Processi cron (tutti i tipi) | `cron` | Ogni esecuzione cron (sessione principale e isolata) | `silent` |
|
||||
| Esecuzioni ACP in background | `acp` | Avvio di una sessione ACP figlia | `done_only` |
|
||||
| Orchestrazione di subagenti | `subagent` | Avvio di un subagente tramite `sessions_spawn` | `done_only` |
|
||||
| Processi cron (tutti i tipi) | `cron` | Ogni esecuzione cron (sessione principale e isolata) | `silent` |
|
||||
| Operazioni CLI | `cli` | Comandi `openclaw agent` eseguiti tramite il gateway | `silent` |
|
||||
| Processi media dell'agent | `cli` | Esecuzioni `video_generate` supportate da sessione | `silent` |
|
||||
| Processi media dell'agente | `cli` | Esecuzioni `video_generate` supportate dalla sessione | `silent` |
|
||||
|
||||
Le attività cron della sessione principale usano per impostazione predefinita il criterio di notifica `silent`: creano record per il monitoraggio ma non generano notifiche. Anche le attività cron isolate usano per impostazione predefinita `silent`, ma sono più visibili perché vengono eseguite nella propria sessione.
|
||||
Le attività cron della sessione principale usano per impostazione predefinita il criterio di notifica `silent` — creano record per il monitoraggio ma non generano notifiche. Anche le attività cron isolate usano per impostazione predefinita `silent`, ma sono più visibili perché vengono eseguite nella propria sessione.
|
||||
|
||||
Anche le esecuzioni `video_generate` supportate da sessione usano il criterio di notifica `silent`. Creano comunque record attività, ma il completamento viene restituito alla sessione agent originale come risveglio interno, così l'agent può scrivere il messaggio di follow-up e allegare personalmente il video completato. Se scegli `tools.media.asyncCompletion.directSend`, i completamenti asincroni di `music_generate` e `video_generate` tentano prima la consegna diretta al canale, per poi ripiegare sul percorso di risveglio della sessione richiedente.
|
||||
Anche le esecuzioni `video_generate` supportate dalla sessione usano il criterio di notifica `silent`. Continuano a creare record attività, ma il completamento viene restituito alla sessione agente originale come risveglio interno, così l'agente può scrivere il messaggio di follow-up e allegare direttamente il video completato. Se scegli `tools.media.asyncCompletion.directSend`, i completamenti asincroni di `music_generate` e `video_generate` tentano prima il recapito diretto al canale, per poi ripiegare sul percorso di risveglio della sessione richiedente.
|
||||
|
||||
Mentre un'attività `video_generate` supportata da sessione è ancora attiva, lo strumento funge anche da protezione: chiamate ripetute a `video_generate` nella stessa sessione restituiscono lo stato dell'attività attiva invece di avviare una seconda generazione concorrente. Usa `action: "status"` quando desideri una ricerca esplicita di avanzamento/stato dal lato agent.
|
||||
Mentre un'attività `video_generate` supportata dalla sessione è ancora attiva, lo strumento funge anche da guardrail: chiamate ripetute a `video_generate` nella stessa sessione restituiscono lo stato dell'attività attiva invece di avviare una seconda generazione concorrente. Usa `action: "status"` quando vuoi una ricerca esplicita di avanzamento/stato dal lato agente.
|
||||
|
||||
**Cosa non crea attività:**
|
||||
|
||||
- Turni heartbeat — sessione principale; vedi [Heartbeat](/it/gateway/heartbeat)
|
||||
- Normali turni di chat interattiva
|
||||
- Risposte dirette `/command`
|
||||
- Turni di chat interattiva normali
|
||||
- Risposte dirette a `/command`
|
||||
|
||||
## Ciclo di vita dell'attività
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> queued
|
||||
queued --> running : agent starts
|
||||
running --> succeeded : completes ok
|
||||
running --> failed : error
|
||||
running --> timed_out : timeout exceeded
|
||||
running --> cancelled : operator cancels
|
||||
queued --> lost : session gone > 5 min
|
||||
running --> lost : session gone > 5 min
|
||||
queued --> running : l'agente avvia
|
||||
running --> succeeded : completamento riuscito
|
||||
running --> failed : errore
|
||||
running --> timed_out : timeout superato
|
||||
running --> cancelled : l'operatore annulla
|
||||
queued --> lost : sessione assente > 5 min
|
||||
running --> lost : sessione assente > 5 min
|
||||
```
|
||||
|
||||
| Stato | Significato |
|
||||
| ----------- | ------------------------------------------------------------------------- |
|
||||
| `queued` | Creata, in attesa che l'agent inizi |
|
||||
| `running` | Il turno dell'agent è in esecuzione attiva |
|
||||
| Stato | Significato |
|
||||
| ----------- | -------------------------------------------------------------------------- |
|
||||
| `queued` | Creata, in attesa che l'agente si avvii |
|
||||
| `running` | Il turno dell'agente è attivamente in esecuzione |
|
||||
| `succeeded` | Completata con successo |
|
||||
| `failed` | Completata con un errore |
|
||||
| `timed_out` | Ha superato il timeout configurato |
|
||||
| `cancelled` | Interrotta dall'operatore tramite `openclaw tasks cancel` |
|
||||
| `failed` | Completata con un errore |
|
||||
| `timed_out` | Ha superato il timeout configurato |
|
||||
| `cancelled` | Arrestata dall'operatore tramite `openclaw tasks cancel` |
|
||||
| `lost` | Il runtime ha perso lo stato di supporto autorevole dopo un periodo di tolleranza di 5 minuti |
|
||||
|
||||
Le transizioni avvengono automaticamente: quando termina l'esecuzione dell'agent associata, lo stato dell'attività si aggiorna di conseguenza.
|
||||
Le transizioni avvengono automaticamente — quando termina l'esecuzione dell'agente associata, lo stato dell'attività si aggiorna di conseguenza.
|
||||
|
||||
`lost` dipende dal runtime:
|
||||
|
||||
- Attività ACP: i metadati della sessione figlia ACP di supporto sono scomparsi.
|
||||
- Attività subagent: la sessione figlia di supporto è scomparsa dallo store agent di destinazione.
|
||||
- Attività cron: il runtime cron non monitora più il job come attivo.
|
||||
- Attività CLI: le attività di sessione figlia isolate usano la sessione figlia; le attività CLI supportate dalla chat usano invece il contesto di esecuzione live, quindi righe residue di sessione canale/gruppo/diretta non le mantengono attive.
|
||||
- Attività di subagenti: la sessione figlia di supporto è scomparsa dallo store dell'agente di destinazione.
|
||||
- Attività cron: il runtime cron non tiene più traccia del processo come attivo.
|
||||
- Attività CLI: le attività isolate della sessione figlia usano la sessione figlia; le attività CLI supportate dalla chat usano invece il contesto di esecuzione live, quindi righe persistenti di sessione di canale/gruppo/diretta non le mantengono attive.
|
||||
|
||||
## Consegna e notifiche
|
||||
## Recapito e notifiche
|
||||
|
||||
Quando un'attività raggiunge uno stato terminale, OpenClaw ti notifica. Esistono due percorsi di consegna:
|
||||
Quando un'attività raggiunge uno stato terminale, OpenClaw ti notifica. Esistono due percorsi di recapito:
|
||||
|
||||
**Consegna diretta** — se l'attività ha una destinazione di canale (il `requesterOrigin`), il messaggio di completamento viene inviato direttamente a quel canale (Telegram, Discord, Slack, ecc.). Per i completamenti dei subagent, OpenClaw preserva anche l'instradamento di thread/topic associati quando disponibile e può riempire un `to` / account mancante dalla route memorizzata della sessione richiedente (`lastChannel` / `lastTo` / `lastAccountId`) prima di rinunciare alla consegna diretta.
|
||||
**Recapito diretto** — se l'attività ha una destinazione di canale (`requesterOrigin`), il messaggio di completamento viene inviato direttamente a quel canale (Telegram, Discord, Slack, ecc.). Per i completamenti dei subagenti, OpenClaw preserva anche l'instradamento di thread/topic associato quando disponibile e può riempire un valore `to` / account mancante dalla route memorizzata della sessione richiedente (`lastChannel` / `lastTo` / `lastAccountId`) prima di rinunciare al recapito diretto.
|
||||
|
||||
**Consegna in coda alla sessione** — se la consegna diretta fallisce o non è impostata alcuna origine, l'aggiornamento viene messo in coda come evento di sistema nella sessione del richiedente e compare al prossimo heartbeat.
|
||||
**Recapito in coda alla sessione** — se il recapito diretto fallisce o non è impostata alcuna origine, l'aggiornamento viene accodato come evento di sistema nella sessione del richiedente e appare al heartbeat successivo.
|
||||
|
||||
<Tip>
|
||||
Il completamento dell'attività attiva un risveglio heartbeat immediato, così puoi vedere rapidamente il risultato: non devi aspettare il prossimo tick heartbeat pianificato.
|
||||
Il completamento dell'attività attiva un risveglio heartbeat immediato, così vedi rapidamente il risultato — non devi aspettare il successivo tick heartbeat pianificato.
|
||||
</Tip>
|
||||
|
||||
Questo significa che il flusso di lavoro normale è basato su push: avvia una volta il lavoro distaccato, poi lascia che il runtime ti risvegli o ti notifichi al completamento. Interroga lo stato dell'attività solo quando hai bisogno di debug, intervento o di un audit esplicito.
|
||||
Questo significa che il normale flusso di lavoro è basato su push: avvia una sola volta il lavoro scollegato, poi lascia che il runtime ti risvegli o ti notifichi il completamento. Esegui il polling dello stato dell'attività solo quando ti serve debug, intervento o un audit esplicito.
|
||||
|
||||
### Criteri di notifica
|
||||
|
||||
Controlla quanto vuoi essere informato su ciascuna attività:
|
||||
Controlla quante informazioni ricevi per ogni attività:
|
||||
|
||||
| Criterio | Cosa viene consegnato |
|
||||
| Criterio | Cosa viene recapitato |
|
||||
| --------------------- | ------------------------------------------------------------------------- |
|
||||
| `done_only` (predefinito) | Solo lo stato terminale (succeeded, failed, ecc.) — **questo è il predefinito** |
|
||||
| `done_only` (predefinito) | Solo lo stato terminale (`succeeded`, `failed`, ecc.) — **questo è il valore predefinito** |
|
||||
| `state_changes` | Ogni transizione di stato e aggiornamento di avanzamento |
|
||||
| `silent` | Nulla |
|
||||
|
||||
Modifica il criterio mentre un'attività è in esecuzione:
|
||||
Cambia il criterio mentre un'attività è in esecuzione:
|
||||
|
||||
```bash
|
||||
openclaw tasks notify <lookup> state_changes
|
||||
@ -165,7 +165,7 @@ openclaw tasks notify <lookup> state_changes
|
||||
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
|
||||
```
|
||||
|
||||
Colonne di output: ID attività, Tipo, Stato, Consegna, ID esecuzione, Sessione figlia, Riepilogo.
|
||||
Colonne di output: ID attività, tipo, stato, recapito, Run ID, sessione figlia, riepilogo.
|
||||
|
||||
### `tasks show`
|
||||
|
||||
@ -173,7 +173,7 @@ Colonne di output: ID attività, Tipo, Stato, Consegna, ID esecuzione, Sessione
|
||||
openclaw tasks show <lookup>
|
||||
```
|
||||
|
||||
Il token di ricerca accetta un ID attività, un ID esecuzione o una chiave sessione. Mostra il record completo, inclusi tempi, stato di consegna, errore e riepilogo terminale.
|
||||
Il token di ricerca accetta un ID attività, un run ID o una chiave sessione. Mostra il record completo, inclusi tempi, stato del recapito, errore e riepilogo terminale.
|
||||
|
||||
### `tasks cancel`
|
||||
|
||||
@ -181,7 +181,7 @@ Il token di ricerca accetta un ID attività, un ID esecuzione o una chiave sessi
|
||||
openclaw tasks cancel <lookup>
|
||||
```
|
||||
|
||||
Per le attività ACP e subagent, questo termina la sessione figlia. Lo stato passa a `cancelled` e viene inviata una notifica di consegna.
|
||||
Per le attività ACP e dei subagenti, questo termina la sessione figlia. Per le attività tracciate dalla CLI, l'annullamento viene registrato nel registro delle attività (non esiste un handle di runtime figlio separato). Lo stato passa a `cancelled` e, se applicabile, viene inviata una notifica di recapito.
|
||||
|
||||
### `tasks notify`
|
||||
|
||||
@ -197,14 +197,14 @@ openclaw tasks audit [--json]
|
||||
|
||||
Evidenzia problemi operativi. I risultati compaiono anche in `openclaw status` quando vengono rilevati problemi.
|
||||
|
||||
| Risultato | Gravità | Trigger |
|
||||
| -------------------------- | ------- | ----------------------------------------------------- |
|
||||
| `stale_queued` | warn | In coda da più di 10 minuti |
|
||||
| `stale_running` | error | In esecuzione da più di 30 minuti |
|
||||
| `lost` | error | La proprietà dell'attività supportata dal runtime è scomparsa |
|
||||
| `delivery_failed` | warn | La consegna è fallita e il criterio di notifica non è `silent` |
|
||||
| `missing_cleanup` | warn | Attività terminale senza timestamp di pulizia |
|
||||
| `inconsistent_timestamps` | warn | Violazione della timeline (ad esempio terminata prima di iniziare) |
|
||||
| Risultato | Gravità | Trigger |
|
||||
| -------------------------- | ------- | ---------------------------------------------------- |
|
||||
| `stale_queued` | warn | In coda da più di 10 minuti |
|
||||
| `stale_running` | error | In esecuzione da più di 30 minuti |
|
||||
| `lost` | error | La proprietà del task supportata dal runtime è scomparsa |
|
||||
| `delivery_failed` | warn | Il recapito è fallito e il criterio di notifica non è `silent` |
|
||||
| `missing_cleanup` | warn | Attività terminale senza timestamp di pulizia |
|
||||
| `inconsistent_timestamps` | warn | Violazione della timeline (ad esempio, terminata prima di iniziare) |
|
||||
|
||||
### `tasks maintenance`
|
||||
|
||||
@ -213,21 +213,21 @@ openclaw tasks maintenance [--json]
|
||||
openclaw tasks maintenance --apply [--json]
|
||||
```
|
||||
|
||||
Usa questo comando per visualizzare in anteprima o applicare riconciliazione, marcatura della pulizia ed eliminazione per le attività e lo stato di Task Flow.
|
||||
Usa questo comando per vedere in anteprima o applicare riconciliazione, marcatura della pulizia ed eliminazione per le attività e lo stato di Task Flow.
|
||||
|
||||
La riconciliazione dipende dal runtime:
|
||||
|
||||
- Le attività ACP/subagent controllano la sessione figlia di supporto.
|
||||
- Le attività cron controllano se il runtime cron possiede ancora il job.
|
||||
- Le attività CLI supportate dalla chat controllano il relativo contesto di esecuzione live, non solo la riga della sessione chat.
|
||||
- Le attività ACP/subagenti controllano la sessione figlia di supporto.
|
||||
- Le attività cron controllano se il runtime cron possiede ancora il processo.
|
||||
- Le attività CLI supportate dalla chat controllano il contesto di esecuzione live proprietario, non solo la riga della sessione chat.
|
||||
|
||||
Anche la pulizia del completamento dipende dal runtime:
|
||||
Anche la pulizia al completamento dipende dal runtime:
|
||||
|
||||
- Il completamento dei subagent chiude, nei limiti del possibile, le schede/processi del browser tracciati per la sessione figlia prima che prosegua la pulizia dell'annuncio.
|
||||
- Il completamento cron isolato chiude, nei limiti del possibile, le schede/processi del browser tracciati per la sessione cron prima che l'esecuzione venga completamente smantellata.
|
||||
- La consegna cron isolata attende, quando necessario, il follow-up dei subagent discendenti e sopprime il testo di conferma del parent ormai obsoleto invece di annunciarlo.
|
||||
- La consegna del completamento dei subagent preferisce il testo visibile più recente dell'assistente; se è vuoto ripiega sul testo più recente sanitizzato di tool/toolResult, e le esecuzioni di sole chiamate tool terminate per timeout possono essere ridotte a un breve riepilogo di avanzamento parziale.
|
||||
- Gli errori di pulizia non mascherano il vero esito dell'attività.
|
||||
- Il completamento dei subagenti chiude, per quanto possibile, le schede/processi del browser tracciati per la sessione figlia prima che continui la pulizia dell'annuncio.
|
||||
- Il completamento cron isolato chiude, per quanto possibile, le schede/processi del browser tracciati per la sessione cron prima che l'esecuzione venga completamente smantellata.
|
||||
- Il recapito cron isolato attende il follow-up del subagente discendente quando necessario e sopprime il testo di conferma del padre ormai obsoleto invece di annunciarlo.
|
||||
- Il recapito del completamento dei subagenti preferisce l'ultimo testo visibile dell'assistente; se è vuoto, ripiega sull'ultimo testo `tool`/`toolResult` sanificato, e le esecuzioni basate solo su chiamate di strumenti andate in timeout possono ridursi a un breve riepilogo del progresso parziale.
|
||||
- I fallimenti della pulizia non mascherano il reale esito dell'attività.
|
||||
|
||||
### `tasks flow list|show|cancel`
|
||||
|
||||
@ -237,21 +237,21 @@ openclaw tasks flow show <lookup> [--json]
|
||||
openclaw tasks flow cancel <lookup>
|
||||
```
|
||||
|
||||
Usa questi comandi quando ciò che ti interessa è il Task Flow di orchestrazione piuttosto che un singolo record di attività in background.
|
||||
Usa questi comandi quando l'elemento che ti interessa è il Task Flow di orchestrazione piuttosto che un singolo record di attività in background.
|
||||
|
||||
## Bacheca attività della chat (`/tasks`)
|
||||
## Bacheca attività chat (`/tasks`)
|
||||
|
||||
Usa `/tasks` in qualsiasi sessione chat per vedere le attività in background collegate a quella sessione. La bacheca mostra
|
||||
attività attive e completate di recente con runtime, stato, tempi e dettagli su avanzamento o errore.
|
||||
attività attive e completate di recente con runtime, stato, tempi e dettagli di avanzamento o errore.
|
||||
|
||||
Quando la sessione corrente non ha attività collegate visibili, `/tasks` ripiega sui conteggi attività locali dell'agent
|
||||
così ottieni comunque una panoramica senza esporre dettagli di altre sessioni.
|
||||
Quando la sessione corrente non ha attività collegate visibili, `/tasks` ripiega sui conteggi delle attività locali dell'agente
|
||||
così hai comunque una panoramica senza esporre dettagli di altre sessioni.
|
||||
|
||||
Per il registro completo dell'operatore, usa la CLI: `openclaw tasks list`.
|
||||
Per il registro operativo completo, usa la CLI: `openclaw tasks list`.
|
||||
|
||||
## Integrazione stato (pressione attività)
|
||||
## Integrazione dello stato (pressione delle attività)
|
||||
|
||||
`openclaw status` include un riepilogo immediato delle attività:
|
||||
`openclaw status` include un riepilogo delle attività immediatamente consultabile:
|
||||
|
||||
```
|
||||
Tasks: 3 queued · 2 running · 1 issues
|
||||
@ -259,16 +259,17 @@ Tasks: 3 queued · 2 running · 1 issues
|
||||
|
||||
Il riepilogo riporta:
|
||||
|
||||
- **active** — conteggio di `queued` + `running`
|
||||
- **failures** — conteggio di `failed` + `timed_out` + `lost`
|
||||
- **byRuntime** — ripartizione per `acp`, `subagent`, `cron`, `cli`
|
||||
- **active** — numero di `queued` + `running`
|
||||
- **failures** — numero di `failed` + `timed_out` + `lost`
|
||||
- **byRuntime** — suddivisione per `acp`, `subagent`, `cron`, `cli`
|
||||
|
||||
Sia `/status` sia lo strumento `session_status` usano uno snapshot delle attività che tiene conto della pulizia: si dà priorità alle attività attive, le righe completate obsolete vengono nascoste e i guasti recenti emergono solo quando non rimane lavoro attivo.
|
||||
Questo mantiene la scheda di stato concentrata su ciò che conta in questo momento.
|
||||
Sia `/status` sia lo strumento `session_status` usano uno snapshot delle attività consapevole della pulizia: vengono privilegiate le attività attive,
|
||||
le righe completate obsolete vengono nascoste e gli errori recenti emergono solo quando non resta alcun lavoro attivo.
|
||||
In questo modo la scheda di stato resta focalizzata su ciò che conta in questo momento.
|
||||
|
||||
## Archiviazione e manutenzione
|
||||
|
||||
### Dove si trovano le attività
|
||||
### Dove risiedono le attività
|
||||
|
||||
I record delle attività vengono mantenuti in SQLite in:
|
||||
|
||||
@ -276,50 +277,50 @@ I record delle attività vengono mantenuti in SQLite in:
|
||||
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
|
||||
```
|
||||
|
||||
Il registro viene caricato in memoria all'avvio del gateway e sincronizza le scritture su SQLite per garantire la durabilità tra i riavvii.
|
||||
Il registro viene caricato in memoria all'avvio del gateway e sincronizza le scritture su SQLite per garantire la persistenza attraverso i riavvii.
|
||||
|
||||
### Manutenzione automatica
|
||||
|
||||
Uno sweeper viene eseguito ogni **60 secondi** e gestisce tre aspetti:
|
||||
Un processo di sweep viene eseguito ogni **60 secondi** e gestisce tre aspetti:
|
||||
|
||||
1. **Riconciliazione** — controlla se le attività attive hanno ancora un supporto runtime autorevole. Le attività ACP/subagent usano lo stato della sessione figlia, le attività cron usano la proprietà del job attivo e le attività CLI supportate dalla chat usano il relativo contesto di esecuzione. Se questo stato di supporto manca per più di 5 minuti, l'attività viene contrassegnata come `lost`.
|
||||
2. **Marcatura della pulizia** — imposta un timestamp `cleanupAfter` sulle attività terminali (`endedAt + 7 days`).
|
||||
3. **Eliminazione** — cancella i record oltre la data `cleanupAfter`.
|
||||
1. **Riconciliazione** — verifica se le attività attive hanno ancora un supporto autorevole nel runtime. Le attività ACP/subagenti usano lo stato della sessione figlia, le attività cron usano la proprietà del job attivo e le attività CLI supportate dalla chat usano il contesto di esecuzione proprietario. Se quello stato di supporto manca per più di 5 minuti, l'attività viene contrassegnata come `lost`.
|
||||
2. **Marcatura della pulizia** — imposta un timestamp `cleanupAfter` sulle attività terminali (`endedAt` + 7 giorni).
|
||||
3. **Eliminazione** — elimina i record che hanno superato la data `cleanupAfter`.
|
||||
|
||||
**Conservazione**: i record delle attività terminali vengono mantenuti per **7 giorni**, poi eliminati automaticamente. Non è richiesta alcuna configurazione.
|
||||
**Conservazione**: i record delle attività terminali vengono mantenuti per **7 giorni**, poi eliminati automaticamente. Non è necessaria alcuna configurazione.
|
||||
|
||||
## Come le attività si relazionano ad altri sistemi
|
||||
|
||||
### Attività e Task Flow
|
||||
|
||||
[Task Flow](/it/automation/taskflow) è il livello di orchestrazione dei flussi sopra le attività in background. Un singolo flusso può coordinare più attività nel corso della sua durata usando modalità di sincronizzazione gestite o mirror. Usa `openclaw tasks` per ispezionare i singoli record attività e `openclaw tasks flow` per ispezionare il flusso di orchestrazione.
|
||||
[Task Flow](/it/automation/taskflow) è il livello di orchestrazione dei flussi sopra le attività in background. Un singolo flusso può coordinare più attività nel corso del suo ciclo di vita usando modalità di sincronizzazione gestite o mirror. Usa `openclaw tasks` per ispezionare i singoli record delle attività e `openclaw tasks flow` per ispezionare il flusso di orchestrazione.
|
||||
|
||||
Consulta [Task Flow](/it/automation/taskflow) per i dettagli.
|
||||
Vedi [Task Flow](/it/automation/taskflow) per i dettagli.
|
||||
|
||||
### Attività e cron
|
||||
|
||||
Una **definizione** di job cron si trova in `~/.openclaw/cron/jobs.json`. **Ogni** esecuzione cron crea un record attività, sia nella sessione principale sia in isolamento. Le attività cron della sessione principale usano per impostazione predefinita il criterio di notifica `silent`, così monitorano senza generare notifiche.
|
||||
Una **definizione** di job cron risiede in `~/.openclaw/cron/jobs.json`. **Ogni** esecuzione cron crea un record attività — sia per la sessione principale sia per quelle isolate. Le attività cron della sessione principale usano per impostazione predefinita il criterio di notifica `silent`, così vengono tracciate senza generare notifiche.
|
||||
|
||||
Consulta [Processi cron](/it/automation/cron-jobs).
|
||||
Vedi [Cron Jobs](/it/automation/cron-jobs).
|
||||
|
||||
### Attività e heartbeat
|
||||
|
||||
Le esecuzioni heartbeat sono turni della sessione principale: non creano record attività. Quando un'attività viene completata, può attivare un risveglio heartbeat così puoi vedere rapidamente il risultato.
|
||||
Le esecuzioni heartbeat sono turni della sessione principale — non creano record attività. Quando un'attività termina, può attivare un risveglio heartbeat così vedi il risultato rapidamente.
|
||||
|
||||
Consulta [Heartbeat](/it/gateway/heartbeat).
|
||||
Vedi [Heartbeat](/it/gateway/heartbeat).
|
||||
|
||||
### Attività e sessioni
|
||||
|
||||
Un'attività può fare riferimento a una `childSessionKey` (dove viene eseguito il lavoro) e a una `requesterSessionKey` (chi l'ha avviata). Le sessioni sono il contesto della conversazione; le attività sono il monitoraggio dell'attività sopra di esse.
|
||||
Un'attività può fare riferimento a una `childSessionKey` (dove viene eseguito il lavoro) e a una `requesterSessionKey` (chi l'ha avviata). Le sessioni sono il contesto della conversazione; le attività sono il tracciamento dell'attività costruito sopra quel contesto.
|
||||
|
||||
### Attività ed esecuzioni agent
|
||||
### Attività ed esecuzioni dell'agente
|
||||
|
||||
Il `runId` di un'attività collega l'esecuzione agent che sta svolgendo il lavoro. Gli eventi del ciclo di vita dell'agent (inizio, fine, errore) aggiornano automaticamente lo stato dell'attività: non devi gestire manualmente il ciclo di vita.
|
||||
Il `runId` di un'attività collega l'esecuzione dell'agente che sta svolgendo il lavoro. Gli eventi del ciclo di vita dell'agente (avvio, fine, errore) aggiornano automaticamente lo stato dell'attività — non devi gestire manualmente il ciclo di vita.
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Automazione e attività](/it/automation) — tutti i meccanismi di automazione in sintesi
|
||||
- [Automation & Tasks](/it/automation) — tutti i meccanismi di automazione in sintesi
|
||||
- [Task Flow](/it/automation/taskflow) — orchestrazione dei flussi sopra le attività
|
||||
- [Attività pianificate](/it/automation/cron-jobs) — pianificazione del lavoro in background
|
||||
- [Scheduled Tasks](/it/automation/cron-jobs) — pianificazione del lavoro in background
|
||||
- [Heartbeat](/it/gateway/heartbeat) — turni periodici della sessione principale
|
||||
- [CLI: Tasks](/cli/index#tasks) — riferimento ai comandi CLI
|
||||
- [CLI: Tasks](/cli/index#tasks) — riferimento dei comandi CLI
|
||||
|
||||
612
docs/it/concepts/active-memory.md
Normal file
612
docs/it/concepts/active-memory.md
Normal file
@ -0,0 +1,612 @@
|
||||
---
|
||||
read_when:
|
||||
- Vuoi capire a cosa serve la memoria attiva
|
||||
- Vuoi attivare la memoria attiva per un agente conversazionale
|
||||
- Vuoi regolare il comportamento della memoria attiva senza abilitarla ovunque
|
||||
summary: Un sotto-agente di memoria bloccante di proprietà del plugin che inserisce la memoria pertinente nelle sessioni di chat interattive
|
||||
title: Memoria attiva
|
||||
x-i18n:
|
||||
generated_at: "2026-04-10T08:13:33Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6a51437df4ae4d9d57764601dfcfcdadb269e2895bf49dc82b9f496c1b3cb341
|
||||
source_path: concepts/active-memory.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Memoria attiva
|
||||
|
||||
La memoria attiva è un sotto-agente di memoria bloccante opzionale di proprietà del plugin che viene eseguito
|
||||
prima della risposta principale per le sessioni conversazionali idonee.
|
||||
|
||||
Esiste perché la maggior parte dei sistemi di memoria è capace ma reattiva. Si affida
|
||||
all'agente principale per decidere quando cercare nella memoria, oppure all'utente per dire cose
|
||||
come "ricorda questo" o "cerca nella memoria". A quel punto, il momento in cui la memoria avrebbe
|
||||
reso la risposta naturale è già passato.
|
||||
|
||||
La memoria attiva offre al sistema una possibilità limitata di far emergere memoria pertinente
|
||||
prima che venga generata la risposta principale.
|
||||
|
||||
## Incolla questo nel tuo agente
|
||||
|
||||
Incolla questo nel tuo agente se vuoi abilitare la memoria attiva con una
|
||||
configurazione autonoma e sicura per impostazione predefinita:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
enabled: true,
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
persistTranscripts: false,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Questo attiva il plugin per l'agente `main`, lo mantiene limitato per impostazione predefinita alle
|
||||
sessioni in stile messaggio diretto, gli consente di ereditare prima il modello della sessione corrente e
|
||||
consente comunque il fallback remoto integrato se non è disponibile alcun modello esplicito o ereditato.
|
||||
|
||||
Dopo, riavvia il gateway:
|
||||
|
||||
```bash
|
||||
node scripts/run-node.mjs gateway --profile dev
|
||||
```
|
||||
|
||||
Per ispezionarlo in tempo reale in una conversazione:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
```
|
||||
|
||||
## Attiva la memoria attiva
|
||||
|
||||
La configurazione più sicura è:
|
||||
|
||||
1. abilitare il plugin
|
||||
2. scegliere come target un agente conversazionale
|
||||
3. mantenere il logging attivo solo durante la regolazione
|
||||
|
||||
Inizia con questo in `openclaw.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
allowedChatTypes: ["direct"],
|
||||
modelFallbackPolicy: "default-remote",
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
persistTranscripts: false,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Poi riavvia il gateway:
|
||||
|
||||
```bash
|
||||
node scripts/run-node.mjs gateway --profile dev
|
||||
```
|
||||
|
||||
Cosa significa:
|
||||
|
||||
- `plugins.entries.active-memory.enabled: true` attiva il plugin
|
||||
- `config.agents: ["main"]` abilita la memoria attiva solo per l'agente `main`
|
||||
- `config.allowedChatTypes: ["direct"]` mantiene la memoria attiva abilitata solo per impostazione predefinita per le sessioni in stile messaggio diretto
|
||||
- se `config.model` non è impostato, la memoria attiva eredita prima il modello della sessione corrente
|
||||
- `config.modelFallbackPolicy: "default-remote"` mantiene come impostazione predefinita il fallback remoto integrato quando non è disponibile alcun modello esplicito o ereditato
|
||||
- `config.promptStyle: "balanced"` usa lo stile di prompt predefinito per uso generale per la modalità `recent`
|
||||
- la memoria attiva viene comunque eseguita solo su sessioni di chat persistenti interattive idonee
|
||||
|
||||
## Come vederla
|
||||
|
||||
La memoria attiva inserisce contesto di sistema nascosto per il modello. Non espone
|
||||
tag raw `<active_memory_plugin>...</active_memory_plugin>` al client.
|
||||
|
||||
## Interruttore della sessione
|
||||
|
||||
Usa il comando del plugin quando vuoi mettere in pausa o riprendere la memoria attiva per la
|
||||
sessione di chat corrente senza modificare la configurazione:
|
||||
|
||||
```text
|
||||
/active-memory status
|
||||
/active-memory off
|
||||
/active-memory on
|
||||
```
|
||||
|
||||
Questo è limitato alla sessione. Non modifica
|
||||
`plugins.entries.active-memory.enabled`, il targeting dell'agente o altre
|
||||
configurazioni globali.
|
||||
|
||||
Se vuoi che il comando scriva la configurazione e metta in pausa o riprenda la memoria attiva per
|
||||
tutte le sessioni, usa la forma globale esplicita:
|
||||
|
||||
```text
|
||||
/active-memory status --global
|
||||
/active-memory off --global
|
||||
/active-memory on --global
|
||||
```
|
||||
|
||||
La forma globale scrive `plugins.entries.active-memory.config.enabled`. Lascia
|
||||
`plugins.entries.active-memory.enabled` attivo in modo che il comando resti disponibile per
|
||||
riattivare la memoria attiva in seguito.
|
||||
|
||||
Se vuoi vedere cosa sta facendo la memoria attiva in una sessione in tempo reale, attiva la modalità
|
||||
verbose per quella sessione:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
```
|
||||
|
||||
Con verbose abilitato, OpenClaw può mostrare:
|
||||
|
||||
- una riga di stato della memoria attiva come `Active Memory: ok 842ms recent 34 chars`
|
||||
- un riepilogo di debug leggibile come `Active Memory Debug: Lemon pepper wings with blue cheese.`
|
||||
|
||||
Queste righe derivano dallo stesso passaggio della memoria attiva che alimenta il contesto di
|
||||
sistema nascosto, ma sono formattate per le persone invece di esporre markup raw del prompt.
|
||||
|
||||
Per impostazione predefinita, la trascrizione del sotto-agente di memoria bloccante è temporanea e viene eliminata
|
||||
dopo il completamento dell'esecuzione.
|
||||
|
||||
Flusso di esempio:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
quali ali dovrei ordinare?
|
||||
```
|
||||
|
||||
Forma prevista della risposta visibile:
|
||||
|
||||
```text
|
||||
...normale risposta dell'assistente...
|
||||
|
||||
🧩 Active Memory: ok 842ms recent 34 chars
|
||||
🔎 Active Memory Debug: Lemon pepper wings with blue cheese.
|
||||
```
|
||||
|
||||
## Quando viene eseguita
|
||||
|
||||
La memoria attiva usa due criteri:
|
||||
|
||||
1. **Adesione esplicita nella configurazione**
|
||||
Il plugin deve essere abilitato e l'id dell'agente corrente deve comparire in
|
||||
`plugins.entries.active-memory.config.agents`.
|
||||
2. **Idoneità rigorosa in fase di esecuzione**
|
||||
Anche quando è abilitata e selezionata, la memoria attiva viene eseguita solo per
|
||||
sessioni di chat persistenti interattive idonee.
|
||||
|
||||
La regola effettiva è:
|
||||
|
||||
```text
|
||||
plugin abilitato
|
||||
+
|
||||
id agente selezionato
|
||||
+
|
||||
tipo di chat consentito
|
||||
+
|
||||
sessione di chat persistente interattiva idonea
|
||||
=
|
||||
la memoria attiva viene eseguita
|
||||
```
|
||||
|
||||
Se uno qualsiasi di questi fallisce, la memoria attiva non viene eseguita.
|
||||
|
||||
## Tipi di sessione
|
||||
|
||||
`config.allowedChatTypes` controlla quali tipi di conversazioni possono eseguire la Memoria
|
||||
attiva.
|
||||
|
||||
Il valore predefinito è:
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
Questo significa che la Memoria attiva viene eseguita per impostazione predefinita nelle sessioni in stile messaggio diretto, ma
|
||||
non nelle sessioni di gruppo o di canale a meno che tu non le abiliti esplicitamente.
|
||||
|
||||
Esempi:
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct"]
|
||||
```
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct", "group"]
|
||||
```
|
||||
|
||||
```json5
|
||||
allowedChatTypes: ["direct", "group", "channel"]
|
||||
```
|
||||
|
||||
## Dove viene eseguita
|
||||
|
||||
La memoria attiva è una funzionalità di arricchimento conversazionale, non una
|
||||
funzionalità di inferenza valida per tutta la piattaforma.
|
||||
|
||||
| Superficie | Esegue la memoria attiva? |
|
||||
| ------------------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| Sessioni persistenti di chat in Control UI / web chat | Sì, se il plugin è abilitato e l'agente è selezionato |
|
||||
| Altre sessioni di canale interattive sullo stesso percorso di chat persistente | Sì, se il plugin è abilitato e l'agente è selezionato |
|
||||
| Esecuzioni headless one-shot | No |
|
||||
| Esecuzioni heartbeat/background | No |
|
||||
| Percorsi interni generici `agent-command` | No |
|
||||
| Esecuzione di sotto-agenti/helper interni | No |
|
||||
|
||||
## Perché usarla
|
||||
|
||||
Usa la memoria attiva quando:
|
||||
|
||||
- la sessione è persistente e rivolta all'utente
|
||||
- l'agente ha una memoria a lungo termine significativa da cercare
|
||||
- continuità e personalizzazione contano più del puro determinismo del prompt
|
||||
|
||||
Funziona particolarmente bene per:
|
||||
|
||||
- preferenze stabili
|
||||
- abitudini ricorrenti
|
||||
- contesto utente a lungo termine che dovrebbe emergere in modo naturale
|
||||
|
||||
È poco adatta per:
|
||||
|
||||
- automazione
|
||||
- worker interni
|
||||
- attività API one-shot
|
||||
- contesti in cui una personalizzazione nascosta sarebbe sorprendente
|
||||
|
||||
## Come funziona
|
||||
|
||||
La forma di esecuzione è:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U["Messaggio utente"] --> Q["Crea query di memoria"]
|
||||
Q --> R["Sotto-agente di memoria bloccante della memoria attiva"]
|
||||
R -->|NONE or empty| M["Risposta principale"]
|
||||
R -->|relevant summary| I["Aggiungi contesto di sistema nascosto active_memory_plugin"]
|
||||
I --> M["Risposta principale"]
|
||||
```
|
||||
|
||||
Il sotto-agente di memoria bloccante può usare solo:
|
||||
|
||||
- `memory_search`
|
||||
- `memory_get`
|
||||
|
||||
Se la connessione è debole, dovrebbe restituire `NONE`.
|
||||
|
||||
## Modalità di query
|
||||
|
||||
`config.queryMode` controlla quanta parte della conversazione vede il sotto-agente di memoria bloccante.
|
||||
|
||||
## Stili di prompt
|
||||
|
||||
`config.promptStyle` controlla quanto il sotto-agente di memoria bloccante sia
|
||||
propenso o rigoroso quando decide se restituire memoria.
|
||||
|
||||
Stili disponibili:
|
||||
|
||||
- `balanced`: valore predefinito per uso generale per la modalità `recent`
|
||||
- `strict`: il meno propenso; ideale quando vuoi pochissima influenza dal contesto vicino
|
||||
- `contextual`: il più favorevole alla continuità; ideale quando la cronologia della conversazione dovrebbe contare di più
|
||||
- `recall-heavy`: più disposto a far emergere memoria anche con corrispondenze meno forti ma comunque plausibili
|
||||
- `precision-heavy`: preferisce in modo aggressivo `NONE` a meno che la corrispondenza non sia ovvia
|
||||
- `preference-only`: ottimizzato per preferiti, abitudini, routine, gusti e fatti personali ricorrenti
|
||||
|
||||
Mappatura predefinita quando `config.promptStyle` non è impostato:
|
||||
|
||||
```text
|
||||
message -> strict
|
||||
recent -> balanced
|
||||
full -> contextual
|
||||
```
|
||||
|
||||
Se imposti `config.promptStyle` esplicitamente, quell'override prevale.
|
||||
|
||||
Esempio:
|
||||
|
||||
```json5
|
||||
promptStyle: "preference-only"
|
||||
```
|
||||
|
||||
## Criterio di fallback del modello
|
||||
|
||||
Se `config.model` non è impostato, la Memoria attiva prova a risolvere un modello in questo ordine:
|
||||
|
||||
```text
|
||||
modello esplicito del plugin
|
||||
-> modello della sessione corrente
|
||||
-> modello primario dell'agente
|
||||
-> fallback remoto integrato opzionale
|
||||
```
|
||||
|
||||
`config.modelFallbackPolicy` controlla l'ultimo passaggio.
|
||||
|
||||
Valore predefinito:
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "default-remote"
|
||||
```
|
||||
|
||||
Altra opzione:
|
||||
|
||||
```json5
|
||||
modelFallbackPolicy: "resolved-only"
|
||||
```
|
||||
|
||||
Usa `resolved-only` se vuoi che la Memoria attiva salti il recupero invece di usare
|
||||
il valore predefinito remoto integrato quando non è disponibile alcun modello esplicito o
|
||||
ereditato.
|
||||
|
||||
## Meccanismi di uscita avanzati
|
||||
|
||||
Queste opzioni intenzionalmente non fanno parte della configurazione consigliata.
|
||||
|
||||
`config.thinking` può sostituire il livello di thinking del sotto-agente di memoria bloccante:
|
||||
|
||||
```json5
|
||||
thinking: "medium"
|
||||
```
|
||||
|
||||
Valore predefinito:
|
||||
|
||||
```json5
|
||||
thinking: "off"
|
||||
```
|
||||
|
||||
Non abilitarlo per impostazione predefinita. La Memoria attiva viene eseguita nel percorso della risposta, quindi tempo di
|
||||
thinking aggiuntivo aumenta direttamente la latenza visibile all'utente.
|
||||
|
||||
`config.promptAppend` aggiunge istruzioni supplementari per l'operatore dopo il prompt predefinito della Memoria
|
||||
attiva e prima del contesto della conversazione:
|
||||
|
||||
```json5
|
||||
promptAppend: "Dai priorità alle preferenze stabili a lungo termine rispetto agli eventi una tantum."
|
||||
```
|
||||
|
||||
`config.promptOverride` sostituisce il prompt predefinito della Memoria attiva. OpenClaw
|
||||
continua comunque ad aggiungere dopo il contesto della conversazione:
|
||||
|
||||
```json5
|
||||
promptOverride: "Sei un agente di ricerca della memoria. Restituisci NONE o un fatto utente compatto."
|
||||
```
|
||||
|
||||
La personalizzazione del prompt non è consigliata a meno che tu non stia testando deliberatamente un
|
||||
contratto di recupero diverso. Il prompt predefinito è regolato per restituire `NONE`
|
||||
oppure un contesto compatto di fatti utente per il modello principale.
|
||||
|
||||
### `message`
|
||||
|
||||
Viene inviato solo l'ultimo messaggio dell'utente.
|
||||
|
||||
```text
|
||||
Solo l'ultimo messaggio dell'utente
|
||||
```
|
||||
|
||||
Usalo quando:
|
||||
|
||||
- vuoi il comportamento più veloce
|
||||
- vuoi il bias più forte verso il recupero di preferenze stabili
|
||||
- i turni successivi non hanno bisogno del contesto conversazionale
|
||||
|
||||
Timeout consigliato:
|
||||
|
||||
- inizia intorno a `3000` a `5000` ms
|
||||
|
||||
### `recent`
|
||||
|
||||
Vengono inviati l'ultimo messaggio dell'utente più una piccola coda conversazionale recente.
|
||||
|
||||
```text
|
||||
Coda recente della conversazione:
|
||||
user: ...
|
||||
assistant: ...
|
||||
user: ...
|
||||
|
||||
Ultimo messaggio dell'utente:
|
||||
...
|
||||
```
|
||||
|
||||
Usalo quando:
|
||||
|
||||
- vuoi un miglior equilibrio tra velocità e ancoraggio conversazionale
|
||||
- le domande di follow-up spesso dipendono dagli ultimi pochi turni
|
||||
|
||||
Timeout consigliato:
|
||||
|
||||
- inizia intorno a `15000` ms
|
||||
|
||||
### `full`
|
||||
|
||||
L'intera conversazione viene inviata al sotto-agente di memoria bloccante.
|
||||
|
||||
```text
|
||||
Contesto completo della conversazione:
|
||||
user: ...
|
||||
assistant: ...
|
||||
user: ...
|
||||
...
|
||||
```
|
||||
|
||||
Usalo quando:
|
||||
|
||||
- la massima qualità del recupero conta più della latenza
|
||||
- la conversazione contiene impostazioni importanti molto indietro nel thread
|
||||
|
||||
Timeout consigliato:
|
||||
|
||||
- aumentalo in modo significativo rispetto a `message` o `recent`
|
||||
- inizia intorno a `15000` ms o più, a seconda della dimensione del thread
|
||||
|
||||
In generale, il timeout dovrebbe aumentare con la dimensione del contesto:
|
||||
|
||||
```text
|
||||
message < recent < full
|
||||
```
|
||||
|
||||
## Persistenza della trascrizione
|
||||
|
||||
Le esecuzioni del sotto-agente di memoria bloccante della memoria attiva creano una vera trascrizione `session.jsonl` durante la chiamata del sotto-agente di memoria bloccante.
|
||||
|
||||
Per impostazione predefinita, quella trascrizione è temporanea:
|
||||
|
||||
- viene scritta in una directory temporanea
|
||||
- viene usata solo per l'esecuzione del sotto-agente di memoria bloccante
|
||||
- viene eliminata immediatamente dopo la fine dell'esecuzione
|
||||
|
||||
Se vuoi conservare su disco quelle trascrizioni del sotto-agente di memoria bloccante per debug o
|
||||
ispezione, attiva esplicitamente la persistenza:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
persistTranscripts: true,
|
||||
transcriptDir: "active-memory",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Quando è abilitata, la memoria attiva archivia le trascrizioni in una directory separata sotto la
|
||||
cartella delle sessioni dell'agente di destinazione, non nel percorso principale della trascrizione
|
||||
della conversazione utente.
|
||||
|
||||
Il layout predefinito è, concettualmente:
|
||||
|
||||
```text
|
||||
agents/<agent>/sessions/active-memory/<blocking-memory-sub-agent-session-id>.jsonl
|
||||
```
|
||||
|
||||
Puoi modificare la sottodirectory relativa con `config.transcriptDir`.
|
||||
|
||||
Usalo con attenzione:
|
||||
|
||||
- le trascrizioni del sotto-agente di memoria bloccante possono accumularsi rapidamente nelle sessioni molto attive
|
||||
- la modalità di query `full` può duplicare molto contesto conversazionale
|
||||
- queste trascrizioni contengono contesto nascosto del prompt e memorie recuperate
|
||||
|
||||
## Configurazione
|
||||
|
||||
Tutta la configurazione della memoria attiva si trova in:
|
||||
|
||||
```text
|
||||
plugins.entries.active-memory
|
||||
```
|
||||
|
||||
I campi più importanti sono:
|
||||
|
||||
| Chiave | Tipo | Significato |
|
||||
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
|
||||
| `enabled` | `boolean` | Abilita il plugin stesso |
|
||||
| `config.agents` | `string[]` | ID agente che possono usare la memoria attiva |
|
||||
| `config.model` | `string` | Riferimento facoltativo al modello del sotto-agente di memoria bloccante; se non è impostato, la memoria attiva usa il modello della sessione corrente |
|
||||
| `config.queryMode` | `"message" \| "recent" \| "full"` | Controlla quanta parte della conversazione vede il sotto-agente di memoria bloccante |
|
||||
| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Controlla quanto il sotto-agente di memoria bloccante sia propenso o rigoroso nel decidere se restituire memoria |
|
||||
| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Override avanzato del thinking per il sotto-agente di memoria bloccante; valore predefinito `off` per velocità |
|
||||
| `config.promptOverride` | `string` | Sostituzione avanzata completa del prompt; non consigliata per l'uso normale |
|
||||
| `config.promptAppend` | `string` | Istruzioni supplementari avanzate aggiunte al prompt predefinito o sostituito |
|
||||
| `config.timeoutMs` | `number` | Timeout rigido per il sotto-agente di memoria bloccante |
|
||||
| `config.maxSummaryChars` | `number` | Numero massimo totale di caratteri consentiti nel riepilogo di active-memory |
|
||||
| `config.logging` | `boolean` | Emette log della memoria attiva durante la regolazione |
|
||||
| `config.persistTranscripts` | `boolean` | Mantiene su disco le trascrizioni del sotto-agente di memoria bloccante invece di eliminare i file temporanei |
|
||||
| `config.transcriptDir` | `string` | Directory relativa delle trascrizioni del sotto-agente di memoria bloccante sotto la cartella delle sessioni dell'agente |
|
||||
|
||||
Campi utili per la regolazione:
|
||||
|
||||
| Chiave | Tipo | Significato |
|
||||
| ----------------------------- | -------- | ----------------------------------------------------------------- |
|
||||
| `config.maxSummaryChars` | `number` | Numero massimo totale di caratteri consentiti nel riepilogo di active-memory |
|
||||
| `config.recentUserTurns` | `number` | Turni utente precedenti da includere quando `queryMode` è `recent` |
|
||||
| `config.recentAssistantTurns` | `number` | Turni assistente precedenti da includere quando `queryMode` è `recent` |
|
||||
| `config.recentUserChars` | `number` | Numero massimo di caratteri per turno utente recente |
|
||||
| `config.recentAssistantChars` | `number` | Numero massimo di caratteri per turno assistente recente |
|
||||
| `config.cacheTtlMs` | `number` | Riutilizzo della cache per query identiche ripetute |
|
||||
|
||||
## Configurazione consigliata
|
||||
|
||||
Inizia con `recent`.
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
entries: {
|
||||
"active-memory": {
|
||||
enabled: true,
|
||||
config: {
|
||||
agents: ["main"],
|
||||
queryMode: "recent",
|
||||
promptStyle: "balanced",
|
||||
timeoutMs: 15000,
|
||||
maxSummaryChars: 220,
|
||||
logging: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Se vuoi ispezionare il comportamento in tempo reale durante la regolazione, usa `/verbose on` nella
|
||||
sessione invece di cercare un comando di debug separato per active-memory.
|
||||
|
||||
Poi passa a:
|
||||
|
||||
- `message` se vuoi una latenza inferiore
|
||||
- `full` se decidi che il contesto aggiuntivo vale un sotto-agente di memoria bloccante più lento
|
||||
|
||||
## Debug
|
||||
|
||||
Se la memoria attiva non compare dove ti aspetti:
|
||||
|
||||
1. Conferma che il plugin sia abilitato in `plugins.entries.active-memory.enabled`.
|
||||
2. Conferma che l'ID dell'agente corrente sia elencato in `config.agents`.
|
||||
3. Conferma che il test avvenga tramite una sessione di chat persistente interattiva.
|
||||
4. Attiva `config.logging: true` e osserva i log del gateway.
|
||||
5. Verifica che la ricerca in memoria funzioni con `openclaw memory status --deep`.
|
||||
|
||||
Se i risultati di memoria sono troppo rumorosi, restringi:
|
||||
|
||||
- `maxSummaryChars`
|
||||
|
||||
Se la memoria attiva è troppo lenta:
|
||||
|
||||
- riduci `queryMode`
|
||||
- riduci `timeoutMs`
|
||||
- riduci il numero di turni recenti
|
||||
- riduci i limiti di caratteri per turno
|
||||
|
||||
## Pagine correlate
|
||||
|
||||
- [Ricerca nella memoria](/it/concepts/memory-search)
|
||||
- [Riferimento della configurazione della memoria](/it/reference/memory-config)
|
||||
- [Configurazione del Plugin SDK](/it/plugins/sdk-setup)
|
||||
@ -1,73 +1,73 @@
|
||||
---
|
||||
read_when:
|
||||
- Hai bisogno di una panoramica esatta del loop dell'agente o degli eventi del ciclo di vita
|
||||
- Hai bisogno di una guida dettagliata esatta del loop dell'agente o degli eventi del ciclo di vita
|
||||
summary: Ciclo di vita del loop dell'agente, stream e semantica di attesa
|
||||
title: Loop dell'agente
|
||||
x-i18n:
|
||||
generated_at: "2026-04-09T01:27:50Z"
|
||||
generated_at: "2026-04-10T08:13:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 32d3a73df8dabf449211a6183a70dcfd2a9b6f584dc76d0c4c9147582b2ca6a1
|
||||
source_hash: b6831a5b11e9100e49f650feca51ab44a2bef242ce1b5db2766d0b3b5c5ba729
|
||||
source_path: concepts/agent-loop.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Loop dell'agente (OpenClaw)
|
||||
|
||||
Un loop agentico è l'esecuzione completa “reale” di un agente: acquisizione → assemblaggio del contesto → inferenza del modello →
|
||||
Un loop agentico è l'esecuzione completa e “reale” di un agente: acquisizione → assemblaggio del contesto → inferenza del modello →
|
||||
esecuzione degli strumenti → risposte in streaming → persistenza. È il percorso autorevole che trasforma un messaggio
|
||||
in azioni e in una risposta finale, mantenendo coerente lo stato della sessione.
|
||||
|
||||
In OpenClaw, un loop è una singola esecuzione serializzata per sessione che emette eventi di ciclo di vita e di stream
|
||||
mentre il modello ragiona, chiama strumenti e trasmette output in streaming. Questo documento spiega come questo loop autentico
|
||||
è collegato end-to-end.
|
||||
mentre il modello elabora, chiama strumenti e trasmette l'output in streaming. Questo documento spiega come questo loop autentico è
|
||||
collegato end-to-end.
|
||||
|
||||
## Punti di ingresso
|
||||
|
||||
- RPC Gateway: `agent` e `agent.wait`.
|
||||
- Gateway RPC: `agent` e `agent.wait`.
|
||||
- CLI: comando `agent`.
|
||||
|
||||
## Come funziona (panoramica)
|
||||
|
||||
1. L'RPC `agent` valida i parametri, risolve la sessione (sessionKey/sessionId), rende persistenti i metadati della sessione, restituisce immediatamente `{ runId, acceptedAt }`.
|
||||
1. L'RPC `agent` convalida i parametri, risolve la sessione (sessionKey/sessionId), persiste i metadati della sessione e restituisce immediatamente `{ runId, acceptedAt }`.
|
||||
2. `agentCommand` esegue l'agente:
|
||||
- risolve il modello + i valori predefiniti di thinking/verbose
|
||||
- risolve i valori predefiniti di model + thinking/verbose
|
||||
- carica lo snapshot delle Skills
|
||||
- chiama `runEmbeddedPiAgent` (runtime pi-agent-core)
|
||||
- emette **fine/errore del ciclo di vita** se il loop incorporato non ne emette uno
|
||||
- chiama `runEmbeddedPiAgent` (runtime di pi-agent-core)
|
||||
- emette **lifecycle end/error** se il loop incorporato non ne emette uno
|
||||
3. `runEmbeddedPiAgent`:
|
||||
- serializza le esecuzioni tramite code per sessione e globali
|
||||
- risolve il profilo di modello + autenticazione e costruisce la sessione pi
|
||||
- si sottoscrive agli eventi pi e trasmette in streaming i delta dell'assistente/degli strumenti
|
||||
- serializza le esecuzioni tramite code per-sessione e globali
|
||||
- risolve il profilo model + auth e costruisce la sessione pi
|
||||
- si sottoscrive agli eventi pi e trasmette in streaming i delta assistant/tool
|
||||
- applica il timeout -> interrompe l'esecuzione se superato
|
||||
- restituisce payload + metadati di utilizzo
|
||||
- restituisce payload e metadati di utilizzo
|
||||
4. `subscribeEmbeddedPiSession` collega gli eventi di pi-agent-core allo stream `agent` di OpenClaw:
|
||||
- eventi degli strumenti => `stream: "tool"`
|
||||
- delta dell'assistente => `stream: "assistant"`
|
||||
- eventi del ciclo di vita => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
|
||||
5. `agent.wait` usa `waitForAgentRun`:
|
||||
- attende la **fine/errore del ciclo di vita** per `runId`
|
||||
- attende **lifecycle end/error** per `runId`
|
||||
- restituisce `{ status: ok|error|timeout, startedAt, endedAt, error? }`
|
||||
|
||||
## Accodamento + concorrenza
|
||||
|
||||
- Le esecuzioni sono serializzate per chiave di sessione (corsia della sessione) e facoltativamente tramite una corsia globale.
|
||||
- Questo evita race tra strumenti/sessione e mantiene coerente la cronologia della sessione.
|
||||
- Le esecuzioni sono serializzate per chiave di sessione (corsia di sessione) e facoltativamente tramite una corsia globale.
|
||||
- Questo previene race condition tra strumenti/sessioni e mantiene coerente la cronologia della sessione.
|
||||
- I canali di messaggistica possono scegliere modalità di coda (collect/steer/followup) che alimentano questo sistema di corsie.
|
||||
Vedi [Coda dei comandi](/it/concepts/queue).
|
||||
Vedi [Command Queue](/it/concepts/queue).
|
||||
|
||||
## Preparazione della sessione + workspace
|
||||
## Preparazione di sessione + workspace
|
||||
|
||||
- Il workspace viene risolto e creato; le esecuzioni in sandbox possono reindirizzare a una root del workspace sandbox.
|
||||
- Le Skills vengono caricate (o riutilizzate da uno snapshot) e iniettate nell'ambiente e nel prompt.
|
||||
- I file bootstrap/contesto vengono risolti e iniettati nel report del prompt di sistema.
|
||||
- Il workspace viene risolto e creato; le esecuzioni sandboxed possono reindirizzare a una radice workspace sandbox.
|
||||
- Le Skills vengono caricate (o riutilizzate da uno snapshot) e iniettate nell'env e nel prompt.
|
||||
- I file bootstrap/context vengono risolti e iniettati nel report del prompt di sistema.
|
||||
- Viene acquisito un lock di scrittura della sessione; `SessionManager` viene aperto e preparato prima dello streaming.
|
||||
|
||||
## Assemblaggio del prompt + prompt di sistema
|
||||
|
||||
- Il prompt di sistema viene costruito a partire dal prompt di base di OpenClaw, dal prompt delle Skills, dal contesto bootstrap e dagli override per esecuzione.
|
||||
- Il prompt di sistema viene costruito a partire dal prompt base di OpenClaw, dal prompt delle Skills, dal contesto bootstrap e dagli override per esecuzione.
|
||||
- Vengono applicati i limiti specifici del modello e i token di riserva per la compattazione.
|
||||
- Vedi [Prompt di sistema](/it/concepts/system-prompt) per ciò che vede il modello.
|
||||
- Vedi [System prompt](/it/concepts/system-prompt) per sapere cosa vede il modello.
|
||||
|
||||
## Punti di hook (dove puoi intercettare)
|
||||
|
||||
@ -78,46 +78,46 @@ OpenClaw ha due sistemi di hook:
|
||||
|
||||
### Hook interni (hook del Gateway)
|
||||
|
||||
- **`agent:bootstrap`**: viene eseguito durante la costruzione dei file bootstrap prima che il prompt di sistema sia finalizzato.
|
||||
- **`agent:bootstrap`**: viene eseguito durante la costruzione dei file bootstrap prima che il prompt di sistema venga finalizzato.
|
||||
Usalo per aggiungere/rimuovere file di contesto bootstrap.
|
||||
- **Hook dei comandi**: `/new`, `/reset`, `/stop` e altri eventi dei comandi (vedi la documentazione Hooks).
|
||||
- **Hook di comando**: `/new`, `/reset`, `/stop` e altri eventi di comando (vedi il documento Hooks).
|
||||
|
||||
Vedi [Hooks](/it/automation/hooks) per configurazione ed esempi.
|
||||
|
||||
### Hook plugin (ciclo di vita dell'agente + del gateway)
|
||||
### Hook plugin (ciclo di vita di agente + gateway)
|
||||
|
||||
Questi vengono eseguiti all'interno del loop dell'agente o della pipeline del gateway:
|
||||
|
||||
- **`before_model_resolve`**: viene eseguito prima della sessione (senza `messages`) per sovrascrivere in modo deterministico provider/modello prima della risoluzione del modello.
|
||||
- **`before_prompt_build`**: viene eseguito dopo il caricamento della sessione (con `messages`) per iniettare `prependContext`, `systemPrompt`, `prependSystemContext` o `appendSystemContext` prima dell'invio del prompt. Usa `prependContext` per testo dinamico per turno e i campi di contesto di sistema per indicazioni stabili che devono trovarsi nello spazio del prompt di sistema.
|
||||
- **`before_model_resolve`**: viene eseguito prima della sessione (senza `messages`) per sovrascrivere in modo deterministico provider/model prima della risoluzione del modello.
|
||||
- **`before_prompt_build`**: viene eseguito dopo il caricamento della sessione (con `messages`) per iniettare `prependContext`, `systemPrompt`, `prependSystemContext` o `appendSystemContext` prima dell'invio del prompt. Usa `prependContext` per testo dinamico per-turno e i campi di contesto di sistema per indicazioni stabili che dovrebbero stare nello spazio del prompt di sistema.
|
||||
- **`before_agent_start`**: hook di compatibilità legacy che può essere eseguito in una delle due fasi; preferisci gli hook espliciti sopra.
|
||||
- **`before_agent_reply`**: viene eseguito dopo le azioni inline e prima della chiamata all'LLM, consentendo a un plugin di prendersi carico del turno e restituire una risposta sintetica o silenziare completamente il turno.
|
||||
- **`agent_end`**: ispeziona l'elenco finale dei messaggi e i metadati di esecuzione dopo il completamento.
|
||||
- **`before_agent_reply`**: viene eseguito dopo le azioni inline e prima della chiamata LLM, permettendo a un plugin di prendere in carico il turno e restituire una risposta sintetica o silenziare completamente il turno.
|
||||
- **`agent_end`**: ispeziona l'elenco finale dei messaggi e i metadati dell'esecuzione dopo il completamento.
|
||||
- **`before_compaction` / `after_compaction`**: osserva o annota i cicli di compattazione.
|
||||
- **`before_tool_call` / `after_tool_call`**: intercetta parametri/risultati degli strumenti.
|
||||
- **`before_install`**: ispeziona i risultati della scansione integrata e può facoltativamente bloccare installazioni di Skills o plugin.
|
||||
- **`before_install`**: ispeziona i risultati della scansione integrata e può facoltativamente bloccare installazioni di skill o plugin.
|
||||
- **`tool_result_persist`**: trasforma in modo sincrono i risultati degli strumenti prima che vengano scritti nella trascrizione della sessione.
|
||||
- **`message_received` / `message_sending` / `message_sent`**: hook per messaggi in ingresso + in uscita.
|
||||
- **`session_start` / `session_end`**: confini del ciclo di vita della sessione.
|
||||
- **`gateway_start` / `gateway_stop`**: eventi del ciclo di vita del gateway.
|
||||
|
||||
Regole decisionali degli hook per le protezioni in uscita/degli strumenti:
|
||||
Regole decisionali degli hook per le protezioni su uscita/strumenti:
|
||||
|
||||
- `before_tool_call`: `{ block: true }` è terminale e interrompe i gestori a priorità inferiore.
|
||||
- `before_tool_call`: `{ block: false }` non ha effetto e non annulla un blocco precedente.
|
||||
- `before_install`: `{ block: true }` è terminale e interrompe i gestori a priorità inferiore.
|
||||
- `before_install`: `{ block: false }` non ha effetto e non annulla un blocco precedente.
|
||||
- `message_sending`: `{ cancel: true }` è terminale e interrompe i gestori a priorità inferiore.
|
||||
- `message_sending`: `{ cancel: false }` non ha effetto e non annulla una cancellazione precedente.
|
||||
- `before_tool_call`: `{ block: true }` è terminale e interrompe gli handler con priorità inferiore.
|
||||
- `before_tool_call`: `{ block: false }` è un no-op e non annulla un blocco precedente.
|
||||
- `before_install`: `{ block: true }` è terminale e interrompe gli handler con priorità inferiore.
|
||||
- `before_install`: `{ block: false }` è un no-op e non annulla un blocco precedente.
|
||||
- `message_sending`: `{ cancel: true }` è terminale e interrompe gli handler con priorità inferiore.
|
||||
- `message_sending`: `{ cancel: false }` è un no-op e non annulla una cancellazione precedente.
|
||||
|
||||
Vedi [Hook plugin](/it/plugins/architecture#provider-runtime-hooks) per l'API degli hook e i dettagli di registrazione.
|
||||
Vedi [Plugin hooks](/it/plugins/architecture#provider-runtime-hooks) per l'API degli hook e i dettagli di registrazione.
|
||||
|
||||
## Streaming + risposte parziali
|
||||
|
||||
- I delta dell'assistente vengono trasmessi in streaming da pi-agent-core ed emessi come eventi `assistant`.
|
||||
- Lo streaming a blocchi può emettere risposte parziali su `text_end` o `message_end`.
|
||||
- Lo streaming del ragionamento può essere emesso come stream separato o come risposte a blocchi.
|
||||
- Vedi [Streaming](/it/concepts/streaming) per il comportamento di suddivisione in chunk e delle risposte a blocchi.
|
||||
- Vedi [Streaming](/it/concepts/streaming) per il comportamento di chunking e delle risposte a blocchi.
|
||||
|
||||
## Esecuzione degli strumenti + strumenti di messaggistica
|
||||
|
||||
@ -130,21 +130,20 @@ Vedi [Hook plugin](/it/plugins/architecture#provider-runtime-hooks) per l'API de
|
||||
- I payload finali vengono assemblati da:
|
||||
- testo dell'assistente (e ragionamento facoltativo)
|
||||
- riepiloghi inline degli strumenti (quando verbose + consentito)
|
||||
- testo di errore dell'assistente quando il modello restituisce un errore
|
||||
- testo di errore dell'assistente quando il modello genera un errore
|
||||
- Il token silenzioso esatto `NO_REPLY` / `no_reply` viene filtrato dai
|
||||
payload in uscita.
|
||||
- I duplicati degli strumenti di messaggistica vengono rimossi dall'elenco finale dei payload.
|
||||
- Se non rimangono payload renderizzabili e uno strumento ha restituito un errore, viene emessa
|
||||
una risposta di fallback per l'errore dello strumento
|
||||
- Se non rimangono payload renderizzabili e uno strumento ha generato un errore, viene emessa una risposta di fallback per l'errore dello strumento
|
||||
(a meno che uno strumento di messaggistica abbia già inviato una risposta visibile all'utente).
|
||||
|
||||
## Compattazione + tentativi
|
||||
## Compattazione + retry
|
||||
|
||||
- La compattazione automatica emette eventi di stream `compaction` e può attivare un nuovo tentativo.
|
||||
- Al nuovo tentativo, i buffer in memoria e i riepiloghi degli strumenti vengono reimpostati per evitare output duplicati.
|
||||
- Vedi [Compattazione](/it/concepts/compaction) per la pipeline di compattazione.
|
||||
- La compattazione automatica emette eventi di stream `compaction` e può attivare un retry.
|
||||
- Al retry, i buffer in memoria e i riepiloghi degli strumenti vengono reimpostati per evitare output duplicato.
|
||||
- Vedi [Compaction](/it/concepts/compaction) per la pipeline di compattazione.
|
||||
|
||||
## Stream di eventi (attualmente)
|
||||
## Stream di eventi (oggi)
|
||||
|
||||
- `lifecycle`: emesso da `subscribeEmbeddedPiSession` (e come fallback da `agentCommand`)
|
||||
- `assistant`: delta in streaming da pi-agent-core
|
||||
@ -152,26 +151,26 @@ Vedi [Hook plugin](/it/plugins/architecture#provider-runtime-hooks) per l'API de
|
||||
|
||||
## Gestione del canale chat
|
||||
|
||||
- I delta dell'assistente vengono inseriti in buffer in messaggi chat `delta`.
|
||||
- Un `final` della chat viene emesso alla **fine/errore del ciclo di vita**.
|
||||
- I delta dell'assistente vengono bufferizzati in messaggi chat `delta`.
|
||||
- Un `final` della chat viene emesso su **lifecycle end/error**.
|
||||
|
||||
## Timeout
|
||||
|
||||
- Valore predefinito di `agent.wait`: 30s (solo l'attesa). Il parametro `timeoutMs` esegue l'override.
|
||||
- Runtime dell'agente: `agents.defaults.timeoutSeconds` predefinito 172800s (48 ore); applicato nel timer di interruzione di `runEmbeddedPiAgent`.
|
||||
- Timeout di inattività dell'LLM: `agents.defaults.llm.idleTimeoutSeconds` interrompe una richiesta al modello quando non arrivano chunk di risposta prima della finestra di inattività. Impostalo esplicitamente per modelli locali lenti o provider di ragionamento/chiamata strumenti; impostalo a 0 per disabilitarlo. Se non è impostato, OpenClaw usa `agents.defaults.timeoutSeconds` se configurato, altrimenti 60s. Le esecuzioni attivate da cron senza un timeout esplicito dell'LLM o dell'agente disabilitano il watchdog di inattività e si affidano al timeout esterno del cron.
|
||||
- Valore predefinito di `agent.wait`: 30s (solo per l'attesa). Il parametro `timeoutMs` lo sovrascrive.
|
||||
- Runtime dell'agente: valore predefinito `agents.defaults.timeoutSeconds` 172800s (48 ore); applicato nel timer di interruzione di `runEmbeddedPiAgent`.
|
||||
- Timeout di inattività LLM: `agents.defaults.llm.idleTimeoutSeconds` interrompe una richiesta al modello quando non arrivano chunk di risposta prima della finestra di inattività. Impostalo esplicitamente per modelli locali lenti o provider di ragionamento/chiamata strumenti; impostalo a 0 per disabilitarlo. Se non è impostato, OpenClaw usa `agents.defaults.timeoutSeconds` quando configurato, altrimenti 120s. Le esecuzioni attivate da cron senza timeout LLM o dell'agente esplicito disabilitano il watchdog di inattività e si affidano al timeout esterno del cron.
|
||||
|
||||
## Dove le cose possono terminare in anticipo
|
||||
|
||||
- Timeout dell'agente (interruzione)
|
||||
- AbortSignal (annullamento)
|
||||
- Disconnessione del gateway o timeout RPC
|
||||
- Timeout di `agent.wait` (solo attesa, non arresta l'agente)
|
||||
- Disconnessione del Gateway o timeout RPC
|
||||
- Timeout di `agent.wait` (solo attesa, non ferma l'agente)
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Strumenti](/it/tools) — strumenti dell'agente disponibili
|
||||
- [Tools](/it/tools) — strumenti dell'agente disponibili
|
||||
- [Hooks](/it/automation/hooks) — script guidati da eventi attivati dagli eventi del ciclo di vita dell'agente
|
||||
- [Compattazione](/it/concepts/compaction) — come vengono riepilogate le conversazioni lunghe
|
||||
- [Approvazioni Exec](/it/tools/exec-approvals) — controlli di approvazione per i comandi shell
|
||||
- [Compaction](/it/concepts/compaction) — come vengono riepilogate le conversazioni lunghe
|
||||
- [Exec Approvals](/it/tools/exec-approvals) — controlli di approvazione per i comandi shell
|
||||
- [Thinking](/it/tools/thinking) — configurazione del livello di thinking/ragionamento
|
||||
|
||||
@ -3,27 +3,27 @@ read_when:
|
||||
- Vuoi capire come funziona `memory_search`
|
||||
- Vuoi scegliere un provider di embedding
|
||||
- Vuoi ottimizzare la qualità della ricerca
|
||||
summary: Come la ricerca della memoria trova note pertinenti usando embeddings e recupero ibrido
|
||||
title: Memory Search
|
||||
summary: Come la ricerca nella memoria trova note pertinenti usando embeddings e recupero ibrido
|
||||
title: Ricerca nella memoria
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:06:32Z"
|
||||
generated_at: "2026-04-10T08:13:31Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b6541cd702bff41f9a468dad75ea438b70c44db7c65a4b793cbacaf9e583c7e9
|
||||
source_hash: ca0237f4f1ee69dcbfb12e6e9527a53e368c0bf9b429e506831d4af2f3a3ac6f
|
||||
source_path: concepts/memory-search.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Memory Search
|
||||
# Ricerca nella memoria
|
||||
|
||||
`memory_search` trova note pertinenti nei tuoi file di memoria, anche quando la
|
||||
formulazione è diversa dal testo originale. Funziona indicizzando la memoria in piccoli
|
||||
blocchi e cercandoli usando embeddings, parole chiave o entrambi.
|
||||
`memory_search` trova note pertinenti dai tuoi file di memoria, anche quando la
|
||||
formulazione è diversa dal testo originale. Funziona indicizzando la memoria in
|
||||
piccoli blocchi e cercandoli tramite embeddings, parole chiave o entrambi.
|
||||
|
||||
## Avvio rapido
|
||||
|
||||
Se hai configurato una chiave API OpenAI, Gemini, Voyage o Mistral, la ricerca
|
||||
della memoria funziona automaticamente. Per impostare esplicitamente un provider:
|
||||
nella memoria funziona automaticamente. Per impostare esplicitamente un provider:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -37,8 +37,8 @@ della memoria funziona automaticamente. Per impostare esplicitamente un provider
|
||||
}
|
||||
```
|
||||
|
||||
Per embedding locali senza chiave API, usa `provider: "local"` (richiede
|
||||
node-llama-cpp).
|
||||
Per embeddings locali senza chiave API, usa `provider: "local"` (richiede
|
||||
`node-llama-cpp`).
|
||||
|
||||
## Provider supportati
|
||||
|
||||
@ -50,11 +50,11 @@ node-llama-cpp).
|
||||
| Mistral | `mistral` | Sì | Rilevato automaticamente |
|
||||
| Bedrock | `bedrock` | No | Rilevato automaticamente quando la catena di credenziali AWS viene risolta |
|
||||
| Ollama | `ollama` | No | Locale, deve essere impostato esplicitamente |
|
||||
| Local | `local` | No | Modello GGUF, download di circa 0,6 GB |
|
||||
| Local | `local` | No | Modello GGUF, download di ~0,6 GB |
|
||||
|
||||
## Come funziona la ricerca
|
||||
|
||||
OpenClaw esegue in parallelo due percorsi di recupero e ne unisce i risultati:
|
||||
OpenClaw esegue due percorsi di recupero in parallelo e unisce i risultati:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@ -72,31 +72,33 @@ flowchart LR
|
||||
- **Ricerca per parole chiave BM25** trova corrispondenze esatte (ID, stringhe di errore, chiavi
|
||||
di configurazione).
|
||||
|
||||
Se è disponibile un solo percorso (niente embeddings o niente FTS), viene eseguito solo l'altro.
|
||||
Se è disponibile solo un percorso (nessun embeddings o nessun FTS), l'altro viene eseguito da solo.
|
||||
|
||||
## Migliorare la qualità della ricerca
|
||||
|
||||
Due funzionalità facoltative aiutano quando hai una cronologia ampia di note:
|
||||
Due funzionalità opzionali aiutano quando hai una cronologia delle note molto ampia:
|
||||
|
||||
### Decadimento temporale
|
||||
|
||||
Le note vecchie perdono gradualmente peso nel ranking, così le informazioni recenti emergono per prime.
|
||||
Con l'emivita predefinita di 30 giorni, una nota del mese scorso ottiene il 50% del
|
||||
suo peso originale. I file sempreverdi come `MEMORY.md` non subiscono mai decadimento.
|
||||
Le note vecchie perdono gradualmente peso nel ranking, così le informazioni
|
||||
recenti emergono per prime. Con l'emivita predefinita di 30 giorni, una nota
|
||||
del mese scorso ottiene il 50% del suo peso originale. I file sempre validi come
|
||||
`MEMORY.md` non subiscono mai decadimento.
|
||||
|
||||
<Tip>
|
||||
Abilita il decadimento temporale se il tuo agente ha mesi di note giornaliere e informazioni obsolete
|
||||
continuano a superare nel ranking il contesto recente.
|
||||
Abilita il decadimento temporale se il tuo agente ha mesi di note quotidiane e
|
||||
le informazioni obsolete continuano a superare nel ranking il contesto recente.
|
||||
</Tip>
|
||||
|
||||
### MMR (diversità)
|
||||
|
||||
Riduce i risultati ridondanti. Se cinque note menzionano tutte la stessa configurazione del router, MMR
|
||||
garantisce che i risultati principali coprano argomenti diversi invece di ripetersi.
|
||||
Riduce i risultati ridondanti. Se cinque note menzionano tutte la stessa
|
||||
configurazione del router, MMR assicura che i risultati principali coprano temi
|
||||
diversi invece di ripetersi.
|
||||
|
||||
<Tip>
|
||||
Abilita MMR se `memory_search` continua a restituire snippet quasi duplicati da
|
||||
note giornaliere diverse.
|
||||
Abilita MMR se `memory_search` continua a restituire frammenti quasi duplicati
|
||||
provenienti da note quotidiane diverse.
|
||||
</Tip>
|
||||
|
||||
### Abilita entrambi
|
||||
@ -120,15 +122,16 @@ note giornaliere diverse.
|
||||
|
||||
## Memoria multimodale
|
||||
|
||||
Con Gemini Embedding 2, puoi indicizzare file di immagini e audio insieme al
|
||||
Markdown. Le query di ricerca restano testuali, ma corrispondono a contenuti visivi e audio.
|
||||
Per la configurazione, vedi il [Riferimento della configurazione della memoria](/it/reference/memory-config).
|
||||
Con Gemini Embedding 2, puoi indicizzare immagini e file audio insieme al
|
||||
Markdown. Le query di ricerca restano testuali, ma corrispondono a contenuti
|
||||
visivi e audio. Vedi il [riferimento della configurazione della memoria](/it/reference/memory-config) per
|
||||
la configurazione.
|
||||
|
||||
## Ricerca nella memoria della sessione
|
||||
## Ricerca nella memoria di sessione
|
||||
|
||||
Puoi facoltativamente indicizzare le trascrizioni delle sessioni in modo che `memory_search` possa recuperare
|
||||
conversazioni precedenti. Questa funzionalità è opt-in tramite
|
||||
`memorySearch.experimental.sessionMemory`. Vedi il
|
||||
Puoi facoltativamente indicizzare le trascrizioni delle sessioni così che
|
||||
`memory_search` possa richiamare conversazioni precedenti. Questa opzione è
|
||||
attivabile tramite `memorySearch.experimental.sessionMemory`. Vedi il
|
||||
[riferimento della configurazione](/it/reference/memory-config) per i dettagli.
|
||||
|
||||
## Risoluzione dei problemi
|
||||
@ -142,7 +145,8 @@ conversazioni precedenti. Questa funzionalità è opt-in tramite
|
||||
**Testo CJK non trovato?** Ricostruisci l'indice FTS con
|
||||
`openclaw memory index --force`.
|
||||
|
||||
## Ulteriori letture
|
||||
## Approfondimenti
|
||||
|
||||
- [Memory](/it/concepts/memory) -- layout dei file, backend, strumenti
|
||||
- [Memoria attiva](/it/concepts/active-memory) -- memoria del sub-agente per sessioni di chat interattive
|
||||
- [Memoria](/it/concepts/memory) -- layout dei file, backend, strumenti
|
||||
- [Riferimento della configurazione della memoria](/it/reference/memory-config) -- tutte le opzioni di configurazione
|
||||
|
||||
@ -1,23 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- Estensione di qa-lab o qa-channel
|
||||
- Aggiunta di scenari QA supportati dal repository
|
||||
- Creazione di un'automazione QA con maggiore realismo attorno alla dashboard Gateway
|
||||
summary: Struttura dell'automazione QA privata per qa-lab, qa-channel, scenari seed e report di protocollo
|
||||
title: Automazione QA E2E
|
||||
- Estendere qa-lab o qa-channel
|
||||
- Aggiungere scenari QA supportati dal repository
|
||||
- Creare un'automazione QA con maggiore realismo attorno alla dashboard del Gateway
|
||||
summary: Struttura dell'automazione QA privata per qa-lab, qa-channel, scenari inizializzati e report di protocollo
|
||||
title: Automazione QA end-to-end
|
||||
x-i18n:
|
||||
generated_at: "2026-04-09T01:27:42Z"
|
||||
generated_at: "2026-04-10T08:13:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c922607d67e0f3a2489ac82bc9f510f7294ced039c1014c15b676d826441d833
|
||||
source_hash: 357d6698304ff7a8c4aa8a7be97f684d50f72b524740050aa761ac0ee68266de
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Automazione QA E2E
|
||||
# Automazione QA end-to-end
|
||||
|
||||
Lo stack QA privato è pensato per testare OpenClaw in un modo più realistico,
|
||||
simile a un canale, rispetto a quanto possa fare un singolo test unitario.
|
||||
Lo stack QA privato è pensato per testare OpenClaw in modo più realistico,
|
||||
con una forma simile a quella di un canale, rispetto a quanto possa fare un
|
||||
singolo test unitario.
|
||||
|
||||
Componenti attuali:
|
||||
|
||||
@ -25,12 +26,12 @@ Componenti attuali:
|
||||
reazione, modifica ed eliminazione.
|
||||
- `extensions/qa-lab`: interfaccia utente di debug e bus QA per osservare la trascrizione,
|
||||
iniettare messaggi in ingresso ed esportare un report Markdown.
|
||||
- `qa/`: risorse seed supportate dal repository per l'attività iniziale e gli
|
||||
- `qa/`: risorse seed supportate dal repository per il task iniziale e gli
|
||||
scenari QA di base.
|
||||
|
||||
L'attuale flusso dell'operatore QA è un sito QA a due pannelli:
|
||||
L'attuale flusso operativo QA è un sito QA a due pannelli:
|
||||
|
||||
- Sinistra: dashboard Gateway (Control UI) con l'agente.
|
||||
- Sinistra: dashboard del Gateway (Control UI) con l'agente.
|
||||
- Destra: QA Lab, che mostra la trascrizione in stile Slack e il piano dello scenario.
|
||||
|
||||
Eseguilo con:
|
||||
@ -39,12 +40,12 @@ Eseguilo con:
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
Questo compila il sito QA, avvia la corsia gateway supportata da Docker ed espone la
|
||||
pagina QA Lab in cui un operatore o un ciclo di automazione può assegnare all'agente una
|
||||
missione QA, osservare il comportamento reale del canale e registrare ciò che ha
|
||||
funzionato, ciò che non ha funzionato o ciò che è rimasto bloccato.
|
||||
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 cosa ha funzionato,
|
||||
cosa è fallito o cosa è rimasto bloccato.
|
||||
|
||||
Per un'iterazione più rapida dell'interfaccia utente di QA Lab senza ricompilare ogni volta l'immagine Docker,
|
||||
Per iterare più velocemente sull'interfaccia utente di QA Lab senza ricompilare ogni volta l'immagine Docker,
|
||||
avvia lo stack con un bundle QA Lab montato tramite bind:
|
||||
|
||||
```bash
|
||||
@ -56,9 +57,24 @@ pnpm qa:lab:watch
|
||||
|
||||
`qa:lab:up:fast` mantiene i servizi Docker su un'immagine precompilata e monta tramite bind
|
||||
`extensions/qa-lab/web/dist` nel container `qa-lab`. `qa:lab:watch`
|
||||
ricompila quel bundle a ogni modifica e il browser si ricarica automaticamente quando cambia l'hash
|
||||
ricompila quel bundle a ogni modifica, e il browser si ricarica automaticamente quando cambia l'hash
|
||||
delle risorse di QA Lab.
|
||||
|
||||
Per una lane VM Linux usa e getta senza introdurre Docker nel percorso QA, esegui:
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
```
|
||||
|
||||
Questo avvia una nuova guest Multipass, installa le dipendenze, compila OpenClaw all'interno della guest,
|
||||
esegue `qa suite`, quindi copia il normale report QA e il riepilogo in `.artifacts/qa-e2e/...`
|
||||
sull'host.
|
||||
Riutilizza lo stesso comportamento di selezione dello scenario di `qa suite` sull'host.
|
||||
Le esecuzioni live inoltrano gli input di autenticazione QA supportati e pratici per la
|
||||
guest: chiavi provider basate su env, il percorso della configurazione del provider live QA e
|
||||
`CODEX_HOME` quando presente. Mantieni `--output-dir` sotto la root del repository in modo che la guest
|
||||
possa scrivere di nuovo attraverso il workspace montato.
|
||||
|
||||
## Seed supportati dal repository
|
||||
|
||||
Le risorse seed si trovano in `qa/`:
|
||||
@ -66,30 +82,30 @@ Le risorse seed si trovano in `qa/`:
|
||||
- `qa/scenarios/index.md`
|
||||
- `qa/scenarios/*.md`
|
||||
|
||||
Sono intenzionalmente in git in modo che il piano QA sia visibile sia agli esseri umani sia
|
||||
Questi file sono intenzionalmente presenti in git in modo che il piano QA sia visibile sia agli esseri umani sia
|
||||
all'agente. L'elenco di base dovrebbe rimanere abbastanza ampio da coprire:
|
||||
|
||||
- chat DM e di canale
|
||||
- chat in DM e nei canali
|
||||
- comportamento dei thread
|
||||
- ciclo di vita delle azioni sui messaggi
|
||||
- callback cron
|
||||
- richiamo della memoria
|
||||
- cambio modello
|
||||
- passaggio a sottoagente
|
||||
- handoff a subagente
|
||||
- lettura del repository e della documentazione
|
||||
- una piccola attività di build come Lobster Invaders
|
||||
- un piccolo task di build come Lobster Invaders
|
||||
|
||||
## Reportistica
|
||||
|
||||
`qa-lab` esporta un report di protocollo Markdown dalla timeline osservata del bus.
|
||||
Il report dovrebbe rispondere a queste domande:
|
||||
`qa-lab` esporta un report di protocollo Markdown dalla timeline del bus osservato.
|
||||
Il report dovrebbe rispondere a:
|
||||
|
||||
- Che cosa ha funzionato
|
||||
- Che cosa non ha funzionato
|
||||
- Che cosa è rimasto bloccato
|
||||
- Cosa ha funzionato
|
||||
- Cosa è fallito
|
||||
- Cosa è rimasto bloccato
|
||||
- Quali scenari di follow-up vale la pena aggiungere
|
||||
|
||||
Per verifiche di carattere e stile, esegui lo stesso scenario su più riferimenti di modelli live
|
||||
Per i controlli di carattere e stile, esegui lo stesso scenario su più riferimenti di modelli live
|
||||
e scrivi un report Markdown valutato:
|
||||
|
||||
```bash
|
||||
@ -109,31 +125,31 @@ pnpm openclaw qa character-eval \
|
||||
--judge-concurrency 16
|
||||
```
|
||||
|
||||
Il comando esegue processi figli del gateway QA locale, 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 per il 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 esecuzione di base, quindi chiede ai modelli giudice in modalità fast con
|
||||
ragionamento `xhigh` di classificare le esecuzioni in base a naturalezza, vibe e umorismo.
|
||||
come chat, assistenza sul workspace e piccoli task sui file. Al modello candidato non
|
||||
dovrebbe essere detto che è in fase di valutazione. Il comando preserva ogni trascrizione completa,
|
||||
registra statistiche di base sull'esecuzione, quindi chiede ai modelli giudice in modalità fast con
|
||||
ragionamento `xhigh` di classificare le esecuzioni per naturalezza, vibe e umorismo.
|
||||
Usa `--blind-judge-models` quando confronti provider: il prompt del giudice riceve comunque
|
||||
ogni trascrizione e stato di esecuzione, ma i riferimenti dei candidati vengono sostituiti con
|
||||
etichette neutrali come `candidate-01`; il report riconduce le classifiche ai riferimenti reali dopo
|
||||
ogni trascrizione e stato di esecuzione, ma i riferimenti dei candidati vengono sostituiti con etichette
|
||||
neutrali come `candidate-01`; il report riconduce le classifiche ai riferimenti reali dopo
|
||||
il parsing.
|
||||
Le esecuzioni candidate usano per impostazione predefinita `high` thinking, con `xhigh` per i modelli OpenAI che
|
||||
Le esecuzioni dei candidati usano per impostazione predefinita il livello di ragionamento `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 forma precedente `--model-thinking <provider/model=level>` viene
|
||||
mantenuta per compatibilità.
|
||||
I riferimenti candidati OpenAI usano per impostazione predefinita la modalità fast in modo che venga utilizzata l'elaborazione prioritaria dove
|
||||
`--model provider/model,thinking=<level>`. `--thinking <level>` continua a impostare un
|
||||
fallback globale, e la forma meno recente `--model-thinking <provider/model=level>` viene mantenuta
|
||||
per compatibilità.
|
||||
I riferimenti candidati OpenAI usano per impostazione predefinita la modalità fast in modo che venga usata l'elaborazione prioritaria dove
|
||||
il provider la supporta. Aggiungi `,fast`, `,no-fast` o `,fast=false` inline quando un
|
||||
singolo candidato o giudice necessita di una sostituzione. Passa `--fast` solo quando vuoi
|
||||
forzare la modalità fast per ogni modello candidato. Le durate di candidati e giudici vengono
|
||||
registrate nel report per l'analisi comparativa, ma i prompt dei giudici indicano esplicitamente
|
||||
singolo candidato o giudice richiede una sostituzione. Passa `--fast` solo quando vuoi
|
||||
forzare la modalità fast per ogni modello candidato. Le durate dei candidati e dei giudici vengono
|
||||
registrate nel report per l'analisi comparativa, ma i prompt dei giudici dicono esplicitamente
|
||||
di non classificare in base alla velocità.
|
||||
Sia le esecuzioni dei modelli candidati sia quelle dei modelli giudice usano per impostazione predefinita una concorrenza pari a 16. Riduci
|
||||
`--concurrency` o `--judge-concurrency` quando i limiti del provider o il carico del gateway locale
|
||||
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`, il character eval usa per impostazione predefinita
|
||||
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
|
||||
@ -145,5 +161,5 @@ Quando non viene passato alcun `--judge-model`, i giudici usano per impostazione
|
||||
## Documentazione correlata
|
||||
|
||||
- [Testing](/it/help/testing)
|
||||
- [QA Channel](/it/channels/qa-channel)
|
||||
- [Canale QA](/it/channels/qa-channel)
|
||||
- [Dashboard](/web/dashboard)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,32 +1,32 @@
|
||||
---
|
||||
read_when:
|
||||
- Implementazione o aggiornamento di client WS del gateway
|
||||
- Debug di mismatch del protocollo o errori di connessione
|
||||
- Rigenerazione di schema/modelli del protocollo
|
||||
summary: 'Protocollo WebSocket del gateway: handshake, frame, versioning'
|
||||
title: Protocollo del gateway
|
||||
- Implementazione o aggiornamento dei client WS del gateway
|
||||
- Debug del protocollo non corrispondente o degli errori di connessione
|
||||
- Rigenerazione dello schema/dei modelli del protocollo
|
||||
summary: 'Protocollo WebSocket del Gateway: handshake, frame, versioning'
|
||||
title: Protocollo del Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-04-08T02:15:55Z"
|
||||
generated_at: "2026-04-10T08:14:12Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 8635e3ac1dd311dbd3a770b088868aa1495a8d53b3ebc1eae0dfda3b2bf4694a
|
||||
source_hash: 83c820c46d4803d571c770468fd6782619eaa1dca253e156e8087dec735c127f
|
||||
source_path: gateway/protocol.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Protocollo del gateway (WebSocket)
|
||||
|
||||
Il protocollo WS del gateway è il **singolo control plane + trasporto dei nodi** per
|
||||
OpenClaw. Tutti i client (CLI, interfaccia web, app macOS, nodi iOS/Android, nodi
|
||||
headless) si connettono tramite WebSocket e dichiarano il proprio **ruolo** + **ambito** al
|
||||
momento dell'handshake.
|
||||
Il protocollo WS del Gateway è il **singolo control plane + trasporto dei nodi** per
|
||||
OpenClaw. Tutti i client (CLI, interfaccia web, app macOS, nodi iOS/Android,
|
||||
nodi headless) si connettono tramite WebSocket e dichiarano il proprio **ruolo** + **ambito**
|
||||
al momento dell'handshake.
|
||||
|
||||
## Trasporto
|
||||
|
||||
- WebSocket, frame di testo con payload JSON.
|
||||
- Il primo frame **deve** essere una richiesta `connect`.
|
||||
|
||||
## Handshake (connect)
|
||||
## Handshake (`connect`)
|
||||
|
||||
Gateway → Client (challenge pre-connessione):
|
||||
|
||||
@ -96,7 +96,7 @@ Quando viene emesso un token del dispositivo, `hello-ok` include anche:
|
||||
}
|
||||
```
|
||||
|
||||
Durante il passaggio di bootstrap attendibile, `hello-ok.auth` può includere anche voci di ruolo aggiuntive limitate in `deviceTokens`:
|
||||
Durante il passaggio affidabile del bootstrap, `hello-ok.auth` può anche includere voci di ruolo aggiuntive limitate in `deviceTokens`:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -115,14 +115,12 @@ Durante il passaggio di bootstrap attendibile, `hello-ok.auth` può includere an
|
||||
}
|
||||
```
|
||||
|
||||
Per il flusso di bootstrap integrato node/operator, il token primario del nodo resta
|
||||
`scopes: []` e qualsiasi token operator passato resta limitato all'allowlist dell'operatore di bootstrap
|
||||
(`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). I controlli dell'ambito di bootstrap restano
|
||||
con prefisso del ruolo: le voci operator soddisfano solo richieste operator, e i ruoli non-operator
|
||||
continuano a richiedere ambiti sotto il proprio prefisso di ruolo.
|
||||
Per il flusso di bootstrap integrato nodo/operatore, il token principale del nodo rimane
|
||||
`scopes: []` e qualsiasi token operatore passato rimane limitato alla allowlist dell'operatore di bootstrap (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). I controlli degli ambiti di bootstrap restano con prefisso del ruolo: le voci operatore soddisfano solo richieste operatore, e i ruoli non operatore
|
||||
richiedono comunque ambiti con il prefisso del proprio ruolo.
|
||||
|
||||
### Esempio node
|
||||
### Esempio di nodo
|
||||
|
||||
```json
|
||||
{
|
||||
@ -159,9 +157,9 @@ continuano a richiedere ambiti sotto il proprio prefisso di ruolo.
|
||||
|
||||
## Framing
|
||||
|
||||
- **Request**: `{type:"req", id, method, params}`
|
||||
- **Response**: `{type:"res", id, ok, payload|error}`
|
||||
- **Event**: `{type:"event", event, payload, seq?, stateVersion?}`
|
||||
- **Richiesta**: `{type:"req", id, method, params}`
|
||||
- **Risposta**: `{type:"res", id, ok, payload|error}`
|
||||
- **Evento**: `{type:"event", event, payload, seq?, stateVersion?}`
|
||||
|
||||
I metodi con effetti collaterali richiedono **chiavi di idempotenza** (vedi schema).
|
||||
|
||||
@ -170,9 +168,9 @@ I metodi con effetti collaterali richiedono **chiavi di idempotenza** (vedi sche
|
||||
### Ruoli
|
||||
|
||||
- `operator` = client del control plane (CLI/UI/automazione).
|
||||
- `node` = host di capacità (camera/screen/canvas/system.run).
|
||||
- `node` = host delle capacità (camera/screen/canvas/system.run).
|
||||
|
||||
### Ambiti (operator)
|
||||
### Ambiti (`operator`)
|
||||
|
||||
Ambiti comuni:
|
||||
|
||||
@ -186,129 +184,128 @@ Ambiti comuni:
|
||||
`talk.config` con `includeSecrets: true` richiede `operator.talk.secrets`
|
||||
(o `operator.admin`).
|
||||
|
||||
I metodi RPC del gateway registrati dai plugin possono richiedere il proprio ambito operator, ma
|
||||
i prefissi admin core riservati (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
I metodi RPC del gateway registrati dai plugin possono richiedere il proprio ambito operatore, ma
|
||||
i prefissi amministrativi core riservati (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) vengono sempre risolti in `operator.admin`.
|
||||
|
||||
L'ambito del metodo è solo il primo gate. Alcuni slash command raggiunti tramite
|
||||
`chat.send` applicano controlli a livello di comando più restrittivi in aggiunta. Per esempio, le scritture persistenti
|
||||
L'ambito del metodo è solo il primo controllo. Alcuni slash command raggiunti tramite
|
||||
`chat.send` applicano controlli più rigorosi a livello di comando. Ad esempio, le scritture persistenti
|
||||
`/config set` e `/config unset` richiedono `operator.admin`.
|
||||
|
||||
`node.pair.approve` ha anche un controllo aggiuntivo dell'ambito al momento dell'approvazione oltre al
|
||||
metodo base:
|
||||
`node.pair.approve` ha anche un controllo aggiuntivo dell'ambito al momento dell'approvazione oltre all'ambito base del metodo:
|
||||
|
||||
- richieste senza comando: `operator.pairing`
|
||||
- richieste con comandi del nodo non-exec: `operator.pairing` + `operator.write`
|
||||
- richieste senza comandi: `operator.pairing`
|
||||
- richieste con comandi del nodo non `exec`: `operator.pairing` + `operator.write`
|
||||
- richieste che includono `system.run`, `system.run.prepare` o `system.which`:
|
||||
`operator.pairing` + `operator.admin`
|
||||
|
||||
### Caps/commands/permissions (node)
|
||||
### `caps`/`commands`/`permissions` (`node`)
|
||||
|
||||
I nodi dichiarano le proprie capability claim al momento della connessione:
|
||||
I nodi dichiarano le capacità richieste al momento della connessione:
|
||||
|
||||
- `caps`: categorie di capacità di alto livello.
|
||||
- `commands`: allowlist dei comandi per invoke.
|
||||
- `permissions`: toggle granulari (ad esempio `screen.record`, `camera.capture`).
|
||||
- `commands`: allowlist dei comandi per `invoke`.
|
||||
- `permissions`: interruttori granulari (ad esempio `screen.record`, `camera.capture`).
|
||||
|
||||
Il gateway tratta questi elementi come **claim** e applica allowlist lato server.
|
||||
Il Gateway tratta questi elementi come **dichiarazioni** e applica allowlist lato server.
|
||||
|
||||
## Presence
|
||||
## Presenza
|
||||
|
||||
- `system-presence` restituisce voci indicizzate per identità del dispositivo.
|
||||
- Le voci di presence includono `deviceId`, `roles` e `scopes` così le UI possono mostrare una singola riga per dispositivo
|
||||
- Le voci di presenza includono `deviceId`, `roles` e `scopes` così che le UI possano mostrare una singola riga per dispositivo
|
||||
anche quando si connette sia come **operator** sia come **node**.
|
||||
|
||||
## Famiglie comuni di metodi RPC
|
||||
|
||||
Questa pagina non è un dump completo generato, ma la superficie WS pubblica è più ampia
|
||||
degli esempi di handshake/auth sopra. Queste sono le principali famiglie di metodi che il
|
||||
gateway espone oggi.
|
||||
Gateway espone oggi.
|
||||
|
||||
`hello-ok.features.methods` è un elenco conservativo di discovery costruito da
|
||||
`src/gateway/server-methods-list.ts` più le esportazioni dei metodi plugin/channel caricati.
|
||||
Trattalo come discovery delle funzionalità, non come un dump generato di ogni helper invocabile
|
||||
`hello-ok.features.methods` è un elenco di discovery conservativo costruito da
|
||||
`src/gateway/server-methods-list.ts` più le esportazioni dei metodi di plugin/canali caricati.
|
||||
Trattalo come feature discovery, non come un dump generato di ogni helper invocabile
|
||||
implementato in `src/gateway/server-methods/*.ts`.
|
||||
|
||||
### Sistema e identità
|
||||
|
||||
- `health` restituisce lo snapshot di health del gateway memorizzato in cache o appena sondato.
|
||||
- `health` restituisce lo snapshot di salute del gateway memorizzato in cache o appena verificato.
|
||||
- `status` restituisce il riepilogo del gateway in stile `/status`; i campi sensibili sono
|
||||
inclusi solo per client operator con ambito admin.
|
||||
inclusi solo per i client operatore con ambito admin.
|
||||
- `gateway.identity.get` restituisce l'identità del dispositivo gateway usata dai flussi di relay e
|
||||
pairing.
|
||||
- `system-presence` restituisce lo snapshot corrente della presence per i dispositivi
|
||||
- `system-presence` restituisce lo snapshot corrente della presenza dei dispositivi
|
||||
operator/node connessi.
|
||||
- `system-event` aggiunge un evento di sistema e può aggiornare/trasmettere il contesto
|
||||
di presence.
|
||||
di presenza.
|
||||
- `last-heartbeat` restituisce l'ultimo evento heartbeat persistito.
|
||||
- `set-heartbeats` attiva/disattiva l'elaborazione heartbeat sul gateway.
|
||||
- `set-heartbeats` attiva o disattiva l'elaborazione degli heartbeat sul gateway.
|
||||
|
||||
### Modelli e utilizzo
|
||||
|
||||
- `models.list` restituisce il catalogo dei modelli consentiti a runtime.
|
||||
- `usage.status` restituisce finestre di utilizzo del provider/riepiloghi della quota residua.
|
||||
- `usage.cost` restituisce riepiloghi aggregati del costo di utilizzo per un intervallo di date.
|
||||
- `doctor.memory.status` restituisce lo stato di preparazione di vector-memory / embedding per il
|
||||
workspace dell'agente predefinito attivo.
|
||||
- `models.list` restituisce il catalogo dei modelli consentiti dal runtime.
|
||||
- `usage.status` restituisce le finestre di utilizzo dei provider e i riepiloghi della quota rimanente.
|
||||
- `usage.cost` restituisce riepiloghi aggregati dei costi di utilizzo per un intervallo di date.
|
||||
- `doctor.memory.status` restituisce lo stato di prontezza della memoria vettoriale / degli embedding per il
|
||||
workspace predefinito attivo dell'agente.
|
||||
- `sessions.usage` restituisce riepiloghi di utilizzo per sessione.
|
||||
- `sessions.usage.timeseries` restituisce serie temporali di utilizzo per una sessione.
|
||||
- `sessions.usage.logs` restituisce voci del log di utilizzo per una sessione.
|
||||
- `sessions.usage.logs` restituisce le voci del log di utilizzo per una sessione.
|
||||
|
||||
### Canali e helper di login
|
||||
|
||||
- `channels.status` restituisce riepiloghi di stato dei canali/plugin integrati + inclusi.
|
||||
- `channels.logout` disconnette uno specifico canale/account nei casi in cui il canale
|
||||
supporti il logout.
|
||||
- `web.login.start` avvia un flusso di login QR/web per il provider del canale web corrente con supporto QR.
|
||||
- `channels.status` restituisce riepiloghi di stato dei canali/plugin integrati e bundled.
|
||||
- `channels.logout` esegue il logout di un canale/account specifico dove il canale
|
||||
supporta il logout.
|
||||
- `web.login.start` avvia un flusso di login QR/web per il provider del canale web attuale con supporto QR.
|
||||
- `web.login.wait` attende il completamento di quel flusso di login QR/web e avvia il
|
||||
canale in caso di successo.
|
||||
- `push.test` invia una push APNs di test a un nodo iOS registrato.
|
||||
- `voicewake.get` restituisce i trigger della parola di attivazione memorizzati.
|
||||
- `voicewake.set` aggiorna i trigger della parola di attivazione e trasmette la modifica.
|
||||
- `voicewake.get` restituisce i trigger wake-word memorizzati.
|
||||
- `voicewake.set` aggiorna i trigger wake-word e trasmette la modifica.
|
||||
|
||||
### Messaggistica e log
|
||||
|
||||
- `send` è l'RPC diretto di consegna in uscita per invii indirizzati a canale/account/thread
|
||||
al di fuori del runner chat.
|
||||
- `logs.tail` restituisce il tail configurato del log file del gateway con controlli di cursore/limite e
|
||||
- `send` è l'RPC diretto di consegna in uscita per invii mirati a canale/account/thread
|
||||
al di fuori del runner di chat.
|
||||
- `logs.tail` restituisce il tail del log file del gateway configurato con controlli di cursore/limite e
|
||||
byte massimi.
|
||||
|
||||
### Talk e TTS
|
||||
|
||||
- `talk.config` restituisce il payload di configurazione Talk effettivo; `includeSecrets`
|
||||
- `talk.config` restituisce il payload effettivo della configurazione Talk; `includeSecrets`
|
||||
richiede `operator.talk.secrets` (o `operator.admin`).
|
||||
- `talk.mode` imposta/trasmette lo stato corrente della modalità Talk per i client WebChat/Control UI.
|
||||
- `talk.mode` imposta/trasmette lo stato corrente della modalità Talk per i client
|
||||
WebChat/Control UI.
|
||||
- `talk.speak` sintetizza il parlato tramite il provider speech Talk attivo.
|
||||
- `tts.status` restituisce stato TTS abilitato, provider attivo, provider di fallback
|
||||
e stato della configurazione del provider.
|
||||
- `tts.status` restituisce lo stato di abilitazione del TTS, il provider attivo, i provider di fallback
|
||||
e lo stato della configurazione del provider.
|
||||
- `tts.providers` restituisce l'inventario visibile dei provider TTS.
|
||||
- `tts.enable` e `tts.disable` attivano/disattivano lo stato delle preferenze TTS.
|
||||
- `tts.enable` e `tts.disable` attivano o disattivano lo stato delle preferenze TTS.
|
||||
- `tts.setProvider` aggiorna il provider TTS preferito.
|
||||
- `tts.convert` esegue una conversione text-to-speech one-shot.
|
||||
- `tts.convert` esegue una conversione text-to-speech una tantum.
|
||||
|
||||
### Secrets, config, update e wizard
|
||||
### Secrets, configurazione, aggiornamento e wizard
|
||||
|
||||
- `secrets.reload` risolve nuovamente i SecretRef attivi e sostituisce lo stato runtime dei secret
|
||||
- `secrets.reload` risolve di nuovo i SecretRef attivi e sostituisce lo stato segreto del runtime
|
||||
solo in caso di successo completo.
|
||||
- `secrets.resolve` risolve le assegnazioni di secret destinate ai comandi per uno specifico
|
||||
insieme comando/target.
|
||||
- `secrets.resolve` risolve le assegnazioni di secret mirate ai comandi per uno specifico insieme di comando/target.
|
||||
- `config.get` restituisce lo snapshot e l'hash della configurazione corrente.
|
||||
- `config.set` scrive un payload di configurazione validato.
|
||||
- `config.patch` unisce un aggiornamento parziale della configurazione.
|
||||
- `config.apply` valida + sostituisce l'intero payload di configurazione.
|
||||
- `config.apply` valida + sostituisce il payload completo della configurazione.
|
||||
- `config.schema` restituisce il payload dello schema di configurazione live usato da Control UI e
|
||||
strumenti CLI: schema, `uiHints`, versione e metadati di generazione, inclusi
|
||||
i metadati di schema di plugin + canale quando il runtime può caricarli. Lo schema
|
||||
include i metadati dei campi `title` / `description` derivati dalle stesse etichette
|
||||
e dal testo di aiuto usati dalla UI, incluse diramazioni di composizione annidate di oggetto, wildcard,
|
||||
elemento di array e `anyOf` / `oneOf` / `allOf` quando esiste documentazione
|
||||
di campo corrispondente.
|
||||
dagli strumenti CLI: schema, `uiHints`, versione e metadati di generazione, inclusi
|
||||
i metadati di schema di plugin + canali quando il runtime può caricarli. Lo schema
|
||||
include metadati dei campi `title` / `description` derivati dalle stesse etichette
|
||||
e dallo stesso testo di aiuto usati dalla UI, incluse le diramazioni annidate di object, wildcard, array-item
|
||||
e composizione `anyOf` / `oneOf` / `allOf` quando esiste documentazione dei campi
|
||||
corrispondente.
|
||||
- `config.schema.lookup` restituisce un payload di lookup con ambito di percorso per un percorso di configurazione:
|
||||
percorso normalizzato, nodo di schema superficiale, hint corrispondente + `hintPath`, e
|
||||
percorso normalizzato, un nodo di schema superficiale, hint corrispondente + `hintPath`, e
|
||||
riepiloghi dei figli immediati per drill-down UI/CLI.
|
||||
- I nodi di schema di lookup mantengono la documentazione rivolta all'utente e i comuni campi di validazione:
|
||||
- I nodi di schema di lookup mantengono la documentazione rivolta all'utente e i campi di validazione comuni:
|
||||
`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`,
|
||||
limiti numerici/stringa/array/oggetto, e flag booleani come
|
||||
limiti numerici/stringa/array/object e flag booleani come
|
||||
`additionalProperties`, `deprecated`, `readOnly`, `writeOnly`.
|
||||
- I riepiloghi dei figli espongono `key`, `path` normalizzato, `type`, `required`,
|
||||
`hasChildren`, più `hint` / `hintPath` corrispondenti.
|
||||
@ -317,250 +314,263 @@ implementato in `src/gateway/server-methods/*.ts`.
|
||||
- `wizard.start`, `wizard.next`, `wizard.status` e `wizard.cancel` espongono il
|
||||
wizard di onboarding tramite WS RPC.
|
||||
|
||||
### Principali famiglie esistenti
|
||||
### Famiglie principali esistenti
|
||||
|
||||
#### Helper di agente e workspace
|
||||
#### Helper per agente e workspace
|
||||
|
||||
- `agents.list` restituisce le voci di agente configurate.
|
||||
- `agents.list` restituisce le voci degli agenti configurati.
|
||||
- `agents.create`, `agents.update` e `agents.delete` gestiscono i record degli agenti e
|
||||
il wiring del workspace.
|
||||
- `agents.files.list`, `agents.files.get` e `agents.files.set` gestiscono i
|
||||
file bootstrap del workspace esposti per un agente.
|
||||
file del workspace di bootstrap esposti per un agente.
|
||||
- `agent.identity.get` restituisce l'identità effettiva dell'assistente per un agente o
|
||||
sessione.
|
||||
- `agent.wait` attende che un'esecuzione finisca e restituisce lo snapshot terminale quando
|
||||
una sessione.
|
||||
- `agent.wait` attende la fine di un'esecuzione e restituisce lo snapshot terminale quando
|
||||
disponibile.
|
||||
|
||||
#### Controllo della sessione
|
||||
|
||||
- `sessions.list` restituisce l'indice corrente delle sessioni.
|
||||
- `sessions.subscribe` e `sessions.unsubscribe` attivano/disattivano le sottoscrizioni agli eventi di modifica della sessione
|
||||
- `sessions.subscribe` e `sessions.unsubscribe` attivano o disattivano le sottoscrizioni agli eventi di modifica delle sessioni
|
||||
per il client WS corrente.
|
||||
- `sessions.messages.subscribe` e `sessions.messages.unsubscribe` attivano/disattivano
|
||||
le sottoscrizioni agli eventi di transcript/messaggi per una sessione.
|
||||
- `sessions.preview` restituisce anteprime limitate del transcript per specifiche chiavi di sessione.
|
||||
- `sessions.resolve` risolve o canonizza un target di sessione.
|
||||
- `sessions.messages.subscribe` e `sessions.messages.unsubscribe` attivano o disattivano
|
||||
le sottoscrizioni agli eventi di trascrizione/messaggio per una sessione.
|
||||
- `sessions.preview` restituisce anteprime limitate della trascrizione per specifiche
|
||||
chiavi di sessione.
|
||||
- `sessions.resolve` risolve o canonicalizza una destinazione di sessione.
|
||||
- `sessions.create` crea una nuova voce di sessione.
|
||||
- `sessions.send` invia un messaggio in una sessione esistente.
|
||||
- `sessions.steer` è la variante di interrompi-e-sterza per una sessione attiva.
|
||||
- `sessions.steer` è la variante interrupt-and-steer per una sessione attiva.
|
||||
- `sessions.abort` interrompe il lavoro attivo per una sessione.
|
||||
- `sessions.patch` aggiorna metadati/override della sessione.
|
||||
- `sessions.reset`, `sessions.delete` e `sessions.compact` eseguono manutenzione della sessione.
|
||||
- `sessions.get` restituisce l'intera riga di sessione memorizzata.
|
||||
- l'esecuzione della chat usa ancora `chat.history`, `chat.send`, `chat.abort` e
|
||||
- `sessions.patch` aggiorna i metadati/le override della sessione.
|
||||
- `sessions.reset`, `sessions.delete` e `sessions.compact` eseguono la manutenzione
|
||||
della sessione.
|
||||
- `sessions.get` restituisce la riga completa della sessione memorizzata.
|
||||
- l'esecuzione della chat continua a usare `chat.history`, `chat.send`, `chat.abort` e
|
||||
`chat.inject`.
|
||||
- `chat.history` è normalizzato per la visualizzazione per i client UI: i tag di direttiva inline vengono
|
||||
rimossi dal testo visibile, i payload XML di chiamata strumento in testo semplice (inclusi
|
||||
- `chat.history` è normalizzato per la visualizzazione per i client UI: i tag delle direttive inline vengono
|
||||
rimossi dal testo visibile, i payload XML plain-text delle tool call (inclusi
|
||||
`<tool_call>...</tool_call>`, `<function_call>...</function_call>`,
|
||||
`<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, e
|
||||
blocchi di chiamata strumento troncati) e i token di controllo del modello ASCII/full-width trapelati
|
||||
vengono rimossi, le righe dell'assistente composte solo da token silenziosi come esatto `NO_REPLY` /
|
||||
`no_reply` vengono omesse, e le righe troppo grandi possono essere sostituite con placeholder.
|
||||
`<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` e
|
||||
blocchi di tool call troncati) e i token di controllo del modello ASCII/full-width trapelati
|
||||
vengono rimossi, le righe dell'assistente composte solo da token silenziosi come `NO_REPLY` /
|
||||
`no_reply` esatti vengono omesse, e le righe troppo grandi possono essere sostituite con segnaposto.
|
||||
|
||||
#### Pairing del dispositivo e token del dispositivo
|
||||
#### Pairing dei dispositivi e token dispositivo
|
||||
|
||||
- `device.pair.list` restituisce i dispositivi associati in attesa e approvati.
|
||||
- `device.pair.approve`, `device.pair.reject` e `device.pair.remove` gestiscono
|
||||
i record di pairing del dispositivo.
|
||||
- `device.token.rotate` ruota un token di dispositivo associato entro i limiti di ruolo
|
||||
e ambito approvati.
|
||||
i record di pairing dei dispositivi.
|
||||
- `device.token.rotate` ruota un token di dispositivo associato entro i limiti del ruolo
|
||||
e degli ambiti approvati.
|
||||
- `device.token.revoke` revoca un token di dispositivo associato.
|
||||
|
||||
#### Pairing dei nodi, invoke e lavoro in sospeso
|
||||
|
||||
- `node.pair.request`, `node.pair.list`, `node.pair.approve`,
|
||||
`node.pair.reject` e `node.pair.verify` coprono il pairing dei nodi e la verifica
|
||||
del bootstrap.
|
||||
- `node.list` e `node.describe` restituiscono lo stato dei nodi noti/connessi.
|
||||
`node.pair.reject` e `node.pair.verify` coprono il pairing dei nodi e la
|
||||
verifica del bootstrap.
|
||||
- `node.list` e `node.describe` restituiscono lo stato dei nodi conosciuti/connessi.
|
||||
- `node.rename` aggiorna un'etichetta di nodo associato.
|
||||
- `node.invoke` inoltra un comando a un nodo connesso.
|
||||
- `node.invoke.result` restituisce il risultato di una richiesta invoke.
|
||||
- `node.event` trasporta eventi originati dal nodo di nuovo nel gateway.
|
||||
- `node.event` trasporta nel gateway gli eventi originati dal nodo.
|
||||
- `node.canvas.capability.refresh` aggiorna i token di capacità canvas con ambito.
|
||||
- `node.pending.pull` e `node.pending.ack` sono le API della coda dei nodi connessi.
|
||||
- `node.pending.enqueue` e `node.pending.drain` gestiscono il lavoro persistente in sospeso
|
||||
- `node.pending.pull` e `node.pending.ack` sono le API di coda dei nodi connessi.
|
||||
- `node.pending.enqueue` e `node.pending.drain` gestiscono il lavoro in sospeso durevole
|
||||
per nodi offline/disconnessi.
|
||||
|
||||
#### Famiglie di approvazione
|
||||
|
||||
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` e
|
||||
`exec.approval.resolve` coprono le richieste di approvazione exec one-shot più
|
||||
lookup/replay delle approvazioni in sospeso.
|
||||
- `exec.approval.waitDecision` attende una singola approvazione exec in sospeso e restituisce
|
||||
la decisione finale (o `null` in caso di timeout).
|
||||
- `exec.approvals.get` e `exec.approvals.set` gestiscono gli snapshot della policy di approvazione exec del gateway.
|
||||
- `exec.approvals.node.get` e `exec.approvals.node.set` gestiscono la policy di approvazione exec locale del nodo
|
||||
tramite comandi di relay del nodo.
|
||||
`exec.approval.resolve` coprono le richieste di approvazione exec one-shot più la
|
||||
ricerca/riproduzione delle approvazioni in sospeso.
|
||||
- `exec.approval.waitDecision` attende una decisione di approvazione exec in sospeso e restituisce
|
||||
la decisione finale (oppure `null` in caso di timeout).
|
||||
- `exec.approvals.get` e `exec.approvals.set` gestiscono gli snapshot della policy di approvazione exec
|
||||
del gateway.
|
||||
- `exec.approvals.node.get` e `exec.approvals.node.set` gestiscono la policy locale del nodo per exec
|
||||
tramite comandi relay del nodo.
|
||||
- `plugin.approval.request`, `plugin.approval.list`,
|
||||
`plugin.approval.waitDecision` e `plugin.approval.resolve` coprono
|
||||
i flussi di approvazione definiti dai plugin.
|
||||
|
||||
#### Altre principali famiglie
|
||||
#### Altre famiglie principali
|
||||
|
||||
- automazione:
|
||||
- `wake` pianifica un'iniezione di testo wake immediata o al successivo heartbeat
|
||||
- `wake` pianifica un'iniezione di testo wake immediata o al prossimo heartbeat
|
||||
- `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`,
|
||||
`cron.run`, `cron.runs`
|
||||
- skills/tools: `skills.*`, `tools.catalog`, `tools.effective`
|
||||
- skills/tool: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`
|
||||
|
||||
### Famiglie comuni di eventi
|
||||
|
||||
- `chat`: aggiornamenti della chat UI come `chat.inject` e altri eventi chat
|
||||
solo transcript.
|
||||
- `session.message` e `session.tool`: aggiornamenti del transcript/event-stream per una
|
||||
sessione sottoscritta.
|
||||
- `chat`: aggiornamenti della chat UI come `chat.inject` e altri eventi di chat
|
||||
solo di trascrizione.
|
||||
- `session.message` e `session.tool`: aggiornamenti dello stream di trascrizione/eventi per una sessione sottoscritta.
|
||||
- `sessions.changed`: l'indice della sessione o i metadati sono cambiati.
|
||||
- `presence`: aggiornamenti dello snapshot della presence di sistema.
|
||||
- `presence`: aggiornamenti dello snapshot della presenza di sistema.
|
||||
- `tick`: evento periodico di keepalive / liveness.
|
||||
- `health`: aggiornamento dello snapshot di health del gateway.
|
||||
- `heartbeat`: aggiornamento del flusso di eventi heartbeat.
|
||||
- `health`: aggiornamento dello snapshot di salute del gateway.
|
||||
- `heartbeat`: aggiornamento dello stream di eventi heartbeat.
|
||||
- `cron`: evento di modifica di esecuzione/job cron.
|
||||
- `shutdown`: notifica di arresto del gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved`: ciclo di vita del pairing dei nodi.
|
||||
- `shutdown`: notifica di spegnimento del gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved`: ciclo di vita del pairing del nodo.
|
||||
- `node.invoke.request`: broadcast di richiesta invoke del nodo.
|
||||
- `device.pair.requested` / `device.pair.resolved`: ciclo di vita del dispositivo associato.
|
||||
- `voicewake.changed`: la configurazione dei trigger della parola di attivazione è cambiata.
|
||||
- `voicewake.changed`: la configurazione dei trigger della wake-word è cambiata.
|
||||
- `exec.approval.requested` / `exec.approval.resolved`: ciclo di vita
|
||||
dell'approvazione exec.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`: ciclo di vita dell'approvazione del plugin.
|
||||
|
||||
### Metodi helper node
|
||||
### Metodi helper del nodo
|
||||
|
||||
- I nodi possono chiamare `skills.bins` per recuperare l'elenco corrente degli eseguibili delle skill
|
||||
per i controlli di auto-allow.
|
||||
|
||||
### Metodi helper operator
|
||||
### Metodi helper dell'operatore
|
||||
|
||||
- Gli operator possono chiamare `tools.catalog` (`operator.read`) per recuperare il catalogo runtime degli strumenti per un
|
||||
agente. La risposta include strumenti raggruppati e metadati di provenienza:
|
||||
- Gli operatori possono chiamare `commands.list` (`operator.read`) per recuperare l'inventario dei comandi runtime per un agente.
|
||||
- `agentId` è facoltativo; omettilo per leggere il workspace dell'agente predefinito.
|
||||
- `scope` controlla quale superficie viene presa di mira dal `name` primario:
|
||||
- `text` restituisce il token del comando testuale primario senza la barra iniziale `/`
|
||||
- `native` e il percorso predefinito `both` restituiscono nomi nativi aware del provider
|
||||
quando disponibili
|
||||
- `textAliases` contiene alias slash esatti come `/model` e `/m`.
|
||||
- `nativeName` contiene il nome del comando nativo aware del provider quando esiste.
|
||||
- `provider` è facoltativo e influisce solo sulla denominazione nativa più sulla disponibilità dei
|
||||
comandi nativi del plugin.
|
||||
- `includeArgs=false` omette dai risultati i metadati serializzati degli argomenti.
|
||||
- Gli operatori possono chiamare `tools.catalog` (`operator.read`) per recuperare il catalogo dei tool runtime per un
|
||||
agente. La risposta include tool raggruppati e metadati di provenienza:
|
||||
- `source`: `core` o `plugin`
|
||||
- `pluginId`: proprietario del plugin quando `source="plugin"`
|
||||
- `optional`: se uno strumento plugin è facoltativo
|
||||
- Gli operator possono chiamare `tools.effective` (`operator.read`) per recuperare l'inventario degli strumenti effettivo a runtime
|
||||
- `optional`: se un tool del plugin è facoltativo
|
||||
- Gli operatori possono chiamare `tools.effective` (`operator.read`) per recuperare l'inventario dei tool effettivo del runtime
|
||||
per una sessione.
|
||||
- `sessionKey` è obbligatorio.
|
||||
- Il gateway deriva il contesto runtime attendibile dalla sessione lato server invece di accettare
|
||||
auth o contesto di consegna forniti dal chiamante.
|
||||
- La risposta ha ambito di sessione e riflette ciò che la conversazione attiva può usare in questo momento,
|
||||
inclusi strumenti core, plugin e canale.
|
||||
- Gli operator possono chiamare `skills.status` (`operator.read`) per recuperare l'inventario visibile
|
||||
- Il gateway deriva il contesto runtime affidabile dalla sessione lato server invece di accettare
|
||||
contesto auth o di consegna fornito dal chiamante.
|
||||
- La risposta è limitata alla sessione e riflette ciò che la conversazione attiva può usare in questo momento,
|
||||
inclusi tool core, plugin e canali.
|
||||
- Gli operatori possono chiamare `skills.status` (`operator.read`) per recuperare l'inventario visibile
|
||||
delle skill per un agente.
|
||||
- `agentId` è facoltativo; omettilo per leggere il workspace dell'agente predefinito.
|
||||
- La risposta include idoneità, requisiti mancanti, controlli di configurazione e
|
||||
opzioni di installazione sanificate senza esporre valori segreti grezzi.
|
||||
- Gli operator possono chiamare `skills.search` e `skills.detail` (`operator.read`) per i metadati di discovery di
|
||||
ClawHub.
|
||||
- Gli operator possono chiamare `skills.install` (`operator.admin`) in due modalità:
|
||||
- Gli operatori possono chiamare `skills.search` e `skills.detail` (`operator.read`) per i
|
||||
metadati di discovery di ClawHub.
|
||||
- Gli operatori possono chiamare `skills.install` (`operator.admin`) in due modalità:
|
||||
- Modalità ClawHub: `{ source: "clawhub", slug, version?, force? }` installa una
|
||||
cartella skill nella directory `skills/` del workspace dell'agente predefinito.
|
||||
- Modalità installer gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
esegue un'azione dichiarata `metadata.openclaw.install` sull'host gateway.
|
||||
- Gli operator possono chiamare `skills.update` (`operator.admin`) in due modalità:
|
||||
- Modalità installer del gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
esegue un'azione dichiarata `metadata.openclaw.install` sull'host del gateway.
|
||||
- Gli operatori possono chiamare `skills.update` (`operator.admin`) in due modalità:
|
||||
- La modalità ClawHub aggiorna uno slug tracciato o tutte le installazioni ClawHub tracciate nel
|
||||
workspace dell'agente predefinito.
|
||||
- La modalità Config modifica i valori `skills.entries.<skillKey>` come `enabled`,
|
||||
`apiKey` ed `env`.
|
||||
- La modalità Config applica patch ai valori `skills.entries.<skillKey>` come `enabled`,
|
||||
`apiKey` e `env`.
|
||||
|
||||
## Approvazioni exec
|
||||
|
||||
- Quando una richiesta exec richiede approvazione, il gateway trasmette `exec.approval.requested`.
|
||||
- I client operator risolvono chiamando `exec.approval.resolve` (richiede ambito `operator.approvals`).
|
||||
- Per `host=node`, `exec.approval.request` deve includere `systemRunPlan` (`argv`/`cwd`/`rawCommand`/metadati di sessione canonici). Le richieste senza `systemRunPlan` vengono rifiutate.
|
||||
- Dopo l'approvazione, le chiamate `node.invoke system.run` inoltrate riutilizzano quel
|
||||
- Quando una richiesta exec necessita di approvazione, il gateway trasmette `exec.approval.requested`.
|
||||
- I client operatore risolvono chiamando `exec.approval.resolve` (richiede l'ambito `operator.approvals`).
|
||||
- Per `host=node`, `exec.approval.request` deve includere `systemRunPlan` (`argv`/`cwd`/`rawCommand`/metadati della sessione canonici). Le richieste senza `systemRunPlan` vengono rifiutate.
|
||||
- Dopo l'approvazione, le chiamate inoltrate `node.invoke system.run` riutilizzano quel
|
||||
`systemRunPlan` canonico come contesto autorevole di comando/cwd/sessione.
|
||||
- Se un chiamante modifica `command`, `rawCommand`, `cwd`, `agentId` o
|
||||
`sessionKey` tra prepare e l'inoltro finale approvato di `system.run`, il
|
||||
`sessionKey` tra `prepare` e l'inoltro finale approvato di `system.run`, il
|
||||
gateway rifiuta l'esecuzione invece di fidarsi del payload modificato.
|
||||
|
||||
## Fallback di consegna dell'agente
|
||||
|
||||
- Le richieste `agent` possono includere `deliver=true` per richiedere la consegna in uscita.
|
||||
- `bestEffortDeliver=false` mantiene il comportamento rigoroso: i target di consegna irrisolti o solo interni restituiscono `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` consente il fallback all'esecuzione solo-sessione quando non è possibile risolvere alcun percorso di consegna esterno (ad esempio sessioni internal/webchat o configurazioni multi-canale ambigue).
|
||||
- `bestEffortDeliver=false` mantiene il comportamento rigoroso: le destinazioni di consegna irrisolte o solo interne restituiscono `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` consente il fallback all'esecuzione solo in sessione quando non è possibile risolvere alcun percorso di consegna esterno (ad esempio sessioni interne/webchat o configurazioni multi-canale ambigue).
|
||||
|
||||
## Versioning
|
||||
|
||||
- `PROTOCOL_VERSION` si trova in `src/gateway/protocol/schema.ts`.
|
||||
- I client inviano `minProtocol` + `maxProtocol`; il server rifiuta i mismatch.
|
||||
- Schemi + modelli sono generati da definizioni TypeBox:
|
||||
- I client inviano `minProtocol` + `maxProtocol`; il server rifiuta le incompatibilità.
|
||||
- Schemi + modelli vengono generati a partire dalle definizioni TypeBox:
|
||||
- `pnpm protocol:gen`
|
||||
- `pnpm protocol:gen:swift`
|
||||
- `pnpm protocol:check`
|
||||
|
||||
## Auth
|
||||
|
||||
- L'autenticazione gateway con secret condiviso usa `connect.params.auth.token` o
|
||||
- L'auth del gateway con segreto condiviso usa `connect.params.auth.token` oppure
|
||||
`connect.params.auth.password`, a seconda della modalità auth configurata.
|
||||
- Le modalità con identità portante come Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) o `gateway.auth.mode: "trusted-proxy"` non-loopback
|
||||
soddisfano il controllo auth di connect dagli header della richiesta invece che da `connect.params.auth.*`.
|
||||
- L'ingresso privato `gateway.auth.mode: "none"` salta completamente l'auth connect con secret condiviso; non esporre quella modalità su ingressi pubblici/non attendibili.
|
||||
- Dopo il pairing, il gateway emette un **token del dispositivo** con ambito del ruolo + degli ambiti della connessione. Viene restituito in `hello-ok.auth.deviceToken` e dovrebbe essere
|
||||
- Le modalità che trasportano identità, come Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) o `gateway.auth.mode: "trusted-proxy"`
|
||||
su endpoint non-loopback, soddisfano il controllo auth di connessione dagli header
|
||||
della richiesta invece che da `connect.params.auth.*`.
|
||||
- `gateway.auth.mode: "none"` su ingressi privati salta completamente l'auth di connessione con segreto condiviso; non esporre questa modalità su ingressi pubblici/non affidabili.
|
||||
- Dopo il pairing, il Gateway emette un **token dispositivo** limitato al ruolo + agli ambiti della connessione. Viene restituito in `hello-ok.auth.deviceToken` e deve essere
|
||||
persistito dal client per le connessioni future.
|
||||
- I client dovrebbero persistere il `hello-ok.auth.deviceToken` primario dopo ogni
|
||||
- I client devono persistere il `hello-ok.auth.deviceToken` primario dopo ogni
|
||||
connessione riuscita.
|
||||
- La riconnessione con quel token del dispositivo **memorizzato** dovrebbe anche riutilizzare l'insieme di ambiti approvati memorizzato
|
||||
per quel token. Questo preserva l'accesso in lettura/probe/stato
|
||||
già concesso ed evita di ridurre silenziosamente le riconnessioni a un
|
||||
ambito implicito più ristretto solo admin.
|
||||
- La normale precedenza auth di connect è prima token/password condivisi espliciti, poi
|
||||
- La riconnessione con quel token dispositivo **memorizzato** deve anche riutilizzare l'insieme di ambiti approvati memorizzato per quel token. Questo preserva l'accesso
|
||||
già concesso in lettura/probe/status ed evita che le riconnessioni si riducano silenziosamente a un
|
||||
ambito implicito solo admin più ristretto.
|
||||
- La precedenza auth normale della connessione è: token/password condiviso esplicito per primo, poi
|
||||
`deviceToken` esplicito, poi token per dispositivo memorizzato, poi token di bootstrap.
|
||||
- Le voci aggiuntive `hello-ok.auth.deviceTokens` sono token di passaggio bootstrap.
|
||||
Persistile solo quando la connessione ha usato auth bootstrap su un trasporto attendibile
|
||||
come `wss://` o pairing loopback/locale.
|
||||
- Se un client fornisce un **`deviceToken` esplicito** o `scopes` espliciti, quell'insieme di ambiti richiesto dal chiamante resta autorevole; gli ambiti in cache vengono riutilizzati solo
|
||||
quando il client sta riutilizzando il token per dispositivo memorizzato.
|
||||
- I token del dispositivo possono essere ruotati/revocati tramite `device.token.rotate` e
|
||||
`device.token.revoke` (richiede ambito `operator.pairing`).
|
||||
- L'emissione/rotazione dei token resta limitata all'insieme di ruoli approvati registrato nella
|
||||
voce di pairing di quel dispositivo; ruotare un token non può espandere il dispositivo in un
|
||||
- Le voci aggiuntive `hello-ok.auth.deviceTokens` sono token di handoff del bootstrap.
|
||||
Persistile solo quando la connessione ha usato auth di bootstrap su un trasporto affidabile
|
||||
come `wss://` o loopback/pairing locale.
|
||||
- Se un client fornisce un `deviceToken` **esplicito** o `scopes` espliciti, quell'insieme di ambiti richiesto dal chiamante rimane autorevole; gli ambiti in cache vengono riutilizzati solo quando il client sta riutilizzando il token per dispositivo memorizzato.
|
||||
- I token dispositivo possono essere ruotati/revocati tramite `device.token.rotate` e
|
||||
`device.token.revoke` (richiede l'ambito `operator.pairing`).
|
||||
- L'emissione/la rotazione dei token rimane limitata all'insieme di ruoli approvato registrato nella
|
||||
voce di pairing di quel dispositivo; la rotazione di un token non può espandere il dispositivo a un
|
||||
ruolo che l'approvazione del pairing non ha mai concesso.
|
||||
- Per le sessioni token di dispositivo associato, la gestione del dispositivo ha ambito proprio salvo che il
|
||||
chiamante abbia anche `operator.admin`: i chiamanti non-admin possono rimuovere/revocare/ruotare
|
||||
solo la **propria** voce dispositivo.
|
||||
- `device.token.rotate` controlla anche l'insieme di ambiti operator richiesto rispetto agli
|
||||
ambiti della sessione corrente del chiamante. I chiamanti non-admin non possono ruotare un token in un insieme di ambiti operator più ampio di quello che già possiedono.
|
||||
- I fallimenti auth includono `error.details.code` più suggerimenti di recupero:
|
||||
- Per le sessioni di token di dispositivi associati, la gestione del dispositivo è limitata al proprio ambito a meno che il
|
||||
chiamante non abbia anche `operator.admin`: i chiamanti non admin possono rimuovere/revocare/ruotare
|
||||
solo la **propria** voce di dispositivo.
|
||||
- `device.token.rotate` controlla anche l'insieme di ambiti operatore richiesto rispetto agli
|
||||
ambiti della sessione corrente del chiamante. I chiamanti non admin non possono ruotare un token verso
|
||||
un insieme di ambiti operatore più ampio di quello che già possiedono.
|
||||
- I fallimenti auth includono `error.details.code` più suggerimenti per il recupero:
|
||||
- `error.details.canRetryWithDeviceToken` (boolean)
|
||||
- `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)
|
||||
- Comportamento del client per `AUTH_TOKEN_MISMATCH`:
|
||||
- I client attendibili possono tentare un unico retry limitato con un token per dispositivo in cache.
|
||||
- I client affidabili possono tentare un singolo retry limitato con un token per dispositivo in cache.
|
||||
- Se quel retry fallisce, i client devono interrompere i loop di riconnessione automatica e mostrare indicazioni per l'azione dell'operatore.
|
||||
|
||||
## Identità del dispositivo + pairing
|
||||
|
||||
- I nodi devono includere un'identità del dispositivo stabile (`device.id`) derivata da un
|
||||
- I nodi devono includere un'identità del dispositivo stabile (`device.id`) derivata da una
|
||||
fingerprint della coppia di chiavi.
|
||||
- I gateway emettono token per dispositivo + ruolo.
|
||||
- Le approvazioni di pairing sono richieste per nuovi ID dispositivo a meno che non sia abilitata
|
||||
l'auto-approvazione locale.
|
||||
- L'auto-approvazione del pairing è centrata sulle connessioni dirette local loopback.
|
||||
- OpenClaw ha anche un percorso ristretto di self-connect backend/container-local per
|
||||
flussi helper attendibili con secret condiviso.
|
||||
- Le approvazioni di pairing sono richieste per i nuovi ID dispositivo a meno che l'approvazione automatica locale
|
||||
non sia abilitata.
|
||||
- L'approvazione automatica del pairing è incentrata sulle connessioni dirette local loopback.
|
||||
- OpenClaw ha anche un percorso self-connect backend/container-local limitato per
|
||||
flussi helper affidabili con segreto condiviso.
|
||||
- Le connessioni tailnet o LAN sullo stesso host sono comunque trattate come remote per il pairing e
|
||||
richiedono approvazione.
|
||||
- Tutti i client WS devono includere l'identità `device` durante `connect` (operator + node).
|
||||
Control UI può ometterla solo in queste modalità:
|
||||
- `gateway.controlUi.allowInsecureAuth=true` per compatibilità localhost-only con HTTP insicuro.
|
||||
- `gateway.controlUi.allowInsecureAuth=true` per compatibilità HTTP non sicura solo localhost.
|
||||
- auth operator Control UI riuscita con `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (break-glass, grave downgrade della sicurezza).
|
||||
- Tutte le connessioni devono firmare il nonce `connect.challenge` fornito dal server.
|
||||
|
||||
### Diagnostica di migrazione auth del dispositivo
|
||||
### Diagnostica della migrazione dell'auth del dispositivo
|
||||
|
||||
Per i client legacy che usano ancora il comportamento di firma pre-challenge, `connect` ora restituisce
|
||||
codici di dettaglio `DEVICE_AUTH_*` sotto `error.details.code` con un `error.details.reason` stabile.
|
||||
|
||||
Fallimenti di migrazione comuni:
|
||||
Errori di migrazione comuni:
|
||||
|
||||
| Messaggio | details.code | details.reason | Significato |
|
||||
| ---------------------------- | -------------------------------- | ------------------------ | --------------------------------------------------- |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Il client ha omesso `device.nonce` (o lo ha inviato vuoto). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Il client ha firmato con un nonce vecchio/errato. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Il payload della firma non corrisponde al payload v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Il timestamp firmato è fuori dallo skew consentito. |
|
||||
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` non corrisponde al fingerprint della chiave pubblica. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Il formato/canonicalizzazione della chiave pubblica non è riuscito. |
|
||||
| Messaggio | details.code | details.reason | Significato |
|
||||
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Il client ha omesso `device.nonce` (o lo ha inviato vuoto). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Il client ha firmato con un nonce obsoleto/errato. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Il payload della firma non corrisponde al payload v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Il timestamp firmato è fuori dallo skew consentito. |
|
||||
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` non corrisponde alla fingerprint della chiave pubblica. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Il formato/canonicalizzazione della chiave pubblica non è riuscito. |
|
||||
|
||||
Obiettivo della migrazione:
|
||||
|
||||
@ -569,16 +579,17 @@ Obiettivo della migrazione:
|
||||
- Inviare lo stesso nonce in `connect.params.device.nonce`.
|
||||
- Il payload di firma preferito è `v3`, che vincola `platform` e `deviceFamily`
|
||||
oltre ai campi device/client/role/scopes/token/nonce.
|
||||
- Le firme legacy `v2` restano accettate per compatibilità, ma il pinning dei metadati del dispositivo associato continua a controllare la policy dei comandi alla riconnessione.
|
||||
- Le firme legacy `v2` restano accettate per compatibilità, ma il pinning dei metadati
|
||||
del dispositivo associato continua a controllare la policy dei comandi alla riconnessione.
|
||||
|
||||
## TLS + pinning
|
||||
|
||||
- TLS è supportato per le connessioni WS.
|
||||
- I client possono opzionalmente fissare il fingerprint del certificato del gateway (vedi config `gateway.tls`
|
||||
più `gateway.remote.tlsFingerprint` o CLI `--tls-fingerprint`).
|
||||
- I client possono facoltativamente fare pinning della fingerprint del certificato del gateway (vedi configurazione `gateway.tls`
|
||||
più `gateway.remote.tlsFingerprint` o il flag CLI `--tls-fingerprint`).
|
||||
|
||||
## Ambito
|
||||
|
||||
Questo protocollo espone la **API completa del gateway** (status, channels, models, chat,
|
||||
Questo protocollo espone l'**API completa del gateway** (status, channels, models, chat,
|
||||
agent, sessions, nodes, approvals, ecc.). La superficie esatta è definita dagli
|
||||
schemi TypeBox in `src/gateway/protocol/schema.ts`.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,43 +1,54 @@
|
||||
---
|
||||
read_when:
|
||||
- Vuoi configurare provider di memory search o modelli di embedding
|
||||
- Vuoi configurare i provider di ricerca nella memoria o i modelli di embedding
|
||||
- Vuoi configurare il backend QMD
|
||||
- Vuoi regolare la ricerca ibrida, MMR o il decadimento temporale
|
||||
- Vuoi abilitare l'indicizzazione memory multimodale
|
||||
summary: Tutte le opzioni di configurazione per memory search, provider di embedding, QMD, ricerca ibrida e indicizzazione multimodale
|
||||
title: Riferimento della configurazione memory
|
||||
- Vuoi ottimizzare la ricerca ibrida, MMR o il decadimento temporale
|
||||
- Vuoi abilitare l'indicizzazione multimodale della memoria
|
||||
summary: Tutte le opzioni di configurazione per la ricerca nella memoria, i provider di embedding, QMD, la ricerca ibrida e l'indicizzazione multimodale
|
||||
title: Riferimento della configurazione della memoria
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T03:12:17Z"
|
||||
generated_at: "2026-04-10T08:13:49Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0de0b85125443584f4e575cf673ca8d9bd12ecd849d73c537f4a17545afa93fd
|
||||
source_hash: 5f9076bdfad95b87bd70625821bf401326f8eaeb53842b70823881419dbe43cb
|
||||
source_path: reference/memory-config.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Riferimento della configurazione memory
|
||||
# Riferimento della configurazione della memoria
|
||||
|
||||
Questa pagina elenca ogni opzione di configurazione per memory search di OpenClaw. Per
|
||||
le panoramiche concettuali, vedi:
|
||||
Questa pagina elenca tutte le opzioni di configurazione per la ricerca nella memoria di OpenClaw. Per panoramiche concettuali, vedi:
|
||||
|
||||
- [Panoramica memory](/it/concepts/memory) -- come funziona memory
|
||||
- [Panoramica della memoria](/it/concepts/memory) -- come funziona la memoria
|
||||
- [Motore integrato](/it/concepts/memory-builtin) -- backend SQLite predefinito
|
||||
- [Motore QMD](/it/concepts/memory-qmd) -- sidecar local-first
|
||||
- [Memory Search](/it/concepts/memory-search) -- pipeline di ricerca e regolazione
|
||||
- [Motore QMD](/it/concepts/memory-qmd) -- sidecar locale-first
|
||||
- [Ricerca nella memoria](/it/concepts/memory-search) -- pipeline di ricerca e ottimizzazione
|
||||
- [Memoria attiva](/it/concepts/active-memory) -- abilitazione del sub-agente di memoria per sessioni interattive
|
||||
|
||||
Tutte le impostazioni di memory search si trovano in `agents.defaults.memorySearch` in
|
||||
Tutte le impostazioni della ricerca nella memoria si trovano in `agents.defaults.memorySearch` in
|
||||
`openclaw.json`, salvo diversa indicazione.
|
||||
|
||||
Se stai cercando l'interruttore della funzionalità **memoria attiva** e la configurazione del sub-agente,
|
||||
si trovano in `plugins.entries.active-memory` invece che in `memorySearch`.
|
||||
|
||||
La memoria attiva usa un modello a due condizioni:
|
||||
|
||||
1. il plugin deve essere abilitato e avere come destinazione l'ID dell'agente corrente
|
||||
2. la richiesta deve essere una sessione di chat interattiva persistente idonea
|
||||
|
||||
Vedi [Memoria attiva](/it/concepts/active-memory) per il modello di attivazione,
|
||||
la configurazione gestita dal plugin, la persistenza delle trascrizioni e il modello di distribuzione sicura.
|
||||
|
||||
---
|
||||
|
||||
## Selezione del provider
|
||||
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------ |
|
||||
| `provider` | `string` | rilevato automaticamente | ID adattatore di embedding: `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` |
|
||||
| `provider` | `string` | rilevato automaticamente | ID dell'adapter di embedding: `openai`, `gemini`, `voyage`, `mistral`, `bedrock`, `ollama`, `local` |
|
||||
| `model` | `string` | predefinito del provider | Nome del modello di embedding |
|
||||
| `fallback` | `string` | `"none"` | ID adattatore di fallback quando il primario fallisce |
|
||||
| `enabled` | `boolean` | `true` | Abilita o disabilita memory search |
|
||||
| `fallback` | `string` | `"none"` | ID dell'adapter di fallback quando quello primario fallisce |
|
||||
| `enabled` | `boolean` | `true` | Abilita o disabilita la ricerca nella memoria |
|
||||
|
||||
### Ordine di rilevamento automatico
|
||||
|
||||
@ -48,26 +59,26 @@ Quando `provider` non è impostato, OpenClaw seleziona il primo disponibile:
|
||||
3. `gemini` -- se è possibile risolvere una chiave Gemini.
|
||||
4. `voyage` -- se è possibile risolvere una chiave Voyage.
|
||||
5. `mistral` -- se è possibile risolvere una chiave Mistral.
|
||||
6. `bedrock` -- se la catena di credenziali AWS SDK viene risolta (ruolo istanza, chiavi di accesso, profilo, SSO, web identity o configurazione condivisa).
|
||||
6. `bedrock` -- se la catena di credenziali dell'SDK AWS viene risolta (ruolo dell'istanza, chiavi di accesso, profilo, SSO, web identity o configurazione condivisa).
|
||||
|
||||
`ollama` è supportato ma non viene rilevato automaticamente (impostalo esplicitamente).
|
||||
|
||||
### Risoluzione della chiave API
|
||||
|
||||
Gli embedding remoti richiedono una chiave API. Bedrock usa invece la catena predefinita
|
||||
di credenziali AWS SDK (ruoli istanza, SSO, chiavi di accesso).
|
||||
Gli embeddings remoti richiedono una chiave API. Bedrock usa invece la catena
|
||||
di credenziali predefinita dell'SDK AWS (ruoli dell'istanza, SSO, chiavi di accesso).
|
||||
|
||||
| Provider | Variabile d'ambiente | Chiave di configurazione |
|
||||
| -------- | ---------------------------- | --------------------------------- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
|
||||
| Bedrock | catena di credenziali AWS | Nessuna chiave API necessaria |
|
||||
| Ollama | `OLLAMA_API_KEY` (segnaposto) | -- |
|
||||
| Provider | Variabile d'ambiente | Chiave di configurazione |
|
||||
| -------- | ------------------------------ | --------------------------------- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
|
||||
| Bedrock | catena di credenziali AWS | Nessuna chiave API necessaria |
|
||||
| Ollama | `OLLAMA_API_KEY` (segnaposto) | -- |
|
||||
|
||||
Codex OAuth copre solo chat/completions e non soddisfa le
|
||||
richieste di embedding.
|
||||
OAuth di Codex copre solo chat/completions e non soddisfa le richieste
|
||||
di embedding.
|
||||
|
||||
---
|
||||
|
||||
@ -75,11 +86,11 @@ richieste di embedding.
|
||||
|
||||
Per endpoint personalizzati compatibili con OpenAI o per sovrascrivere i valori predefiniti del provider:
|
||||
|
||||
| Chiave | Tipo | Descrizione |
|
||||
| ----------------- | -------- | ---------------------------------------------------- |
|
||||
| `remote.baseUrl` | `string` | URL base API personalizzato |
|
||||
| `remote.apiKey` | `string` | Sovrascrive la chiave API |
|
||||
| `remote.headers` | `object` | Header HTTP aggiuntivi (uniti ai valori predefiniti del provider) |
|
||||
| Chiave | Tipo | Descrizione |
|
||||
| ---------------- | -------- | ------------------------------------------------ |
|
||||
| `remote.baseUrl` | `string` | URL base API personalizzato |
|
||||
| `remote.apiKey` | `string` | Sovrascrive la chiave API |
|
||||
| `remote.headers` | `object` | Header HTTP aggiuntivi (uniti a quelli predefiniti del provider) |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -102,21 +113,21 @@ Per endpoint personalizzati compatibili con OpenAI o per sovrascrivere i valori
|
||||
|
||||
## Configurazione specifica di Gemini
|
||||
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ---------------------- | -------- | ---------------------- | ------------------------------------------ |
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ---------------------- | -------- | --------------------- | ------------------------------------------ |
|
||||
| `model` | `string` | `gemini-embedding-001` | Supporta anche `gemini-embedding-2-preview` |
|
||||
| `outputDimensionality` | `number` | `3072` | Per Embedding 2: 768, 1536 o 3072 |
|
||||
| `outputDimensionality` | `number` | `3072` | Per Embedding 2: 768, 1536 o 3072 |
|
||||
|
||||
<Warning>
|
||||
Cambiare il modello o `outputDimensionality` attiva automaticamente una reindicizzazione completa.
|
||||
La modifica di `model` o `outputDimensionality` attiva automaticamente una reindicizzazione completa.
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Configurazione degli embedding Bedrock
|
||||
|
||||
Bedrock usa la catena predefinita di credenziali AWS SDK -- non servono chiavi API.
|
||||
Se OpenClaw viene eseguito su EC2 con un ruolo di istanza Bedrock-enabled, basta impostare
|
||||
Bedrock usa la catena di credenziali predefinita dell'SDK AWS -- non servono chiavi API.
|
||||
Se OpenClaw viene eseguito su EC2 con un ruolo dell'istanza abilitato per Bedrock, imposta semplicemente
|
||||
provider e modello:
|
||||
|
||||
```json5
|
||||
@ -132,48 +143,48 @@ provider e modello:
|
||||
}
|
||||
```
|
||||
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ---------------------- | -------- | ------------------------------ | ------------------------------ |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | Qualsiasi ID modello embedding Bedrock |
|
||||
| `outputDimensionality` | `number` | predefinito del modello | Per Titan V2: 256, 512 o 1024 |
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ---------------------- | -------- | ----------------------------- | ------------------------------ |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | Qualsiasi ID di modello di embedding Bedrock |
|
||||
| `outputDimensionality` | `number` | predefinito del modello | Per Titan V2: 256, 512 o 1024 |
|
||||
|
||||
### Modelli supportati
|
||||
|
||||
Sono supportati i seguenti modelli (con rilevamento della famiglia e valori predefiniti
|
||||
delle dimensioni):
|
||||
Sono supportati i seguenti modelli (con rilevamento della famiglia e dimensioni
|
||||
predefinite):
|
||||
|
||||
| ID modello | Provider | Dim predefinite | Dim configurabili |
|
||||
| ------------------------------------------ | ---------- | --------------- | --------------------- |
|
||||
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
|
||||
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
|
||||
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
|
||||
| `cohere.embed-english-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
|
||||
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
|
||||
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
|
||||
| ID modello | Provider | Dim predefinite | Dim configurabili |
|
||||
| ------------------------------------------- | ---------- | --------------- | --------------------- |
|
||||
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 |
|
||||
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
|
||||
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 |
|
||||
| `cohere.embed-english-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
|
||||
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
|
||||
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
|
||||
|
||||
Le varianti con suffisso di throughput (ad esempio `amazon.titan-embed-text-v1:2:8k`) ereditano
|
||||
la configurazione del modello base.
|
||||
la configurazione del modello di base.
|
||||
|
||||
### Autenticazione
|
||||
|
||||
L'autenticazione Bedrock usa l'ordine standard di risoluzione delle credenziali AWS SDK:
|
||||
L'autenticazione Bedrock usa l'ordine standard di risoluzione delle credenziali dell'SDK AWS:
|
||||
|
||||
1. Variabili d'ambiente (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)
|
||||
2. Cache dei token SSO
|
||||
3. Credenziali del token web identity
|
||||
4. File condivisi di credenziali e configurazione
|
||||
5. Credenziali metadata ECS o EC2
|
||||
5. Credenziali dei metadati ECS o EC2
|
||||
|
||||
La regione viene risolta da `AWS_REGION`, `AWS_DEFAULT_REGION`, dal
|
||||
`baseUrl` del provider `amazon-bedrock`, oppure usa `us-east-1` come predefinito.
|
||||
`baseUrl` del provider `amazon-bedrock`, oppure per impostazione predefinita da `us-east-1`.
|
||||
|
||||
### Permessi IAM
|
||||
|
||||
Il ruolo o l'utente IAM richiede:
|
||||
Il ruolo o l'utente IAM deve avere:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -193,42 +204,42 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
|
||||
## Configurazione degli embedding locali
|
||||
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| --------------------- | -------- | ------------------------ | ----------------------------- |
|
||||
| `local.modelPath` | `string` | scaricato automaticamente | Percorso del file modello GGUF |
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| --------------------- | -------- | ------------------------ | ----------------------------------- |
|
||||
| `local.modelPath` | `string` | scaricato automaticamente | Percorso del file del modello GGUF |
|
||||
| `local.modelCacheDir` | `string` | predefinito di node-llama-cpp | Directory cache per i modelli scaricati |
|
||||
|
||||
Modello predefinito: `embeddinggemma-300m-qat-Q8_0.gguf` (~0,6 GB, scaricato automaticamente).
|
||||
Richiede build nativa: `pnpm approve-builds` poi `pnpm rebuild node-llama-cpp`.
|
||||
Richiede una build nativa: `pnpm approve-builds` poi `pnpm rebuild node-llama-cpp`.
|
||||
|
||||
---
|
||||
|
||||
## Configurazione della ricerca ibrida
|
||||
|
||||
Tutto in `memorySearch.query.hybrid`:
|
||||
Tutto sotto `memorySearch.query.hybrid`:
|
||||
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| --------------------- | --------- | ----------- | ----------------------------------- |
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| --------------------- | --------- | ----------- | ------------------------------------- |
|
||||
| `enabled` | `boolean` | `true` | Abilita la ricerca ibrida BM25 + vettoriale |
|
||||
| `vectorWeight` | `number` | `0.7` | Peso dei punteggi vettoriali (0-1) |
|
||||
| `textWeight` | `number` | `0.3` | Peso dei punteggi BM25 (0-1) |
|
||||
| `vectorWeight` | `number` | `0.7` | Peso per i punteggi vettoriali (0-1) |
|
||||
| `textWeight` | `number` | `0.3` | Peso per i punteggi BM25 (0-1) |
|
||||
| `candidateMultiplier` | `number` | `4` | Moltiplicatore della dimensione del pool di candidati |
|
||||
|
||||
### MMR (diversità)
|
||||
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ------------- | --------- | ----------- | ---------------------------------------- |
|
||||
| `mmr.enabled` | `boolean` | `false` | Abilita il riordinamento MMR |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = massima diversità, 1 = massima rilevanza |
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ------------- | --------- | ----------- | ----------------------------------------- |
|
||||
| `mmr.enabled` | `boolean` | `false` | Abilita il riordinamento MMR |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = massima diversità, 1 = massima pertinenza |
|
||||
|
||||
### Decadimento temporale (recency)
|
||||
### Decadimento temporale (recenza)
|
||||
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ---------------------------- | --------- | ----------- | ------------------------------ |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | Abilita il boost di recency |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | Abilita il boost di recenza |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | Il punteggio si dimezza ogni N giorni |
|
||||
|
||||
I file evergreen (`MEMORY.md`, file non datati in `memory/`) non decadono mai.
|
||||
I file sempre validi (`MEMORY.md`, file non datati in `memory/`) non subiscono mai decadimento.
|
||||
|
||||
### Esempio completo
|
||||
|
||||
@ -253,7 +264,7 @@ I file evergreen (`MEMORY.md`, file non datati in `memory/`) non decadono mai.
|
||||
|
||||
---
|
||||
|
||||
## Percorsi memory aggiuntivi
|
||||
## Percorsi di memoria aggiuntivi
|
||||
|
||||
| Chiave | Tipo | Descrizione |
|
||||
| ------------ | ---------- | ---------------------------------------- |
|
||||
@ -273,10 +284,10 @@ I file evergreen (`MEMORY.md`, file non datati in `memory/`) non decadono mai.
|
||||
|
||||
I percorsi possono essere assoluti o relativi al workspace. Le directory vengono analizzate
|
||||
ricorsivamente per i file `.md`. La gestione dei symlink dipende dal backend attivo:
|
||||
il motore integrato ignora i symlink, mentre QMD segue il comportamento dello scanner QMD
|
||||
sottostante.
|
||||
il motore integrato ignora i symlink, mentre QMD segue il comportamento dello
|
||||
scanner QMD sottostante.
|
||||
|
||||
Per la ricerca di transcript cross-agent scoped per agente, usa
|
||||
Per la ricerca nelle trascrizioni cross-agent con ambito agente, usa
|
||||
`agents.list[].memorySearch.qmd.extraCollections` invece di `memory.qmd.paths`.
|
||||
Queste raccolte aggiuntive seguono la stessa forma `{ path, name, pattern? }`, ma
|
||||
vengono unite per agente e possono preservare nomi condivisi espliciti quando il percorso
|
||||
@ -287,17 +298,17 @@ duplicato.
|
||||
|
||||
---
|
||||
|
||||
## Memory multimodale (Gemini)
|
||||
## Memoria multimodale (Gemini)
|
||||
|
||||
Indicizza immagini e audio insieme a Markdown usando Gemini Embedding 2:
|
||||
Indicizza immagini e audio insieme al Markdown usando Gemini Embedding 2:
|
||||
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ------------------------- | ---------- | ----------- | ---------------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | Abilita l'indicizzazione multimodale |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` o `["all"]` |
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ------------------------- | ---------- | ----------- | -------------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | Abilita l'indicizzazione multimodale |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` o `["all"]` |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | Dimensione massima del file per l'indicizzazione |
|
||||
|
||||
Si applica solo ai file in `extraPaths`. Le radici memory predefinite restano solo Markdown.
|
||||
Si applica solo ai file in `extraPaths`. Le radici di memoria predefinite restano solo Markdown.
|
||||
Richiede `gemini-embedding-2-preview`. `fallback` deve essere `"none"`.
|
||||
|
||||
Formati supportati: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif`
|
||||
@ -307,65 +318,65 @@ Formati supportati: `.jpg`, `.jpeg`, `.png`, `.webp`, `.gif`, `.heic`, `.heif`
|
||||
|
||||
## Cache degli embedding
|
||||
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ------------------ | --------- | ----------- | ----------------------------------- |
|
||||
| `cache.enabled` | `boolean` | `false` | Memorizza nella cache gli embedding dei chunk in SQLite |
|
||||
| `cache.maxEntries` | `number` | `50000` | Numero massimo di embedding in cache |
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ------------------ | --------- | ----------- | ------------------------------ |
|
||||
| `cache.enabled` | `boolean` | `false` | Memorizza nella cache gli embeddings dei blocchi in SQLite |
|
||||
| `cache.maxEntries` | `number` | `50000` | Numero massimo di embeddings in cache |
|
||||
|
||||
Impedisce il ri-embedding del testo invariato durante reindicizzazione o aggiornamenti dei transcript.
|
||||
Evita di ricalcolare gli embedding per testo invariato durante la reindicizzazione o gli aggiornamenti delle trascrizioni.
|
||||
|
||||
---
|
||||
|
||||
## Indicizzazione batch
|
||||
## Indicizzazione in batch
|
||||
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ----------------------------- | --------- | ----------- | -------------------------------- |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | Abilita l'API di embedding batch |
|
||||
| `remote.batch.concurrency` | `number` | `2` | Job batch paralleli |
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ----------------------------- | --------- | ----------- | ------------------------------- |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | Abilita l'API di embedding in batch |
|
||||
| `remote.batch.concurrency` | `number` | `2` | Job batch paralleli |
|
||||
| `remote.batch.wait` | `boolean` | `true` | Attende il completamento del batch |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | Intervallo di polling |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | Timeout del batch |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | Intervallo di polling |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | Timeout del batch |
|
||||
|
||||
Disponibile per `openai`, `gemini` e `voyage`. Il batch OpenAI è di solito
|
||||
il più rapido ed economico per grandi backfill.
|
||||
Disponibile per `openai`, `gemini` e `voyage`. Il batch OpenAI è in genere
|
||||
il più rapido e conveniente per grandi backfill.
|
||||
|
||||
---
|
||||
|
||||
## Session memory search (sperimentale)
|
||||
## Ricerca nella memoria di sessione (sperimentale)
|
||||
|
||||
Indicizza i transcript di sessione e li espone tramite `memory_search`:
|
||||
Indicizza le trascrizioni delle sessioni e le rende disponibili tramite `memory_search`:
|
||||
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ----------------------------- | ---------- | ------------- | ----------------------------------------- |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | Abilita l'indicizzazione delle sessioni |
|
||||
| `sources` | `string[]` | `["memory"]` | Aggiungi `"sessions"` per includere i transcript |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | Soglia in byte per la reindicizzazione |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | Soglia in messaggi per la reindicizzazione |
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ----------------------------- | ---------- | ------------ | ---------------------------------------- |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | Abilita l'indicizzazione delle sessioni |
|
||||
| `sources` | `string[]` | `["memory"]` | Aggiungi `"sessions"` per includere le trascrizioni |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | Soglia in byte per la reindicizzazione |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | Soglia in messaggi per la reindicizzazione |
|
||||
|
||||
L'indicizzazione delle sessioni è opt-in e viene eseguita in modo asincrono. I risultati possono essere leggermente
|
||||
obsoleti. I log di sessione vivono su disco, quindi considera l'accesso al filesystem come il
|
||||
confine di trust.
|
||||
L'indicizzazione delle sessioni è su base opt-in e viene eseguita in modo asincrono. I risultati possono essere leggermente
|
||||
non aggiornati. I log delle sessioni sono archiviati su disco, quindi considera l'accesso al filesystem come confine
|
||||
di attendibilità.
|
||||
|
||||
---
|
||||
|
||||
## Accelerazione vettoriale SQLite (sqlite-vec)
|
||||
## Accelerazione vettoriale SQLite (`sqlite-vec`)
|
||||
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ---------------------------- | --------- | ----------- | ----------------------------------- |
|
||||
| `store.vector.enabled` | `boolean` | `true` | Usa sqlite-vec per le query vettoriali |
|
||||
| `store.vector.extensionPath` | `string` | bundled | Sovrascrive il percorso sqlite-vec |
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| -------------------------- | --------- | ----------- | -------------------------------------- |
|
||||
| `store.vector.enabled` | `boolean` | `true` | Usa `sqlite-vec` per le query vettoriali |
|
||||
| `store.vector.extensionPath` | `string` | bundled | Sovrascrive il percorso di `sqlite-vec` |
|
||||
|
||||
Quando sqlite-vec non è disponibile, OpenClaw ripiega automaticamente sulla
|
||||
Quando `sqlite-vec` non è disponibile, OpenClaw usa automaticamente come fallback la
|
||||
similarità coseno in-process.
|
||||
|
||||
---
|
||||
|
||||
## Archiviazione dell'indice
|
||||
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| --------------------- | -------- | ------------------------------------- | ------------------------------------------- |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Posizione dell'indice (supporta il token `{agentId}`) |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizer FTS5 (`unicode61` o `trigram`) |
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| -------------------- | -------- | ------------------------------------ | -------------------------------------------- |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Posizione dell'indice (supporta il token `{agentId}`) |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | Tokenizer FTS5 (`unicode61` o `trigram`) |
|
||||
|
||||
---
|
||||
|
||||
@ -380,17 +391,18 @@ Imposta `memory.backend = "qmd"` per abilitarlo. Tutte le impostazioni QMD si tr
|
||||
| `searchMode` | `string` | `search` | Comando di ricerca: `search`, `vsearch`, `query` |
|
||||
| `includeDefaultMemory` | `boolean` | `true` | Indicizza automaticamente `MEMORY.md` + `memory/**/*.md` |
|
||||
| `paths[]` | `array` | -- | Percorsi aggiuntivi: `{ name, path, pattern? }` |
|
||||
| `sessions.enabled` | `boolean` | `false` | Indicizza i transcript di sessione |
|
||||
| `sessions.retentionDays` | `number` | -- | Conservazione dei transcript |
|
||||
| `sessions.enabled` | `boolean` | `false` | Indicizza le trascrizioni delle sessioni |
|
||||
| `sessions.retentionDays` | `number` | -- | Conservazione delle trascrizioni |
|
||||
| `sessions.exportDir` | `string` | -- | Directory di esportazione |
|
||||
|
||||
OpenClaw preferisce le attuali forme di raccolta QMD e query MCP, ma mantiene
|
||||
funzionanti le versioni QMD meno recenti ripiegando sui flag legacy di raccolta `--mask`
|
||||
e sui vecchi nomi degli strumenti MCP quando necessario.
|
||||
OpenClaw preferisce le forme correnti delle raccolte QMD e delle query MCP, ma mantiene
|
||||
compatibili anche le versioni meno recenti di QMD usando come fallback i flag legacy di raccolta `--mask`
|
||||
e i vecchi nomi degli strumenti MCP quando necessario.
|
||||
|
||||
Gli override dei modelli QMD restano sul lato QMD, non nella configurazione OpenClaw. Se hai bisogno di
|
||||
Le sovrascritture dei modelli QMD restano sul lato QMD, non nella configurazione di OpenClaw. Se devi
|
||||
sovrascrivere globalmente i modelli di QMD, imposta variabili d'ambiente come
|
||||
`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` e `QMD_GENERATE_MODEL` nell'ambiente runtime del gateway.
|
||||
`QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` e `QMD_GENERATE_MODEL` nell'ambiente di runtime
|
||||
del gateway.
|
||||
|
||||
### Pianificazione degli aggiornamenti
|
||||
|
||||
@ -414,7 +426,7 @@ sovrascrivere globalmente i modelli di QMD, imposta variabili d'ambiente come
|
||||
| `limits.maxInjectedChars` | `number` | -- | Limita il totale dei caratteri iniettati |
|
||||
| `limits.timeoutMs` | `number` | `4000` | Timeout della ricerca |
|
||||
|
||||
### Scope
|
||||
### Ambito
|
||||
|
||||
Controlla quali sessioni possono ricevere risultati di ricerca QMD. Stesso schema di
|
||||
[`session.sendPolicy`](/it/gateway/configuration-reference#session):
|
||||
@ -432,17 +444,17 @@ Controlla quali sessioni possono ricevere risultati di ricerca QMD. Stesso schem
|
||||
}
|
||||
```
|
||||
|
||||
Il valore predefinito è solo DM. `match.keyPrefix` corrisponde alla chiave di sessione normalizzata;
|
||||
`match.rawKeyPrefix` corrisponde alla chiave raw inclusa `agent:<id>:`.
|
||||
L'impostazione predefinita è solo DM. `match.keyPrefix` corrisponde alla chiave di sessione normalizzata;
|
||||
`match.rawKeyPrefix` corrisponde alla chiave grezza che include `agent:<id>:`.
|
||||
|
||||
### Citazioni
|
||||
|
||||
`memory.citations` si applica a tutti i backend:
|
||||
|
||||
| Valore | Comportamento |
|
||||
| ---------------- | --------------------------------------------------- |
|
||||
| Valore | Comportamento |
|
||||
| ---------------- | -------------------------------------------------- |
|
||||
| `auto` (predefinito) | Include il footer `Source: <path#line>` negli snippet |
|
||||
| `on` | Include sempre il footer |
|
||||
| `on` | Include sempre il footer |
|
||||
| `off` | Omette il footer (il percorso viene comunque passato internamente all'agente) |
|
||||
|
||||
### Esempio completo QMD
|
||||
@ -470,20 +482,20 @@ Il valore predefinito è solo DM. `match.keyPrefix` corrisponde alla chiave di s
|
||||
|
||||
## Dreaming (sperimentale)
|
||||
|
||||
Dreaming viene configurato in `plugins.entries.memory-core.config.dreaming`,
|
||||
Dreaming è configurato in `plugins.entries.memory-core.config.dreaming`,
|
||||
non in `agents.defaults.memorySearch`.
|
||||
|
||||
Dreaming viene eseguito come una scansione pianificata unica e usa fasi interne light/deep/REM come
|
||||
Dreaming viene eseguito come una singola esecuzione pianificata e usa fasi interne light/deep/REM come
|
||||
dettaglio di implementazione.
|
||||
|
||||
Per il comportamento concettuale e i comandi slash, vedi [Dreaming](/concepts/dreaming).
|
||||
Per il comportamento concettuale e i comandi slash, vedi [Dreaming](/it/concepts/dreaming).
|
||||
|
||||
### Impostazioni utente
|
||||
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ----------- | --------- | ------------ | ------------------------------------------------ |
|
||||
| `enabled` | `boolean` | `false` | Abilita o disabilita completamente dreaming |
|
||||
| `frequency` | `string` | `0 3 * * *` | Cadenza cron facoltativa per la scansione completa di dreaming |
|
||||
| Chiave | Tipo | Predefinito | Descrizione |
|
||||
| ----------- | --------- | ----------- | ------------------------------------------------ |
|
||||
| `enabled` | `boolean` | `false` | Abilita o disabilita completamente Dreaming |
|
||||
| `frequency` | `string` | `0 3 * * *` | Cadenza cron facoltativa per l'esecuzione completa di Dreaming |
|
||||
|
||||
### Esempio
|
||||
|
||||
@ -506,6 +518,6 @@ Per il comportamento concettuale e i comandi slash, vedi [Dreaming](/concepts/dr
|
||||
|
||||
Note:
|
||||
|
||||
- Dreaming scrive lo stato della macchina in `memory/.dreams/`.
|
||||
- Dreaming scrive output narrativo leggibile da esseri umani in `DREAMS.md` (o nell'esistente `dreams.md`).
|
||||
- La policy e le soglie delle fasi light/deep/REM sono comportamento interno, non configurazione esposta all'utente.
|
||||
- Dreaming scrive lo stato macchina in `memory/.dreams/`.
|
||||
- Dreaming scrive l'output narrativo leggibile dagli esseri umani in `DREAMS.md` (o nell'esistente `dreams.md`).
|
||||
- La politica e le soglie delle fasi light/deep/REM sono comportamento interno, non configurazione esposta all'utente.
|
||||
|
||||
@ -1,22 +1,22 @@
|
||||
---
|
||||
read_when:
|
||||
- Aggiunta di automazione del browser controllata dall'agente
|
||||
- Debug del motivo per cui openclaw interferisce con il tuo Chrome
|
||||
- Implementazione delle impostazioni del browser e del ciclo di vita nell'app macOS
|
||||
- Aggiungere l'automazione del browser controllata dall'agente
|
||||
- Debuggare il motivo per cui openclaw interferisce con il tuo Chrome
|
||||
- Implementare impostazioni + ciclo di vita del browser nell'app macOS
|
||||
summary: Servizio di controllo del browser integrato + comandi di azione
|
||||
title: Browser (gestito da OpenClaw)
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T14:07:08Z"
|
||||
generated_at: "2026-04-10T08:14:01Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a41162efd397ea918469e16aa67e554bcbb517b3112df1d3e7927539b6a0926a
|
||||
source_hash: cd3424f62178bbf25923b8bc8e4d9f70e330f35428d01fe153574e5fa45d7604
|
||||
source_path: tools/browser.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Browser (gestito da openclaw)
|
||||
|
||||
OpenClaw può eseguire un **profilo Chrome/Brave/Edge/Chromium dedicato** controllato dall'agente.
|
||||
OpenClaw può eseguire un **profilo Chrome/Brave/Edge/Chromium dedicato** che l'agente controlla.
|
||||
È isolato dal tuo browser personale ed è gestito tramite un piccolo servizio di
|
||||
controllo locale all'interno del Gateway (solo loopback).
|
||||
|
||||
@ -24,18 +24,18 @@ 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 integrato `user` si collega alla tua vera sessione Chrome autenticata tramite Chrome MCP.
|
||||
- L'agente può **aprire schede, leggere pagine, fare clic e digitare** in una lane sicura.
|
||||
- Il profilo `user` integrato si collega alla tua vera sessione Chrome con accesso effettuato tramite Chrome MCP.
|
||||
|
||||
## Cosa ottieni
|
||||
|
||||
- Un profilo browser separato chiamato **openclaw** (accento arancione per impostazione predefinita).
|
||||
- Controllo deterministico delle schede (elenco/apri/metti a fuoco/chiudi).
|
||||
- Azioni dell'agente (clic/digita/trascina/seleziona), snapshot, screenshot, PDF.
|
||||
- Controllo deterministico delle schede (elencare/aprire/mettere a fuoco/chiudere).
|
||||
- Azioni dell'agente (clic/digitazione/trascinamento/selezione), snapshot, screenshot, PDF.
|
||||
- Supporto opzionale per più profili (`openclaw`, `work`, `remote`, ...).
|
||||
|
||||
Questo browser **non** è il tuo browser quotidiano. È una superficie sicura e isolata per
|
||||
l'automazione e la verifica da parte dell'agente.
|
||||
l'automazione e la verifica dell'agente.
|
||||
|
||||
## Avvio rapido
|
||||
|
||||
@ -50,11 +50,11 @@ Se ricevi “Browser disabled”, abilitalo nella configurazione (vedi sotto) e
|
||||
Gateway.
|
||||
|
||||
Se `openclaw browser` manca del tutto, oppure l'agente dice che lo strumento browser
|
||||
non è disponibile, vai a [Comando o strumento browser mancante](/tools/browser#missing-browser-command-or-tool).
|
||||
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
|
||||
Lo strumento predefinito `browser` ora è un plugin bundle che viene distribuito abilitato per
|
||||
impostazione predefinita. Questo significa che puoi disabilitarlo o sostituirlo senza rimuovere il resto del
|
||||
sistema di plugin di OpenClaw:
|
||||
|
||||
@ -70,33 +70,33 @@ sistema di plugin di OpenClaw:
|
||||
}
|
||||
```
|
||||
|
||||
Disabilita il plugin incluso prima di installare un altro plugin che fornisce lo
|
||||
Disabilita il plugin bundle 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 dell'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 bundle (`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 perché possa essere riutilizzata da
|
||||
un plugin sostitutivo.
|
||||
|
||||
Il plugin browser incluso ora possiede anche l'implementazione runtime del browser.
|
||||
Il core conserva solo helper condivisi del Plugin SDK più re-export di compatibilità per
|
||||
vecchi percorsi di importazione interni. In pratica, rimuovere o sostituire il pacchetto plugin browser
|
||||
rimuove l'insieme delle funzionalità browser invece di lasciare dietro una seconda implementazione runtime
|
||||
posseduta dal core.
|
||||
Il plugin browser bundle ora possiede anche l'implementazione runtime del browser.
|
||||
Il core mantiene solo helper condivisi del Plugin SDK più re-export di compatibilità per
|
||||
i vecchi percorsi di import 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 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 in modo che il plugin bundle
|
||||
possa registrare di nuovo il suo 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 lo strumento browser manca, la causa più comune è una
|
||||
lista `plugins.allow` restrittiva che non include `browser`.
|
||||
l'agente segnala che manca lo strumento browser, la causa più comune è un elenco `plugins.allow`
|
||||
restrittivo che non include `browser`.
|
||||
|
||||
Esempio di configurazione errata:
|
||||
Esempio di configurazione non funzionante:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -106,7 +106,7 @@ Esempio di configurazione errata:
|
||||
}
|
||||
```
|
||||
|
||||
Correggila aggiungendo `browser` alla allowlist dei plugin:
|
||||
Correggilo aggiungendo `browser` alla allowlist dei plugin:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -120,8 +120,8 @@ Note importanti:
|
||||
|
||||
- `browser.enabled=true` da solo non è sufficiente quando è impostato `plugins.allow`.
|
||||
- Anche `plugins.entries.browser.enabled=true` da solo non è sufficiente quando è impostato `plugins.allow`.
|
||||
- `tools.alsoAllow: ["browser"]` **non** carica il plugin browser incluso. Regola soltanto la policy degli strumenti dopo che il plugin è già stato caricato.
|
||||
- Se non hai bisogno di una allowlist restrittiva dei plugin, rimuovere `plugins.allow` ripristina anche il comportamento predefinito del browser incluso.
|
||||
- `tools.alsoAllow: ["browser"]` **non** carica il plugin browser bundle. Regola solo la policy degli strumenti dopo che il plugin è già stato caricato.
|
||||
- Se non hai bisogno di una allowlist plugin restrittiva, rimuovere `plugins.allow` ripristina anche il comportamento browser bundle predefinito.
|
||||
|
||||
Sintomi tipici:
|
||||
|
||||
@ -132,16 +132,16 @@ Sintomi tipici:
|
||||
## Profili: `openclaw` vs `user`
|
||||
|
||||
- `openclaw`: browser gestito e isolato (nessuna estensione richiesta).
|
||||
- `user`: profilo di collegamento Chrome MCP integrato per la tua **vera sessione Chrome autenticata**.
|
||||
- `user`: profilo integrato di collegamento Chrome MCP per la tua **vera sessione Chrome con accesso effettuato**.
|
||||
|
||||
Per le chiamate allo strumento browser dell'agente:
|
||||
|
||||
- Predefinito: usa il browser isolato `openclaw`.
|
||||
- Preferisci `profile="user"` quando le sessioni già autenticate sono importanti e l'utente
|
||||
è al computer per fare clic/approvare eventuali richieste di collegamento.
|
||||
- `profile` è la sovrascrittura esplicita quando vuoi una modalità browser specifica.
|
||||
- Preferisci `profile="user"` quando contano le sessioni già connesse e l'utente
|
||||
è al computer per fare clic/approvare eventuali prompt di collegamento.
|
||||
- `profile` è la sostituzione esplicita quando vuoi una modalità browser specifica.
|
||||
|
||||
Imposta `browser.defaultProfile: "openclaw"` se vuoi la modalità gestita come predefinita.
|
||||
Imposta `browser.defaultProfile: "openclaw"` se vuoi la modalità gestita per impostazione predefinita.
|
||||
|
||||
## Configurazione
|
||||
|
||||
@ -150,14 +150,14 @@ Le impostazioni del browser si trovano in `~/.openclaw/openclaw.json`.
|
||||
```json5
|
||||
{
|
||||
browser: {
|
||||
enabled: true, // default: true
|
||||
enabled: true, // predefinito: true
|
||||
ssrfPolicy: {
|
||||
dangerouslyAllowPrivateNetwork: true, // modalità trusted-network predefinita
|
||||
// allowPrivateNetwork: true, // alias legacy
|
||||
// hostnameAllowlist: ["*.example.com", "example.com"],
|
||||
// allowedHostnames: ["localhost"],
|
||||
},
|
||||
// cdpUrl: "http://127.0.0.1:18792", // sovrascrittura legacy per profilo singolo
|
||||
// cdpUrl: "http://127.0.0.1:18792", // sostituzione legacy a profilo singolo
|
||||
remoteCdpTimeoutMs: 1500, // timeout HTTP CDP remoto (ms)
|
||||
remoteCdpHandshakeTimeoutMs: 3000, // timeout handshake WebSocket CDP remoto (ms)
|
||||
defaultProfile: "openclaw",
|
||||
@ -188,32 +188,32 @@ Le impostazioni del browser si trovano in `~/.openclaw/openclaw.json`.
|
||||
|
||||
Note:
|
||||
|
||||
- Il servizio di controllo browser si collega al loopback su una porta derivata da `gateway.port`
|
||||
(predefinita: `18791`, che corrisponde a gateway + 2).
|
||||
- Se sovrascrivi la porta del Gateway (`gateway.port` o `OPENCLAW_GATEWAY_PORT`),
|
||||
le porte browser derivate si spostano per rimanere nella stessa “famiglia”.
|
||||
- Il servizio di controllo del browser si collega a loopback su una porta derivata da `gateway.port`
|
||||
(predefinita: `18791`, che è gateway + 2).
|
||||
- Se sostituisci la porta del Gateway (`gateway.port` o `OPENCLAW_GATEWAY_PORT`),
|
||||
le porte browser derivate cambiano 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 remota (non loopback).
|
||||
- `remoteCdpHandshakeTimeoutMs` si applica ai controlli di raggiungibilità WebSocket CDP remoti.
|
||||
- La navigazione/apertura scheda del browser è protetta contro SSRF prima della navigazione e ricontrollata al meglio sull'URL finale `http(s)` dopo la navigazione.
|
||||
- In modalità SSRF rigida vengono controllati anche il rilevamento/sonde degli endpoint CDP remoti (`cdpUrl`, incluse le ricerche `/json/version`).
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` è `true` per impostazione predefinita (modello trusted-network). Impostalo su `false` per una navigazione rigorosa solo pubblica.
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` resta supportato come alias legacy per compatibilità.
|
||||
- `remoteCdpTimeoutMs` si applica ai controlli di raggiungibilità CDP remoti (non loopback).
|
||||
- `remoteCdpHandshakeTimeoutMs` si applica ai controlli di raggiungibilità handshake WebSocket CDP remoti.
|
||||
- La navigazione/apertura di schede del browser è protetta da SSRF prima della navigazione e ricontrollata con la massima accuratezza possibile sull'URL `http(s)` finale dopo la navigazione.
|
||||
- In modalità SSRF rigorosa, anche il rilevamento/i probe degli endpoint CDP remoti (`cdpUrl`, incluse le ricerche `/json/version`) vengono controllati.
|
||||
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` usa per impostazione predefinita `true` (modello trusted-network). Impostalo su `false` per una navigazione rigorosa solo pubblica.
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` rimane supportato come alias legacy per compatibilità.
|
||||
- `attachOnly: true` significa “non avviare mai un browser locale; collegarsi 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 autenticato.
|
||||
- Ordine di rilevamento automatico: browser predefinito di 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 del CDP grezzo. Non
|
||||
- `color` + `color` per profilo colorano l'interfaccia del browser in modo che tu possa vedere quale profilo è attivo.
|
||||
- Il profilo predefinito è `openclaw` (browser standalone gestito da OpenClaw). Usa `defaultProfile: "user"` per scegliere il browser dell'utente con accesso effettuato.
|
||||
- Ordine di rilevamento automatico: browser di sistema predefinito se basato su Chromium; altrimenti Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
- I profili locali `openclaw` assegnano automaticamente `cdpPort`/`cdpUrl` — impostali solo per CDP remoto.
|
||||
- `driver: "existing-session"` usa Chrome DevTools MCP invece di CDP raw. 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.
|
||||
|
||||
## Usare Brave (o un altro browser basato su Chromium)
|
||||
|
||||
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:
|
||||
Se il tuo browser **di sistema predefinito** è basato su Chromium (Chrome/Brave/Edge/ecc.),
|
||||
OpenClaw lo usa automaticamente. Imposta `browser.executablePath` per sostituire
|
||||
il rilevamento automatico:
|
||||
|
||||
Esempio CLI:
|
||||
|
||||
@ -246,9 +246,9 @@ 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 remoto (host del nodo):** esegui un host del nodo sulla macchina che ha il browser; il Gateway inoltra le azioni del browser a esso.
|
||||
- **CDP remoto:** imposta `browser.profiles.<name>.cdpUrl` (oppure `browser.cdpUrl`) per
|
||||
- **Controllo locale (predefinito):** il Gateway avvia il servizio di controllo loopback e può lanciare un browser locale.
|
||||
- **Controllo remoto (host nodo):** esegui un host nodo sulla macchina che ha il browser; il Gateway instrada tramite proxy le azioni del browser verso di esso.
|
||||
- **CDP remoto:** imposta `browser.profiles.<name>.cdpUrl` (o `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:
|
||||
@ -256,31 +256,31 @@ Il comportamento di arresto varia in base alla modalità del profilo:
|
||||
- profili gestiti locali: `openclaw browser stop` arresta il processo browser che
|
||||
OpenClaw ha avviato
|
||||
- profili attach-only e CDP remoti: `openclaw browser stop` chiude la sessione di
|
||||
controllo attiva e rilascia le sovrascritture di emulazione Playwright/CDP (viewport,
|
||||
schema colori, impostazioni locali, fuso orario, modalità offline e stato simile), anche
|
||||
controllo attiva e rilascia le sostituzioni di emulazione Playwright/CDP (viewport,
|
||||
schema di colori, lingua, fuso orario, modalità offline e stato simile), anche
|
||||
se nessun processo browser è stato avviato da OpenClaw
|
||||
|
||||
Gli URL CDP remoti possono includere autenticazione:
|
||||
|
||||
- Token in query (ad es. `https://provider.example?token=<token>`)
|
||||
- HTTP Basic auth (ad es. `https://user:pass@provider.example`)
|
||||
- Token di query (ad esempio `https://provider.example?token=<token>`)
|
||||
- Autenticazione HTTP Basic (ad esempio `https://user:pass@provider.example`)
|
||||
|
||||
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 salvarli nei file di configurazione.
|
||||
al WebSocket CDP. Preferisci variabili di ambiente o gestori di segreti per i
|
||||
token invece di eseguirne il commit nei file di configurazione.
|
||||
|
||||
## Proxy browser del nodo (predefinito zero-config)
|
||||
|
||||
Se esegui un **host del nodo** sulla macchina che ha il browser, OpenClaw può
|
||||
Se esegui un **host nodo** sulla macchina che ha il tuo browser, OpenClaw può
|
||||
instradare automaticamente le chiamate allo strumento browser verso quel nodo senza alcuna configurazione browser aggiuntiva.
|
||||
Questo è il percorso predefinito per i Gateway remoti.
|
||||
Questo è il percorso predefinito per i gateway remoti.
|
||||
|
||||
Note:
|
||||
|
||||
- L'host del nodo espone il proprio server locale di controllo browser tramite un **comando proxy**.
|
||||
- L'host nodo espone il suo server locale di controllo browser tramite un **comando proxy**.
|
||||
- I profili provengono dalla configurazione `browser.profiles` del nodo stesso (uguale a quella locale).
|
||||
- `nodeHost.browserProxy.allowProfiles` è facoltativo. Lascialo vuoto per il comportamento legacy/predefinito: tutti i profili configurati restano raggiungibili tramite il proxy, comprese 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 persistenti di creazione/eliminazione profilo vengono bloccate sulla superficie proxy.
|
||||
- `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 dei profili.
|
||||
- Se imposti `nodeHost.browserProxy.allowProfiles`, OpenClaw lo tratta come un confine di privilegio minimo: solo i profili nella allowlist possono essere selezionati, e le route di creazione/eliminazione dei profili persistenti vengono bloccate sulla superficie proxy.
|
||||
- Disabilitalo se non lo vuoi:
|
||||
- Sul nodo: `nodeHost.browserProxy.enabled=false`
|
||||
- Sul gateway: `gateway.nodes.browser.mode="off"`
|
||||
@ -288,7 +288,7 @@ Note:
|
||||
## Browserless (CDP remoto ospitato)
|
||||
|
||||
[Browserless](https://browserless.io) è un servizio Chromium ospitato che espone
|
||||
URL di connessione CDP tramite HTTPS e WebSocket. OpenClaw può usare entrambe le forme, ma
|
||||
URL di connessione CDP su HTTPS e WebSocket. OpenClaw può usare entrambe le forme, ma
|
||||
per un profilo browser remoto l'opzione più semplice è l'URL WebSocket diretto
|
||||
dalla documentazione di connessione di Browserless.
|
||||
|
||||
@ -314,19 +314,19 @@ Esempio:
|
||||
Note:
|
||||
|
||||
- Sostituisci `<BROWSERLESS_API_KEY>` con il tuo vero token Browserless.
|
||||
- Scegli l'endpoint regionale corrispondente al tuo account Browserless (vedi la loro documentazione).
|
||||
- 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
|
||||
scopra `/json/version`.
|
||||
rilevi `/json/version`.
|
||||
|
||||
## Provider CDP WebSocket diretti
|
||||
## Provider CDP WebSocket diretto
|
||||
|
||||
Alcuni servizi browser ospitati espongono un endpoint **WebSocket diretto** invece
|
||||
del rilevamento CDP standard basato su HTTP (`/json/version`). OpenClaw supporta entrambi:
|
||||
Alcuni servizi browser ospitati espongono un endpoint **WebSocket diretto** invece del
|
||||
rilevamento CDP standard basato su HTTP (`/json/version`). OpenClaw supporta entrambe le forme:
|
||||
|
||||
- **Endpoint HTTP(S)** — OpenClaw chiama `/json/version` per scoprire l'URL
|
||||
WebSocket del debugger, quindi si collega.
|
||||
- **Endpoint WebSocket** (`ws://` / `wss://`) — OpenClaw si collega direttamente,
|
||||
- **Endpoint HTTP(S)** — OpenClaw chiama `/json/version` per rilevare l'URL
|
||||
del debugger WebSocket, quindi si connette.
|
||||
- **Endpoint WebSocket** (`ws://` / `wss://`) — OpenClaw si connette direttamente,
|
||||
saltando `/json/version`. Usalo per servizi come
|
||||
[Browserless](https://browserless.io),
|
||||
[Browserbase](https://www.browserbase.com), o qualsiasi provider che ti fornisca un
|
||||
@ -335,8 +335,8 @@ del rilevamento CDP standard basato su HTTP (`/json/version`). OpenClaw supporta
|
||||
### Browserbase
|
||||
|
||||
[Browserbase](https://www.browserbase.com) è una piattaforma cloud per eseguire
|
||||
browser headless con risoluzione CAPTCHA integrata, modalità stealth e
|
||||
proxy residenziali.
|
||||
browser headless con risoluzione CAPTCHA integrata, modalità stealth e proxy
|
||||
residenziali.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -359,58 +359,58 @@ 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 chiave API Browserbase.
|
||||
- Sostituisci `<BROWSERBASE_API_KEY>` con la tua vera API key Browserbase.
|
||||
- Browserbase crea automaticamente una sessione browser alla connessione WebSocket, quindi
|
||||
non è necessario alcun passaggio manuale di creazione sessione.
|
||||
- Il livello gratuito consente una sessione concorrente e un'ora di browser al mese.
|
||||
non è necessario alcun passaggio manuale di creazione della sessione.
|
||||
- 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.
|
||||
- Consulta la [documentazione Browserbase](https://docs.browserbase.com) per il riferimento
|
||||
API completo, le guide SDK e gli esempi di integrazione.
|
||||
|
||||
## Sicurezza
|
||||
|
||||
Concetti chiave:
|
||||
|
||||
- Il controllo browser è solo loopback; l'accesso passa tramite l'autenticazione del Gateway o l'associazione del nodo.
|
||||
- L'API HTTP browser standalone su loopback usa **solo autenticazione con segreto condiviso**:
|
||||
autenticazione bearer con token gateway, `x-openclaw-password`, oppure HTTP Basic auth con la
|
||||
- Il controllo del browser è solo loopback; l'accesso passa tramite l'autenticazione del Gateway o l'abbinamento del nodo.
|
||||
- L'API HTTP browser loopback standalone usa **solo autenticazione con segreto condiviso**:
|
||||
auth bearer del 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 browser è abilitato e non è configurata alcuna autenticazione con segreto condiviso, OpenClaw
|
||||
autenticano questa API browser loopback standalone.
|
||||
- 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`.
|
||||
- Mantieni il Gateway e gli eventuali host del nodo su una rete privata (Tailscale); evita l'esposizione pubblica.
|
||||
- Tratta URL/token CDP remoti come segreti; preferisci variabili d'ambiente o un gestore di segreti.
|
||||
- Mantieni il Gateway e qualsiasi host nodo su una rete privata (Tailscale); evita l'esposizione pubblica.
|
||||
- Tratta gli URL/token CDP remoti come segreti; preferisci variabili di ambiente o un gestore di segreti.
|
||||
|
||||
Suggerimenti per CDP remoto:
|
||||
|
||||
- Preferisci endpoint cifrati (HTTPS o WSS) e token di breve durata quando possibile.
|
||||
- Evita di incorporare token di lunga durata direttamente nei file di configurazione.
|
||||
- Preferisci endpoint cifrati (HTTPS o WSS) e token a breve durata quando possibile.
|
||||
- Evita di incorporare direttamente token a lunga durata nei file di configurazione.
|
||||
|
||||
## Profili (multi-browser)
|
||||
## Profili (browser multipli)
|
||||
|
||||
OpenClaw supporta più profili nominati (configurazioni di instradamento). I profili possono essere:
|
||||
|
||||
- **gestiti da openclaw**: un'istanza browser dedicata basata su Chromium con propria directory dati utente + porta CDP
|
||||
- **remoti**: un URL CDP esplicito (browser basato su Chromium in esecuzione altrove)
|
||||
- **sessione esistente**: il tuo profilo Chrome esistente tramite collegamento automatico Chrome DevTools MCP
|
||||
- **gestiti da openclaw**: un'istanza dedicata di browser basato 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 connessione automatica 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 opt-in oltre a `user`; creali con `--driver existing-session`.
|
||||
- Le porte CDP locali vengono allocate nell'intervallo **18800–18899** per impostazione predefinita.
|
||||
- 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.
|
||||
|
||||
Tutti gli endpoint di controllo accettano `?profile=<name>`; la CLI usa `--browser-profile`.
|
||||
|
||||
## 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 di browser basato su Chromium già in esecuzione tramite il
|
||||
server MCP ufficiale di Chrome DevTools. Questo riutilizza le schede e lo stato di accesso
|
||||
già aperti in quel profilo browser.
|
||||
|
||||
Riferimenti ufficiali di contesto e configurazione:
|
||||
@ -422,13 +422,13 @@ Profilo integrato:
|
||||
|
||||
- `user`
|
||||
|
||||
Opzionale: crea il tuo profilo existing-session personalizzato se vuoi un
|
||||
nome, un colore o una directory dati del browser diversi.
|
||||
Facoltativo: crea il tuo profilo existing-session personalizzato se vuoi un
|
||||
nome, colore o directory dati browser diversi.
|
||||
|
||||
Comportamento predefinito:
|
||||
|
||||
- Il profilo integrato `user` usa il collegamento automatico Chrome MCP, che punta al
|
||||
profilo locale predefinito di Google Chrome.
|
||||
- Il profilo `user` integrato usa la connessione automatica Chrome MCP, che punta al
|
||||
profilo Google Chrome locale predefinito.
|
||||
|
||||
Usa `userDataDir` per Brave, Edge, Chromium o un profilo Chrome non predefinito:
|
||||
|
||||
@ -451,7 +451,7 @@ Poi, nel browser corrispondente:
|
||||
|
||||
1. Apri la pagina inspect di quel browser per il debug remoto.
|
||||
2. Abilita il debug remoto.
|
||||
3. Tieni il browser in esecuzione e approva la richiesta 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:
|
||||
|
||||
@ -459,7 +459,7 @@ Pagine inspect comuni:
|
||||
- Brave: `brave://inspect/#remote-debugging`
|
||||
- Edge: `edge://inspect/#remote-debugging`
|
||||
|
||||
Smoke test live del collegamento:
|
||||
Smoke test di collegamento live:
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile user start
|
||||
@ -468,73 +468,74 @@ openclaw browser --browser-profile user tabs
|
||||
openclaw browser --browser-profile user snapshot --format ai
|
||||
```
|
||||
|
||||
Che aspetto ha il successo:
|
||||
Ecco come si presenta il successo:
|
||||
|
||||
- `status` mostra `driver: existing-session`
|
||||
- `status` mostra `transport: chrome-mcp`
|
||||
- `status` mostra `running: true`
|
||||
- `tabs` elenca le tue schede 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 browser basato su Chromium di destinazione è alla versione `144+`
|
||||
- il debug remoto è abilitato nella pagina inspect di quel browser
|
||||
- il browser ha mostrato e tu hai accettato la richiesta di consenso al collegamento
|
||||
- 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 controlla che
|
||||
Chrome sia installato localmente per i profili predefiniti con collegamento automatico, ma non può
|
||||
abilitare il debug remoto lato browser al posto tuo
|
||||
Chrome sia installato localmente per i profili predefiniti con connessione automatica, 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 autenticato dell'utente.
|
||||
- Se usi un profilo existing-session personalizzato, passa quel nome di profilo esplicito.
|
||||
- Scegli questa modalità solo quando l'utente è al computer per approvare la richiesta
|
||||
di collegamento.
|
||||
- il Gateway o l'host del nodo possono avviare `npx chrome-devtools-mcp@latest --autoConnect`
|
||||
- Usa `profile="user"` quando ti serve lo stato del browser dell'utente con accesso effettuato.
|
||||
- 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 nodo possono avviare `npx chrome-devtools-mcp@latest --autoConnect`
|
||||
|
||||
Note:
|
||||
|
||||
- Questo percorso è più rischioso del profilo isolato `openclaw` perché può
|
||||
agire all'interno della tua sessione browser autenticata.
|
||||
- Questo percorso ha un rischio maggiore rispetto al profilo isolato `openclaw` perché può
|
||||
agire all'interno della tua sessione browser con accesso effettuato.
|
||||
- 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
|
||||
directory dati utente Chromium.
|
||||
- Gli screenshot existing-session supportano acquisizioni di pagina e acquisizioni di elemento con `--ref`
|
||||
dagli output snapshot, ma non selettori CSS `--element`.
|
||||
- OpenClaw usa qui il flusso ufficiale `--autoConnect` di Chrome DevTools MCP. Se
|
||||
`userDataDir` è impostato, OpenClaw lo passa attraverso per puntare a quella
|
||||
directory dati utente Chromium esplicita.
|
||||
- Gli screenshot existing-session supportano catture di pagina e catture di elemento `--ref`
|
||||
dagli output snapshot, ma non i selettori CSS `--element`.
|
||||
- Gli screenshot di pagina existing-session funzionano senza Playwright tramite Chrome MCP.
|
||||
Anche gli screenshot di elementi basati su ref (`--ref`) funzionano lì, ma `--full-page`
|
||||
Anche gli screenshot di elemento 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:
|
||||
- Le azioni existing-session sono ancora più limitate rispetto al percorso del browser
|
||||
gestito:
|
||||
- `click`, `type`, `hover`, `scrollIntoView`, `drag` e `select` richiedono
|
||||
ref dello snapshot invece di selettori CSS
|
||||
- `click` supporta solo il pulsante sinistro (nessuna sovrascrittura del pulsante o modificatori)
|
||||
ref snapshot invece dei selettori CSS
|
||||
- `click` è solo con tasto sinistro (nessuna sostituzione del pulsante o modificatore)
|
||||
- `type` non supporta `slowly=true`; usa `fill` o `press`
|
||||
- `press` non supporta `delayMs`
|
||||
- `hover`, `scrollIntoView`, `drag`, `select`, `fill` ed `evaluate` non
|
||||
supportano sovrascritture del timeout per chiamata
|
||||
- `select` al momento supporta un solo valore
|
||||
- Existing-session `wait --url` supporta pattern esatti, per sottostringa e glob
|
||||
supportano sostituzioni timeout per chiamata
|
||||
- `select` attualmente supporta solo un singolo valore
|
||||
- Existing-session `wait --url` supporta pattern esatti, di 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 di dialog existing-session non supportano sovrascritture del timeout.
|
||||
- Alcune funzionalità richiedono ancora il percorso del browser gestito, incluse azioni batch,
|
||||
esportazione PDF, intercettazione dei download e `responsebody`.
|
||||
- Existing-session è locale all'host. Se Chrome si trova su una macchina diversa o in
|
||||
uno spazio dei nomi di rete diverso, usa invece CDP remoto o un host del nodo.
|
||||
- Gli hook dialog existing-session non supportano sostituzioni timeout.
|
||||
- Alcune funzionalità richiedono ancora il percorso browser gestito, tra cui
|
||||
azioni batch, esportazione PDF, intercettazione download e `responsebody`.
|
||||
- Existing-session è locale all'host. Se Chrome si trova su un'altra macchina o in un
|
||||
namespace di rete diverso, usa invece CDP remoto o un host nodo.
|
||||
|
||||
## 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 vengono indirizzate tramite `targetId`, non tramite “ultima scheda”.
|
||||
- **Controllo deterministico delle schede**: indirizza le schede tramite `targetId`, non “ultima scheda”.
|
||||
|
||||
## Selezione del browser
|
||||
|
||||
Quando viene avviato localmente, OpenClaw sceglie il primo disponibile:
|
||||
Quando esegue l'avvio locale, OpenClaw sceglie il primo disponibile:
|
||||
|
||||
1. Chrome
|
||||
2. Brave
|
||||
@ -542,7 +543,7 @@ Quando viene avviato localmente, OpenClaw sceglie il primo disponibile:
|
||||
4. Chromium
|
||||
5. Chrome Canary
|
||||
|
||||
Puoi sovrascriverlo con `browser.executablePath`.
|
||||
Puoi sostituire questa scelta con `browser.executablePath`.
|
||||
|
||||
Piattaforme:
|
||||
|
||||
@ -552,7 +553,7 @@ Piattaforme:
|
||||
|
||||
## API di controllo (facoltativa)
|
||||
|
||||
Solo per integrazioni locali, il Gateway espone una piccola API HTTP su loopback:
|
||||
Solo per integrazioni locali, il Gateway espone una piccola API HTTP loopback:
|
||||
|
||||
- Stato/avvio/arresto: `GET /`, `POST /start`, `POST /stop`
|
||||
- Schede: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`
|
||||
@ -572,36 +573,57 @@ Tutti gli endpoint accettano `?profile=<name>`.
|
||||
Se è configurata l'autenticazione gateway con segreto condiviso, anche le route HTTP browser richiedono autenticazione:
|
||||
|
||||
- `Authorization: Bearer <gateway token>`
|
||||
- `x-openclaw-password: <gateway password>` oppure HTTP Basic auth con quella password
|
||||
- `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 loopback standalone **non** usa trusted-proxy o
|
||||
gli header di identità Tailscale Serve.
|
||||
- Se `gateway.auth.mode` è `none` o `trusted-proxy`, queste route browser su loopback
|
||||
non ereditano quelle modalità basate sull'identità; mantienile solo su loopback.
|
||||
- Se `gateway.auth.mode` è `none` o `trusted-proxy`, queste route browser loopback
|
||||
non ereditano quelle modalità con identità; mantienile solo loopback.
|
||||
|
||||
### Contratto di errore `/act`
|
||||
|
||||
`POST /act` usa una risposta di errore strutturata per la validazione a livello di route e
|
||||
per gli errori di policy:
|
||||
|
||||
```json
|
||||
{ "error": "<message>", "code": "ACT_*" }
|
||||
```
|
||||
|
||||
Valori `code` attuali:
|
||||
|
||||
- `ACT_KIND_REQUIRED` (HTTP 400): `kind` manca 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` (o `wait --fn`) è disabilitato dalla configurazione.
|
||||
- `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` di primo livello o batch è in conflitto con la destinazione della richiesta.
|
||||
- `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): l'azione non è supportata per i profili existing-session.
|
||||
|
||||
Altri errori runtime possono ancora 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/snapshot ruolo, screenshot di elementi,
|
||||
PDF) richiedono Playwright. Se Playwright non è installato, quegli endpoint restituiscono
|
||||
un chiaro errore 501.
|
||||
|
||||
Cosa funziona ancora senza Playwright:
|
||||
Cosa continua a funzionare 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 (`--ref`) dall'output 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 snapshot
|
||||
|
||||
Cosa richiede ancora Playwright:
|
||||
|
||||
- `navigate`
|
||||
- `act`
|
||||
- Snapshot AI / role snapshot
|
||||
- Screenshot di elementi con selettore CSS (`--element`)
|
||||
- Esportazione PDF completa del browser
|
||||
- snapshot AI / snapshot ruolo
|
||||
- screenshot di elementi con selettore CSS (`--element`)
|
||||
- esportazione PDF completa del browser
|
||||
|
||||
Gli screenshot di elementi rifiutano anche `--full-page`; la route restituisce `fullPage is
|
||||
not supported for element screenshots`.
|
||||
@ -613,7 +635,7 @@ OpenClaw con supporto browser.
|
||||
#### Installazione di Playwright in Docker
|
||||
|
||||
Se il tuo Gateway è in esecuzione in Docker, evita `npx playwright` (conflitti con gli override npm).
|
||||
Usa invece la CLI inclusa:
|
||||
Usa invece la CLI bundle:
|
||||
|
||||
```bash
|
||||
docker compose run --rm openclaw-cli \
|
||||
@ -626,23 +648,23 @@ Per rendere persistenti i download del browser, imposta `PLAYWRIGHT_BROWSERS_PAT
|
||||
|
||||
## Come funziona (interno)
|
||||
|
||||
Flusso di alto livello:
|
||||
Flusso ad alto livello:
|
||||
|
||||
- Un piccolo **server di controllo** accetta richieste HTTP.
|
||||
- Si collega ai browser basati su Chromium (Chrome/Brave/Edge/Chromium) tramite **CDP**.
|
||||
- Si connette ai browser basati su Chromium (Chrome/Brave/Edge/Chromium) tramite **CDP**.
|
||||
- Per azioni avanzate (clic/digitazione/snapshot/PDF), usa **Playwright** sopra
|
||||
CDP.
|
||||
- Quando Playwright manca, sono disponibili solo le operazioni non basate su Playwright.
|
||||
- Quando Playwright non è presente, sono disponibili solo le operazioni che non usano Playwright.
|
||||
|
||||
Questo design mantiene l'agente su un'interfaccia stabile e deterministica, permettendoti allo stesso tempo
|
||||
di cambiare browser e profili locali/remoti.
|
||||
Questo design mantiene l'agente su un'interfaccia stabile e deterministica, consentendoti al tempo stesso
|
||||
di sostituire browser e profili locali/remoti.
|
||||
|
||||
## Riferimento rapido CLI
|
||||
|
||||
Tutti i comandi accettano `--browser-profile <name>` per destinare un profilo specifico.
|
||||
Tutti i comandi accettano anche `--json` per output leggibili dalla macchina (payload stabili).
|
||||
Tutti i comandi accettano `--browser-profile <name>` per indirizzare un profilo specifico.
|
||||
Tutti i comandi accettano anche `--json` per output leggibile dalla macchina (payload stabili).
|
||||
|
||||
Elementi di base:
|
||||
Di base:
|
||||
|
||||
- `openclaw browser status`
|
||||
- `openclaw browser start`
|
||||
@ -674,9 +696,9 @@ Ispezione:
|
||||
Nota sul ciclo di vita:
|
||||
|
||||
- Per i profili attach-only e CDP remoti, `openclaw browser stop` è comunque il
|
||||
comando corretto di pulizia dopo i test. Chiude la sessione di controllo attiva e
|
||||
cancella le sovrascritture temporanee di emulazione invece di terminare il browser
|
||||
sottostante.
|
||||
comando di pulizia corretto dopo i test. Chiude la sessione di controllo attiva e
|
||||
cancella le sostituzioni temporanee di emulazione invece di terminare il
|
||||
browser sottostante.
|
||||
- `openclaw browser errors --clear`
|
||||
- `openclaw browser requests --filter api --clear`
|
||||
- `openclaw browser pdf`
|
||||
@ -727,25 +749,25 @@ Stato:
|
||||
|
||||
Note:
|
||||
|
||||
- `upload` e `dialog` sono chiamate di **preparazione**; eseguirle prima del clic/premi
|
||||
che attiva il selettore file/dialog.
|
||||
- I percorsi di output per download e trace sono vincolati alle radici temp di OpenClaw:
|
||||
- `upload` e `dialog` sono chiamate di **armamento**; eseguirle prima del clic/della pressione
|
||||
che attiva il selettore/la finestra di dialogo.
|
||||
- I percorsi di output per download e trace sono vincolati alle root temporanee 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 radice temp uploads di OpenClaw:
|
||||
- uploads: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`)
|
||||
- I percorsi di upload sono vincolati a una root temporanea di upload OpenClaw:
|
||||
- upload: `/tmp/openclaw/uploads` (fallback: `${os.tmpdir()}/openclaw/uploads`)
|
||||
- `upload` può anche impostare direttamente input file tramite `--input-ref` o `--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à (nessun ref; solo ispezione).
|
||||
- `--efficient` (oppure `--mode efficient`): preset di role snapshot compatto (interactive + compact + depth + maxChars inferiore).
|
||||
- Predefinito di configurazione (solo tool/CLI): imposta `browser.snapshotDefaults.mode: "efficient"` per usare snapshot efficienti quando il chiamante non passa una modalità (vedi [configurazione del Gateway](/it/gateway/configuration-reference#browser)).
|
||||
- Le opzioni role snapshot (`--interactive`, `--compact`, `--depth`, `--selector`) forzano uno snapshot basato sui 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, facile da selezionare, di elementi interattivi (ideale per pilotare le azioni).
|
||||
- `--efficient` (o `--mode efficient`): preset snapshot di ruolo compatto (interactive + compact + depth + maxChars più basso).
|
||||
- Predefinito di configurazione (solo strumento/CLI): imposta `browser.snapshotDefaults.mode: "efficient"` per usare snapshot efficienti quando il chiamante non passa una modalità (vedi [Configurazione del Gateway](/it/gateway/configuration-reference#browser)).
|
||||
- Le opzioni snapshot di ruolo (`--interactive`, `--compact`, `--depth`, `--selector`) forzano uno snapshot basato sui ruoli con ref come `ref=e12`.
|
||||
- `--frame "<iframe selector>"` limita gli snapshot di ruolo a un iframe (si abbina a ref di ruolo come `e12`).
|
||||
- `--interactive` produce un elenco piatto, facile da selezionare, di elementi interattivi (ideale per guidare le azioni).
|
||||
- `--labels` aggiunge uno screenshot solo viewport con etichette ref sovrapposte (stampa `MEDIA:<path>`).
|
||||
- `click`/`type`/ecc. richiedono un `ref` da `snapshot` (numerico `12` o ref di ruolo `e12`).
|
||||
I selettori CSS non sono intenzionalmente supportati per le azioni.
|
||||
I selettori CSS intenzionalmente non sono supportati per le azioni.
|
||||
|
||||
## Snapshot e ref
|
||||
|
||||
@ -756,7 +778,7 @@ OpenClaw supporta due stili di “snapshot”:
|
||||
- Azioni: `openclaw browser click 12`, `openclaw browser type 23 "hello"`.
|
||||
- Internamente, il ref viene risolto tramite `aria-ref` di Playwright.
|
||||
|
||||
- **Role snapshot (ref di ruolo come `e12`)**: `openclaw browser snapshot --interactive` (oppure `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- **Snapshot di ruolo (ref di ruolo come `e12`)**: `openclaw browser snapshot --interactive` (oppure `--compact`, `--depth`, `--selector`, `--frame`)
|
||||
- Output: un elenco/albero basato sui 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).
|
||||
@ -764,12 +786,12 @@ OpenClaw supporta due stili di “snapshot”:
|
||||
|
||||
Comportamento dei ref:
|
||||
|
||||
- I ref **non sono stabili tra navigazioni**; se qualcosa fallisce, riesegui `snapshot` e usa un ref nuovo.
|
||||
- Se il role snapshot è stato acquisito con `--frame`, i ref di ruolo sono limitati a quell'iframe fino al role snapshot successivo.
|
||||
- I ref **non sono stabili tra navigazioni**; se qualcosa fallisce, esegui di nuovo `snapshot` e usa un ref aggiornato.
|
||||
- Se lo snapshot di ruolo è stato acquisito con `--frame`, i ref di ruolo sono limitati a quell'iframe fino al successivo snapshot di ruolo.
|
||||
|
||||
## Potenziamenti di attesa
|
||||
## Potenziamenti di wait
|
||||
|
||||
Puoi attendere più di semplice tempo/testo:
|
||||
Puoi aspettare più del semplice tempo/testo:
|
||||
|
||||
- Attendere un URL (glob supportati da Playwright):
|
||||
- `openclaw browser wait --url "**/dash"`
|
||||
@ -780,7 +802,7 @@ Puoi attendere più di semplice tempo/testo:
|
||||
- Attendere che un selettore diventi visibile:
|
||||
- `openclaw browser wait "#main"`
|
||||
|
||||
Questi possono essere combinati:
|
||||
Questi elementi possono essere combinati:
|
||||
|
||||
```bash
|
||||
openclaw browser wait "#main" \
|
||||
@ -792,22 +814,22 @@ openclaw browser wait "#main" \
|
||||
|
||||
## Flussi di debug
|
||||
|
||||
Quando un'azione fallisce (ad es. “not visible”, “strict mode violation”, “covered”):
|
||||
Quando un'azione fallisce (ad esempio “not visible”, “strict mode violation”, “covered”):
|
||||
|
||||
1. `openclaw browser snapshot --interactive`
|
||||
2. Usa `click <ref>` / `type <ref>` (preferisci i ref di ruolo in modalità interactive)
|
||||
3. Se fallisce ancora: `openclaw browser highlight <ref>` per vedere cosa Playwright sta prendendo di mira
|
||||
3. Se fallisce ancora: `openclaw browser highlight <ref>` per vedere cosa Playwright sta indirizzando
|
||||
4. Se la pagina si comporta in modo strano:
|
||||
- `openclaw browser errors --clear`
|
||||
- `openclaw browser requests --filter api --clear`
|
||||
5. Per debug approfondito: registra una trace:
|
||||
5. Per un debug approfondito: registra una trace:
|
||||
- `openclaw browser trace start`
|
||||
- riproduci il problema
|
||||
- `openclaw browser trace stop` (stampa `TRACE:<path>`)
|
||||
|
||||
## Output JSON
|
||||
|
||||
`--json` è pensato per scripting e tooling strutturato.
|
||||
`--json` è pensato per scripting e strumenti strutturati.
|
||||
|
||||
Esempi:
|
||||
|
||||
@ -818,35 +840,35 @@ openclaw browser requests --filter api --json
|
||||
openclaw browser cookies --json
|
||||
```
|
||||
|
||||
I role snapshot in JSON includono `refs` più un piccolo blocco `stats` (righe/caratteri/ref/interattivi) così gli strumenti possono ragionare su dimensione e densità del payload.
|
||||
Gli snapshot di ruolo in JSON includono `refs` più un piccolo blocco `stats` (linee/caratteri/ref/interattivi) così gli strumenti possono ragionare su dimensione e densità del payload.
|
||||
|
||||
## Stato e opzioni dell'ambiente
|
||||
## Controlli di stato e ambiente
|
||||
|
||||
Sono utili per flussi del tipo “fai comportare il sito come X”:
|
||||
Sono utili per flussi “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`)
|
||||
- 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 / lingua: `set timezone ...`, `set locale ...`
|
||||
- Dispositivo / viewport:
|
||||
- `set device "iPhone 14"` (preset dispositivi Playwright)
|
||||
- `set device "iPhone 14"` (preset dispositivo Playwright)
|
||||
- `set viewport 1280 720`
|
||||
|
||||
## Sicurezza e privacy
|
||||
|
||||
- Il profilo browser openclaw può contenere sessioni autenticate; trattalo come sensibile.
|
||||
- Il profilo browser openclaw può contenere sessioni con accesso effettuato; trattalo come sensibile.
|
||||
- `browser act kind=evaluate` / `openclaw browser evaluate` e `wait --fn`
|
||||
eseguono JavaScript arbitrario nel contesto della pagina. Il prompt injection può influenzare
|
||||
eseguono JavaScript arbitrario nel contesto della pagina. Il prompt injection può indirizzare
|
||||
questo comportamento. Disabilitalo con `browser.evaluateEnabled=false` se non ti serve.
|
||||
- Per login e note anti-bot (X/Twitter, ecc.), vedi [Browser login + pubblicazione X/Twitter](/tools/browser-login).
|
||||
- Mantieni Gateway/host del nodo privati (solo loopback o tailnet).
|
||||
- Gli endpoint CDP remoti sono potenti; instradali tramite tunnel e proteggili.
|
||||
- Per accessi e note anti-bot (X/Twitter, ecc.), vedi [Accesso browser + pubblicazione su X/Twitter](/it/tools/browser-login).
|
||||
- Mantieni privato il Gateway/l'host nodo (solo loopback o tailnet).
|
||||
- Gli endpoint CDP remoti sono potenti; incanalali tramite tunnel e proteggili.
|
||||
|
||||
Esempio di modalità rigorosa (blocca per impostazione predefinita destinazioni private/interne):
|
||||
Esempio di modalità rigorosa (bloccare per impostazione predefinita destinazioni private/interne):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -862,13 +884,13 @@ Esempio di modalità rigorosa (blocca per impostazione predefinita destinazioni
|
||||
|
||||
## Risoluzione dei problemi
|
||||
|
||||
Per problemi specifici di Linux (soprattutto Chromium snap), vedi
|
||||
[Risoluzione dei problemi del browser](/tools/browser-linux-troubleshooting).
|
||||
Per problemi specifici di Linux (in particolare snap Chromium), vedi
|
||||
[Risoluzione dei problemi del browser](/it/tools/browser-linux-troubleshooting).
|
||||
|
||||
Per configurazioni divise WSL2 Gateway + Chrome Windows su host separato, vedi
|
||||
[Risoluzione dei problemi WSL2 + Windows + Chrome remoto CDP](/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
Per configurazioni con Gateway WSL2 + Chrome Windows su host separati, vedi
|
||||
[Risoluzione dei problemi WSL2 + Windows + CDP Chrome remoto](/it/tools/browser-wsl2-windows-remote-cdp-troubleshooting).
|
||||
|
||||
## Strumenti dell'agente + come funziona il controllo
|
||||
## Strumenti agente + funzionamento del controllo
|
||||
|
||||
L'agente riceve **uno strumento** per l'automazione del browser:
|
||||
|
||||
@ -883,13 +905,13 @@ Mappatura:
|
||||
- `profile` per scegliere un profilo browser nominato (openclaw, chrome o CDP remoto).
|
||||
- `target` (`sandbox` | `host` | `node`) per selezionare dove si trova il browser.
|
||||
- Nelle sessioni sandbox, `target: "host"` richiede `agents.defaults.sandbox.browser.allowHostControl=true`.
|
||||
- Se `target` viene omesso: le sessioni sandbox usano per impostazione predefinita `sandbox`, le sessioni non sandbox usano per impostazione predefinita `host`.
|
||||
- Se è collegato un nodo con capacità browser, lo strumento può instradarsi automaticamente a esso a meno che tu non fissi `target="host"` o `target="node"`.
|
||||
- Se `target` è omesso: le sessioni sandbox usano `sandbox` come predefinito, le sessioni non sandbox usano `host`.
|
||||
- Se è connesso un nodo 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](/tools) — tutti gli strumenti agente disponibili
|
||||
- [Panoramica degli strumenti](/it/tools) — tutti gli strumenti agente disponibili
|
||||
- [Sandboxing](/it/gateway/sandboxing) — controllo del browser in ambienti sandbox
|
||||
- [Sicurezza](/it/gateway/security) — rischi del controllo browser e hardening
|
||||
- [Sicurezza](/it/gateway/security) — rischi e hardening del controllo del browser
|
||||
|
||||
@ -1,70 +1,75 @@
|
||||
---
|
||||
read_when:
|
||||
- Configurazione di approvazioni exec o allowlist
|
||||
- Implementazione della UX delle approvazioni exec nell'app macOS
|
||||
- Configurazione delle approvazioni exec o delle allowlist
|
||||
- Implementazione della UX di approvazione exec nell'app macOS
|
||||
- Revisione dei prompt di uscita dalla sandbox e delle relative implicazioni
|
||||
summary: Approvazioni exec, allowlist e prompt di uscita dalla sandbox
|
||||
title: Approvazioni exec
|
||||
x-i18n:
|
||||
generated_at: "2026-04-08T02:19:39Z"
|
||||
generated_at: "2026-04-10T08:14:37Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6041929185bab051ad873cc4822288cb7d6f0470e19e7ae7a16b70f76dfc2cd9
|
||||
source_hash: 5f4a2e2f1f3c13a1d1926c9de0720513ea8a74d1ca571dbe74b188d8c560c14c
|
||||
source_path: tools/exec-approvals.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Approvazioni exec
|
||||
|
||||
Le approvazioni exec sono il **guardrail dell'app companion / host del nodo** per consentire a un agente in sandbox di eseguire
|
||||
Le approvazioni exec sono la **protezione dell'app companion / dell'host del nodo** per consentire a un agente sandboxed di eseguire
|
||||
comandi su un host reale (`gateway` o `node`). Considerale come un interblocco di sicurezza:
|
||||
i comandi sono consentiti solo quando policy + allowlist + (eventuale) approvazione dell'utente concordano tutte.
|
||||
Le approvazioni exec sono **aggiuntive** rispetto alla tool policy e al gating elevato (a meno che elevated non sia impostato su `full`, che salta le approvazioni).
|
||||
La policy effettiva è la **più restrittiva** tra `tools.exec.*` e i valori predefiniti delle approvazioni; se un campo delle approvazioni viene omesso, viene usato il valore di `tools.exec`.
|
||||
L'exec host usa anche lo stato locale delle approvazioni su quella macchina. Un valore host-local
|
||||
`ask: "always"` in `~/.openclaw/exec-approvals.json` continua a richiedere prompt anche se
|
||||
i valori predefiniti della sessione o della configurazione richiedono `ask: "on-miss"`.
|
||||
i comandi sono consentiti solo quando criteri + allowlist + approvazione utente (facoltativa) sono tutti concordi.
|
||||
Le approvazioni exec sono **in aggiunta** ai criteri degli strumenti e ai controlli elevati (a meno che elevated sia impostato su `full`, che salta le approvazioni).
|
||||
Il criterio effettivo è il **più restrittivo** tra i valori predefiniti di `tools.exec.*` e delle approvazioni; se un campo delle approvazioni viene omesso, viene usato il valore di `tools.exec`.
|
||||
L'exec host usa anche lo stato locale delle approvazioni su quella macchina. Un valore locale sull'host
|
||||
`ask: "always"` in `~/.openclaw/exec-approvals.json` continua a richiedere conferma anche se
|
||||
la sessione o i valori predefiniti della configurazione richiedono `ask: "on-miss"`.
|
||||
Usa `openclaw approvals get`, `openclaw approvals get --gateway` oppure
|
||||
`openclaw approvals get --node <id|name|ip>` per ispezionare la policy richiesta,
|
||||
le fonti della policy host e il risultato effettivo.
|
||||
`openclaw approvals get --node <id|name|ip>` per ispezionare il criterio richiesto,
|
||||
le origini dei criteri host e il risultato effettivo.
|
||||
Per la macchina locale, `openclaw exec-policy show` espone la stessa vista unificata e
|
||||
`openclaw exec-policy set|preset` può sincronizzare in un unico passaggio il criterio richiesto locale con il
|
||||
file locale delle approvazioni host. Quando un ambito locale richiede `host=node`,
|
||||
`openclaw exec-policy show` segnala quell'ambito come gestito dal nodo in fase di esecuzione invece di
|
||||
far finta che il file locale delle approvazioni sia la fonte effettiva di verità.
|
||||
|
||||
Se l'interfaccia dell'app companion **non è disponibile**, qualsiasi richiesta che richiede un prompt viene
|
||||
risolta tramite il **fallback ask** (predefinito: deny).
|
||||
risolta dal **fallback ask** (predefinito: deny).
|
||||
|
||||
I client di approvazione chat nativi possono anche esporre affordance specifiche del canale sul
|
||||
messaggio di approvazione in sospeso. Ad esempio, Matrix può precompilare scorciatoie a reazione sul
|
||||
I client di approvazione nativi della chat possono anche esporre affordance specifiche del canale nel
|
||||
messaggio di approvazione in attesa. Ad esempio, Matrix può precompilare scorciatoie tramite reaction nel
|
||||
prompt di approvazione (`✅` consenti una volta, `❌` nega e `♾️` consenti sempre quando disponibile)
|
||||
lasciando comunque i comandi `/approve ...` nel messaggio come fallback.
|
||||
continuando comunque a lasciare i comandi `/approve ...` nel messaggio come fallback.
|
||||
|
||||
## Dove si applica
|
||||
|
||||
Le approvazioni exec sono applicate localmente sull'host di esecuzione:
|
||||
Le approvazioni exec vengono applicate localmente sull'host di esecuzione:
|
||||
|
||||
- **gateway host** → processo `openclaw` sulla macchina gateway
|
||||
- **node host** → runner del nodo (app companion macOS o host nodo headless)
|
||||
- **host gateway** → processo `openclaw` sulla macchina gateway
|
||||
- **host nodo** → runner del nodo (app companion macOS o host nodo headless)
|
||||
|
||||
Nota sul modello di fiducia:
|
||||
|
||||
- I chiamanti autenticati al gateway sono operator trusted per quel gateway.
|
||||
- I nodi associati estendono questa capacità di operatore trusted all'host del nodo.
|
||||
- Le approvazioni exec riducono il rischio di esecuzione accidentale, ma non sono un confine di auth per utente.
|
||||
- Le esecuzioni approvate sull'host del nodo vincolano il contesto di esecuzione canonico: `cwd` canonico, `argv` esatto, binding dell'env
|
||||
quando presente e path dell'eseguibile fissato quando applicabile.
|
||||
- Per script shell e invocazioni dirette di file interpreter/runtime, OpenClaw prova anche a vincolare
|
||||
un singolo operando file locale concreto. Se quel file vincolato cambia dopo l'approvazione ma prima dell'esecuzione,
|
||||
- I chiamanti autenticati dal Gateway sono operatori attendibili per quel Gateway.
|
||||
- I nodi accoppiati estendono questa capacità di operatore attendibile all'host del nodo.
|
||||
- Le approvazioni exec riducono il rischio di esecuzione accidentale, ma non sono un confine di autenticazione per utente.
|
||||
- Le esecuzioni approvate sull'host del nodo vincolano il contesto di esecuzione canonico: `cwd` canonico, `argv` esatto, binding di `env`
|
||||
quando presente e percorso dell'eseguibile fissato quando applicabile.
|
||||
- Per script shell e invocazioni dirette di file tramite interprete/runtime, OpenClaw cerca anche di vincolare
|
||||
un unico operando file locale concreto. Se quel file vincolato cambia dopo l'approvazione ma prima dell'esecuzione,
|
||||
l'esecuzione viene negata invece di eseguire contenuto modificato.
|
||||
- Questo binding dei file è intenzionalmente best-effort, non un modello semantico completo di ogni
|
||||
percorso di caricamento di interpreter/runtime. Se la modalità di approvazione non riesce a identificare esattamente un file locale concreto
|
||||
da vincolare, rifiuta di emettere un'esecuzione supportata da approvazione invece di fingere una copertura completa.
|
||||
- Questo binding del file è intenzionalmente best-effort, non un modello semantico completo di ogni
|
||||
percorso di caricamento di interpreti/runtime. Se la modalità di approvazione non riesce a identificare esattamente un unico
|
||||
file locale concreto da vincolare, rifiuta di emettere un'esecuzione supportata da approvazione invece di fingere una copertura completa.
|
||||
|
||||
Suddivisione macOS:
|
||||
Separazione macOS:
|
||||
|
||||
- Il **servizio host del nodo** inoltra `system.run` alla **app macOS** tramite IPC locale.
|
||||
- La **app macOS** applica le approvazioni + esegue il comando nel contesto UI.
|
||||
- **servizio host del nodo** inoltra `system.run` alla **app macOS** tramite IPC locale.
|
||||
- **app macOS** applica le approvazioni + esegue il comando nel contesto UI.
|
||||
|
||||
## Impostazioni e archiviazione
|
||||
|
||||
Le approvazioni vivono in un file JSON locale sull'host di esecuzione:
|
||||
Le approvazioni risiedono in un file JSON locale sull'host di esecuzione:
|
||||
|
||||
`~/.openclaw/exec-approvals.json`
|
||||
|
||||
@ -105,12 +110,12 @@ Schema di esempio:
|
||||
|
||||
## Modalità "YOLO" senza approvazione
|
||||
|
||||
Se vuoi che l'exec host venga eseguito senza prompt di approvazione, devi aprire **entrambi** i livelli di policy:
|
||||
Se vuoi che l'exec host venga eseguito senza prompt di approvazione, devi aprire **entrambi** i livelli di criterio:
|
||||
|
||||
- policy exec richiesta nella configurazione di OpenClaw (`tools.exec.*`)
|
||||
- policy locale delle approvazioni host in `~/.openclaw/exec-approvals.json`
|
||||
- criterio exec richiesto nella configurazione di OpenClaw (`tools.exec.*`)
|
||||
- criterio locale delle approvazioni host in `~/.openclaw/exec-approvals.json`
|
||||
|
||||
Questo ora è il comportamento host predefinito a meno che tu non lo restringa esplicitamente:
|
||||
Questo è ora il comportamento host predefinito, a meno che tu non lo renda esplicitamente più restrittivo:
|
||||
|
||||
- `tools.exec.security`: `full` su `gateway`/`node`
|
||||
- `tools.exec.ask`: `off`
|
||||
@ -118,15 +123,15 @@ Questo ora è il comportamento host predefinito a meno che tu non lo restringa e
|
||||
|
||||
Distinzione importante:
|
||||
|
||||
- `tools.exec.host=auto` sceglie dove eseguire exec: nella sandbox quando disponibile, altrimenti sul gateway.
|
||||
- `tools.exec.host=auto` sceglie dove viene eseguito exec: nella sandbox quando disponibile, altrimenti sul gateway.
|
||||
- YOLO sceglie come viene approvato l'exec host: `security=full` più `ask=off`.
|
||||
- In modalità YOLO, OpenClaw non aggiunge un gate separato di approvazione euristica per l'offuscamento dei comandi sopra la policy exec host configurata.
|
||||
- `auto` non rende il routing gateway una sovrascrittura libera da una sessione in sandbox. Una richiesta per chiamata `host=node` è consentita da `auto`, e `host=gateway` è consentito da `auto` solo quando non è attivo alcun runtime sandbox. Se vuoi un valore predefinito stabile non-auto, imposta `tools.exec.host` o usa esplicitamente `/exec host=...`.
|
||||
- In modalità YOLO, OpenClaw non aggiunge un controllo di approvazione separato basato su euristiche di offuscamento dei comandi sopra il criterio exec host configurato.
|
||||
- `auto` non rende il routing gateway una sostituzione libera da una sessione sandboxed. Una richiesta per chiamata `host=node` è consentita da `auto`, e `host=gateway` è consentito da `auto` solo quando non è attivo alcun runtime sandbox. Se vuoi un valore predefinito stabile non auto, imposta `tools.exec.host` o usa `/exec host=...` esplicitamente.
|
||||
|
||||
Se vuoi una configurazione più conservativa, restringi di nuovo uno dei due livelli a `allowlist` / `on-miss`
|
||||
oppure `deny`.
|
||||
Se vuoi una configurazione più conservativa, riporta uno dei due livelli a `allowlist` / `on-miss`
|
||||
o `deny`.
|
||||
|
||||
Configurazione persistente gateway-host "non chiedere mai":
|
||||
Configurazione persistente dell'host gateway "non chiedere mai":
|
||||
|
||||
```bash
|
||||
openclaw config set tools.exec.host gateway
|
||||
@ -135,7 +140,7 @@ openclaw config set tools.exec.ask off
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Quindi imposta il file delle approvazioni host in modo corrispondente:
|
||||
Poi imposta il file delle approvazioni host in modo corrispondente:
|
||||
|
||||
```bash
|
||||
openclaw approvals set --stdin <<'EOF'
|
||||
@ -150,7 +155,22 @@ openclaw approvals set --stdin <<'EOF'
|
||||
EOF
|
||||
```
|
||||
|
||||
Per un host nodo, applica invece lo stesso file delle approvazioni su quel nodo:
|
||||
Scorciatoia locale per lo stesso criterio host gateway sulla macchina corrente:
|
||||
|
||||
```bash
|
||||
openclaw exec-policy preset yolo
|
||||
```
|
||||
|
||||
Questa scorciatoia locale aggiorna entrambi:
|
||||
|
||||
- `tools.exec.host/security/ask` locali
|
||||
- valori predefiniti locali di `~/.openclaw/exec-approvals.json`
|
||||
|
||||
È intenzionalmente solo locale. Se devi modificare da remoto le approvazioni dell'host gateway o dell'host nodo,
|
||||
continua a usare `openclaw approvals set --gateway` oppure
|
||||
`openclaw approvals set --node <id|name|ip>`.
|
||||
|
||||
Per un host nodo, applica invece lo stesso file di approvazioni su quel nodo:
|
||||
|
||||
```bash
|
||||
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
|
||||
@ -165,39 +185,45 @@ openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
|
||||
EOF
|
||||
```
|
||||
|
||||
Importante limitazione solo locale:
|
||||
|
||||
- `openclaw exec-policy` non sincronizza le approvazioni del nodo
|
||||
- `openclaw exec-policy set --host node` viene rifiutato
|
||||
- le approvazioni exec del nodo vengono recuperate dal nodo in fase di esecuzione, quindi gli aggiornamenti destinati al nodo devono usare `openclaw approvals --node ...`
|
||||
|
||||
Scorciatoia solo sessione:
|
||||
|
||||
- `/exec security=full ask=off` cambia solo la sessione corrente.
|
||||
- `/elevated full` è una scorciatoia break-glass che salta anche le approvazioni exec per quella sessione.
|
||||
- `/exec security=full ask=off` modifica solo la sessione corrente.
|
||||
- `/elevated full` è una scorciatoia di emergenza che salta anche le approvazioni exec per quella sessione.
|
||||
|
||||
Se il file delle approvazioni host resta più restrittivo della configurazione, la policy host più restrittiva continua a prevalere.
|
||||
Se il file delle approvazioni host resta più restrittivo della configurazione, continua comunque a prevalere il criterio host più restrittivo.
|
||||
|
||||
## Manopole della policy
|
||||
## Manopole del criterio
|
||||
|
||||
### Security (`exec.security`)
|
||||
|
||||
- **deny**: blocca tutte le richieste exec host.
|
||||
- **deny**: blocca tutte le richieste di exec host.
|
||||
- **allowlist**: consente solo i comandi presenti nell'allowlist.
|
||||
- **full**: consente tutto (equivalente a elevated).
|
||||
|
||||
### Ask (`exec.ask`)
|
||||
|
||||
- **off**: non chiedere mai.
|
||||
- **on-miss**: chiedi solo quando l'allowlist non corrisponde.
|
||||
- **always**: chiedi per ogni comando.
|
||||
- la fiducia persistente `allow-always` non sopprime i prompt quando la modalità ask effettiva è `always`
|
||||
- **off**: non richiedere mai conferma.
|
||||
- **on-miss**: richiedi conferma solo quando l'allowlist non corrisponde.
|
||||
- **always**: richiedi conferma per ogni comando.
|
||||
- la fiducia durevole `allow-always` non sopprime i prompt quando la modalità ask effettiva è `always`
|
||||
|
||||
### Ask fallback (`askFallback`)
|
||||
|
||||
Se è richiesto un prompt ma nessuna UI è raggiungibile, fallback decide:
|
||||
Se è richiesto un prompt ma non è raggiungibile alcuna UI, il fallback decide:
|
||||
|
||||
- **deny**: blocca.
|
||||
- **allowlist**: consente solo se l'allowlist corrisponde.
|
||||
- **full**: consente.
|
||||
- **allowlist**: consenti solo se l'allowlist corrisponde.
|
||||
- **full**: consenti.
|
||||
|
||||
### Hardening dell'eval inline dell'interpreter (`tools.exec.strictInlineEval`)
|
||||
### Hardening dell'eval inline dell'interprete (`tools.exec.strictInlineEval`)
|
||||
|
||||
Quando `tools.exec.strictInlineEval=true`, OpenClaw tratta le forme di eval inline del codice come solo-approvazione anche se il binario dell'interpreter stesso è nell'allowlist.
|
||||
Quando `tools.exec.strictInlineEval=true`, OpenClaw tratta le forme inline di code-eval come soggette a sola approvazione anche se il binario dell'interprete stesso è nell'allowlist.
|
||||
|
||||
Esempi:
|
||||
|
||||
@ -209,16 +235,16 @@ Esempi:
|
||||
- `lua -e`
|
||||
- `osascript -e`
|
||||
|
||||
Questo è un meccanismo di difesa in profondità per loader di interpreter che non si mappano in modo pulito a un singolo operando file stabile. In modalità strict:
|
||||
Questa è una difesa in profondità per i loader degli interpreti che non si mappano in modo pulito a un unico operando file stabile. In modalità strict:
|
||||
|
||||
- questi comandi richiedono comunque approvazione esplicita;
|
||||
- `allow-always` non persiste automaticamente nuove voci di allowlist per essi.
|
||||
- `allow-always` non rende persistenti automaticamente nuove voci di allowlist per essi.
|
||||
|
||||
## Allowlist (per agente)
|
||||
|
||||
Le allowlist sono **per agente**. Se esistono più agenti, cambia l'agente che stai
|
||||
modificando nell'app macOS. I pattern sono **corrispondenze glob case-insensitive**.
|
||||
I pattern dovrebbero risolversi in **path di binari** (le voci con solo basename vengono ignorate).
|
||||
I pattern devono risolversi in **percorsi di binari** (le voci con solo basename vengono ignorate).
|
||||
Le voci legacy `agents.default` vengono migrate a `agents.main` al caricamento.
|
||||
Le catene shell come `echo ok && pwd` richiedono comunque che ogni segmento di primo livello soddisfi le regole dell'allowlist.
|
||||
|
||||
@ -228,44 +254,44 @@ Esempi:
|
||||
- `~/.local/bin/*`
|
||||
- `/opt/homebrew/bin/rg`
|
||||
|
||||
Ogni voce di allowlist tiene traccia di:
|
||||
Ogni voce dell'allowlist tiene traccia di:
|
||||
|
||||
- **id** UUID stabile usato per l'identità UI (facoltativo)
|
||||
- timestamp **ultimo utilizzo**
|
||||
- **ultimo utilizzo** timestamp
|
||||
- **ultimo comando usato**
|
||||
- **ultimo path risolto**
|
||||
- **ultimo percorso risolto**
|
||||
|
||||
## Auto-allow delle CLI delle skill
|
||||
## Auto-consenti le CLI delle skill
|
||||
|
||||
Quando **Auto-allow skill CLIs** è abilitato, gli eseguibili referenziati da skill note
|
||||
sono trattati come presenti nell'allowlist sui nodi (nodo macOS o host nodo headless). Questo usa
|
||||
`skills.bins` tramite Gateway RPC per recuperare l'elenco dei bin delle skill. Disabilitalo se vuoi allowlist manuali rigorose.
|
||||
Quando **Auto-consenti le CLI delle skill** è abilitato, gli eseguibili referenziati da skill note
|
||||
vengono trattati come presenti nell'allowlist sui nodi (nodo macOS o host nodo headless). Questo usa
|
||||
`skills.bins` tramite Gateway RPC per recuperare l'elenco dei binari delle skill. Disabilitalo se vuoi allowlist manuali rigorose.
|
||||
|
||||
Note importanti sul trust:
|
||||
Note importanti sul modello di fiducia:
|
||||
|
||||
- Questa è un'**allowlist implicita di comodità**, separata dalle voci manuali di allowlist dei path.
|
||||
- È pensata per ambienti trusted dell'operatore in cui gateway e nodo si trovano nello stesso confine di fiducia.
|
||||
- Se ti serve una fiducia esplicita rigorosa, mantieni `autoAllowSkills: false` e usa solo voci manuali di allowlist dei path.
|
||||
- Questa è un'**allowlist implicita di comodità**, separata dalle voci manuali di allowlist per percorso.
|
||||
- È pensata per ambienti con operatori attendibili in cui Gateway e nodo si trovano nello stesso confine di fiducia.
|
||||
- Se richiedi una fiducia esplicita rigorosa, mantieni `autoAllowSkills: false` e usa solo voci manuali di allowlist per percorso.
|
||||
|
||||
## Safe bins (solo stdin)
|
||||
|
||||
`tools.exec.safeBins` definisce un piccolo elenco di binari **solo stdin** (ad esempio `cut`)
|
||||
che possono essere eseguiti in modalità allowlist **senza** voci esplicite di allowlist. I safe bin rifiutano
|
||||
argomenti file posizionali e token simili a path, quindi possono operare solo sul flusso in ingresso.
|
||||
Trattalo come un percorso rapido ristretto per filtri di stream, non come un elenco generale di fiducia.
|
||||
**Non** aggiungere binari interpreter o runtime (ad esempio `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) a `safeBins`.
|
||||
argomenti file posizionali e token simili a percorsi, quindi possono operare solo sullo stream in ingresso.
|
||||
Consideralo un percorso rapido e limitato per i filtri di stream, non un elenco generale di fiducia.
|
||||
**Non** aggiungere binari di interpreti o runtime (ad esempio `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) a `safeBins`.
|
||||
Se un comando può valutare codice, eseguire sottocomandi o leggere file per progettazione, preferisci voci esplicite di allowlist e mantieni abilitati i prompt di approvazione.
|
||||
I safe bin personalizzati devono definire un profilo esplicito in `tools.exec.safeBinProfiles.<bin>`.
|
||||
La validazione è deterministica solo dalla forma di argv (nessun controllo di esistenza del filesystem host), il che
|
||||
impedisce comportamenti da oracolo sull'esistenza dei file derivanti da differenze allow/deny.
|
||||
Le opzioni orientate ai file sono negate per i safe bin predefiniti (ad esempio `sort -o`, `sort --output`,
|
||||
La validazione è deterministica solo dalla forma di `argv` (senza controlli sull'esistenza del filesystem host), cosa che
|
||||
impedisce comportamenti di tipo oracolo di esistenza dei file dalle differenze tra allow/deny.
|
||||
Le opzioni orientate ai file vengono negate per i safe bin predefiniti (ad esempio `sort -o`, `sort --output`,
|
||||
`sort --files0-from`, `sort --compress-program`, `sort --random-source`,
|
||||
`sort --temporary-directory`/`-T`, `wc --files0-from`, `jq -f/--from-file`,
|
||||
`grep -f/--file`).
|
||||
I safe bin applicano anche una policy esplicita per binario sui flag che rompono il comportamento solo-stdin
|
||||
(ad esempio `sort -o/--output/--compress-program` e i flag ricorsivi di grep).
|
||||
Le opzioni lunghe vengono validate in modalità safe-bin con fail-closed: flag sconosciuti e abbreviazioni
|
||||
ambigue vengono rifiutati.
|
||||
I safe bin applicano inoltre un criterio esplicito per-binario sui flag per le opzioni che interrompono il
|
||||
comportamento solo stdin (ad esempio `sort -o/--output/--compress-program` e i flag ricorsivi di grep).
|
||||
Le opzioni lunghe vengono validate in modalità safe-bin in modo fail-closed: i flag sconosciuti e le
|
||||
abbreviazioni ambigue vengono rifiutati.
|
||||
Flag negati per profilo safe-bin:
|
||||
|
||||
[//]: # "SAFE_BIN_DENIED_FLAGS:START"
|
||||
@ -277,32 +303,32 @@ Flag negati per profilo safe-bin:
|
||||
|
||||
[//]: # "SAFE_BIN_DENIED_FLAGS:END"
|
||||
|
||||
I safe bin forzano anche i token argv a essere trattati come **testo letterale** al momento dell'esecuzione (niente globbing
|
||||
e nessuna espansione di `$VARS`) per i segmenti solo-stdin, così pattern come `*` o `$HOME/...` non possono essere
|
||||
I safe bin forzano inoltre che i token `argv` vengano trattati come **testo letterale** al momento dell'esecuzione (nessun globbing
|
||||
e nessuna espansione di `$VARS`) per i segmenti solo stdin, quindi pattern come `*` o `$HOME/...` non possono essere
|
||||
usati per introdurre di nascosto letture di file.
|
||||
I safe bin devono inoltre risolversi da directory di binari trusted (valori predefiniti di sistema più eventuali
|
||||
`tools.exec.safeBinTrustedDirs`). Le voci `PATH` non sono mai auto-trusted.
|
||||
Le directory trusted predefinite dei safe bin sono intenzionalmente minime: `/bin`, `/usr/bin`.
|
||||
Se il tuo eseguibile safe-bin si trova in path di package-manager/utente (ad esempio
|
||||
I safe bin devono inoltre risolversi da directory di binari attendibili (valori predefiniti di sistema più eventuali
|
||||
`tools.exec.safeBinTrustedDirs`). Le voci di `PATH` non vengono mai considerate attendibili automaticamente.
|
||||
Le directory attendibili predefinite per i safe bin sono intenzionalmente minime: `/bin`, `/usr/bin`.
|
||||
Se il tuo eseguibile safe-bin si trova in percorsi package-manager/utente (ad esempio
|
||||
`/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), aggiungili esplicitamente
|
||||
a `tools.exec.safeBinTrustedDirs`.
|
||||
Il chaining shell e le redirezioni non sono auto-consentiti in modalità allowlist.
|
||||
Le concatenazioni shell e i reindirizzamenti non sono consentiti automaticamente in modalità allowlist.
|
||||
|
||||
Il chaining shell (`&&`, `||`, `;`) è consentito quando ogni segmento di primo livello soddisfa l'allowlist
|
||||
(inclusi safe bin o auto-allow delle skill). Le redirezioni restano non supportate in modalità allowlist.
|
||||
La command substitution (`$()` / backtick) viene rifiutata durante il parsing dell'allowlist, inclusa all'interno
|
||||
La concatenazione shell (`&&`, `||`, `;`) è consentita quando ogni segmento di primo livello soddisfa l'allowlist
|
||||
(inclusi safe bin o auto-consenti delle skill). I reindirizzamenti restano non supportati in modalità allowlist.
|
||||
La sostituzione di comandi (`$()` / backtick) viene rifiutata durante il parsing dell'allowlist, incluso all'interno
|
||||
delle virgolette doppie; usa virgolette singole se ti serve testo letterale `$()`.
|
||||
Nelle approvazioni dell'app companion macOS, il testo shell grezzo contenente sintassi di controllo o espansione della shell
|
||||
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) viene trattato come un mancato match dell'allowlist a meno che
|
||||
il binario shell stesso non sia nell'allowlist.
|
||||
Per i wrapper shell (`bash|sh|zsh ... -c/-lc`), gli override env con ambito richiesta sono ridotti a una
|
||||
Nelle approvazioni dell'app companion macOS, il testo shell grezzo contenente sintassi di controllo o espansione shell
|
||||
(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`) viene trattato come mancata corrispondenza dell'allowlist a meno che
|
||||
il binario della shell stessa non sia nell'allowlist.
|
||||
Per i wrapper shell (`bash|sh|zsh ... -c/-lc`), gli override `env` con ambito richiesta vengono ridotti a una
|
||||
piccola allowlist esplicita (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`).
|
||||
Per le decisioni allow-always in modalità allowlist, i wrapper di dispatch noti
|
||||
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) persistono i path degli eseguibili interni invece dei path dei wrapper.
|
||||
Anche i multiplexer shell (`busybox`, `toybox`) vengono spacchettati per gli applet shell (`sh`, `ash`,
|
||||
ecc.) così vengono persistiti gli eseguibili interni invece dei binari del multiplexer. Se un wrapper o
|
||||
multiplexer non può essere spacchettato in sicurezza, nessuna voce di allowlist viene persistita automaticamente.
|
||||
Se inserisci nell'allowlist interpreter come `python3` o `node`, preferisci `tools.exec.strictInlineEval=true` così l'eval inline richiede comunque approvazione esplicita. In modalità strict, `allow-always` può ancora persistere invocazioni benigne di interpreter/script, ma i vettori di eval inline non vengono persistiti automaticamente.
|
||||
(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) persistono i percorsi degli eseguibili interni invece dei
|
||||
percorsi dei wrapper. Anche i multiplexer shell (`busybox`, `toybox`) vengono spacchettati per le applet shell (`sh`, `ash`,
|
||||
ecc.) così che vengano persistiti gli eseguibili interni invece dei binari del multiplexer. Se un wrapper o
|
||||
un multiplexer non può essere spacchettato in modo sicuro, nessuna voce di allowlist viene persistita automaticamente.
|
||||
Se inserisci interpreti come `python3` o `node` nell'allowlist, preferisci `tools.exec.strictInlineEval=true` così l'eval inline richiede comunque un'approvazione esplicita. In modalità strict, `allow-always` può comunque rendere persistenti invocazioni innocue di interpreti/script, ma i vettori di inline-eval non vengono persistiti automaticamente.
|
||||
|
||||
Safe bin predefiniti:
|
||||
|
||||
@ -313,103 +339,104 @@ Safe bin predefiniti:
|
||||
[//]: # "SAFE_BIN_DEFAULTS:END"
|
||||
|
||||
`grep` e `sort` non sono nell'elenco predefinito. Se li abiliti esplicitamente, mantieni voci di allowlist esplicite per
|
||||
i loro workflow non-stdin.
|
||||
Per `grep` in modalità safe-bin, fornisci il pattern con `-e`/`--regexp`; la forma con pattern posizionale è
|
||||
rifiutata così gli operandi file non possono essere introdotti di nascosto come posizionali ambigui.
|
||||
i loro flussi di lavoro non-stdin.
|
||||
Per `grep` in modalità safe-bin, fornisci il pattern con `-e`/`--regexp`; la forma con pattern posizionale viene
|
||||
rifiutata così che gli operandi file non possano essere introdotti di nascosto come posizionali ambigui.
|
||||
|
||||
### Safe bins vs allowlist
|
||||
### Safe bin rispetto all'allowlist
|
||||
|
||||
| Argomento | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) |
|
||||
| Argomento | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) |
|
||||
| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
|
||||
| Obiettivo | Auto-consentire filtri stdin ristretti | Affidarsi esplicitamente a eseguibili specifici |
|
||||
| Tipo di corrispondenza | Nome dell'eseguibile + policy argv del safe-bin | Pattern glob del path dell'eseguibile risolto |
|
||||
| Ambito degli argomenti | Limitato dal profilo safe-bin e dalle regole dei token letterali | Solo corrispondenza del path; gli argomenti sono altrimenti responsabilità tua |
|
||||
| Esempi tipici | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, CLI personalizzate |
|
||||
| Miglior uso | Trasformazioni testuali a basso rischio nelle pipeline | Qualsiasi strumento con comportamento più ampio o effetti collaterali |
|
||||
| Obiettivo | Consenti automaticamente filtri stdin limitati | Considera attendibili esplicitamente eseguibili specifici |
|
||||
| Tipo di match | Nome dell'eseguibile + criterio `argv` del safe-bin | Pattern glob del percorso dell'eseguibile risolto |
|
||||
| Ambito argomenti | Limitato dal profilo safe-bin e dalle regole dei token letterali | Solo match del percorso; per il resto gli argomenti sono tua responsabilità |
|
||||
| Esempi tipici | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, CLI personalizzate |
|
||||
| Uso migliore | Trasformazioni di testo a basso rischio nelle pipeline | Qualsiasi strumento con comportamento più ampio o effetti collaterali |
|
||||
|
||||
Posizione della configurazione:
|
||||
|
||||
- `safeBins` proviene dalla configurazione (`tools.exec.safeBins` oppure per agente `agents.list[].tools.exec.safeBins`).
|
||||
- `safeBinTrustedDirs` proviene dalla configurazione (`tools.exec.safeBinTrustedDirs` oppure per agente `agents.list[].tools.exec.safeBinTrustedDirs`).
|
||||
- `safeBinProfiles` proviene dalla configurazione (`tools.exec.safeBinProfiles` oppure per agente `agents.list[].tools.exec.safeBinProfiles`). Le chiavi dei profili per agente sovrascrivono le chiavi globali.
|
||||
- Le voci di allowlist vivono nel file host-local `~/.openclaw/exec-approvals.json` sotto `agents.<id>.allowlist` (oppure tramite Control UI / `openclaw approvals allowlist ...`).
|
||||
- `openclaw security audit` avvisa con `tools.exec.safe_bins_interpreter_unprofiled` quando bin interpreter/runtime compaiono in `safeBins` senza profili espliciti.
|
||||
- `openclaw doctor --fix` può creare lo scaffold delle voci mancanti `safeBinProfiles.<bin>` come `{}` (rivedile e restringile in seguito). I bin interpreter/runtime non vengono creati automaticamente.
|
||||
- `safeBins` proviene dalla configurazione (`tools.exec.safeBins` o per-agente `agents.list[].tools.exec.safeBins`).
|
||||
- `safeBinTrustedDirs` proviene dalla configurazione (`tools.exec.safeBinTrustedDirs` o per-agente `agents.list[].tools.exec.safeBinTrustedDirs`).
|
||||
- `safeBinProfiles` proviene dalla configurazione (`tools.exec.safeBinProfiles` o per-agente `agents.list[].tools.exec.safeBinProfiles`). Le chiavi di profilo per-agente sovrascrivono le chiavi globali.
|
||||
- le voci di allowlist risiedono nel file locale dell'host `~/.openclaw/exec-approvals.json` in `agents.<id>.allowlist` (oppure tramite Control UI / `openclaw approvals allowlist ...`).
|
||||
- `openclaw security audit` avvisa con `tools.exec.safe_bins_interpreter_unprofiled` quando binari di interpreti/runtime compaiono in `safeBins` senza profili espliciti.
|
||||
- `openclaw doctor --fix` può generare le voci mancanti `safeBinProfiles.<bin>` come `{}` (rivedile e rendile più restrittive in seguito). I binari di interpreti/runtime non vengono generati automaticamente.
|
||||
|
||||
Esempio di profilo personalizzato:
|
||||
__OC_I18N_900004__
|
||||
Se includi esplicitamente `jq` in `safeBins`, OpenClaw rifiuta comunque il builtin `env` in modalità safe-bin
|
||||
così `jq -n env` non può scaricare l'ambiente del processo host senza un path esplicito nell'allowlist
|
||||
__OC_I18N_900005__
|
||||
Se abiliti esplicitamente `jq` in `safeBins`, OpenClaw continua comunque a rifiutare la builtin `env` in modalità safe-bin
|
||||
così che `jq -n env` non possa esporre l'ambiente del processo host senza un percorso esplicito nell'allowlist
|
||||
o un prompt di approvazione.
|
||||
|
||||
## Modifica nella Control UI
|
||||
|
||||
Usa la scheda **Control UI → Nodes → Exec approvals** per modificare valori predefiniti, override
|
||||
per agente e allowlist. Scegli un ambito (Defaults o un agente), modifica la policy,
|
||||
aggiungi/rimuovi pattern di allowlist, quindi fai clic su **Save**. La UI mostra i metadati di **ultimo utilizzo**
|
||||
per pattern così puoi mantenere l'elenco ordinato.
|
||||
Usa la scheda **Control UI → Nodes → Exec approvals** per modificare i valori predefiniti, gli
|
||||
override per-agente e le allowlist. Scegli un ambito (Defaults o un agente), modifica il criterio,
|
||||
aggiungi/rimuovi pattern di allowlist, quindi fai clic su **Save**. L'interfaccia mostra i metadati di **ultimo utilizzo**
|
||||
per pattern così puoi mantenere ordinato l'elenco.
|
||||
|
||||
Il selettore del target sceglie **Gateway** (approvazioni locali) oppure un **Node**. I nodi
|
||||
devono pubblicizzare `system.execApprovals.get/set` (app macOS o host nodo headless).
|
||||
Se un nodo non pubblicizza ancora le approvazioni exec, modifica direttamente il suo file locale
|
||||
Il selettore della destinazione sceglie **Gateway** (approvazioni locali) oppure un **Node**. I nodi
|
||||
devono dichiarare `system.execApprovals.get/set` (app macOS o host nodo headless).
|
||||
Se un nodo non dichiara ancora le approvazioni exec, modifica direttamente il suo file locale
|
||||
`~/.openclaw/exec-approvals.json`.
|
||||
|
||||
CLI: `openclaw approvals` supporta la modifica del gateway o del nodo (vedi [Approvals CLI](/cli/approvals)).
|
||||
CLI: `openclaw approvals` supporta la modifica di gateway o nodo (vedi [Approvals CLI](/cli/approvals)).
|
||||
|
||||
## Flusso di approvazione
|
||||
|
||||
Quando è richiesto un prompt, il gateway trasmette `exec.approval.requested` ai client operator.
|
||||
La Control UI e la app macOS lo risolvono tramite `exec.approval.resolve`, quindi il gateway inoltra la
|
||||
Quando è richiesto un prompt, il gateway trasmette `exec.approval.requested` ai client operatore.
|
||||
La Control UI e l'app macOS lo risolvono tramite `exec.approval.resolve`, quindi il gateway inoltra la
|
||||
richiesta approvata all'host del nodo.
|
||||
|
||||
Per `host=node`, le richieste di approvazione includono un payload canonico `systemRunPlan`. Il gateway usa
|
||||
quel piano come contesto autorevole di comando/cwd/sessione quando inoltra richieste approvate `system.run`.
|
||||
quel piano come contesto autorevole di comando/cwd/sessione quando inoltra le richieste approvate di `system.run`.
|
||||
|
||||
Questo è importante per la latenza dell'approvazione asincrona:
|
||||
Questo è importante per la latenza delle approvazioni asincrone:
|
||||
|
||||
- il percorso exec del nodo prepara un unico piano canonico in anticipo
|
||||
- il record di approvazione memorizza quel piano e i relativi metadati di binding
|
||||
- una volta approvato, la chiamata finale inoltrata `system.run` riusa il piano memorizzato
|
||||
invece di fidarsi di successive modifiche del chiamante
|
||||
- se il chiamante cambia `command`, `rawCommand`, `cwd`, `agentId` oppure
|
||||
`sessionKey` dopo che la richiesta di approvazione è stata creata, il gateway rifiuta l'esecuzione
|
||||
inoltrata come mismatch di approvazione
|
||||
- il percorso exec del nodo prepara in anticipo un unico piano canonico
|
||||
- il record di approvazione memorizza quel piano e i suoi metadati di binding
|
||||
- una volta approvato, la chiamata finale inoltrata `system.run` riutilizza il piano memorizzato
|
||||
invece di fidarsi di modifiche successive del chiamante
|
||||
- se il chiamante modifica `command`, `rawCommand`, `cwd`, `agentId` o
|
||||
`sessionKey` dopo che la richiesta di approvazione è stata creata, il gateway rifiuta
|
||||
l'esecuzione inoltrata come mancata corrispondenza dell'approvazione
|
||||
|
||||
## Comandi interpreter/runtime
|
||||
## Comandi di interprete/runtime
|
||||
|
||||
Le esecuzioni di interpreter/runtime supportate da approvazione sono intenzionalmente conservative:
|
||||
Le esecuzioni di interprete/runtime supportate da approvazione sono intenzionalmente conservative:
|
||||
|
||||
- Il contesto esatto di argv/cwd/env viene sempre vincolato.
|
||||
- Le forme di script shell diretto e file runtime diretto vengono vincolate in best-effort a uno snapshot di file locale concreto.
|
||||
- Le forme comuni di wrapper di package manager che si risolvono comunque in un singolo file locale diretto (ad esempio
|
||||
- Il contesto esatto di argv/cwd/env è sempre vincolato.
|
||||
- Le forme dirette di script shell e di file runtime diretto vengono vincolate in best-effort a un unico snapshot
|
||||
di file locale concreto.
|
||||
- Le comuni forme wrapper di package-manager che si risolvono comunque in un unico file locale diretto (ad esempio
|
||||
`pnpm exec`, `pnpm node`, `npm exec`, `npx`) vengono spacchettate prima del binding.
|
||||
- Se OpenClaw non riesce a identificare esattamente un singolo file locale concreto per un comando interpreter/runtime
|
||||
(ad esempio script di package, forme eval, catene di loader specifiche del runtime o forme ambigue multi-file),
|
||||
l'esecuzione supportata da approvazione viene negata invece di affermare una copertura semantica che in realtà non
|
||||
possiede.
|
||||
- Per questi workflow, preferisci la sandbox, un confine host separato o un workflow esplicito trusted
|
||||
di allowlist/full in cui l'operatore accetta la semantica runtime più ampia.
|
||||
- Se OpenClaw non riesce a identificare esattamente un unico file locale concreto per un comando di interprete/runtime
|
||||
(ad esempio script di package, forme eval, catene di loader specifiche del runtime o forme
|
||||
ambigue multi-file), l'esecuzione supportata da approvazione viene negata invece di dichiarare una copertura semantica
|
||||
che in realtà non ha.
|
||||
- Per questi flussi di lavoro, preferisci la sandbox, un confine host separato o un flusso esplicito
|
||||
allowlist/full attendibile in cui l'operatore accetta la semantica più ampia del runtime.
|
||||
|
||||
Quando sono richieste approvazioni, lo strumento exec restituisce immediatamente un id di approvazione. Usa quell'id per
|
||||
Quando sono richieste approvazioni, lo strumento exec restituisce immediatamente un ID di approvazione. Usa quell'ID per
|
||||
correlare eventi di sistema successivi (`Exec finished` / `Exec denied`). Se non arriva alcuna decisione prima del
|
||||
timeout, la richiesta viene trattata come timeout di approvazione e mostrata come motivo di negazione.
|
||||
timeout, la richiesta viene trattata come timeout di approvazione ed esposta come motivo di negazione.
|
||||
|
||||
### Comportamento di consegna del follow-up
|
||||
### Comportamento di consegna del followup
|
||||
|
||||
Dopo che un exec asincrono approvato è terminato, OpenClaw invia un turno `agent` di follow-up alla stessa sessione.
|
||||
Dopo che un exec asincrono approvato termina, OpenClaw invia un turno `agent` di followup alla stessa sessione.
|
||||
|
||||
- Se esiste un target di consegna esterno valido (canale consegnabile più target `to`), il follow-up usa quel canale.
|
||||
- Nei flussi solo webchat o sessione interna senza target esterno, la consegna del follow-up resta solo di sessione (`deliver: false`).
|
||||
- Se esiste una destinazione di consegna esterna valida (canale consegnabile più target `to`), la consegna del followup usa quel canale.
|
||||
- Nei flussi solo webchat o solo sessione interna senza destinazione esterna, la consegna del followup resta solo di sessione (`deliver: false`).
|
||||
- Se un chiamante richiede esplicitamente una consegna esterna rigorosa senza alcun canale esterno risolvibile, la richiesta fallisce con `INVALID_REQUEST`.
|
||||
- Se `bestEffortDeliver` è abilitato e non è possibile risolvere alcun canale esterno, la consegna viene degradata a sola sessione invece di fallire.
|
||||
- Se `bestEffortDeliver` è abilitato e non può essere risolto alcun canale esterno, la consegna viene declassata a solo sessione invece di fallire.
|
||||
|
||||
La finestra di dialogo di conferma include:
|
||||
|
||||
- comando + argomenti
|
||||
- cwd
|
||||
- id agente
|
||||
- path dell'eseguibile risolto
|
||||
- host + metadati della policy
|
||||
- percorso dell'eseguibile risolto
|
||||
- host + metadati del criterio
|
||||
|
||||
Azioni:
|
||||
|
||||
@ -420,102 +447,101 @@ Azioni:
|
||||
## Inoltro delle approvazioni ai canali chat
|
||||
|
||||
Puoi inoltrare i prompt di approvazione exec a qualsiasi canale chat (inclusi i canali plugin) e approvarli
|
||||
con `/approve`. Questo usa il normale pipeline di consegna in uscita.
|
||||
con `/approve`. Questo usa la normale pipeline di consegna in uscita.
|
||||
|
||||
Configurazione:
|
||||
__OC_I18N_900005__
|
||||
Rispondi in chat:
|
||||
__OC_I18N_900006__
|
||||
Il comando `/approve` gestisce sia le approvazioni exec sia le approvazioni dei plugin. Se l'ID non corrisponde a un'approvazione exec in sospeso, controlla automaticamente invece le approvazioni dei plugin.
|
||||
|
||||
### Inoltro delle approvazioni dei plugin
|
||||
|
||||
L'inoltro delle approvazioni dei plugin usa lo stesso pipeline di consegna delle approvazioni exec ma ha una
|
||||
configurazione indipendente sotto `approvals.plugin`. Abilitare o disabilitare l'una non influisce sull'altra.
|
||||
Rispondi nella chat:
|
||||
__OC_I18N_900007__
|
||||
Il comando `/approve` gestisce sia le approvazioni exec sia le approvazioni plugin. Se l'ID non corrisponde a un'approvazione exec in attesa, controlla automaticamente invece le approvazioni plugin.
|
||||
|
||||
### Inoltro delle approvazioni plugin
|
||||
|
||||
L'inoltro delle approvazioni plugin usa la stessa pipeline di consegna delle approvazioni exec, ma ha una propria
|
||||
configurazione indipendente in `approvals.plugin`. Abilitare o disabilitare una non influisce sull'altra.
|
||||
__OC_I18N_900008__
|
||||
La forma della configurazione è identica a `approvals.exec`: `enabled`, `mode`, `agentFilter`,
|
||||
`sessionFilter` e `targets` funzionano allo stesso modo.
|
||||
|
||||
I canali che supportano risposte interattive condivise renderizzano gli stessi pulsanti di approvazione sia per le approvazioni exec sia per quelle dei plugin. I canali senza UI interattiva condivisa ricadono su testo semplice con istruzioni `/approve`.
|
||||
I canali che supportano risposte interattive condivise mostrano gli stessi pulsanti di approvazione sia per le approvazioni exec sia per quelle plugin. I canali senza UI interattiva condivisa ricorrono al testo semplice con istruzioni `/approve`.
|
||||
|
||||
### Approvazioni nella stessa chat su qualsiasi canale
|
||||
|
||||
Quando una richiesta di approvazione exec o plugin ha origine da una superficie chat consegnabile, la stessa chat
|
||||
può ora approvarla con `/approve` per impostazione predefinita. Questo si applica a canali come Slack, Matrix e
|
||||
Quando una richiesta di approvazione exec o plugin proviene da una superficie chat consegnabile, la stessa chat
|
||||
può ora approvarla con `/approve` per impostazione predefinita. Questo vale per canali come Slack, Matrix e
|
||||
Microsoft Teams oltre ai flussi già esistenti di Web UI e terminal UI.
|
||||
|
||||
Questo percorso condiviso tramite comando testuale usa il normale modello auth del canale per quella conversazione. Se la
|
||||
Questo percorso condiviso di comando testuale usa il normale modello di autenticazione del canale per quella conversazione. Se la
|
||||
chat di origine può già inviare comandi e ricevere risposte, le richieste di approvazione non hanno più bisogno di un
|
||||
adattatore di consegna nativo separato solo per restare in sospeso.
|
||||
adapter di consegna nativo separato solo per restare in attesa.
|
||||
|
||||
Discord e Telegram supportano anche `/approve` nella stessa chat, ma quei canali usano ancora
|
||||
il loro elenco di approvatori risolto per l'autorizzazione anche quando la consegna nativa delle approvazioni è disabilitata.
|
||||
Discord e Telegram supportano anche `/approve` nella stessa chat, ma questi canali usano comunque il loro
|
||||
elenco approvatori risolto per l'autorizzazione anche quando la consegna nativa delle approvazioni è disabilitata.
|
||||
|
||||
Per Telegram e altri client di approvazione nativi che chiamano direttamente il Gateway,
|
||||
questo fallback è intenzionalmente limitato ai fallimenti "approvazione non trovata". Un vero
|
||||
rifiuto/errore di approvazione exec non ritenta silenziosamente come approvazione plugin.
|
||||
questo fallback è intenzionalmente limitato ai fallimenti "approval not found". Un vero
|
||||
rifiuto/errore di approvazione exec non viene ritentato silenziosamente come approvazione plugin.
|
||||
|
||||
### Consegna di approvazioni native
|
||||
### Consegna nativa delle approvazioni
|
||||
|
||||
Alcuni canali possono anche agire come client nativi di approvazione. I client nativi aggiungono DM degli approvatori, fanout della chat di origine e UX di approvazione interattiva specifica del canale sopra il flusso condiviso `/approve`
|
||||
nella stessa chat.
|
||||
Alcuni canali possono anche agire come client di approvazione nativi. I client nativi aggiungono DM agli approvatori, fanout alla chat di origine e UX di approvazione interattiva specifica del canale sopra il flusso condiviso `/approve` nella stessa chat.
|
||||
|
||||
Quando sono disponibili card/pulsanti di approvazione nativi, quella UI nativa è il
|
||||
percorso principale rivolto all'agente. L'agente non dovrebbe anche ripetere un duplicato del comando semplice in chat
|
||||
`/approve`, a meno che il risultato dello strumento non dica che le approvazioni in chat non sono disponibili o che
|
||||
l'approvazione manuale sia l'unico percorso rimasto.
|
||||
Quando sono disponibili card/pulsanti di approvazione nativi, quella UI nativa è il percorso principale
|
||||
visibile all'agente. L'agente non dovrebbe anche ripetere un comando semplice di chat
|
||||
`/approve` duplicato, a meno che il risultato dello strumento indichi che le approvazioni via chat non sono disponibili o
|
||||
che l'approvazione manuale è l'unico percorso rimasto.
|
||||
|
||||
Modello generico:
|
||||
|
||||
- la policy exec host continua a decidere se è richiesta l'approvazione exec
|
||||
- `approvals.exec` controlla l'inoltro dei prompt di approvazione ad altre destinazioni chat
|
||||
- `channels.<channel>.execApprovals` controlla se quel canale agisce come client nativo di approvazione
|
||||
- il criterio exec host continua a decidere se è richiesta un'approvazione exec
|
||||
- `approvals.exec` controlla l'inoltro dei prompt di approvazione verso altre destinazioni chat
|
||||
- `channels.<channel>.execApprovals` controlla se quel canale agisce come client di approvazione nativo
|
||||
|
||||
I client nativi di approvazione abilitano automaticamente la consegna DM-first quando tutte queste condizioni sono vere:
|
||||
I client di approvazione nativi abilitano automaticamente la consegna DM-first quando tutte queste condizioni sono vere:
|
||||
|
||||
- il canale supporta la consegna nativa delle approvazioni
|
||||
- gli approvatori possono essere risolti da `execApprovals.approvers` espliciti o dalle fonti di fallback documentate
|
||||
di quel canale
|
||||
- il canale supporta la consegna di approvazioni native
|
||||
- gli approvatori possono essere risolti da `execApprovals.approvers` esplicito oppure dalle
|
||||
origini di fallback documentate di quel canale
|
||||
- `channels.<channel>.execApprovals.enabled` non è impostato oppure è `"auto"`
|
||||
|
||||
Imposta `enabled: false` per disabilitare esplicitamente un client nativo di approvazione. Imposta `enabled: true` per forzarlo
|
||||
quando gli approvatori si risolvono. La consegna pubblica nella chat di origine resta esplicita tramite
|
||||
Imposta `enabled: false` per disabilitare esplicitamente un client di approvazione nativo. Imposta `enabled: true` per forzarlo
|
||||
all'attivazione quando gli approvatori vengono risolti. La consegna pubblica alla chat di origine resta esplicita tramite
|
||||
`channels.<channel>.execApprovals.target`.
|
||||
|
||||
FAQ: [Perché ci sono due configurazioni delle approvazioni exec per le approvazioni chat?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
|
||||
FAQ: [Perché esistono due configurazioni di approvazione exec per le approvazioni in chat?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals)
|
||||
|
||||
- Discord: `channels.discord.execApprovals.*`
|
||||
- Slack: `channels.slack.execApprovals.*`
|
||||
- Telegram: `channels.telegram.execApprovals.*`
|
||||
|
||||
Questi client nativi di approvazione aggiungono routing DM e fanout facoltativo del canale sopra il flusso condiviso
|
||||
Questi client di approvazione nativi aggiungono instradamento DM e fanout opzionale del canale sopra il flusso condiviso
|
||||
`/approve` nella stessa chat e i pulsanti di approvazione condivisi.
|
||||
|
||||
Comportamento condiviso:
|
||||
|
||||
- Slack, Matrix, Microsoft Teams e chat consegnabili simili usano il normale modello auth del canale
|
||||
- Slack, Matrix, Microsoft Teams e chat consegnabili simili usano il normale modello di autenticazione del canale
|
||||
per `/approve` nella stessa chat
|
||||
- quando un client nativo di approvazione si abilita automaticamente, il target di consegna nativo predefinito sono i DM degli approvatori
|
||||
- quando un client di approvazione nativo si abilita automaticamente, la destinazione nativa predefinita di consegna sono i DM degli approvatori
|
||||
- per Discord e Telegram, solo gli approvatori risolti possono approvare o negare
|
||||
- gli approvatori Discord possono essere espliciti (`execApprovals.approvers`) o dedotti da `commands.ownerAllowFrom`
|
||||
- gli approvatori Telegram possono essere espliciti (`execApprovals.approvers`) o dedotti dalla configurazione owner esistente (`allowFrom`, più `defaultTo` dei messaggi diretti dove supportato)
|
||||
- gli approvatori Telegram possono essere espliciti (`execApprovals.approvers`) o dedotti dalla configurazione owner esistente (`allowFrom`, più `defaultTo` del messaggio diretto dove supportato)
|
||||
- gli approvatori Slack possono essere espliciti (`execApprovals.approvers`) o dedotti da `commands.ownerAllowFrom`
|
||||
- i pulsanti nativi Slack preservano il tipo di id di approvazione, così gli id `plugin:` possono risolvere le approvazioni dei plugin
|
||||
- i pulsanti nativi di Slack preservano il tipo dell'ID di approvazione, quindi gli ID `plugin:` possono risolvere le approvazioni plugin
|
||||
senza un secondo livello di fallback locale a Slack
|
||||
- il routing DM/canale nativo di Matrix e le scorciatoie a reazione gestiscono sia le approvazioni exec sia quelle plugin;
|
||||
l'autorizzazione dei plugin continua comunque a provenire da `channels.matrix.dm.allowFrom`
|
||||
- il richiedente non deve necessariamente essere un approvatore
|
||||
- l'instradamento nativo DM/canale di Matrix e le scorciatoie tramite reaction gestiscono sia le approvazioni exec sia quelle plugin;
|
||||
l'autorizzazione plugin continua però a provenire da `channels.matrix.dm.allowFrom`
|
||||
- chi effettua la richiesta non deve essere un approvatore
|
||||
- la chat di origine può approvare direttamente con `/approve` quando quella chat supporta già comandi e risposte
|
||||
- i pulsanti nativi di approvazione Discord instradano in base al tipo di id di approvazione: gli id `plugin:` vanno
|
||||
direttamente alle approvazioni dei plugin, tutto il resto va alle approvazioni exec
|
||||
- i pulsanti nativi di approvazione Telegram seguono lo stesso fallback limitato da exec a plugin di `/approve`
|
||||
- quando `target` nativo abilita la consegna nella chat di origine, i prompt di approvazione includono il testo del comando
|
||||
- le approvazioni exec in sospeso scadono dopo 30 minuti per impostazione predefinita
|
||||
- se nessuna UI operatore o client di approvazione configurato può accettare la richiesta, il prompt torna a `askFallback`
|
||||
- i pulsanti nativi di approvazione Discord instradano in base al tipo dell'ID di approvazione: gli ID `plugin:` vanno
|
||||
direttamente alle approvazioni plugin, tutto il resto va alle approvazioni exec
|
||||
- i pulsanti nativi di approvazione Telegram seguono lo stesso fallback limitato exec-to-plugin di `/approve`
|
||||
- quando `target` nativo abilita la consegna alla chat di origine, i prompt di approvazione includono il testo del comando
|
||||
- le approvazioni exec in attesa scadono dopo 30 minuti per impostazione predefinita
|
||||
- se nessuna UI operatore o client di approvazione configurato può accettare la richiesta, il prompt ricorre a `askFallback`
|
||||
|
||||
Telegram usa come predefinito i DM degli approvatori (`target: "dm"`). Puoi passare a `channel` o `both` quando
|
||||
vuoi che i prompt di approvazione appaiano anche nella chat/topic Telegram di origine. Per i topic forum Telegram,
|
||||
OpenClaw preserva il topic per il prompt di approvazione e per il follow-up post-approvazione.
|
||||
Telegram usa come valore predefinito i DM degli approvatori (`target: "dm"`). Puoi passare a `channel` o `both` quando
|
||||
vuoi che i prompt di approvazione compaiano anche nella chat/topic Telegram di origine. Per i topic forum di Telegram,
|
||||
OpenClaw preserva il topic per il prompt di approvazione e il follow-up post-approvazione.
|
||||
|
||||
Vedi:
|
||||
|
||||
@ -523,10 +549,10 @@ Vedi:
|
||||
- [Telegram](/channels/telegram)
|
||||
|
||||
### Flusso IPC macOS
|
||||
__OC_I18N_900008__
|
||||
__OC_I18N_900009__
|
||||
Note di sicurezza:
|
||||
|
||||
- Modalità socket Unix `0600`, token memorizzato in `exec-approvals.json`.
|
||||
- Modalità del socket Unix `0600`, token archiviato in `exec-approvals.json`.
|
||||
- Controllo del peer con stesso UID.
|
||||
- Challenge/response (nonce + token HMAC + hash della richiesta) + TTL breve.
|
||||
|
||||
@ -534,40 +560,40 @@ Note di sicurezza:
|
||||
|
||||
Il ciclo di vita exec viene esposto come messaggi di sistema:
|
||||
|
||||
- `Exec running` (solo se il comando supera la soglia di notifica running)
|
||||
- `Exec running` (solo se il comando supera la soglia dell'avviso di esecuzione)
|
||||
- `Exec finished`
|
||||
- `Exec denied`
|
||||
|
||||
Questi vengono pubblicati nella sessione dell'agente dopo che il nodo segnala l'evento.
|
||||
Le approvazioni exec sull'host gateway emettono gli stessi eventi di ciclo di vita quando il comando termina (e facoltativamente quando è in esecuzione oltre la soglia).
|
||||
Gli exec soggetti ad approvazione riutilizzano l'id di approvazione come `runId` in questi messaggi per una facile correlazione.
|
||||
Le approvazioni exec sull'host gateway emettono gli stessi eventi di ciclo di vita quando il comando termina (e facoltativamente quando è in esecuzione più a lungo della soglia).
|
||||
Gli exec soggetti ad approvazione riutilizzano l'ID di approvazione come `runId` in questi messaggi per una correlazione semplice.
|
||||
|
||||
## Comportamento delle approvazioni negate
|
||||
|
||||
Quando un'approvazione exec asincrona viene negata, OpenClaw impedisce all'agente di riutilizzare
|
||||
l'output di eventuali esecuzioni precedenti dello stesso comando nella sessione. Il motivo della negazione
|
||||
l'output di qualsiasi esecuzione precedente dello stesso comando nella sessione. Il motivo del rifiuto
|
||||
viene passato con indicazioni esplicite che nessun output del comando è disponibile, il che impedisce
|
||||
all'agente di affermare che c'è nuovo output o di ripetere il comando negato con
|
||||
risultati obsoleti di una precedente esecuzione riuscita.
|
||||
all'agente di dichiarare che c'è un nuovo output o di ripetere il comando negato con
|
||||
risultati obsoleti da una precedente esecuzione riuscita.
|
||||
|
||||
## Implicazioni
|
||||
|
||||
- **full** è potente; preferisci le allowlist quando possibile.
|
||||
- **ask** ti mantiene nel ciclo consentendo comunque approvazioni rapide.
|
||||
- Le allowlist per agente impediscono che le approvazioni di un agente si trasferiscano ad altri.
|
||||
- Le approvazioni si applicano solo alle richieste exec host provenienti da **mittenti autorizzati**. I mittenti non autorizzati non possono emettere `/exec`.
|
||||
- `/exec security=full` è una comodità a livello di sessione per operatori autorizzati e salta le approvazioni per progettazione.
|
||||
Per bloccare rigidamente l'exec host, imposta la security delle approvazioni su `deny` oppure nega lo strumento `exec` tramite tool policy.
|
||||
- **ask** ti mantiene nel circuito pur consentendo approvazioni rapide.
|
||||
- Le allowlist per-agente impediscono che le approvazioni di un agente si propaghino ad altri.
|
||||
- Le approvazioni si applicano solo alle richieste di exec host provenienti da **mittenti autorizzati**. I mittenti non autorizzati non possono emettere `/exec`.
|
||||
- `/exec security=full` è una comodità a livello di sessione per operatori autorizzati e per progettazione salta le approvazioni.
|
||||
Per bloccare rigidamente l'exec host, imposta la security delle approvazioni su `deny` o nega lo strumento `exec` tramite il criterio degli strumenti.
|
||||
|
||||
Correlati:
|
||||
|
||||
- [Strumento exec](/it/tools/exec)
|
||||
- [Modalità elevated](/it/tools/elevated)
|
||||
- [Exec tool](/it/tools/exec)
|
||||
- [Elevated mode](/it/tools/elevated)
|
||||
- [Skills](/it/tools/skills)
|
||||
|
||||
## Correlati
|
||||
|
||||
- [Exec](/it/tools/exec) — strumento di esecuzione dei comandi shell
|
||||
- [Exec](/it/tools/exec) — strumento di esecuzione di comandi shell
|
||||
- [Sandboxing](/it/gateway/sandboxing) — modalità sandbox e accesso al workspace
|
||||
- [Security](/it/gateway/security) — modello di sicurezza e hardening
|
||||
- [Sandbox vs Tool Policy vs Elevated](/it/gateway/sandbox-vs-tool-policy-vs-elevated) — quando usare ciascuno
|
||||
|
||||
Loading…
Reference in New Issue
Block a user