Understanding Canvas and A2UI Integration on macOS

The macOS app for OpenClaw uses an embedded Canvas panel powered by WKWebView to provide a flexible visual workspace for agents. This integration enables rich, interactive UIs directly within the desktop environment, supporting HTML/CSS/JS, A2UI (Agent-to-User Interface), and custom widgets—all without requiring a local web server.

How Canvas Works

Canvas state is stored in a dedicated directory under Application Support:

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

The Canvas panel serves these files via a custom URL scheme:

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

• openclaw-canvas://main/ → displays index.html from the main session’s canvas root
• openclaw-canvas://main/assets/app.css → serves a CSS file from the same session
• If no index.html exists, a built-in scaffold page is shown

Panel Behavior

• Borderless, resizable window anchored near the menu bar or cursor
• Remembers size and position per session
• Auto-reloads when local canvas files change
• Only one Canvas panel is shown at a time (switches on session change)
• Can be disabled via Settings → Allow Canvas

When disabled, Canvas-related node commands return CANVAS_DISABLED.

Agent Control via Gateway WebSocket

Agents control Canvas through the Gateway WebSocket, enabling capabilities such as:

• Showing or hiding the panel
• Navigating to local paths, http(s) URLs, or file:// URLs
• Evaluating JavaScript
• Capturing snapshots

CLI examples:

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>

A2UI Integration

A2UI is hosted directly by the Gateway and rendered within the Canvas panel. When a Canvas host is advertised, the macOS app automatically navigates to the A2UI host page on first open.

Default A2UI host URL:

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

Current A2UI Version Support

Canvas currently supports A2UI v0.8, including server-to-client messages:

• beginRendering
• surfaceUpdate
• dataModelUpdate
• deleteSurface

Note: createSurface (introduced in v0.9) is not yet supported.

Pushing A2UI Content

A2UI content is pushed to the Canvas using the a2ui push command:

openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"

For more complex layouts, use a JSONL file:

{"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"}}

Execute with:

openclaw nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>

Triggering Agent Runs

Canvas can initiate new agent runs via deep links:

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

The app prompts for confirmation unless a valid key is provided, ensuring safe interaction.

Security Model

• Directory traversal is blocked; only files within the session root are accessible
• Local content served via secure custom scheme, eliminating need for loopback servers
• External HTTP/HTTPS URLs allowed only via explicit navigation

This integration enables powerful agent-driven UIs while maintaining strict security boundaries—a key advantage for desktop automation within OpenClaw.

Published on February 18, 2026