제어 UI

• Gateway WS를 통해 모델과 채팅합니다(chat.history, chat.send, chat.abort, chat.inject).
• 채팅 기록 새로 고침은 메시지별 텍스트 한도가 있는 제한된 최근 창을 요청하므로, 큰 세션이 채팅을 사용할 수 있게 되기 전에 브라우저가 전체 대화 기록 페이로드를 렌더링하도록 강제하지 않습니다.
• 브라우저 실시간 세션을 통해 대화합니다. OpenAI는 직접 WebRTC를 사용하고, Google Live는 WebSocket을 통한 제한된 일회용 브라우저 토큰을 사용하며, 백엔드 전용 실시간 음성 Plugin은 Gateway 릴레이 전송을 사용합니다. 클라이언트 소유 제공자 세션은 talk.client.create로 시작하고, Gateway 릴레이 세션은 talk.session.create로 시작합니다. 릴레이는 제공자 자격 증명을 Gateway에 보관하는 동안 브라우저는 talk.session.appendAudio를 통해 마이크 PCM을 스트리밍하고, Gateway 정책 및 더 크게 구성된 OpenClaw 모델을 위해 openclaw_agent_consult 제공자 도구 호출을 talk.client.toolCall을 통해 전달합니다.
• 채팅에서 도구 호출과 실시간 도구 출력 카드를 스트리밍합니다(에이전트 이벤트).

• 채널: 내장 채널과 번들/외부 Plugin 채널 상태, QR 로그인, 채널별 구성(channels.status, web.login.*, config.patch).
• 채널 프로브 새로 고침은 느린 제공자 검사가 끝나는 동안 이전 스냅샷을 계속 표시하고, 프로브나 감사가 UI 예산을 초과하면 부분 스냅샷에 레이블을 붙입니다.
• 인스턴스: 존재 목록과 새로 고침(system-presence).
• 세션: 기본적으로 구성된 에이전트 세션을 나열하고, 오래된 미구성 에이전트 세션 키에서 폴백하며, 세션별 모델/사고/빠름/상세/추적/추론 재정의를 적용합니다(sessions.list, sessions.patch).
• 꿈: Dreaming 상태, 활성화/비활성화 토글, Dream Diary 리더(doctor.memory.status, doctor.memory.dreamDiary, config.patch).

• Cron 작업: 나열/추가/편집/실행/활성화/비활성화 및 실행 기록(cron.*).
• Skills: 상태, 활성화/비활성화, 설치, API 키 업데이트(skills.*).
• Node: 나열 및 기능(node.list).
• 실행 승인: Gateway 또는 Node 허용 목록 편집 및 exec host=gateway/node에 대한 요청 정책(exec.approvals.*).

• ~/.openclaw/openclaw.json 보기/편집(config.get, config.set).
• 검증과 함께 적용 및 재시작(config.apply)하고 마지막 활성 세션을 깨웁니다.
• 쓰기에는 동시 편집 덮어쓰기를 방지하기 위한 기본 해시 가드가 포함됩니다.
• 쓰기(config.set/config.apply/config.patch)는 제출된 구성 페이로드의 참조에 대해 활성 SecretRef 확인을 사전 검사합니다. 확인되지 않은 활성 제출 참조는 쓰기 전에 거부됩니다.
• 스키마와 양식 렌더링(config.schema / config.schema.lookup, 필드 title / description, 일치하는 UI 힌트, 직계 하위 요약, 중첩 객체/와일드카드/배열/컴포지션 노드의 문서 메타데이터, 사용 가능한 경우 Plugin 및 채널 스키마 포함). Raw JSON 편집기는 스냅샷이 안전한 원시 왕복을 지원할 때만 사용할 수 있습니다.
• 스냅샷이 원시 텍스트를 안전하게 왕복할 수 없으면 Control UI는 양식 모드를 강제하고 해당 스냅샷의 Raw 모드를 비활성화합니다.
• Raw JSON 편집기의 "저장된 값으로 재설정"은 평탄화된 스냅샷을 다시 렌더링하는 대신 원시로 작성된 형태(서식, 주석, $include 레이아웃)를 보존하므로, 스냅샷이 안전하게 왕복할 수 있을 때 외부 편집 내용이 재설정 후에도 유지됩니다.
• 구조화된 SecretRef 객체 값은 실수로 객체가 문자열로 손상되는 것을 방지하기 위해 양식 텍스트 입력에서 읽기 전용으로 렌더링됩니다.

