Canvas A2UI Integration Architecture in OpenClaw

The integration between Canvas and A2UI in OpenClaw is a cornerstone of the platform's lightweight UI automation capabilities, particularly on macOS. This architecture enables AI agents to present, control, and react to interactive UI surfaces directly from their runtime context.

Core Components

The integration relies on three primary components:

1. Canvas Panel: A borderless, resizable WKWebView embedded within the OpenClaw macOS app. It serves as the dedicated display surface for HTML/CSS/JS content and A2UI applications.

2. A2UI Host: A server component, hosted by the OpenClaw Gateway and served from http://<gateway-host>:18789/__openclaw__/a2ui/. It provides the runtime environment for A2UI applications.

3. Gateway WebSocket API: The communication channel that allows agents to control both Canvas (e.g., presenting the panel, capturing snapshots) and A2UI (e.g., pushing updates, creating surfaces).

How the Integration Works

The integration process is seamless and automated:

1. When the OpenClaw Gateway is configured and running, it starts the A2UI Host service.
2. Upon launching the macOS app and connecting to the Gateway, if a Canvas panel is requested, the app automatically navigates the Canvas's WKWebView to the A2UI Host URL.
3. The agent can then use the canvas a2ui push command to send A2UI messages (in JSONL format) to the Gateway.
4. The Gateway forwards these messages to the A2UI Host, which renders the corresponding UI updates within the Canvas panel.

This setup allows AI agents to dynamically build and modify rich, interactive user interfaces in real-time, making complex automations visible and monitorable.

Supported A2UI Messages

As of the current implementation, Canvas in OpenClaw supports A2UI v0.8 server-to-client messages. Key supported messages include:

• beginRendering: Signals the start of rendering for a given A2UI surface.
• surfaceUpdate: Updates the structure and components of an A2UI surface.
• dataModelUpdate: Updates the data model associated with a surface.
• deleteSurface: Removes a specific A2UI surface.

It's important to note that the createSurface message from v0.9 is not yet supported, defining the current scope of the integration.

Triggering Agent Actions from Canvas

A powerful feature of this architecture is bidirectional communication. Interactive elements within the A2UI-rendered UI in the Canvas can trigger new agent runs. This is achieved through deep links using the openclaw:// URL scheme. For example, a button click in the UI can execute JavaScript that redirects the window to openclaw://agent?message=Action%20Triggered, which prompts the OpenClaw app to start a new agent session with the provided message.

This capability allows for the creation of closed-loop automation workflows where users can approve or modify AI-generated plans directly within the assistant's UI context.