Integrating Canvas and A2UI on macOS

The OpenClaw macOS app provides a powerful visual interface through the Canvas panel, enabling rich UI automation and interactive surfaces for agents. This guide covers how to use Canvas and A2UI effectively for macOS automation.

What is Canvas?

Canvas is a borderless, resizable panel embedded within the OpenClaw macOS app, powered by WKWebView. It serves as a lightweight visual workspace for:

• HTML/CSS/JS content
• A2UI (Agent-to-UI) interfaces
• Interactive UI surfaces and dashboards
• Local file visualization

Canvas Architecture

Canvas state is stored in ~/Library/Application Support/OpenClaw/canvas/<session>/. The panel serves these files via the custom URL scheme openclaw-canvas://<session>/<path>, enabling secure local file access without a loopback server.

Key behaviors:

• Anchored near the menu bar or cursor
• Remembers size and position per session
• Auto-reloads when local canvas files change
• Only one panel visible at a time

Agent Control API

Agents control Canvas through Gateway WebSocket commands. Key operations include:

# Show the Canvas panel
canvas present --node <id>

# Navigate to a local path or URL
canvas navigate --node <id> --url "/widgets/todo"

# Execute JavaScript
canvas eval --node <id> --js "document.title"

# Capture a snapshot
canvas snapshot --node <id>

Working with A2UI

A2UI enables rich component-based interfaces within Canvas. The Gateway hosts A2UI at http://<gateway-host>:18789/__openclaw__/a2ui/.

Currently, Canvas supports A2UI v0.8 messages:

• beginRendering
• surfaceUpdate
• dataModelUpdate
• deleteSurface

To push A2UI content:

cat > /tmp/a2ui.jsonl <<'EOFA2'
{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Hello Canvas"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"This is A2UI content"},"usageHint":"body"}}}]}}
{"beginRendering":{"surfaceId":"main","root":"root"}}
EOFA2

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

Security Model

Canvas implements several security measures:

• Blocks directory traversal attacks
• Restricts file access to the session's canvas directory
• Requires explicit navigation for external HTTP(S) URLs
• Uses a custom URL scheme to prevent web-based exploits

Integration Best Practices

1. Use A2UI for complex interactive components
2. Serve static assets locally via the canvas directory
3. Keep Canvas content lightweight for responsiveness
4. Use snapshot for visual verification in automation workflows
5. Implement deep link triggers (openclaw://agent?message=...) for user-initiated agent runs

The Canvas panel transforms OpenClaw from a text-based agent into a full visual automation platform, enabling sophisticated macOS workflows with rich user feedback.