OpenClaw WebChat 설정: macOS 및 iOS 네이티브 UI 연결

채팅 인터페이스를 개발할 때 로컬 서버를 따로 띄우거나 브라우저를 내장해야 하는 번거로움 때문에 고생하신 적 많으시죠? 백엔드와 UI 사이의 세션이 꼬이거나 라우팅 규칙이 일치하지 않아 디버깅에 시간을 허비하는 일은 개발자에게 정말 피곤한 일입니다.

WebChat은 이러한 불편함을 해결하기 위해 Gateway WebSocket과 직접 통신하도록 설계되었습니다. 복잡한 설정 없이도 일관된 채팅 환경을 구축할 수 있는 WebChat에 대해 자세히 알아보겠습니다.

WebChat이란 무엇인가요?

• Gateway를 위한 네이티브 채팅 UI입니다. 브라우저를 내장하거나 별도의 로컬 정적 서버를 실행할 필요가 없습니다 (macOS/iOS SwiftUI UI).
• 다른 채널과 동일한 세션 및 라우팅 규칙을 사용합니다.
• 결정론적 라우팅(Deterministic routing)을 지원하여, 응답은 항상 WebChat으로 다시 돌아옵니다.

빠른 시작

1. Gateway를 시작하세요.
2. WebChat UI(macOS/iOS 앱) 또는 Control UI의 채팅 탭을 엽니다.
3. Gateway 인증(auth)이 설정되어 있는지 확인하세요. 루프백(loopback) 환경에서도 기본적으로 인증이 필요합니다.

작동 방식 및 동작

• UI는 Gateway WebSocket에 연결되며 chat.history, chat.send, chat.inject를 사용합니다.
• chat.history는 안정성을 위해 제한 범위가 정해져 있습니다. Gateway는 긴 텍스트 필드를 자르거나, 무거운 메타데이터를 생략할 수 있으며, 크기가 너무 큰 항목은 [chat.history omitted: message too large]라는 문구로 대체합니다.
• chat.inject는 어시스턴트 노트를 트랜스크립트에 직접 추가하고 UI에 브로드캐스트합니다. 이때 에이전트(agent)는 실행되지 않습니다.
• 중단된(Aborted) 실행의 경우, 어시스턴트의 부분적인 출력 내용이 UI에 계속 표시될 수 있습니다.
• 버퍼링된 출력이 있는 상태에서 실행이 중단되면, Gateway는 해당 텍스트를 트랜스크립트 히스토리에 저장하고 중단 메타데이터를 마크합니다.
• 히스토리는 항상 Gateway에서 가져옵니다. 로컬 파일을 감시(watching)하지 않습니다.
• Gateway에 연결할 수 없는 경우, WebChat은 읽기 전용 모드로 작동합니다.

Control UI 에이전트 도구 패널

• Control UI의 /agents 도구(Tools) 패널은 두 가지 별도의 뷰를 제공합니다.
  • Available Right Now: tools.effective(sessionKey=...)를 사용하며, 코어, 플러그인, 채널 소유 도구를 포함하여 현재 세션이 런타임에 실제로 사용할 수 있는 도구들을 보여줍니다.
  • Tool Configuration: tools.catalog를 사용하며 프로필, 오버라이드, 카탈로그 시맨틱에 집중합니다.
• 런타임 가용성은 세션 범위(session-scoped)에 따라 달라집니다. 동일한 에이전트에서 세션을 전환하면 Available Right Now 목록이 변경될 수 있습니다.
• 설정 에디터에서 보인다고 해서 런타임 가용성이 보장되는 것은 아닙니다. 실제 액세스 권한은 정책 우선순위(allow/deny, 에이전트별 및 Provider/Channel 오버라이드)를 따릅니다.

원격 사용

• 원격 모드에서는 SSH 또는 Tailscale을 통해 Gateway WebSocket을 터널링합니다.
• 별도의 WebChat 서버를 실행할 필요가 없습니다.

설정 참조 (WebChat)

전체 설정 확인하기: Configuration

WebChat 옵션:

• gateway.webchat.chatHistoryMaxChars: chat.history 응답에서 텍스트 필드의 최대 문자 수입니다. 트랜스크립트 항목이 이 제한을 초과하면 Gateway는 긴 텍스트 필드를 자르고 자리 표시자(placeholder)로 대체할 수 있습니다. 클라이언트가 단일 chat.history 호출 시 maxChars를 보내 이 기본값을 오버라이드할 수도 있습니다.

관련 글로벌 옵션:

• gateway.port, gateway.bind: WebSocket 호스트 및 포트입니다.
• gateway.auth.mode, gateway.auth.token, gateway.auth.password: WebSocket 인증(토큰/비밀번호) 설정입니다.
• gateway.auth.mode: "trusted-proxy": 브라우저 클라이언트를 위한 역방향 프록시 인증입니다. (Trusted Proxy Auth 참고)
• gateway.remote.url, gateway.remote.token, gateway.remote.password: 원격 Gateway 타겟 설정입니다.
• session.*: 세션 저장소 및 메인 키 기본값 설정입니다.

다음 단계

• Gateway 설정 가이드
• 신뢰할 수 있는 프록시 인증 이해하기

AI Setup Assistant