Canvas를 활용한 macOS용 시각적 워크스페이스 구축하기

코드만으로 UI 결과물을 확인하거나 에이전트가 생성한 인터랙티브한 화면을 실시간으로 보는 건 꽤 번거로운 일이죠. 매번 브라우저를 따로 띄우거나 복잡한 설정을 거치지 않고, 작업 중인 환경 안에서 가볍고 빠르게 시각적인 피드백을 받고 싶을 때가 많을 거예요.

OpenClaw의 Canvas는 이런 고민을 해결해 줍니다. WKWebView를 기반으로 한 경량 시각적 워크스페이스를 통해 HTML, CSS, JavaScript는 물론 A2UI까지 한곳에서 관리할 수 있어요.

필요한 것

• macOS용 OpenClaw 앱
• 활성화된 Gateway WebSocket 연결
• 제어할 대상 Node ID

빠른 시작

CLI를 사용해 5분 안에 Canvas를 띄우고 제어할 수 있습니다.

1. Canvas 패널 표시하기: 메뉴바나 마우스 커서 근처에 패널을 나타나게 합니다.

   openclaw nodes canvas present --node <id>

2. 특정 경로로 이동하기: 로컬 경로(/)나 외부 URL로 이동합니다. /를 입력하면 기본 스캐폴드 페이지나 index.html이 표시됩니다.

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

3. JavaScript 실행하기: 실행 중인 Canvas 내에서 스크립트를 실행하고 결과를 확인합니다.

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

4. A2UI 푸시하기 (v0.8): 아래 명령어로 간단한 텍스트를 화면에 바로 띄울 수 있습니다.

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

Canvas에서 에이전트를 다시 실행하고 싶다면 JavaScript에서 Deep link를 사용하면 됩니다.

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

문제 해결

• CANVAS_DISABLED 에러가 발생하나요? Settings → Allow Canvas 옵션이 켜져 있는지 확인해 주세요. 이 옵션이 꺼져 있으면 모든 Canvas 관련 명령이 작동하지 않습니다.

• A2UI 구성 요소가 렌더링되지 않나요? 현재 Canvas는 A2UI v0.8 사양만 지원합니다. createSurface 명령이 포함된 v0.9 버전은 지원하지 않으니, surfaceUpdate나 beginRendering 같은 v0.8 메시지를 사용하고 있는지 확인해 보세요.

• 파일 접근에 문제가 있나요? 보안을 위해 openclaw-canvas:// 스킴은 세션 루트 디렉토리 외부로의 접근(Directory Traversal)을 차단합니다. 모든 파일은 ~/Library/Application Support/OpenClaw/canvas/<session>/ 아래에 있어야 합니다.

설정 과정에서 도움이 필요하다면 AI Setup Assistant를 활용해 보세요.

다음 단계

• Gateway WebSocket API 상세 보기
• A2UI v0.8 메시지 규격 안내
• macOS 앱 커스텀 URL 스킴 활용법