Advanced Canvas & A2UI Workflows on macOS

The Canvas panel in the OpenClaw macOS app provides a powerful visual interface for agents and developers. When combined with A2UI, it enables dynamic, interactive user experiences directly on the desktop. This guide explores advanced workflows and integration patterns that leverage Canvas and A2UI for enhanced agent functionality.

Canvas Architecture and Data Flow

The Canvas operates through a structured data flow between the OpenClaw Gateway and the macOS application. The Canvas panel, implemented as a WKWebView, hosts HTML/CSS/JS content and A2UI elements. Canvas state is stored in ~/Library/Application Support/OpenClaw/canvas/<session>/, with content served via the custom URL scheme openclaw-canvas://<session>/<path>. This architecture eliminates the need for a local loopback server while maintaining secure access to session-specific files.

The integration between Canvas and A2UI follows a server-driven model. The Gateway hosts the A2UI endpoint at http://<gateway-host>:18789/__openclaw__/a2ui/, and the Canvas panel automatically navigates to this location when A2UI is enabled. The current implementation supports A2UI v0.8 messages including beginRendering, surfaceUpdate, dataModelUpdate, and deleteSurface, enabling dynamic UI updates from the agent.

Practical Workflows

Dynamic UI Generation

Developers can create responsive UIs by sending A2UI update messages through the Gateway. The following example demonstrates how to construct a simple component tree:

{
  "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"
          }
        }
      }
    ]
  }
}

This JSON payload can be sent using the canvas a2ui push command, allowing agents to update the UI in real-time based on execution context.

Interactive Agent Triggers

Canvas enables bidirectional communication by allowing embedded content to trigger agent runs. Using deep links with the openclaw://agent? scheme, JavaScript running in the Canvas can initiate new agent interactions. For example:

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

This pattern enables interactive prototypes where user actions in the Canvas directly invoke agent processing, creating a seamless loop between visual interface and AI reasoning.

Security Considerations

The Canvas implementation includes multiple security layers. Directory traversal is prevented by restricting file access to the session root, and external HTTP/HTTPS URLs are only accessible through explicit navigation commands. The custom URL scheme ensures that Canvas content remains sandboxed while still allowing integration with external resources when needed.

Integration Best Practices

When developing Canvas-A2UI integrations, consider the following best practices:

1. Use the scaffold page as a starting point for new Canvas sessions
2. Leverage A2UI's dataModelUpdate for dynamic content without full UI re-renders
3. Implement graceful degradation for environments where Canvas is disabled
4. Test deep link interactions thoroughly, as they require user confirmation in most cases
5. Structure Canvas content to auto-reload when local files change, enabling rapid development cycles

By following these patterns, developers can create rich, interactive experiences that enhance OpenClaw's capabilities on macOS systems.