Canvas (ứng dụng macOS)

Ứng dụng macOS nhúng một panel Canvas do Agent điều khiển bằng WKWebView. Đây là một workspace trực quan nhẹ nhàng cho HTML/CSS/JS, A2UI, và các giao diện tương tác nhỏ.

Canvas được lưu ở đâu

Trạng thái Canvas được lưu trong Application Support:

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

Panel Canvas phục vụ các file này qua một custom URL scheme:

  • openclaw-canvas://<session>/<path>

Ví dụ:

  • openclaw-canvas://main/ → <canvasRoot>/main/index.html
  • openclaw-canvas://main/assets/app.css → <canvasRoot>/main/assets/app.css
  • openclaw-canvas://main/widgets/todo/ → <canvasRoot>/main/widgets/todo/index.html

Nếu không có file index.html ở thư mục gốc, ứng dụng sẽ hiển thị một trang scaffold có sẵn.

Hành vi của panel

  • Panel không viền, có thể resize, neo gần thanh menu (hoặc con trỏ chuột).
  • Nhớ kích thước/vị trí theo từng session.
  • Tự động reload khi các file canvas local thay đổi.
  • Chỉ có một panel Canvas hiển thị tại một thời điểm (session được chuyển đổi khi cần).

Canvas có thể tắt từ Settings → Allow Canvas. Khi tắt, các lệnh canvas node sẽ trả về CANVAS_DISABLED.

API surface cho Agent

Canvas được expose qua Gateway WebSocket, cho phép Agent có thể:

  • hiện/ẩn panel
  • điều hướng đến một path hoặc URL
  • thực thi JavaScript
  • chụp ảnh snapshot

Ví dụ CLI:

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>

Lưu ý:

  • canvas.navigate chấp nhận local canvas paths, URL http(s), và URL file://.
  • Nếu các bạn truyền "/", Canvas sẽ hiển thị scaffold local hoặc index.html.

A2UI trong Canvas

A2UI được host bởi Gateway canvas host và render bên trong panel Canvas. Khi Gateway quảng bá một Canvas host, ứng dụng macOS sẽ tự động điều hướng đến trang A2UI host khi mở lần đầu.

URL A2UI host mặc định:

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

Lệnh A2UI (v0.8)

Canvas hiện tại chấp nhận các message A2UI v0.8 từ server→client:

  • beginRendering
  • surfaceUpdate
  • dataModelUpdate
  • deleteSurface

createSurface (v0.9) chưa được hỗ trợ.

Ví dụ CLI:

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>

Test nhanh:

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

Kích hoạt agent runs từ Canvas

Canvas có thể kích hoạt các agent runs mới qua deep links:

  • openclaw://agent?...

Ví dụ (trong JS):

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

Ứng dụng sẽ nhắc xác nhận trừ khi có key hợp lệ được cung cấp.

Lưu ý bảo mật

  • Canvas scheme chặn directory traversal; các file phải nằm trong thư mục gốc của session.
  • Nội dung Canvas local sử dụng custom scheme (không cần loopback server).
  • URL http(s) bên ngoài chỉ được phép khi được điều hướng một cách rõ ràng.