서문
OpenClaw이 지원하는 많은 채팅 채널 중에서 WebChat은 독특한 존재입니다. 어떤 서드파티 플랫폼에도 의존하지 않고, OpenClaw의 웹 관리 패널(Dashboard)에 직접 내장되어 있으며, WebSocket 프로토콜을 통해 브라우저와 AI 어시스턴트 간의 실시간 통신을 구현합니다. 자체 웹사이트에 AI 대화 입구를 제공하거나, 브라우저에서 빠르게 AI 모델을 테스트하고 싶다면, WebChat이 가장 직접적인 선택입니다.
WebChat의 기술 아키텍처
WebChat은 WebSocket 프로토콜 기반으로 구축되었으며, OpenClaw Gateway 인터페이스의 일부입니다. 기존의 HTTP 요청-응답 모델과 달리, WebSocket은 영구적인 양방향 통신 연결을 수립하여, 메시지가 서버와 클라이언트 간에 즉시 전달될 수 있으며 반복적으로 연결을 수립할 필요가 없습니다.
브라우저 클라이언트 OpenClaw Gateway
│ │
│──── WebSocket 핸드셰이크 ──────▶│
│◀─── 101 Switching Protocol ──│
│ │
│──── 사용자 메시지 ──────────────▶│
│ │──▶ AI 모델 처리
│◀─── AI 스트리밍 응답 ───────────│◀──
│◀─── AI 스트리밍 응답 ───────────│
│◀─── 응답 완료 신호 ────────────│
│ │
이 아키텍처는 두 가지 주요 장점을 제공합니다: 첫째, 메시지 지연시간이 매우 짧아 사용자가 보낸 후 거의 즉시 AI 응답을 받기 시작합니다. 둘째, 스트리밍 출력(Streaming)을 지원하여 AI의 답변이 글자 단위로 페이지에 표시되며, 전체 생성이 완료될 때까지 기다릴 필요가 없습니다.
WebChat 활성화
WebChat은 OpenClaw의 네이티브 통합(Native Integration)으로, 기본적으로 Dashboard와 함께 활성화됩니다. OpenClaw Gateway 서비스가 실행 중이면 WebChat을 바로 사용할 수 있습니다.
Gateway 서비스가 시작되었는지 확인합니다:
openclaw up -d
그런 다음 브라우저에서 Dashboard에 접속합니다:
http://localhost:18789/dashboard
Dashboard의 사이드바에서 WebChat 입구를 찾을 수 있습니다. 클릭하면 웹 채팅 인터페이스로 진입합니다.
설정 파일에서 WebChat의 활성화 상태를 명시적으로 관리하려면, ~/.config/openclaw/openclaw.json5를 편집합니다:
{
channels: {
webchat: {
enabled: true,
// WebSocket 연결 경로 (기본값 사용 권장)
wsPath: "/ws/chat",
// 허용된 출처 도메인 (CORS 제어)
allowedOrigins: ["*"],
// 단일 연결 최대 유휴 시간 (초)
idleTimeout: 300,
// 최대 동시 WebSocket 연결 수
maxConnections: 50
}
}
}
WebChat의 독립 설정
다른 채널과 마찬가지로, WebChat도 독립적인 모델, 페르소나 및 스킬 설정을 지원합니다. WebChat에 Telegram이나 Discord와 완전히 다른 AI 동작을 지정할 수 있습니다:
{
channels: {
webchat: {
enabled: true,
model: {
provider: "claude",
name: "claude-sonnet-4-20250514",
apiKey: "sk-ant-xxxxx"
},
persona: {
name: "웹 어시스턴트",
systemPrompt: "당신은 전문적인 온라인 고객 서비스 어시스턴트로, 제품과 서비스에 관한 사용자의 질문에 답변합니다. 친근하면서도 전문적인 톤을 유지하세요."
},
skills: ["faq", "product-docs", "weather"],
temperature: 0.7,
maxTokens: 2048
}
}
}
다른 채널과 병렬 실행
WebChat의 가장 큰 편리함 중 하나는 다른 모든 채널과 동시에 실행할 수 있으며, 서로 간섭하지 않는다는 것입니다. 같은 OpenClaw 인스턴스에서 Telegram, WhatsApp, Discord, WebChat을 동시에 활성화할 수 있으며, 각 채널은 독립적으로 메시지 흐름과 대화 컨텍스트를 처리합니다.
{
channels: {
telegram: { enabled: true, botToken: "your-token" },
whatsapp: { enabled: true, phoneNumber: "+8213800138000" },
webchat: { enabled: true }
}
}
특정 채널에 이상이 발생해도(예: Telegram 연결 끊김) WebChat의 정상 운영에 영향을 미치지 않으며, 반대의 경우도 마찬가지입니다. OpenClaw의 채널 격리 아키텍처가 각 채널의 독립성을 보장합니다.
보안 설정
WebChat은 브라우저 측에 직접 노출되므로 보안 설정이 특히 중요합니다. 다음 조치를 권장합니다:
접근 출처 제한: allowedOrigins로 허용된 도메인을 설정하여, 인가되지 않은 웹사이트가 WebChat 인터페이스를 호출하는 것을 방지합니다.
{
channels: {
webchat: {
enabled: true,
allowedOrigins: ["https://yourdomain.com", "https://app.yourdomain.com"]
}
}
}
Dashboard 비밀번호와 함께 사용: Dashboard에 접근 비밀번호를 설정하여, 인가된 사용자만 WebChat을 사용할 수 있도록 합니다.
openclaw config set dashboard.password "your-secure-password"
openclaw restart
HTTPS 배포: WebChat이 공용 인터넷에 노출된 경우, 반드시 Nginx 리버스 프록시를 통해 HTTPS를 설정해야 합니다. WebSocket 연결도 자동으로 암호화된 WSS 프로토콜로 업그레이드됩니다.
적용 시나리오
WebChat은 특히 다음 사용 시나리오에 적합합니다:
- 빠른 테스트: 새 모델을 설정하거나 페르소나를 조정한 후, 다른 채팅 앱으로 전환하지 않고 브라우저에서 직접 효과를 테스트합니다.
- 웹사이트 고객 서비스: 자체 제품 웹사이트에 AI 대화 입구를 내장하여 방문자에게 즉시 질의응답 서비스를 제공합니다.
- 내부 도구: 팀원들이 브라우저를 통해 직접 AI 어시스턴트와 상호작용하며, 별도의 채팅 클라이언트를 설치할 필요가 없습니다.
- 데모 시연: 다른 사람에게 OpenClaw의 능력을 시연할 때, WebChat이 가장 직관적인 방법입니다.
자주 묻는 질문
WebChat과 Dashboard의 "새 대화"의 차이점은 무엇인가요?
Dashboard의 대화 기능은 주로 각 채널의 과거 대화를 관리하고 조회하는 데 사용됩니다. WebChat은 독립적인 채팅 채널로, 자체 설정 항목(모델, 페르소나, 스킬 등)을 가지며, 대화 기록도 WebChat 채널의 기록으로 저장됩니다.
WebSocket 연결이 끊어지면 어떻게 하나요?
WebChat에는 자동 재연결 메커니즘이 내장되어 있습니다. 네트워크 불안정으로 WebSocket 연결이 중단되면, 클라이언트가 자동으로 연결을 재수립합니다. 지속적으로 연결할 수 없는 경우, Gateway 서비스가 정상적으로 실행 중인지 확인하세요:
openclaw doctor
모바일 브라우저를 지원하나요?
지원합니다. WebChat 인터페이스는 반응형 적응이 적용되어 있으며, 스마트폰과 태블릿 브라우저에서 정상적으로 사용할 수 있습니다.
마무리
WebChat은 OpenClaw에 내장된 웹 채팅 채널로, 의존성 없고 진입 장벽이 낮은 AI 대화 경험을 제공합니다. WebSocket 기반의 실시간 통신 아키텍처가 원활한 인터랙션 효과를 보장하며, 네이티브 통합 설계를 통해 다른 채널과 원활하게 병렬 실행할 수 있습니다. 일상적인 테스트, 웹사이트 통합, 팀 내부 사용 등 어떤 경우에든 WebChat은 활성화할 가치가 있는 채널입니다.