Canvas

Die macOS-App bettet mithilfe von WKWebView ein agentengesteuertes Canvas-Panel ein, einen leichtgewichtigen visuellen Arbeitsbereich für HTML/CSS/JS, A2UI und kleine interaktive UI-Oberflächen.

Speicherort von Canvas

Der Canvas-Status wird unter Application Support gespeichert:

• ~/Library/Application Support/OpenClaw/canvas/<session>/...

Das Canvas-Panel stellt diese Dateien über ein benutzerdefiniertes URL-Schema bereit, 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

Wenn im Stammverzeichnis keine index.html vorhanden ist, zeigt die App eine integrierte Grundgerüstseite an.

Verhalten des Panels

• Rahmenloses, größenveränderbares Panel, das nahe der Menüleiste (oder dem Mauszeiger) verankert ist.
• Das Anzeigen von Canvas wechselt weder die App noch entzieht es den Tastaturfokus.
• Merkt sich Größe und Position für jede Sitzung.
• Wird automatisch neu geladen, wenn sich lokale Canvas-Dateien ändern.
• Es ist jeweils nur ein Canvas-Panel sichtbar (bei Bedarf wird die Sitzung gewechselt).

Canvas kann unter Settings -> Allow Canvas deaktiviert werden. Wenn es deaktiviert ist, geben Canvas-Node-Befehle CANVAS_DISABLED zurück.

Agent-API-Oberfläche

Canvas wird über den Gateway-WebSocket bereitgestellt, sodass der Agent das Panel ein- und ausblenden, zu einem Pfad oder einer URL navigieren, JavaScript auswerten und ein Snapshot-Bild erfassen kann:

openclaw nodes canvas present --node <id>openclaw nodes canvas navigate --node <id> "/"openclaw nodes canvas eval --node <id> --js "document.title"openclaw nodes canvas snapshot --node <id>

eval und a2ui.* aktualisieren Inhalte, ohne das Panel zu öffnen oder einzublenden. Nur present, navigate oder eine Benutzeraktion zeigt es an; nach dem Ausblenden werden Inhaltsaktualisierungen weiterhin auf das ausgeblendete Panel angewendet. snapshot erfordert ein sichtbares Panel und gibt andernfalls CANVAS_HIDDEN zurück; führen Sie zuerst present aus.

canvas.navigate akzeptiert lokale Canvas-Pfade, http(s)-URLs und file://- URLs. Die Übergabe von "/" zeigt das lokale Grundgerüst oder index.html an.

Vom Gateway gehostete Ziele unter /__openclaw__/canvas/ und /__openclaw__/a2ui/ werden über die aktuelle bereichsgebundene Canvas-URL der Node-Sitzung aufgelöst. Die App aktualisiert diese kurzlebige Berechtigung vor der Navigation; Sie müssen eine Berechtigungs-URL weder selbst erstellen noch kopieren.

A2UI in Canvas

A2UI wird vom Canvas-Host des Gateways gehostet und im Canvas- Panel gerendert. Wenn der Gateway einen Canvas-Host ankündigt, navigiert die macOS-App beim ersten Öffnen automatisch zur A2UI-Hostseite.

Die angekündigte URL ist berechtigungsgebunden, zum Beispiel http://<gateway-host>:18789/__openclaw__/cap/<token>/__openclaw__/a2ui/?platform=macos. Behandeln Sie sie als kurzlebige Zugangsdaten, nicht als stabilen Link.

A2UI-Befehle (v0.8)

Canvas akzeptiert A2UI-v0.8-Nachrichten vom Server zum Client: beginRendering, surfaceUpdate, dataModelUpdate, deleteSurface. createSurface (v0.9) wird noch nicht unterstützt.

cat > /tmp/a2ui-v0.8.jsonl <<'EOFA2'{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Canvas (A2UI v0.8)"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"Wenn Sie dies lesen können, funktioniert A2UI Push."},"usageHint":"body"}}}]}}{"beginRendering":{"surfaceId":"main","root":"root"}}EOFA2 openclaw nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>

Schneller Funktionstest:

openclaw nodes canvas a2ui push --node <id> --text "Hallo von A2UI"

Auslösen von Agent-Ausführungen über Canvas

Canvas kann über openclaw://agent?...-Deep-Links neue Agent-Ausführungen auslösen:

window.location.href = "openclaw://agent?message=Review%20this%20design";

Unterstützte Abfrageparameter:

Die App fordert zur Bestätigung auf, sofern kein gültiger Schlüssel bereitgestellt wird. Links ohne Schlüssel zeigen vor der Genehmigung die Nachricht und URL an und ignorieren Felder für die Zustellungsweiterleitung; Links mit Schlüssel verwenden den normalen Gateway-Ausführungspfad.

Sicherheitshinweise

• Das Canvas-Schema blockiert Verzeichnisdurchquerung; Dateien müssen sich unter dem Sitzungsstammverzeichnis befinden.
• Lokale Canvas-Inhalte verwenden ein benutzerdefiniertes Schema (kein Loopback-Server erforderlich).
• Externe http(s)-URLs sind nur zulässig, wenn ausdrücklich zu ihnen navigiert wird.
• Gewöhnliche Webseiten dienen nur der Darstellung. Agent-Aktionen werden nur vom App-eigenen Canvas-Schema oder genau dem berechtigungsgebundenen Gateway-A2UI-Dokument akzeptiert, das von der App ausgewählt wurde; Unterframes, Weiterleitungen, abgelaufene Berechtigungen und geänderte Abfragen können keine Aktionen auslösen.

Verwandte Themen

• macOS-App
• WebChat