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 index.html en la raíz, la aplicación muestra una página de estructura básica integrada.

Comportamiento del panel

  • Panel sin bordes y redimensionable, anclado cerca de la barra de menús (o del cursor del ratón).
  • Mostrar Canvas no cambia de aplicación ni roba el foco del teclado.
  • Recuerda el tamaño y la posición por 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 de 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>

eval y a2ui.* actualizan el contenido sin abrir ni revelar el panel. Solo present, navigate o una acción del usuario lo muestran; después de ocultarlo, las actualizaciones de contenido siguen aplicándose al panel oculto. snapshot necesita un panel visible y, de lo contrario, devuelve CANVAS_HIDDEN; ejecute primero present.

canvas.navigate acepta rutas locales de Canvas, URL http(s) y URL file://. Al pasar "/", se muestra la estructura básica 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 crear ni copiar una URL de capacidad manualmente.

A2UI en Canvas

A2UI está alojado en 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 A2UI v0.8 del servidor al cliente: beginRendering, surfaceUpdate, dataModelUpdate, deleteSurface. createSurface (v0.9) todavía 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 Instrucción del agente prerrellenada.
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 a menos que se proporcione una clave válida. Los enlaces sin clave muestran el mensaje y la URL antes de su 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 residir 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 a ellas.
  • Las páginas web normales son solo de representación. Las acciones del agente solo se aceptan desde el esquema de Canvas propiedad de la aplicación o desde el documento A2UI exacto del Gateway con ámbito de capacidad seleccionado por la aplicación; los submarcos, las redirecciones, las capacidades obsoletas y las consultas modificadas no pueden enviar acciones.

Contenido relacionado

Was this useful?
On this page

On this page