OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

macOS companion app

Lienzo

La aplicación para macOS incorpora un panel Canvas controlado por el agente mediante WKWebView, un espacio de trabajo visual ligero para HTML/CSS/JS, A2UI y pequeñas superficies de interfaz de usuario interactivas.

Dónde se encuentra Canvas

El estado de Canvas se almacena en Application Support:

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

El panel Canvas sirve esos archivos mediante un esquema de URL personalizado, 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

Si no existe ningún archivo index.html en la raíz, la aplicación muestra una página de estructura inicial integrada.

Comportamiento del panel

  • Panel sin bordes y redimensionable, anclado cerca de la barra de menús (o del cursor del ratón).
  • Recuerda el tamaño y la posición de cada sesión.
  • Se recarga automáticamente cuando cambian los archivos locales de Canvas.
  • Solo puede haber un panel Canvas visible a la vez (se cambia de sesión según sea necesario).

Canvas se puede desactivar desde Settings -> Allow Canvas. Cuando está desactivado, los comandos del nodo de Canvas devuelven CANVAS_DISABLED.

Superficie de la API del agente

Canvas se expone mediante el WebSocket del Gateway, por lo que el agente puede mostrar u ocultar el panel, navegar a una ruta o URL, evaluar JavaScript y capturar una imagen instantánea:

bash
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>

canvas.navigate acepta rutas locales de Canvas, URL http(s) y URL file://. Al pasar "/", se muestra la estructura inicial local o index.html.

Los destinos alojados en el Gateway bajo /__openclaw__/canvas/ y /__openclaw__/a2ui/ se resuelven mediante la URL de Canvas con ámbito actual de la sesión del nodo. La aplicación actualiza esa capacidad de corta duración antes de navegar; no es necesario construir ni copiar una URL de capacidad manualmente.

A2UI en Canvas

A2UI está alojado por el host de Canvas del Gateway y se representa dentro del panel Canvas. Cuando el Gateway anuncia un host de Canvas, la aplicación para macOS navega automáticamente a la página del host de A2UI al abrirlo por primera vez.

La URL anunciada tiene un ámbito de capacidad, por ejemplo, http://<gateway-host>:18789/__openclaw__/cap/<token>/__openclaw__/a2ui/?platform=macos. Trátela como credenciales efímeras, no como un enlace estable.

Comandos de A2UI (v0.8)

Canvas acepta mensajes de servidor a cliente de A2UI v0.8: beginRendering, surfaceUpdate, dataModelUpdate, deleteSurface. createSurface (v0.9) aún no es compatible.

bash
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":"Si puede leer esto, el envío de A2UI funciona."},"usageHint":"body"}}}]}}{"beginRendering":{"surfaceId":"main","root":"root"}}EOFA2 openclaw nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>

Prueba rápida de funcionamiento:

bash
openclaw nodes canvas a2ui push --node <id> --text "Hola desde A2UI"

Activación de ejecuciones del agente desde Canvas

Canvas puede activar nuevas ejecuciones del agente mediante enlaces profundos openclaw://agent?...:

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

Parámetros de consulta compatibles:

Parámetro Significado
message Prompt del agente rellenado previamente.
sessionKey Identificador estable de la sesión.
thinking Perfil de razonamiento opcional.
deliver, to, channel Destino de entrega.
timeoutSeconds Tiempo de espera opcional de la ejecución.
key Token de seguridad generado por la aplicación para invocadores locales de confianza.

La aplicación solicita confirmación salvo que se proporcione una clave válida. Los enlaces sin clave muestran el mensaje y la URL antes de la aprobación e ignoran los campos de enrutamiento de entrega; los enlaces con clave utilizan la ruta de ejecución normal del Gateway.

Notas de seguridad

  • El esquema de Canvas bloquea el recorrido de directorios; los archivos deben encontrarse bajo la raíz de la sesión.
  • El contenido local de Canvas utiliza un esquema personalizado (no se requiere un servidor de bucle invertido).
  • Las URL externas http(s) solo se permiten cuando se navega explícitamente hasta ellas.
  • Las páginas web ordinarias son solo de representación. Las acciones del agente solo se aceptan desde el esquema de Canvas propiedad de la aplicación o el documento A2UI del Gateway con el ámbito de capacidad exacto seleccionado por la aplicación; los subframes, las redirecciones, las capacidades obsoletas y las consultas modificadas no pueden enviar acciones.

Contenido relacionado

Was this useful?
On this page

On this page