• 디버그: 상태/상태 점검/모델 스냅샷, 이벤트 로그, 수동 RPC 호출(status, health, models.list).
• 이벤트 로그에는 Control UI 새로 고침/RPC 타이밍, 느린 채팅/구성 렌더링 타이밍, 브라우저가 해당 PerformanceObserver 항목 유형을 노출할 때 긴 애니메이션 프레임 또는 긴 작업에 대한 브라우저 응답성 항목이 포함됩니다.
• 로그: 필터/내보내기가 있는 Gateway 파일 로그 실시간 tail(logs.tail).
• 업데이트: 재시작 보고서와 함께 패키지/git 업데이트 및 재시작을 실행(update.run)한 다음, 재연결 후 update.status를 폴링하여 실행 중인 Gateway 버전을 확인합니다.

• 격리된 작업의 경우 전달 기본값은 요약 알림입니다. 내부 전용 실행을 원하면 없음으로 전환할 수 있습니다.
• 알림이 선택되면 채널/대상 필드가 표시됩니다.
• Webhook 모드는 delivery.mode = "webhook"을 사용하고 delivery.to는 유효한 HTTP(S) Webhook URL로 설정합니다.
• 메인 세션 작업의 경우 Webhook 및 없음 전달 모드를 사용할 수 있습니다.
• 고급 편집 컨트롤에는 실행 후 삭제, 에이전트 재정의 지우기, Cron exact/stagger 옵션, 에이전트 모델/사고 재정의, 최선 노력 전달 토글이 포함됩니다.
• 양식 검증은 필드 수준 오류와 함께 인라인으로 표시됩니다. 잘못된 값은 수정될 때까지 저장 버튼을 비활성화합니다.
• 전용 bearer 토큰을 보내려면 cron.webhookToken을 설정하세요. 생략하면 Webhook은 인증 헤더 없이 전송됩니다.
• 사용 중단된 폴백: notify: true가 있는 저장된 레거시 작업은 마이그레이션될 때까지 계속 cron.webhook을 사용할 수 있습니다.

