Canvas in OpenClaw (macOS): A2UI Integration Patterns

The Canvas panel in the OpenClaw macOS application provides a powerful, lightweight interface for building interactive agent-controlled UIs. When combined with A2UI, it becomes a dynamic surface for real-time feedback, user input, and visual workflows—all driven directly by AI agents. This article outlines the key integration patterns for using A2UI within Canvas, based on the current v0.8 specification, and highlights how to maximize its potential in your OpenClaw automation projects.

What Is Canvas?

Canvas is a browser-based panel embedded directly in the OpenClaw macOS app, accessible via the nodes tool with commands like canvas present, navigate, eval, and snapshot. It operates under a dedicated openclaw-canvas:// URL scheme and serves content from local files stored in ~/Library/Application Support/OpenClaw/canvas/. The panel is borderless, resizable, and auto-reloads when files change, making it ideal for live-updating dashboards or interactive agent interfaces.

What Is A2UI?

A2UI (Agent-to-UI) is a JSONL-based protocol that allows agents to push structured UI updates to the Canvas panel. It enables dynamic creation and manipulation of components like text, buttons, and forms without requiring full page reloads. The Gateway hosts the A2UI server endpoint at http://<gateway-host>:18789/__openclaw__/a2ui/, and the Canvas panel automatically connects to it when A2UI support is advertised.

As of now, OpenClaw supports A2UI v0.8, which includes the following message types:

• beginRendering
• surfaceUpdate
• dataModelUpdate
• deleteSurface

The createSurface command from v0.9 is not yet supported, so all surfaces must be defined upfront or updated via surfaceUpdate.

Integration Patterns

1. Live Status Dashboard

Use A2UI to create a real-time status panel that tracks ongoing agent activities. For example, a system monitoring agent can push updates to show current tasks, completion status, and error logs.

Pattern:

• Initialize a surface with surfaceUpdate defining a column layout.
• Use beginRendering to activate it.
• Push periodic surfaceUpdate messages to refresh text content or component state.

Example Command:

openclaw nodes canvas a2ui push --node <id> --text "Task 3/5 complete - Syncing files..."

This lightweight command pushes a simple text update, ideal for status tracking without complex layout changes.

2. Interactive Input Collection

Canvas can gather user input through A2UI-driven forms. While full form components are limited in v0.8, you can simulate input fields using clickable text or buttons that trigger agent runs via deep links.

Pattern:

• Design a UI with labeled text blocks representing input options.
• Attach openclaw://agent?message=... deep links to each option.
• When clicked, the link triggers a new agent run with context, allowing for step-by-step interaction.

Example Deep Link (JavaScript):

window.location.href = "openclaw://agent?message=Confirm%20deployment%20to%20production";

This pattern enables safe, user-confirmed actions without exposing raw system commands.

3. Debugging and Inspection UI

Developers can use Canvas to surface debug information from agents, such as API call logs, memory traces, or tool execution results.

Pattern:

• Create a scrollable text component in A2UI.
• Push log lines as dataModelUpdate events.
• Use surfaceUpdate to append new content or highlight errors.

This transforms Canvas into a real-time console, reducing context switching during development and troubleshooting.

4. Task Progress Tracker

For long-running workflows, use Canvas to display a progress bar or step-by-step checklist. Since Canvas auto-reloads on file changes, you can also serve static HTML/JS assets that poll a local API or file for updates.

Pattern:

• Host a simple web app in the Canvas directory.
• Use navigate to load /tasks.html.
• Agent writes progress to a local state.json.
• Page polls state.json and updates the UI.

This hybrid approach leverages Canvas’s local file serving for richer interactivity beyond A2UI’s current limits.

Security Considerations

• Canvas content is sandboxed under a custom URL scheme; directory traversal is blocked.
• External http(s) URLs are only loaded when explicitly navigated.
• Deep links require user confirmation unless a valid key is provided, preventing unintended agent activations.

Getting Started

1. Ensure the Canvas panel is enabled in OpenClaw settings.
2. Use nodes canvas present to show the panel.
3. Push A2UI content using nodes canvas a2ui push with JSONL or plain text.
4. Test deep links locally to ensure correct message routing.

Conclusion

Canvas and A2UI together form a flexible platform for building agent-driven interfaces on macOS. While v0.8 has limitations, the existing patterns support dashboards, input collection, and debugging workflows. As the protocol evolves, expect richer components and better form support. For now, combine A2UI with local HTML/JS for advanced use cases, and always prioritize security when exposing interactive surfaces.

For more details, refer to the Canvas documentation and explore the A2UI examples in the OpenClaw CLI.