Integrating Canvas and A2UI on macOS

The OpenClaw macOS app includes a powerful feature called Canvas, an embedded lightweight UI panel powered by WKWebView. This panel serves as a visual workspace for HTML/CSS/JS content and supports direct integration with A2UI, OpenClaw's structured UI protocol for pushing interface elements from server to client.

Understanding Canvas

Canvas provides agents with a dynamic, resizable, and persistent visual surface that can be controlled programmatically. It lives within the macOS app and can be shown, hidden, navigated, and updated via agent commands. The panel is borderless and auto-positions near the menu bar or cursor, remembering its size and location per session.

Canvas content is stored in a dedicated directory:

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

Files are served using a custom URL scheme: openclaw-canvas://<session>/<path>. If no index.html is provided, a built-in scaffold page is shown.

A2UI: Pushing UI from the Server

A2UI allows agents to construct and update rich visual interfaces directly from code, eliminating the need for static HTML templates or full frontends. Instead of writing raw HTML, you define structured UI components—like text, buttons, columns, and lists—as JSON payloads that the Canvas renders in real time.

When A2UI is enabled, the Canvas automatically navigates to the Gateway's A2UI host endpoint:

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

This enables the Canvas to receive and render A2UI server-to-client messages such as:

• surfaceUpdate – Modify component structure
• dataModelUpdate – Update dynamic data
• deleteSurface – Remove a UI surface
• beginRendering – Initialize the rendering of a new surface

⚠️ Note: As of this writing, Canvas supports A2UI v0.8. The newer createSurface (v0.9) command is not yet implemented.

Practical A2UI Example

You can push A2UI content directly using the nodes canvas a2ui push CLI command. Here's a minimal example that renders a heading and paragraph:

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

To send this from the command line:

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

Or for a quick test:

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

Controlling Canvas from Your Agent

Agents can interact with Canvas using several commands:

• present – Show the Canvas panel
• navigate – Load a local path, URL, or file
• eval – Execute JavaScript in the Canvas context
• snapshot – Capture the current Canvas view as an image

Example workflow:

openclaw nodes canvas present --node main
openclaw nodes canvas navigate --node main --url "/widgets/todo"
openclaw nodes canvas eval --node main --js "document.title"

Security & Best Practices

• Canvas restricts file access to its session directory—directory traversal is blocked.
• Local content uses the secure openclaw-canvas:// scheme, avoiding the need for a loopback web server.
• External HTTP/HTTPS URLs are only accessible when explicitly navigated.
• Canvas can be disabled in Settings if not needed.

Use Cases

Canvas + A2UI is ideal for:

• Real-time monitoring dashboards
• Interactive configuration wizards
• Debugging tools with live updates
• Agent decision logs with expandable details
• Lightweight GUIs for automation workflows

By combining Canvas's flexibility with A2UI's structured rendering, OpenClaw agents gain a powerful way to present information and interact visually—without the overhead of a full web app.

Keep building. Keep learning.