WebChat (macOS app) 가이드

개발을 하다 보면 채팅 인터페이스를 확인하기 위해 매번 브라우저 창을 찾아 헤매는 일이 꽤 번거롭습니다. 작업 흐름을 방해하지 않으면서도 필요할 때 즉시 채팅창을 띄워 확인하고 싶은 갈증이 생기곤 하죠.

이런 불편함을 해결하기 위해 WebChat은 macOS 메뉴바 앱 형태로 제공됩니다. SwiftUI로 빌드된 네이티브 뷰를 통해 Gateway에 직접 연결하여 사용할 수 있습니다.

필요한 것

• macOS 환경
• Gateway 연결 권한 (Local 또는 SSH 접근)

빠른 시작

5분 안에 WebChat 앱을 실행하고 디버깅하는 방법입니다.

1. 앱 실행: Lobster 메뉴에서 “Open Chat”을 클릭하세요.
2. 테스트용 자동 실행: 터미널에서 다음 명령어를 입력하면 테스트를 위해 앱을 바로 열 수 있어요.

dist/OpenClaw.app/Contents/MacOS/OpenClaw --webchat

How it’s wired

WebChat이 내부적으로 어떻게 작동하는지 핵심 구조를 정리했습니다.

• Data plane: Gateway WS의 chat.history, chat.send, chat.abort, chat.inject 메서드를 사용합니다. 또한 chat, agent, presence, tick 이벤트를 실시간으로 처리해요.
• Session 관리: 기본적으로 main 세션(스코프가 global인 경우 global)을 사용하지만, UI 내 세션 스위처를 통해 다른 세션으로 바꿀 수 있습니다. 온보딩은 초기 설정을 분리하기 위해 전용 세션을 사용해요.
• 연결 모드: Local mode는 로컬 Gateway WebSocket에 직접 연결하고, Remote mode는 SSH를 통해 Gateway 제어 포트만 포워딩하여 데이터 평면으로 사용합니다.
• 제한 사항: 이 UI는 채팅 세션에 최적화되어 있습니다. 전체 브라우저 기능을 제공하는 샌드박스가 아니라는 점을 참고해 주세요.

문제 해결

문제가 발생했을 때는 로그를 확인하는 것이 가장 빠릅니다.

• 로그 확인: 터미널에서 아래 스크립트를 실행하면 디버깅 정보를 볼 수 있어요.
• 필터링: bot.molt 서브시스템과 WebChatSwiftUI 카테고리를 중점적으로 확인하세요.

./scripts/clawlog.sh

설정 과정에서 도움이 필요하다면 AI Setup Assistant에게 질문해 보세요.

다음 단계

• Gateway 구성 가이드
• CLI 명령어 참조