Skip to main content
L’app macOS incorpora un pannello Canvas controllato dall’agente mediante WKWebView, uno spazio di lavoro visivo leggero per HTML/CSS/JS, A2UI e piccole superfici di interfaccia utente interattive.

​
Dove si trova Canvas

Lo stato di Canvas viene archiviato in Application Support:
  • ~/Library/Application Support/OpenClaw/canvas/<session>/...
Il pannello Canvas espone questi file mediante uno schema URL personalizzato, openclaw-canvas://<session>/<path>:
  • openclaw-canvas://main/ -> <canvasRoot>/main/index.html
  • openclaw-canvas://main/assets/app.css -> <canvasRoot>/main/assets/app.css
  • openclaw-canvas://main/widgets/todo/ -> <canvasRoot>/main/widgets/todo/index.html
Se nella radice non esiste alcun index.html, l’app mostra una pagina di base integrata.

​
Comportamento del pannello

  • Pannello senza bordi e ridimensionabile, ancorato vicino alla barra dei menu (o al cursore del mouse).
  • Memorizza dimensioni e posizione per ogni sessione.
  • Si ricarica automaticamente quando cambiano i file Canvas locali.
  • È visibile un solo pannello Canvas alla volta (la sessione cambia secondo necessità).
Canvas può essere disabilitato da Settings -> Allow Canvas. Quando è disabilitato, i comandi Canvas del nodo restituiscono CANVAS_DISABLED.

​
Superficie API dell’agente

Canvas è esposto tramite il WebSocket del Gateway, consentendo all’agente di mostrare o nascondere il pannello, passare a un percorso o URL, valutare JavaScript e acquisire un’immagine istantanea:
canvas.navigate accetta percorsi Canvas locali, URL http(s) e URL file://. Passando "/" viene mostrata la pagina di base locale o index.html. Le destinazioni ospitate dal Gateway in /__openclaw__/canvas/ e /__openclaw__/a2ui/ vengono risolte mediante l’URL Canvas con ambito corrente della sessione del nodo. L’app aggiorna questa funzionalità di breve durata prima della navigazione; non è necessario creare o copiare manualmente un URL di funzionalità.

​
A2UI in Canvas

A2UI è ospitato dall’host Canvas del Gateway e visualizzato all’interno del pannello Canvas. Quando il Gateway annuncia un host Canvas, al primo avvio l’app macOS passa automaticamente alla pagina dell’host A2UI. L’URL annunciato è limitato all’ambito della funzionalità, ad esempio http://<gateway-host>:18789/__openclaw__/cap/<token>/__openclaw__/a2ui/?platform=macos. Deve essere trattato come credenziale temporanea, non come collegamento stabile.

​
Comandi A2UI (v0.8)

Canvas accetta i messaggi A2UI v0.8 dal server al client: beginRendering, surfaceUpdate, dataModelUpdate, deleteSurface. createSurface (v0.9) non è ancora supportato.
Test rapido di verifica:

​
Avvio delle esecuzioni dell’agente da Canvas

Canvas può avviare nuove esecuzioni dell’agente mediante i deep link openclaw://agent?...:
Parametri di query supportati: L’app richiede una conferma, a meno che non venga fornita una chiave valida. I collegamenti senza chiave mostrano il messaggio e l’URL prima dell’approvazione e ignorano i campi di instradamento del recapito; i collegamenti con chiave utilizzano il normale percorso di esecuzione del Gateway.

​
Note sulla sicurezza

  • Lo schema Canvas blocca l’attraversamento delle directory; i file devono trovarsi nella radice della sessione.
  • I contenuti Canvas locali usano uno schema personalizzato (non è necessario un server di loopback).
  • Gli URL http(s) esterni sono consentiti solo quando vi si accede esplicitamente.
  • Le normali pagine web consentono solo la visualizzazione. Le azioni dell’agente vengono accettate solo dallo schema Canvas di proprietà dell’app o dallo specifico documento A2UI del Gateway con ambito di funzionalità selezionato dall’app; i sottoframe, i reindirizzamenti, le funzionalità scadute e le query modificate non possono inviare azioni.

​
Contenuti correlati