웹 채팅

상태: macOS/iOS SwiftUI 채팅 UI는 Gateway WebSocket과 직접 통신합니다.

# 정의

• 게이트웨이를 위한 네이티브 채팅 UI입니다(내장 브라우저와 로컬 정적 서버 없음).
• 다른 채널과 동일한 세션 및 라우팅 규칙을 사용합니다.
• 결정적 라우팅: 응답은 항상 WebChat으로 돌아갑니다.

# 빠른 시작

1. 게이트웨이를 시작합니다.
2. WebChat UI(macOS/iOS 앱) 또는 Control UI 채팅 탭을 엽니다.
3. 유효한 게이트웨이 인증 경로가 구성되어 있는지 확인합니다(기본값은 공유 비밀이며, 루프백에서도 동일).

# 작동 방식(동작)

• UI는 Gateway WebSocket에 연결하고 chat.history, chat.send, chat.inject를 사용합니다.
• chat.history는 안정성을 위해 제한됩니다. Gateway는 긴 텍스트 필드를 잘라내거나, 무거운 메타데이터를 생략하거나, 너무 큰 항목을 [chat.history omitted: message too large]로 대체할 수 있습니다.
• chat.history는 최신 추가 전용 세션 파일의 활성 트랜스크립트 분기를 따르므로, 버려진 재작성 분기와 대체된 프롬프트 복사본은 WebChat에 렌더링되지 않습니다.
• Compaction 항목은 명시적인 압축된 기록 구분선으로 렌더링됩니다. 이 구분선은 이전 턴이 체크포인트에 보존되어 있음을 설명하고 Sessions 체크포인트 컨트롤로 연결합니다. 운영자는 권한이 허용하는 경우 여기에서 Compaction 이전 보기를 분기하거나 복원할 수 있습니다.
• Control UI는 chat.history가 반환한 백엔드 Gateway sessionId를 기억하고 후속 chat.send 호출에 포함하므로, 사용자가 세션을 시작하거나 재설정하지 않는 한 재연결 및 페이지 새로고침 후에도 동일하게 저장된 대화가 계속됩니다.
• Control UI는 새 chat.send 실행 ID를 생성하기 전에 동일한 세션, 메시지, 첨부 파일에 대한 중복 진행 중 제출을 병합합니다. Gateway는 여전히 동일한 멱등성 키를 재사용하는 반복 요청을 중복 제거합니다.
• 워크스페이스 시작 파일과 대기 중인 BOOTSTRAP.md 지침은 WebChat 사용자 메시지에 복사되지 않고 에이전트 시스템 프롬프트의 Project Context를 통해 제공됩니다. 부트스트랩 잘림은 간결한 시스템 프롬프트 복구 알림만 추가하며, 상세 개수와 구성 조정값은 진단 화면에 유지됩니다.
• chat.history는 표시용으로도 정규화됩니다. 런타임 전용 OpenClaw 컨텍스트, 인바운드 봉투 래퍼, [[reply_to_*]] 및 [[audio_as_voice]] 같은 인라인 전달 지시문 태그, 일반 텍스트 도구 호출 XML 페이로드(<tool_call>...</tool_call>, <function_call>...</function_call>, <tool_calls>...</tool_calls>, <function_calls>...</function_calls>, 잘린 도구 호출 블록 포함), 그리고 유출된 ASCII/전각 모델 제어 토큰은 보이는 텍스트에서 제거되며, 전체 보이는 텍스트가 정확히 무음 토큰 NO_REPLY / no_reply뿐인 어시스턴트 항목은 생략됩니다.
• 추론으로 표시된 응답 페이로드(isReasoning: true)는 WebChat 어시스턴트 콘텐츠, 트랜스크립트 재생 텍스트, 오디오 콘텐츠 블록에서 제외되므로, 사고 전용 페이로드가 보이는 어시스턴트 메시지나 재생 가능한 오디오로 표시되지 않습니다.
• chat.inject는 어시스턴트 메모를 트랜스크립트에 직접 추가하고 UI로 브로드캐스트합니다(에이전트 실행 없음).
• 중단된 실행은 부분 어시스턴트 출력을 UI에 계속 표시할 수 있습니다.
• Gateway는 버퍼링된 출력이 있을 때 중단된 부분 어시스턴트 텍스트를 트랜스크립트 기록에 저장하고, 해당 항목에 중단 메타데이터를 표시합니다.
• 기록은 항상 게이트웨이에서 가져옵니다(로컬 파일 감시 없음).
• 게이트웨이에 연결할 수 없으면 WebChat은 읽기 전용입니다.

