Understanding Canvas A2UI Integration on macOS

The Canvas panel in the OpenClaw macOS app is a lightweight visual workspace that enables HTML/CSS/JS and A2UI-based UI surfaces. It serves as a bridge between agent logic and interactive visuals, providing a seamless integration point for developers and users alike.

Canvas in the macOS App

The Canvas panel is embedded within the OpenClaw macOS app using WKWebView, a high-performance web rendering engine. It operates as a borderless, resizable panel that docks near the menu bar or cursor as needed. Key characteristics include:

• Local Storage: Canvas state is stored under ~/Library/Application Support/OpenClaw/canvas/<session>/...
• URL Scheme: Uses a custom openclaw-canvas:// scheme to serve local content
• Auto-Reload: Automatically refreshes when local canvas files change
• Persistence: Remembers size and position per session

The panel only allows one instance visible at a time, switching context as needed between sessions.

A2UI Integration

A2UI (Agent-to-UI) is hosted by the Gateway and rendered within the Canvas panel. When the Gateway advertises a Canvas host, the macOS app automatically navigates to the A2UI host page on first open. The default A2UI host URL follows this pattern:

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

A2UI Command Support

The current Canvas implementation supports A2UI v0.8 server-to-client messages, including:

• beginRendering
• surfaceUpdate
• dataModelUpdate
• deleteSurface

Notably, createSurface (v0.9) is not yet supported. This means developers should structure their UI updates around existing surfaces rather than creating new ones dynamically.

Implementing A2UI Commands

To push A2UI updates to the Canvas, use the a2ui push command:

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

For more complex UIs, create a JSONL file with component definitions and push it:

cat > /tmp/a2ui-v0.8.jsonl <<'EOFA2'
{"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"}}
EOFA2

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

Triggering Agent Runs from Canvas

The Canvas can initiate new agent runs through deep linking using the openclaw://agent URI scheme. For example:

window.location.href = "openclaw://agent?message=Review%20this%20design";

When executed, the OpenClaw app prompts for confirmation before triggering the agent run, unless a valid security key is provided.

Canvas Controls and Commands

The Canvas exposes several control methods through the nodes interface:

Presentation and Navigation

# Present/show the Canvas
openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com

# Hide the Canvas
openclaw nodes canvas hide --node <idOrNameOrIp>

# Navigate to a URL or local path
openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>

JavaScript Evaluation

# Execute JavaScript in the Canvas context
openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"

Snapshots

# Capture a Canvas snapshot
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png

# Capture with specific quality and size constraints
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

Security Considerations

The Canvas implementation includes several security measures:

• Directory Traversal Prevention: The custom URL scheme blocks attempts to access files outside the session root
• Local Content Isolation: Local Canvas content uses a custom scheme, eliminating the need for loopback servers
• External URL Control: HTTP/HTTPS URLs are only allowed when explicitly navigated to
• Confirmation Prompts: Deep links require user confirmation unless authenticated with a valid key

These protections ensure that Canvas content remains contained within its designated environment while still allowing necessary external interactions.

Practical Applications

The Canvas A2UI integration enables several powerful use cases:

1. Interactive Debugging: Visualize agent state and decision trees in real-time
2. User Feedback Interfaces: Create custom UIs for gathering user input beyond text
3. Data Visualization: Render charts, graphs, and other complex data representations
4. Workflow Automation: Build step-by-step guided processes with visual feedback
5. Status Dashboards: Monitor agent performance and system health through dedicated UIs

By combining the flexibility of web technologies with the agent's processing power, Canvas A2UI integration creates a rich, interactive layer that enhances both development and user experience.

Conclusion

The Canvas A2UI integration in OpenClaw's macOS app provides a robust framework for building interactive agent interfaces. By leveraging web standards and providing secure, efficient communication between agent logic and visual components, it enables developers to create sophisticated UIs that enhance agent capabilities. As the platform evolves, continued improvements to A2UI support will expand the possibilities for creative applications and user experiences.