Canvas
Panel Canvas controlado por agente embebido vía WKWebView + esquema URL personalizado
La app macOS embebe un ''panel Canvas'' controlado por agente usando ''WKWebView''. Es
un workspace visual ligero para HTML/CSS/JS, A2UI y pequeñas superficies de UI
interactivas.
Dónde vive Canvas
El estado de Canvas se almacena bajo Application Support:
- ''~/Library/Application Support/OpenClaw/canvas/<sesión>/...''
El panel Canvas sirve esos archivos vía un esquema URL personalizado:
- ''openclaw-canvas://<sesión>/<ruta>''
Ejemplos:
- ''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''
Si no existe ''index.html'' en la raíz, la app muestra una ''página scaffold integrada''.
Comportamiento del panel
- Panel sin bordes, redimensionable anclado cerca de la barra de menú (o cursor del mouse).
- Recuerda tamaño/posición por sesión.
- Se recarga automáticamente cuando cambian los archivos locales de canvas.
- Solo un panel Canvas está visible a la vez (la sesión se cambia según sea necesario).
Canvas puede deshabilitarse desde Settings → Allow Canvas. Cuando está deshabilitado, los comandos
de nodo canvas retornan ''CANVAS_DISABLED''.
Superficie de API del agente
Canvas está expuesto vía el WebSocket del Gateway, así que el agente puede:
- mostrar/ocultar el panel
PlatformsMacCanvasPage.step03.p3
PlatformsMacCanvasPage.step03.p4
PlatformsMacCanvasPage.step03.p5
PlatformsMacCanvasPage.step03.p6
PlatformsMacCanvasPage.step03.code1
PlatformsMacCanvasPage.step03.p7
PlatformsMacCanvasPage.step03.p8
PlatformsMacCanvasPage.step03.p9
A2UI in Canvas
A2UI is hosted by the Gateway canvas host and rendered inside the Canvas panel.
Cuando el Gateway anuncia un host Canvas, la app macOS auto-navega al
A2UI host page on first open.
Default A2UI host URL:
http://'<gateway-host>':18793/__openclaw__/a2ui/
#
Comandos A2UI (v0.8)
Canvas actualmente acepta mensajes server→client de A2UI v0.8:
- ''beginRendering''
- ''surfaceUpdate''
- ''dataModelUpdate''
- ''deleteSurface''
''createSurface'' (v0.9) no está soportado.
Ejemplo CLI:
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":"If you can read this, A2UI push works."},"usageHint":"body"}}}]}}
{"beginRendering":{"surfaceId":"main","root":"root"}}
EOFA2
openclaw nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>'Prueba rápida:
openclaw nodes canvas a2ui push --node '<id>' --text "Hola desde A2UI"
Disparar ejecuciones de agente desde Canvas
Canvas puede disparar nuevas ejecuciones de agente vía deep links:
- ''openclaw://agent?...''
Ejemplo (en JS):
window.location.href = "openclaw://agent?message=Revisa%20este%20diseño";
La app solicita confirmación a menos que se proporcione una clave válida.
Notas de seguridad
- El esquema de Canvas bloquea directory traversal; los archivos deben vivir bajo la raíz de sesión.
- El contenido de Canvas local usa un esquema personalizado (no se requiere servidor loopback).
- URLs ''http(s)'' externas están permitidas solo cuando se navega explícitamente.