Understanding Canvas and A2UI Integration on macOS

The OpenClaw macOS application includes a powerful feature called the Canvas panel, a lightweight visual workspace designed to host interactive HTML/CSS/JS content and the A2UI interface. This integration allows agents to present rich, dynamic UIs directly within the desktop app, enabling advanced automation and user interaction. Here's how it works.

What is the Canvas panel?

The Canvas panel is a borderless, resizable window embedded within the OpenClaw macOS app. It is controlled by the agent via the Gateway WebSocket and serves as a flexible surface for:

• Hosting custom HTML/CSS/JS applications
• Rendering A2UI interfaces for agent actions
• Displaying interactive widgets and dashboards
• Capturing snapshots of its contents

Canvas state, including files and configurations, is stored in ~/Library/Application\ Support/OpenClaw/canvas/<session>/, and is accessible via the custom URL scheme openclaw-canvas://<session>/<path>. This allows for persistent, session-specific content that reloads automatically when files are modified.

How Canvas is Controlled

Agents interact with the Canvas panel through a set of Gateway commands, accessible via the nodes tool. Key operations include:

• Present/Hide: Show or hide the panel with nodes canvas present or nodes canvas hide
• Navigate: Load local content or external URLs with nodes canvas navigate
• Evaluate JavaScript: Run scripts in the panel context with nodes canvas eval
• Capture Snapshots: Generate images of the current view with nodes canvas snapshot

For example, navigating to the root path (/) will load the session's index.html or display a built-in scaffold if none exists.

A2UI Integration

A2UI, the agent-to-UI protocol, is hosted by the Gateway and rendered directly within the Canvas panel. When the Gateway detects a Canvas-capable node, the macOS app automatically navigates to the A2UI host page at http://<gateway-host>:18789/__openclaw__/a2ui/.

The current implementation supports A2UI v0.8, handling messages like beginRendering, surfaceUpdate, and dataModelUpdate. This allows agents to push structured UI components—such as text, buttons, and layouts—directly to the Canvas for real-time interaction.

A simple smoke test can be run with:

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

Using Canvas for Automation

Beyond display, Canvas supports bidirectional communication. Interactive elements can trigger agent runs via deep links like openclaw://agent?message=..., enabling seamless workflow progression. For instance, a "Submit" button in a Canvas form can initiate a new agent task with structured input.

Security is maintained through strict path controls—only files under the session root are accessible—and external URLs require explicit navigation, preventing unintended access.

Conclusion

The integration of Canvas and A2UI in the OpenClaw macOS app transforms the agent experience from text-only to visually interactive. By leveraging this capability, developers and agents can build powerful, responsive interfaces that enhance usability and automation depth—right from the desktop.