Building Visual Agent Workspaces with Canvas

I’ve often struggled with building small, interactive interfaces for agents. Usually, you end up switching between a terminal and a browser, losing context every time. It is hard to find a middle ground between a full web app and a simple text output when you just need a quick visual surface to show some data or a custom UI.

The macOS app handles this with Canvas. It is a lightweight workspace using WKWebView that lives right near your menu bar or cursor. It lets you render HTML, CSS, JS, and A2UI components without managing a separate browser window.

What You’ll Need

• OpenClaw macOS application
• Gateway WebSocket connection
• The openclaw CLI tool
• “Allow Canvas” enabled in Settings

Quick Start

You can get a visual surface running in about a minute. Here is the fastest path to seeing it in action.

1. Show the Panel

First, tell the agent node to display the Canvas panel.

openclaw nodes canvas present --node \<id\>

2. Push a Simple UI

Canvas supports A2UI v0.8. You can push a quick text message to the panel to verify everything is connected.

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

3. Use Local Files

Canvas looks for files in ~/Library/Application Support/OpenClaw/canvas/<session>/. If you put an index.html there, you can load it using the custom scheme:

openclaw nodes canvas navigate --node \<id\> --url "/"

This command points the panel to your local session root.

4. Run JS directly

If you need to check the state of your page or change something on the fly, use the eval command:

openclaw nodes canvas eval --node \<id\> --js "document.title"

Troubleshooting

Canvas returns CANVAS_DISABLED

If your commands fail with this error, check your app settings. Go to Settings → Allow Canvas and make sure it is toggled on. The app blocks all canvas node commands when this is off.

A2UI content isn’t appearing

Check your A2UI version. Canvas currently accepts A2UI v0.8 messages like beginRendering and surfaceUpdate. If you try to use createSurface (from v0.8 or v0.9), it will not work because that specific command is not supported.

Directory access issues

The Canvas scheme blocks directory traversal for security. Ensure all your HTML and asset files stay inside the session root at ~/Library/Application Support/OpenClaw/canvas/<session>/.

---

If you hit a wall or need help with a specific CLI flag, check the AI Setup Assistant.

What’s Next

• Gateway WebSocket API
• A2UI v0.8 Specification
• Deep Linking into Agent Runs