# 트랜스크립트 및 전달 모델

WebChat에는 두 개의 별도 데이터 경로가 있습니다.

• 세션 JSONL 파일은 지속성 있는 모델/런타임 트랜스크립트입니다. 일반 에이전트 실행의 경우 Pi는 세션 관리자를 통해 모델에 보이는 user, assistant, toolResult 메시지를 저장합니다. WebChat은 임의의 전달, 상태 또는 보조 텍스트를 해당 트랜스크립트에 쓰지 않습니다.
• Gateway ReplyPayload 이벤트는 실시간 전달 투영입니다. WebChat/채널 표시, 블록 스트리밍, 지시문 태그, 미디어 임베딩, TTS/오디오 플래그, UI 폴백 동작에 맞게 정규화될 수 있습니다. 이것들 자체가 표준 세션 로그는 아닙니다.
• WebChat은 Gateway가 일반 Pi 어시스턴트 턴 밖에서 표시된 메시지를 소유할 때만 어시스턴트 트랜스크립트 항목을 삽입합니다. chat.inject, 비에이전트 명령 응답, 중단된 부분 출력, WebChat 관리 미디어 트랜스크립트 보충 항목이 이에 해당합니다.
• chat.history는 저장된 세션 트랜스크립트를 읽고 WebChat 표시 투영을 적용합니다. 실행 중 실시간 어시스턴트 텍스트가 나타났지만 기록 재로드 후 사라진 경우, 먼저 원시 JSONL에 어시스턴트 텍스트가 있는지 확인하고, 그다음 chat.history 투영이 이를 제거했는지 확인한 뒤, Control UI 낙관적 꼬리 병합이 로컬 전달 상태를 저장된 스냅샷으로 대체했는지 확인합니다.

일반 에이전트 실행 최종 답변은 Pi가 어시스턴트 message_end를 기록하므로 지속되어야 합니다. 전달된 최종 페이로드를 트랜스크립트에 미러링하는 폴백은 먼저 Pi가 이미 기록한 어시스턴트 턴을 중복하지 않아야 합니다.

# Control UI 에이전트 도구 패널

• Control UI /agents Tools 패널에는 두 개의 별도 보기가 있습니다.
  • 지금 사용 가능은 tools.effective(sessionKey=...)를 사용하며, 현재 세션이 런타임에서 실제로 사용할 수 있는 항목을 표시합니다. 여기에는 코어, Plugin, 채널 소유 도구가 포함됩니다.
  • 도구 구성은 tools.catalog를 사용하며 프로필, 재정의, 카탈로그 의미 체계에 집중합니다.
• 런타임 가용성은 세션 범위입니다. 같은 에이전트에서 세션을 전환하면 지금 사용 가능 목록이 바뀔 수 있습니다.
• 구성 편집기는 런타임 가용성을 의미하지 않습니다. 유효 접근은 여전히 정책 우선순위(allow/deny, 에이전트별 및 제공자/채널 재정의)를 따릅니다.

# 원격 사용

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

# 구성 참조(WebChat)

전체 구성: 구성

WebChat 옵션:

• gateway.webchat.chatHistoryMaxChars: chat.history 응답에서 텍스트 필드의 최대 문자 수입니다. 트랜스크립트 항목이 이 제한을 초과하면 Gateway는 긴 텍스트 필드를 잘라내고 너무 큰 메시지를 플레이스홀더로 대체할 수 있습니다. 클라이언트는 단일 chat.history 호출에 대해 이 기본값을 재정의하도록 요청별 maxChars를 보낼 수도 있습니다.

관련 전역 옵션:

• gateway.port, gateway.bind: WebSocket 호스트/포트.
• gateway.auth.mode, gateway.auth.token, gateway.auth.password: 공유 비밀 WebSocket 인증.
• gateway.auth.allowTailscale: 활성화하면 브라우저 Control UI 채팅 탭이 Tailscale Serve ID 헤더를 사용할 수 있습니다.
• gateway.auth.mode: "trusted-proxy": ID 인식 비루프백 프록시 소스 뒤의 브라우저 클라이언트를 위한 역방향 프록시 인증입니다(신뢰할 수 있는 프록시 인증 참조).
• gateway.remote.url, gateway.remote.token, gateway.remote.password: 원격 게이트웨이 대상.
• session.*: 세션 저장소 및 기본 키 기본값.

# 관련 항목

• Control UI
• 대시보드