OpenClaw WebChat 채널

WebChat은 세 가지 주요 작업을 통해 WebSocket 연결로 OpenClaw Gateway와 통신합니다: • chat.history — Gateway에서 대화 기록 조회 • chat.send — AI 어시스턴트에 사용자 메시지 전송 • chat.inject — 에이전트 실행을 트리거하지 않고 어시스턴트 노트를 대화 기록에 직접 추가하고 UI에 브로드캐스트 외부 서비스와 Webhook에 의존하는 다른 채널과 달리, WebChat은 Gateway에 완전히 내장되어 있습니다. 메시지가 인프라 외부로 나가지 않으며, WebSocket 연결은 UI 클라이언트와 Gateway 프로세스 간의 직접 연결입니다. 라우팅은 결정론적이므로 AI의 응답은 항상 대화를 시작한 WebChat 세션으로 반환됩니다.

루프백(localhost)에서도 모든 WebChat 연결에 인증이 필요합니다. 이를 통해 AI 어시스턴트에 대한 무단 접근을 방지합니다. OpenClaw는 두 가지 인증 모드를 지원합니다: • token — WebSocket 핸드셰이크에서 전달되는 공유 비밀 토큰입니다. 프로그래밍 방식 접근 및 단일 사용자 설정에 적합합니다. • password — 비밀번호 기반 인증입니다. 각 사용자가 자신의 자격 증명을 가지는 다중 사용자 환경에 적합합니다. WebChat이 연결을 수락하려면 token 또는 password 중 하나 이상이 구성되어야 합니다. openclaw.json의 gateway.auth 설정에서 구성합니다.

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "a-strong-random-token-here"
    }
  }
}

WebChat은 별도의 웹 서버 없이 원격 연결을 지원합니다. 두 가지 접근 방식을 권장합니다: • SSH 터널 — SSH를 통해 Gateway 포트를 포워딩합니다: ssh -L 3000:localhost:3000 user@remote-host. 이를 통해 Gateway가 원격 머신에서 실행되는 동안 로컬에서 WebChat에 접근할 수 있습니다. • Tailscale — Tailscale의 메시 VPN을 통해 디바이스를 연결합니다. 포트 포워딩이나 방화벽 구성 없이 Tailscale IP 주소로 Gateway에 접근할 수 있습니다. 원격 연결의 경우 대상 WebSocket URL과 인증 자격 증명으로 gateway.remote 설정을 구성합니다. 네이티브 클라이언트는 네트워크 상태가 변경되면 자동으로 재연결을 처리합니다.

{
  "gateway": {
    "remote": {
      "url": "wss://your-remote-host:3000",
      "token": "YOUR_REMOTE_TOKEN"
    }
  }
}

WebChat은 Gateway에서 관리하는 세션을 사용하여 대화 컨텍스트를 유지합니다. 각 WebChat 연결은 대화 기록과 AI 컨텍스트를 저장하는 세션에 연결됩니다. 세션은 재연결 시에도 유지됩니다 — WebSocket이 끊어졌다가 다시 연결되면 대화가 중단된 지점부터 계속됩니다. chat.history 작업은 재연결 시 Gateway에서 전체 대화를 조회합니다. 세션 구성은 openclaw.json의 session.* 설정에서 관리되며, 스토리지 백엔드 및 기본 세션 키를 포함합니다.

Gateway에 연결할 수 없게 되면 WebChat은 자동으로 읽기 전용 모드로 전환됩니다. 이 상태에서는: • 이전 대화 기록은 계속 표시됩니다 • 새 메시지를 보낼 수 없습니다 • UI에 연결 해제 상태가 표시됩니다 • 백그라운드에서 자동 재연결을 시도합니다 Gateway가 다시 온라인 상태가 되면 WebChat이 자동으로 재연결되어 전체 기능이 복원됩니다. 모든 기록은 Gateway에서 제공되므로 대화 기록에서 메시지가 손실되지 않습니다.

WebChat은 Apple 플랫폼에서 네이티브 SwiftUI 애플리케이션으로 구현되어 있습니다: • macOS — 키보드 단축키, 시스템 알림 및 메뉴 바 통합을 갖춘 완전한 데스크톱 경험 • iOS — 푸시 알림 및 백그라운드 새로고침을 지원하는 모바일 최적화 인터페이스 네이티브 구현은 임베디드 브라우저나 Electron 래퍼의 오버헤드 없이 반응성이 뛰어난 플랫폼 네이티브 경험을 제공합니다. 텍스트 렌더링, 스크롤링, 입력 처리 모두 네이티브 플랫폼 컴포넌트를 사용합니다. 다른 플랫폼(Windows, Linux, Android)에서는 최신 웹 브라우저의 Control UI 채팅 탭을 통해 WebChat에 접근할 수 있습니다.

WebChat은 긴 AI 응답에 대해 구성 가능한 청킹을 통해 WebSocket 연결로 메시지를 전달합니다: • textChunkLimit — 메시지 청크당 최대 문자 수 (기본값: 2000). 긴 응답은 자동으로 분할됩니다. • blockStreaming — 활성화하면 응답이 생성되는 동안 블록 기반 청크로 전송되어 실시간 피드백을 제공합니다. 메시지는 WebSocket을 통해 즉시 전달됩니다 — 폴링이나 Webhook 지연이 없습니다. 양방향 WebSocket 연결 덕분에 송수신이 모두 실시간으로 이루어집니다.

{
  "channels": {
    "webchat": {
      "textChunkLimit": 2000,
      "blockStreaming": true
    }
  }
}

WebChat 보안은 Gateway 인증 계층을 기반으로 합니다. 안전한 배포를 위해 다음 모범 사례를 따르세요: • 항상 인증 구성 — 익명 접근은 허용되지 않습니다 • TLS 암호화 사용 — 모든 원격 연결에 wss:// (WebSocket Secure)를 통해 연결합니다 • 바인드 주소 제한 — 로컬 전용 접근에는 gateway.bind: "127.0.0.1"을 사용하고, 리버스 프록시 뒤에 있지 않은 경우 0.0.0.0 바인딩을 피합니다 • 강력한 자격 증명 사용 — 랜덤 토큰이나 강력한 비밀번호를 생성합니다 • 리버스 프록시 — 프로덕션 배포에서는 TLS 종료를 수행하는 리버스 프록시(nginx, Caddy) 뒤에 Gateway를 배치합니다 동일 머신에서 리버스 프록시를 사용하는 경우 gateway.trustedProxies를 구성하여 올바른 클라이언트 IP 감지를 보장합니다.