Canvas (macOS App): A Developer's Guide

The OpenClaw macOS app includes a powerful feature called Canvas—an embedded, agent-controlled HTML/CSS/JS panel that serves as a lightweight visual workspace. It's designed for building interactive UIs, dashboards, and small applications directly controlled by your AI agents.

Understanding Canvas

Canvas is not just a browser window; it's a tightly integrated component of the OpenClaw ecosystem. It uses WKWebView to render content and is accessible via a custom URL scheme: openclaw-canvas://<session>/<path>. This scheme allows agents to serve and display content from local files or remote sources securely.

Where Canvas Lives

Canvas state is stored in the Application Support directory:

~/Library/Application Support/OpenClaw/canvas/<session>/...

Each session has its own isolated Canvas environment. When you navigate to openclaw-canvas://main/, it resolves to <canvasRoot>/main/index.html. If no index.html exists, the app shows a built-in scaffold page.

Panel Behavior

• Borderless & Resizable: The panel appears near the menu bar or mouse cursor and remembers its size and position per session.
• Auto-Reload: Changes to local Canvas files trigger an automatic reload, streamlining development.
• Single Instance: Only one Canvas panel is visible at a time. Switching sessions updates the displayed content.

Canvas can be disabled in Settings → Allow Canvas. When disabled, Canvas-related commands return CANVAS_DISABLED.

Agent Control Over Canvas

Agents interact with Canvas through the Gateway WebSocket API, enabling them to:

• Show or hide the panel
• Navigate to local paths, http(s) URLs, or file:// URLs
• Evaluate JavaScript in the current context
• Capture snapshot images

Key CLI commands include:

openclaw nodes canvas present --node <id>
openclaw nodes canvas navigate --node <id> --url "/"
openclaw nodes canvas eval --node <id> --js "document.title"
openclaw nodes canvas snapshot --node <id>

Note: The navigate command accepts / to load the local scaffold or index.html.

Integrating A2UI with Canvas

A2UI (Agent-to-UI) is a protocol that allows agents to push UI updates directly to Canvas. When the Gateway advertises a Canvas host, the macOS app automatically navigates to the A2UI host page (http://<gateway-host>:18789/__openclaw__/a2ui/) on first open.

Supported A2UI Commands (v0.8)

Canvas currently supports A2UI v0.8 server→client messages:

• beginRendering
• surfaceUpdate
• dataModelUpdate
• deleteSurface

The createSurface command (v0.9) is not yet supported.

Example: Pushing A2UI Content

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>

For a quick test:

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

Triggering Agent Runs from Canvas

Canvas can initiate new agent runs using deep links:

openclaw://agent?message=Review%20this%20design

In JavaScript:

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

The app prompts for confirmation unless a valid key is provided, ensuring security.

Security Considerations

• Directory Traversal Protection: Canvas blocks attempts to access files outside the session root.
• Custom Scheme Safety: Local content uses openclaw-canvas://, eliminating the need for a loopback server.
• Controlled External Access: http(s) URLs are only accessible when explicitly navigated by the agent.

Practical Use Cases

1. Interactive Dashboards: Build real-time monitoring interfaces updated by agent logic.
2. Form Input Collection: Create forms rendered in Canvas and submitted back to the agent.
3. Visual Feedback: Display spectrograms, charts, or extracted video frames during processing.
4. UI Prototyping: Rapidly prototype and test UI concepts controlled entirely by agents.

Getting Started

To begin using Canvas in your projects:

1. Ensure Canvas is enabled in the macOS app settings.
2. Use the present command to show the panel.
3. Serve content from your session's Canvas directory or navigate to external resources.
4. Leverage A2UI for dynamic, agent-driven UI updates.

Canvas bridges the gap between command-line agents and rich user interfaces, offering developers a flexible tool for creating engaging, responsive applications within the OpenClaw framework. With its seamless integration and robust security model, Canvas empowers agents to deliver sophisticated visual experiences without complexity.