Canvas

기준일: 2026-07-26
공식 기준: Canvas

Canvas 문서는 OpenClaw 공식 문서(platforms/mac/canvas)를 한국어로 정리한 가이드입니다. Agent-controlled Canvas panel embedded via WKWebView + custom URL scheme 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Agent-controlled Canvas panel embedded via WKWebView + custom URL scheme

한국어 가이드 범위: platforms/mac/canvas 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Where Canvas lives
• Panel behavior
• Agent API surface
• A2UI in Canvas
• A2UI commands (v0.8)
• Triggering agent runs from Canvas
• Security notes
• 관련 문서

상세 내용

본문

The macOS app embeds an agent-controlled Canvas panel using WKWebView, a lightweight visual workspace for HTML/CSS/JS, A2UI, and small interactive UI surfaces.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Where Canvas lives

Canvas state is stored under Application Support:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• ~/Library/Application Support/OpenClaw/canvas/<session>/...
• 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

Panel behavior

Canvas can be disabled from Settings -> Allow Canvas. When disabled, canvas node commands return CANVAS_DISABLED.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Borderless, resizable panel anchored near the menu bar (or mouse cursor).
• Presenting Canvas does not switch apps or steal keyboard focus.
• Remembers size/position per session.
• Auto-reloads when local canvas files change.
• Only one Canvas panel is visible at a time (session switches as needed).

Agent API surface

Canvas is exposed via the Gateway WebSocket, so the agent can show/hide the panel, navigate to a path or URL, evaluate JavaScript, and capture a snapshot image:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

A2UI in Canvas

A2UI is hosted by the Gateway canvas host and rendered inside the Canvas panel. When the Gateway advertises a Canvas host, the macOS app auto-navigates to the A2UI host page on first open.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

A2UI commands (v0.8)

Canvas accepts A2UI v0.8 server-to-client messages: beginRendering, surfaceUpdate, dataModelUpdate, deleteSurface. createSurface (v0.9) is not supported yet.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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>

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

Triggering agent runs from Canvas

Canvas can trigger new agent runs via openclaw://agent?... deep links:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Parameter	Meaning
message	Prefilled agent prompt.
sessionKey	Stable session identifier.
thinking	Optional thinking profile.
deliver, to, channel	Delivery target.
timeoutSeconds	Optional run timeout.
key	App-generated safety token for trusted local callers.

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

Security notes

app-owned Canvas scheme or the exact capability-scoped Gateway A2UI document selected by the app; subframes, redirects, stale capabilities, and changed queries cannot dispatch actions.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Canvas scheme blocks directory traversal; files must live under the session root.
• Local Canvas content uses a custom scheme (no loopback server required).
• External http(s) URLs are allowed only when explicitly navigated.
• Ordinary web pages are render-only. Agent actions are accepted only from the

관련 문서

주요 항목:

• macOS app
• WebChat

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/platforms/mac/canvas
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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>

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

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

관련 링크

• 공식 원문: platforms/mac/canvas
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.