Canvas & A2UI Integration Architecture in OpenClaw

The Canvas panel in the OpenClaw macOS app provides a powerful UI automation surface by integrating with the A2UI protocol. This article explores the architectural details of how Canvas and A2UI work together to create dynamic, agent-controlled interfaces.

Canvas Panel Overview

The Canvas panel is a borderless, resizable UI element embedded within the OpenClaw macOS application. It appears near the menu bar and serves as a dedicated space for HTML/CSS/JS content, small web applications, and A2UI interfaces. The panel remembers its size and position per session, providing a consistent experience across interactions.

Canvas state and files are stored under the user's Application Support directory at ~/Library/Application Support/OpenClaw/canvas/<session>/, where each session maintains its own isolated filesystem. The Canvas panel accesses these files through a custom URL scheme: openclaw-canvas://<session>/<path>. This secure scheme prevents directory traversal attacks and ensures that content remains contained within its designated session.

When no index.html file exists at the root of a session's canvas directory, the panel displays a built-in scaffold page. Canvas can be enabled or disabled through the app's settings under "Allow Canvas" – when disabled, all canvas-related commands return a CANVAS_DISABLED error.

A2UI Integration

A2UI (Agent-to-UI) is OpenClaw's protocol for agents to control UI elements programmatically. In the Canvas context, A2UI integrates by hosting its runtime on the Gateway server and rendering the interface within the Canvas panel. When the Gateway advertises a Canvas host, the macOS app automatically navigates to the A2UI host page at the first opportunity.

The default A2UI host URL follows the pattern http://<gateway-host>:18789/__openclaw__/a2ui/, where the gateway-host is typically 127.0.0.1 for local deployments. This integration allows agents to push UI updates directly to the Canvas panel without requiring the user to navigate to external web interfaces.

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

• beginRendering - Initiates rendering of a surface
• surfaceUpdate - Updates the component tree of a surface
• dataModelUpdate - Updates data models associated with surfaces
• deleteSurface - Removes a surface from the canvas

The createSurface command from A2UI v0.9 is not yet supported in the Canvas integration.

Agent Control API

Agents interact with the Canvas panel through the Gateway WebSocket API, which exposes several control functions:

• present - Shows the Canvas panel
• hide - Hides the Canvas panel
• navigate - Navigates to a local canvas path, HTTPS URL, or file URL
• eval - Executes JavaScript in the Canvas context
• snapshot - Captures a screenshot of the current Canvas content
• a2ui push - Sends A2UI protocol messages to update the interface

These functions are accessible both through direct WebSocket messages and via the openclaw nodes canvas CLI commands. For example, to push a simple A2UI message to display text:

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

Or to send a more complex JSONL payload defining a component structure:

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

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

Security Model

The Canvas-A2UI integration maintains several security boundaries:

1. Filesystem Isolation: The custom openclaw-canvas:// scheme prevents directory traversal, ensuring that files can only be accessed within their designated session directory.

2. Local Content Security: Canvas content uses the custom scheme rather than a local web server, eliminating potential attack vectors through loopback interfaces.

3. External Content Controls: While Canvas can navigate to external HTTPS URLs, this only occurs when explicitly directed by agent commands, preventing unauthorized web content loading.

4. User Confirmation: JavaScript running in Canvas can trigger new agent runs through openclaw:// deep links, but the application prompts for user confirmation unless a valid authorization key is provided.

This architecture enables powerful UI automation capabilities while maintaining appropriate security boundaries between agent code, local files, and external resources.