Canvas (app de macOS)

La app de macOS integra un panel Canvas controlado por el agente usando WKWebView. Es un espacio de trabajo visual ligero para HTML/CSS/JS, A2UI y pequeñas superficies de UI interactivas.

Dónde vive el Canvas

El estado del Canvas se almacena en Application Support:

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

El panel Canvas sirve esos archivos vía un esquema URL personalizado:

openclaw-canvas://<session>/<path>

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 un 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 ratón).
Recuerda tamaño/posición por sesión.
Se recarga automáticamente cuando los archivos locales del canvas cambian.
Solo un panel Canvas es visible a la vez (la sesión se cambia según sea necesario).

El Canvas se puede deshabilitar desde Ajustes → Allow Canvas. Cuando está deshabilitado, los comandos de nodo del canvas devuelven CANVAS_DISABLED.

Superficie API del agente

El Canvas está expuesto vía el WebSocket del Gateway, así que el agente puede:

mostrar/ocultar el panel
navegar a una ruta o URL
evaluar JavaScript
capturar una imagen snapshot

Ejemplos del CLI:

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

Notas:

canvas.navigate acepta rutas locales del canvas, URLs http(s) y URLs file://.
Si pasas "/", el Canvas muestra el scaffold local o index.html.

A2UI en Canvas

A2UI es alojado por el host canvas del Gateway y renderizado dentro del panel Canvas. Cuando el Gateway anuncia un host Canvas, la app de macOS auto-navega a la página del host A2UI al abrirse por primera vez.

URL predeterminada del host A2UI:

http://<gateway-host>:18789/__openclaw__/a2ui/

Comandos A2UI (v0.8)

El Canvas actualmente acepta mensajes servidor→cliente de A2UI v0.8:

beginRendering
surfaceUpdate
dataModelUpdate
deleteSurface

createSurface (v0.9) no está soportado.

Ejemplo del 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 "Hello from A2UI"

Ejecutar acciones del agente desde Canvas

El Canvas puede disparar nuevas ejecuciones del agente vía deep links:

openclaw://agent?...

Ejemplo (en JS):

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

La app solicita confirmación a menos que se proporcione una clave válida.

Notas de seguridad

El esquema Canvas bloquea el recorrido de directorios; los archivos deben vivir bajo la raíz de la sesión.
El contenido local del Canvas usa un esquema personalizado (no se requiere servidor loopback).
Las URLs externas http(s) solo se permiten cuando se navega explícitamente.