Web interfaces

웹 채팅

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

정의

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

빠른 시작

게이트웨이를 시작합니다.
WebChat UI(macOS/iOS 앱) 또는 Control UI 채팅 탭을 엽니다.
유효한 게이트웨이 인증 경로가 구성되어 있는지 확인합니다(기본값은 shared-secret이며, 루프백에서도 마찬가지입니다).

작동 방식(동작)

UI는 Gateway WebSocket에 연결하고 chat.history, chat.send, chat.inject를 사용합니다.
chat.history는 안정성을 위해 제한됩니다. Gateway는 긴 텍스트 필드를 자르거나, 무거운 메타데이터를 생략하거나, 너무 큰 항목을 [chat.history omitted: message too large]로 대체할 수 있습니다.
표시되는 어시스턴트 메시지가 chat.history에서 잘린 경우, Control UI는 기본 히스토리 페이로드를 늘리지 않고도 사이드 리더를 열고 chat.message.get을 통해 요청 시 전체 표시 정규화 항목을 가져올 수 있습니다.
chat.history는 최신 append-only 세션 파일의 활성 트랜스크립트 브랜치를 따르므로, 폐기된 재작성 브랜치와 대체된 프롬프트 사본은 WebChat에 렌더링되지 않습니다.
Compaction 항목은 명시적인 압축된 히스토리 구분선으로 렌더링됩니다. 구분선은 압축된 트랜스크립트가 체크포인트로 보존된다고 설명하고 Sessions 체크포인트 컨트롤로 연결합니다. 운영자는 권한이 허용하는 경우 해당 컨트롤에서 압축된 뷰로부터 브랜치하거나 복원할 수 있습니다.
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뿐인 어시스턴트 항목은 생략됩니다.
Reasoning 플래그가 지정된 응답 페이로드(isReasoning: true)는 WebChat 어시스턴트 콘텐츠, 트랜스크립트 재생 텍스트, 오디오 콘텐츠 블록에서 제외되므로, 사고 전용 페이로드는 표시되는 어시스턴트 메시지나 재생 가능한 오디오로 노출되지 않습니다.
chat.inject는 어시스턴트 노트를 트랜스크립트에 직접 추가하고 UI로 브로드캐스트합니다(에이전트 실행 없음).
중단된 실행은 부분 어시스턴트 출력을 UI에 계속 표시할 수 있습니다.
Gateway는 버퍼링된 출력이 있을 때 중단된 부분 어시스턴트 텍스트를 트랜스크립트 히스토리에 유지하고, 해당 항목에 중단 메타데이터를 표시합니다.
히스토리는 항상 게이트웨이에서 가져옵니다(로컬 파일 감시 없음).
게이트웨이에 연결할 수 없으면 WebChat은 읽기 전용입니다.

트랜스크립트 및 전달 모델

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

세션 JSONL 파일은 지속적인 모델/런타임 트랜스크립트입니다. 일반 에이전트 실행의 경우 임베디드 OpenClaw 런타임은 세션 관리자를 통해 모델에 표시되는 user, assistant, toolResult 메시지를 유지합니다. WebChat은 임의의 전달, 상태, 헬퍼 텍스트를 해당 트랜스크립트에 쓰지 않습니다.
Gateway ReplyPayload 이벤트는 라이브 전달 프로젝션입니다. WebChat/채널 표시, 블록 스트리밍, 지시문 태그, 미디어 임베딩, TTS/오디오 플래그, UI 폴백 동작을 위해 정규화될 수 있습니다. 이 이벤트 자체가 표준 세션 로그는 아닙니다.
tools.message를 통해 표시되는 응답이 필요한 하니스는 여전히 WebChat을 현재 실행 내부 소스 응답 싱크로 사용합니다. 활성 WebChat 실행에서 대상이 없는 message.send는 동일한 채팅으로 프로젝션되고 세션 트랜스크립트에 미러링됩니다. WebChat은 재사용 가능한 아웃바운드 채널이 되지 않으며 lastChannel을 상속하지 않습니다.
WebChat은 Gateway가 일반 임베디드 에이전트 턴 외부에서 표시된 메시지를 소유할 때만 어시스턴트 트랜스크립트 항목을 주입합니다. chat.inject, 비에이전트 명령 응답, 중단된 부분 출력, WebChat 관리 미디어 트랜스크립트 보충이 이에 해당합니다.
chat.history는 저장된 세션 트랜스크립트를 읽고 WebChat 표시 프로젝션을 적용합니다. 실행 중 라이브 어시스턴트 텍스트가 나타났지만 히스토리 다시 로드 후 사라지는 경우, 먼저 원시 JSONL에 어시스턴트 텍스트가 포함되어 있는지 확인한 다음 chat.history 프로젝션이 이를 제거했는지 확인하고, 그다음 Control UI 낙관적 꼬리 병합이 로컬 전달 상태를 지속된 스냅샷으로 대체했는지 확인합니다.
chat.message.get은 활성 에이전트 스코핑을 포함하여 chat.history와 동일한 트랜스크립트 브랜치 및 표시 프로젝션 규칙을 사용하지만, messageId로 하나의 트랜스크립트 항목을 대상으로 하며 전체 콘텐츠를 더 이상 반환할 수 없을 때 솔직한 사용 불가 이유를 반환합니다.

일반 에이전트 실행 최종 답변은 임베디드 런타임이 어시스턴트 message_end를 쓰기 때문에 지속되어야 합니다. 전달된 최종 페이로드를 트랜스크립트로 미러링하는 모든 폴백은 먼저 임베디드 런타임이 이미 쓴 어시스턴트 턴을 중복하지 않아야 합니다.

Control UI 에이전트 도구 패널

Control UI /agents Tools 패널에는 두 개의 별도 뷰가 있습니다.
- 지금 사용 가능은 tools.effective(sessionKey=...)를 사용하며 core, Plugin, 채널 소유, 이미 발견된 MCP 서버 도구를 포함한 현재 세션 인벤토리의 서버 파생 읽기 전용 프로젝션을 표시합니다.
- 도구 구성은 tools.catalog를 사용하며 프로필, 오버라이드, 카탈로그 의미 체계에 초점을 유지합니다.
런타임 가용성은 세션 범위입니다. 동일한 에이전트에서 세션을 전환하면 지금 사용 가능 목록이 변경될 수 있습니다. 구성된 MCP 서버가 아직 연결되지 않았거나 마지막 발견 이후 변경된 경우, 패널은 읽기 경로에서 MCP 전송을 조용히 시작하는 대신 알림을 표시합니다.
구성 편집기는 런타임 가용성을 의미하지 않습니다. 유효 접근은 여전히 정책 우선순위(allow/deny, 에이전트별 및 provider/channel 오버라이드)를 따릅니다.

원격 사용

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

구성 참조(WebChat)

전체 구성: 구성

WebChat에는 지속되는 구성 섹션이 없습니다. Gateway는 내장 chat.history 표시 제한을 사용합니다. API 클라이언트는 요청별 maxChars를 보내 단일 chat.history 호출에 대해 이를 재정의할 수 있습니다. 레거시 channels.webchat 및 gateway.webchat 구성은 폐기되었습니다. openclaw doctor --fix를 실행하여 제거하세요.