• chat.send는 논블로킹입니다. 즉시 { runId, status: "started" }로 확인 응답을 반환하고 응답은 chat 이벤트를 통해 스트리밍됩니다.
• 채팅 업로드는 이미지와 비디오가 아닌 파일을 허용합니다. 이미지는 네이티브 이미지 경로를 유지하고, 그 밖의 파일은 관리형 미디어로 저장되어 기록에 첨부 파일 링크로 표시됩니다.
• 동일한 idempotencyKey로 다시 보내면 실행 중에는 { status: "in_flight" }를 반환하고, 완료 후에는 { status: "ok" }를 반환합니다.
• chat.history 응답은 UI 안전을 위해 크기가 제한됩니다. 트랜스크립트 항목이 너무 크면 Gateway가 긴 텍스트 필드를 잘라내고, 무거운 메타데이터 블록을 생략하며, 지나치게 큰 메시지를 자리 표시자([chat.history omitted: message too large])로 대체할 수 있습니다.
• 어시스턴트/생성 이미지는 관리형 미디어 참조로 유지되고 인증된 Gateway 미디어 URL을 통해 다시 제공되므로, 새로고침은 원시 base64 이미지 페이로드가 채팅 기록 응답에 계속 남아 있는 것에 의존하지 않습니다.
• chat.history를 렌더링할 때 Control UI는 표시 전용 인라인 지시문 태그(예: [[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 또는 Heartbeat 확인 토큰 HEARTBEAT_OK뿐인 어시스턴트 항목을 생략합니다.
• 활성 전송 중과 최종 기록 새로고침 중에 chat.history가 잠시 오래된 스냅샷을 반환하더라도 채팅 보기는 로컬의 낙관적 사용자/어시스턴트 메시지를 계속 표시합니다. Gateway 기록이 따라잡으면 정식 트랜스크립트가 해당 로컬 메시지를 대체합니다.
• 실시간 chat 이벤트는 전달 상태이고, chat.history는 영구 세션 트랜스크립트에서 다시 빌드됩니다. 도구 최종 이벤트 후 Control UI는 기록을 다시 로드하고 작은 낙관적 꼬리만 병합합니다. 트랜스크립트 경계는 WebChat에 문서화되어 있습니다.
• chat.inject는 어시스턴트 노트를 세션 트랜스크립트에 추가하고 UI 전용 업데이트를 위한 chat 이벤트를 브로드캐스트합니다(에이전트 실행 없음, 채널 전달 없음).
• 채팅 헤더는 세션 선택기 앞에 에이전트 필터를 표시하고, 세션 선택기는 선택된 에이전트 범위로 제한됩니다. 에이전트를 전환하면 해당 에이전트에 연결된 세션만 표시되며, 아직 저장된 대시보드 세션이 없으면 해당 에이전트의 기본 세션으로 대체됩니다.
• 데스크톱 너비에서는 채팅 컨트롤이 하나의 컴팩트한 행에 유지되며 트랜스크립트를 아래로 스크롤하는 동안 접힙니다. 위로 스크롤하거나, 맨 위로 돌아가거나, 맨 아래에 도달하면 컨트롤이 복원됩니다.
• 연속된 중복 텍스트 전용 메시지는 개수 배지가 있는 하나의 말풍선으로 렌더링됩니다. 이미지, 첨부 파일, 도구 출력 또는 캔버스 미리보기가 포함된 메시지는 접히지 않은 상태로 유지됩니다.
• 채팅 헤더의 모델 및 thinking 선택기는 sessions.patch를 통해 활성 세션을 즉시 패치합니다. 이는 한 턴 전용 전송 옵션이 아니라 지속되는 세션 오버라이드입니다.
• Control UI에서 /new를 입력하면 New Chat과 동일한 새 대시보드 세션이 생성되고 전환됩니다. /reset을 입력하면 현재 세션에 대해 Gateway의 명시적 제자리 재설정이 유지됩니다.
• 채팅 모델 선택기는 Gateway의 구성된 모델 보기를 요청합니다. agents.defaults.models가 있으면 해당 허용 목록이 선택기를 구동합니다. 그렇지 않으면 선택기에 명시적인 models.providers.*.models 항목과 사용 가능한 인증이 있는 공급자가 표시됩니다. 전체 카탈로그는 디버그 models.list RPC에서 view: "all"을 통해 계속 사용할 수 있습니다.
• 새 Gateway 세션 사용량 보고서에 현재 컨텍스트 토큰이 포함되면 채팅 작성 영역에 컴팩트한 컨텍스트 사용량 표시기가 표시됩니다. 컨텍스트 압박이 높으면 경고 스타일로 전환되고, 권장 Compaction 수준에서는 일반 세션 Compaction 경로를 실행하는 컴팩트한 버튼이 표시됩니다. 오래된 토큰 스냅샷은 Gateway가 새 사용량을 다시 보고할 때까지 숨겨집니다.

Talk 모드는 등록된 실시간 음성 공급자를 사용합니다. OpenAI는 talk.realtime.provider: "openai"와 talk.realtime.providers.openai.apiKey로 구성하거나, Google은 talk.realtime.provider: "google"과 talk.realtime.providers.google.apiKey로 구성하세요. 브라우저는 표준 공급자 API 키를 절대 받지 않습니다. OpenAI는 WebRTC용 임시 Realtime 클라이언트 비밀 값을 받습니다. Google Live는 브라우저 WebSocket 세션을 위한 1회용 제한 Live API 인증 토큰을 받으며, 지침과 도구 선언은 Gateway에 의해 토큰 안에 잠깁니다. 백엔드 실시간 브리지만 노출하는 공급자는 Gateway 릴레이 전송을 통해 실행되므로, 브라우저 오디오는 인증된 Gateway RPC를 통해 이동하는 동안 자격 증명과 벤더 소켓은 서버 측에 유지됩니다. Realtime 세션 프롬프트는 Gateway가 조합합니다. talk.client.create는 호출자가 제공한 지침 오버라이드를 허용하지 않습니다.

Chat 작성기에서 Talk 컨트롤은 마이크 받아쓰기 버튼 옆의 파형 버튼입니다. Talk가 시작되면 작성기 상태 행에 Connecting Talk...가 표시되고, 오디오가 연결되면 Talk live, 실시간 도구 호출이 talk.client.toolCall을 통해 구성된 더 큰 모델에 문의하는 동안에는 Asking OpenClaw...가 표시됩니다.

메인터이너 라이브 스모크: OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts는 OpenAI 브라우저 WebRTC SDP 교환, Google Live 제한 토큰 브라우저 WebSocket 설정, 가짜 마이크 미디어를 사용하는 Gateway 릴레이 브라우저 어댑터를 검증합니다. 이 명령은 공급자 상태만 출력하며 비밀 값을 로그로 남기지 않습니다.

• Stop을 클릭합니다(chat.abort 호출).
• 실행이 활성 상태인 동안 일반 후속 메시지는 대기열에 들어갑니다. 대기 중인 메시지에서 Steer를 클릭하면 해당 후속 메시지를 실행 중인 턴에 주입합니다.
• 대역 외로 중단하려면 /stop을 입력합니다(또는 stop, stop action, stop run, stop openclaw, please stop 같은 독립 실행형 중단 문구).
• chat.abort는 해당 세션의 모든 활성 실행을 중단하기 위해 { sessionKey }(runId 없음)를 지원합니다.

• 실행이 중단되면 부분 어시스턴트 텍스트가 UI에 계속 표시될 수 있습니다.
• Gateway는 버퍼링된 출력이 있는 경우 중단된 부분 어시스턴트 텍스트를 트랜스크립트 기록에 유지합니다.
• 유지된 항목에는 중단 메타데이터가 포함되어 트랜스크립트 소비자가 중단 부분 출력과 정상 완료 출력을 구분할 수 있습니다.

{
  gateway: {
    controlUi: { allowInsecureAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

allowInsecureAuth는 로컬 호환성 토글일 뿐입니다.

• 안전하지 않은 HTTP 컨텍스트에서 localhost Control UI 세션이 기기 ID 없이 진행되도록 허용합니다.
• 페어링 검사를 우회하지 않습니다.
• 원격(localhost가 아닌) 기기 ID 요구 사항을 완화하지 않습니다.

{
  gateway: {
    controlUi: { dangerouslyDisableDeviceAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

• 성공적인 신뢰할 수 있는 프록시 인증은 기기 ID 없이 운영자 Control UI 세션을 허용할 수 있습니다.
• 이는 노드 역할 Control UI 세션에는 확장 적용되지 않습니다.
• 동일 호스트 local loopback 역방향 프록시는 여전히 신뢰할 수 있는 프록시 인증을 충족하지 않습니다. 신뢰할 수 있는 프록시 인증을 참조하세요.

• gatewayUrl은 로드 후 localStorage에 저장되고 URL에서 제거됩니다.
• gatewayUrl을 통해 전체 ws:// 또는 wss:// 엔드포인트를 전달하는 경우 브라우저가 쿼리 문자열을 올바르게 파싱하도록 gatewayUrl 값을 URL 인코딩하세요.
• 가능하면 token은 URL 프래그먼트(#token=...)를 통해 전달해야 합니다. 프래그먼트는 서버로 전송되지 않으므로 요청 로그와 Referer 유출을 피할 수 있습니다. 레거시 ?token= 쿼리 매개변수는 호환성을 위해 여전히 한 번 가져오지만, 대체 수단으로만 사용되며 bootstrap 직후 즉시 제거됩니다.
• password는 메모리에만 보관됩니다.
• gatewayUrl이 설정되면 UI는 구성이나 환경 자격 증명으로 대체하지 않습니다. token(또는 password)을 명시적으로 제공하세요. 명시적 자격 증명이 없으면 오류입니다.
• Gateway가 TLS(Tailscale Serve, HTTPS 프록시 등) 뒤에 있는 경우 wss://를 사용하세요.
• 클릭재킹을 방지하기 위해 gatewayUrl은 최상위 창(임베드되지 않음)에서만 허용됩니다.
• non-loopback Control UI 배포는 gateway.controlUi.allowedOrigins를 명시적으로 설정해야 합니다(전체 출처). 여기에는 원격 dev 설정도 포함됩니다.
• Gateway 시작 시 유효한 런타임 바인드와 포트에서 http://localhost:<port> 및 http://127.0.0.1:<port> 같은 로컬 출처를 시드할 수 있지만, 원격 브라우저 출처에는 여전히 명시적 항목이 필요합니다.
• 엄격하게 제어되는 로컬 테스트를 제외하고는 gateway.controlUi.allowedOrigins: ["*"]를 사용하지 마세요. 이는 "내가 사용 중인 호스트와 일치"가 아니라 모든 브라우저 출처를 허용한다는 의미입니다.
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true는 Host 헤더 출처 대체 모드를 활성화하지만, 이는 위험한 보안 모드입니다.