--- read_when: - 브라우저에서 Gateway를 운영하려는 경우 - SSH 터널 없이 Tailnet에 액세스하려는 경우 sidebarTitle: Control UI summary: Gateway용 브라우저 기반 제어 UI(채팅, 활동, 노드, 구성) title: 제어 UI x-i18n: generated_at: "2026-07-12T21:33:15Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 15 provider: openai source_hash: b1da56979bd134ce0be8ab0a2fbee658952515db5e422fbe9eb685968de8a755 source_path: web/control-ui.md workflow: 16 --- Control UI는 Gateway에서 제공하는 소형 **Vite + Lit** 단일 페이지 앱입니다. - 기본값: `http://:18789/` - 선택적 접두사: `gateway.controlUi.basePath`를 설정합니다(예: `/openclaw`). 동일한 포트의 **Gateway WebSocket에 직접** 연결합니다. ## 빠르게 열기(로컬) Gateway가 동일한 컴퓨터에서 실행 중이면 [http://127.0.0.1:18789/](http://127.0.0.1:18789/)(또는 [http://localhost:18789/](http://localhost:18789/))을 여십시오. 페이지가 로드되지 않으면 먼저 Gateway를 시작하십시오. `openclaw gateway` 네이티브 Windows LAN 바인딩에서는 Gateway 호스트에서 `127.0.0.1`이 작동하더라도 Windows Firewall 또는 조직에서 관리하는 Group Policy가 공지된 LAN URL을 차단할 수 있습니다. Windows 호스트에서 `openclaw gateway status --deep`을 실행하십시오. 정책에서 무시할 수 있는 차단 가능성이 높은 포트, 프로필 불일치 및 로컬 방화벽 규칙을 보고합니다. 인증은 WebSocket 핸드셰이크 중에 다음을 통해 제공됩니다. - `connect.params.auth.token` - `connect.params.auth.password` - `gateway.auth.allowTailscale: true`인 경우 Tailscale Serve ID 헤더 - `gateway.auth.mode: "trusted-proxy"`인 경우 신뢰할 수 있는 프록시 ID 헤더 대시보드 설정 패널은 현재 브라우저 탭 세션과 선택한 Gateway URL에 대한 토큰을 유지하며, 비밀번호는 저장하지 않습니다. 온보딩은 일반적으로 첫 연결 시 공유 비밀 인증용 Gateway 토큰을 생성하지만, `gateway.auth.mode`가 `"password"`인 경우 비밀번호 인증도 사용할 수 있습니다. ## 기기 페어링(첫 연결) 새 브라우저나 기기에서 연결할 때는 일반적으로 **일회성 페어링 승인**이 필요하며, `disconnected (1008): pairing required`로 표시됩니다. ```bash openclaw devices list ``` ```bash openclaw devices approve ``` 브라우저가 변경된 인증 세부 정보(역할/범위/공개 키)로 페어링을 다시 시도하면 이전 대기 요청은 대체되고 새 `requestId`가 생성됩니다. 승인하기 전에 `openclaw devices list`를 다시 실행하십시오. 이미 페어링된 브라우저를 읽기 액세스에서 쓰기/관리자 액세스로 전환하면 자동 재연결이 아닌 승인 업그레이드로 처리됩니다. OpenClaw는 기존 승인을 활성 상태로 유지하고, 더 넓은 권한의 재연결을 차단하며, 새 범위 집합을 명시적으로 승인하도록 요청합니다. 승인된 기기는 기억되며, `openclaw devices revoke --device --role `로 해지하지 않는 한 다시 승인할 필요가 없습니다. 토큰 순환, 해지 및 Paperclip / `openclaw_gateway` 최초 실행 승인 흐름은 [기기 CLI](/ko/cli/devices)를 참조하십시오. - 직접 로컬 루프백 브라우저 연결(`127.0.0.1` / `localhost`)은 자동으로 승인됩니다. - `gateway.auth.allowTailscale: true`이고 Tailscale ID가 확인되며 브라우저가 기기 ID를 제시하면, Tailscale Serve는 Control UI 운영자 세션의 페어링 왕복 과정을 생략할 수 있습니다. 기기 ID가 없는 브라우저와 노드 역할 연결에는 여전히 일반적인 기기 검사가 적용됩니다. - 직접 Tailnet 바인딩, LAN 브라우저 연결 및 기기 ID가 없는 브라우저 프로필은 여전히 명시적 승인이 필요합니다. - 각 브라우저 프로필은 고유한 기기 ID를 생성하므로 브라우저를 전환하거나 브라우저 데이터를 삭제하면 다시 페어링해야 합니다. ## 모바일 기기 페어링 이미 페어링된 관리자는 터미널을 열지 않고 iOS/Android 연결 QR을 생성할 수 있습니다. **Devices**를 선택한 다음 **Devices** 카드에서 **Pair mobile device**를 클릭하십시오. OpenClaw 모바일 앱에서 **Settings** → **Gateway**를 열고 QR 코드를 스캔하십시오. 대신 설정 코드를 복사하여 붙여 넣을 수도 있습니다. 공식 iOS/Android 앱은 자동으로 연결됩니다. **Pending approval**에 요청이 표시되면 승인하기 전에 역할과 범위를 검토하십시오. 설정 코드를 생성하려면 `operator.admin`이 필요합니다. 이 권한이 없는 세션에서는 버튼이 비활성화됩니다. 설정 코드에는 수명이 짧은 부트스트랩 자격 증명이 포함되므로 유효한 동안 QR과 복사한 코드를 비밀번호처럼 취급하십시오. 원격 페어링의 경우 Gateway는 `wss://`로 확인되어야 합니다(예: Tailscale Serve/Funnel 사용). 일반 `ws://`는 루프백 및 사설 LAN 주소로 제한됩니다. 전체 보안 및 대체 방식에 대한 자세한 내용은 [페어링](/ko/channels/pairing#pair-from-the-control-ui-recommended)을 참조하십시오. ## 개인 ID(브라우저 로컬) Control UI는 공유 세션에서 출처를 표시할 수 있도록 발신 메시지에 첨부되는 브라우저별 개인 ID(표시 이름 및 아바타)를 지원합니다. 이 정보는 현재 브라우저 프로필로 범위가 지정된 브라우저 저장소에 있으며, 다른 기기와 동기화되지 않습니다. 또한 전송한 메시지의 일반적인 대화 기록 작성자 메타데이터 외에는 서버 측에 저장되지 않습니다. 사이트 데이터를 삭제하거나 브라우저를 전환하면 빈 상태로 초기화됩니다. 어시스턴트 아바타 재정의도 동일한 브라우저 로컬 방식을 따릅니다. 업로드된 재정의는 Gateway에서 확인된 ID 위에 로컬로 적용되며 `config.patch`를 통해 왕복 전송되지 않습니다. 필드를 직접 작성하는 비 UI 클라이언트에서는 공유 `ui.assistant.avatar` 구성 필드를 계속 사용할 수 있습니다. ## 런타임 구성 엔드포인트 Control UI는 Gateway의 Control UI 기본 경로를 기준으로 확인되는 `/control-ui-config.json`에서 런타임 설정을 가져옵니다(예: 기본 경로 `/__openclaw__/`에서는 `/__openclaw__/control-ui-config.json`). 이 엔드포인트에는 나머지 HTTP 표면과 동일한 Gateway 인증이 적용됩니다. 인증되지 않은 브라우저에서는 가져올 수 없으며, 성공적으로 가져오려면 유효한 Gateway 토큰/비밀번호, Tailscale Serve ID 또는 신뢰할 수 있는 프록시 ID가 필요합니다. ## Gateway 호스트 상태 단순 보기에서 **Settings**를 열면 Gateway 컴퓨터, LAN 주소, 운영 체제, 런타임, 가동 시간, CPU 부하, 메모리 및 상태 볼륨 디스크 공간이 표시되는 **Gateway Host** 카드를 볼 수 있습니다. 카드는 표시되는 동안 `operator.read` 범위가 필요한 `system.info` Gateway RPC를 통해 10초마다 새로 고쳐집니다. 이전 Gateway 및 해당 범위가 없는 연결에서는 카드가 표시되지 않습니다. ## 언어 지원 Control UI는 처음 로드할 때 브라우저 로캘에 따라 자체적으로 현지화됩니다. 나중에 재정의하려면 **Settings -> General -> Language**를 여십시오(선택기는 Appearance 아래가 아니라 General 빠른 설정 카드에 있습니다). - 지원되는 로캘: `en`, `ar`, `de`, `es`, `fa`, `fr`, `hi`, `id`, `it`, `ja-JP`, `ko`, `nl`, `pl`, `pt-BR`, `ru`, `th`, `tr`, `uk`, `vi`, `zh-CN`, `zh-TW` - 영어 이외의 번역은 브라우저에서 지연 로드됩니다. - 선택한 로캘은 브라우저 저장소에 저장되어 이후 방문 시 재사용됩니다. - 누락된 번역 키는 영어로 대체됩니다. 문서 번역은 동일한 비영어 로캘 집합에 대해 생성되지만, 문서 사이트에 내장된 Mintlify 언어 선택기에는 Mintlify가 허용하는 로캘 코드만 표시됩니다. 태국어(`th`) 및 페르시아어(`fa`) 문서도 게시 저장소에 생성되지만, Mintlify가 해당 코드를 지원할 때까지 선택기에 표시되지 않을 수 있습니다. ## 모양 테마 Appearance 패널에는 기본 제공 Claw, Knot 및 Dash 테마(기본값은 Claw)와 브라우저 로컬 tweakcn 가져오기 슬롯 하나가 있습니다. 테마를 가져오려면 [tweakcn 편집기](https://tweakcn.com/editor/theme)를 열고 테마를 선택하거나 만든 후 **Share**를 클릭하고 복사한 링크를 Appearance에 붙여 넣으십시오. 가져오기 도구는 `https://tweakcn.com/r/themes/` 레지스트리 URL, `https://tweakcn.com/editor/theme?theme=amethyst-haze`와 같은 편집기 URL, 상대 `/themes/` 경로, 원시 테마 ID 및 `amethyst-haze`와 같은 기본 테마 이름도 허용합니다. 가져온 테마는 현재 브라우저 프로필에만 저장되며 Gateway 구성에 기록되지 않고 기기 간에 동기화되지 않습니다. 가져온 테마를 교체하면 하나의 로컬 슬롯이 업데이트됩니다. 가져온 테마가 활성 상태일 때 삭제하면 Claw로 다시 전환됩니다. Appearance에는 나머지 Control UI 환경설정과 함께 저장되는 브라우저 로컬 Text size 설정도 있습니다. 채팅 텍스트, 작성기 텍스트, 도구 카드 및 채팅 사이드바에 적용되며, 모바일 Safari에서 포커스 시 자동 확대되지 않도록 텍스트 입력 크기를 최소 16px로 유지합니다. ## Plugin 관리 사이드바에서 **Plugins**를 열거나 구성된 Control UI 기본 경로를 기준으로 `/settings/plugins`를 사용하여 Control UI를 벗어나지 않고 Plugin을 탐색하고 관리할 수 있습니다. 예를 들어 기본 경로가 `/openclaw`이면 `/openclaw/settings/plugins`를 사용합니다. 모든 선택적 Plugin이 비활성화되어 있어도 이 페이지는 항상 사용할 수 있습니다. Plugins는 4개의 탭으로 구성된 허브입니다. **Installed** 및 **Discover**는 `/settings/plugins`에서 Plugin 코드를 관리하고, **Skills**는 `/skills`에서 에이전트별 스킬 관리자를 호스팅하며, **Workshop**은 `/skills/workshop`에서 Skill Workshop 제안 검토를 호스팅합니다. 각 탭은 자체 URL을 유지하며 사이드바에는 모든 탭을 위한 단일 Plugins 항목이 표시됩니다. **Installed** 탭에는 개요 개수와 함께 범주별로 그룹화된 전체 로컬 인벤토리가 표시됩니다. 각 행을 열면 상세 보기가 표시됩니다. 오버플로(`…`) 메뉴에서 Plugin을 활성화 또는 비활성화할 수 있으며 외부에서 설치된 Plugin에는 **Remove** 옵션이 제공됩니다. 또한 구성된 [MCP 서버](/ko/cli/mcp)를 나열하고 인라인으로 추가, 비활성화 및 제거할 수 있습니다. **Discover** 탭은 스토어입니다. OpenClaw에 포함된 추천 Plugin, 공식 외부 Plugin 및 인기 서비스를 위한 원클릭 MCP 커넥터를 제공합니다. 검색 상자에 입력하면 [ClawHub](https://clawhub.ai/plugins)를 인라인으로 검색하고 다운로드 횟수 및 소스 확인 배지가 포함된 **From ClawHub** 섹션을 추가합니다. 딥 링크는 `/settings/plugins?tab=discover`를 사용하여 스토어로 직접 이동할 수 있습니다. **Skills** 탭은 선택한 에이전트 범위에서 스킬 상태 보고서, 활성화/비활성화 토글, API 키 입력 및 인라인 ClawHub 스킬 검색을 유지합니다. **Workshop** 탭은 [스킬 제안](/ko/tools/skill-workshop)을 위한 Skill Workshop 보드 및 Today 검토 흐름을 유지합니다. 포함된 Plugin은 이미 Gateway에 존재하며 **Install** 대신 **Enable** 또는 **Disable**이 표시됩니다. 예를 들어 Workboard는 OpenClaw에 포함되어 있지만 기본적으로 비활성화되어 있으므로 해당 작업은 **Enable**입니다. 번들 Plugin은 제거할 수 없으며 비활성화만 할 수 있습니다. 카탈로그 읽기 및 ClawHub 검색에는 `operator.read`가 필요합니다. Plugin을 설치, 활성화, 비활성화 또는 제거하거나 MCP 서버를 변경하려면 `operator.admin`이 필요합니다. 읽기 전용 운영자에게는 이러한 작업이 비활성화된 상태로 유지됩니다. ClawHub 설치는 Gateway를 통해 실행되며 다른 Gateway 중개 설치와 동일한 신뢰, 무결성 및 Plugin 설치 정책 검사를 유지합니다. Plugin 코드를 설치하거나 제거하려면 Gateway를 다시 시작해야 합니다. 설치된 Plugin의 활성화 또는 비활성화는 Plugin과 현재 Gateway 런타임이 지원하는 경우 재시작 없이 적용할 수 있습니다. 그렇지 않으면 UI에서 재시작이 필요하다고 알립니다. OAuth 기반 MCP 커넥터는 추가한 후 CLI에서 일회성 `openclaw mcp login `을 실행해야 합니다. 이 페이지는 의도적으로 인벤토리, 검색, 설치, 활성화 및 제거에 중점을 둡니다. 임의의 npm, git 또는 로컬 경로 소스, 업데이트 및 고급 Plugin 구성에는 [`openclaw plugins`](/ko/cli/plugins)를 사용하십시오. ## 사이드바 탐색 사이드바는 스크롤 가능한 세션 목록 위에 탐색 메뉴를 고정합니다. 다중 에이전트 구성에서는 모든 에이전트가 접을 수 있는 최상위 섹션으로 표시됩니다. 에이전트를 펼치면 열려 있는 채팅에서 벗어나지 않고 해당 세션을 탐색할 수 있으며, 접힌 에이전트에는 읽지 않음 표시가 나타납니다. 에이전트 내에서 목록은 **고정됨**, 연결된 채널(Telegram, Slack, WhatsApp, ...)별 기본 제공 섹션, 관리형 워크트리 또는 실행 Node에 바인딩된 세션을 위한 기본 제공 **작업** 섹션(행에는 `repo ⎇ branch` 줄과 Node 호스트가 표시됨), 사용자 지정 그룹(세션 `category`), 나머지를 위한 **채팅**으로 나뉩니다. 채널 및 작업 섹션은 행을 자동으로 분류하지만, 세션을 사용자 지정 그룹에 할당하면 항상 이 분류보다 우선합니다. 세션을 열면 행 순서를 변경하지 않고 선택 강조 표시만 이동합니다. 마지막으로 읽은 이후 새 활동이 있는 세션에는 읽지 않음 점이 표시되며, 세션을 열면 읽음으로 표시됩니다. 각 세션 행에는 고정/고정 해제, 읽지 않음/읽음으로 표시, 이름 변경, 포크, 그룹으로 이동(새 그룹 및 그룹에서 제거 포함), 보관, 삭제 항목이 있는 컨텍스트 메뉴(케밥 버튼 또는 오른쪽 클릭)가 있습니다. 터치 레이아웃에서는 직접 고정 및 메뉴 컨트롤이 계속 표시됩니다. Cmd/Ctrl-클릭하면 행의 다중 선택 상태가 전환되고, Shift-클릭하면 표시된 순서에 따라 선택 범위가 확장됩니다. 이후 선택된 행에서 메뉴를 열면 선택된 모든 세션에 적용되는 일괄 작업(N개를 읽지 않음/읽음으로 표시, N개를 그룹으로 이동, N개 보관, N개 삭제)이 제공되며, 일괄 삭제에는 한 번만 확인을 요청합니다. 세션을 사용자 지정 그룹이나 **채팅**으로 끌어 이동할 수 있습니다. 사용자 지정 그룹 헤더는 접거나 펼칠 수 있으며, 끌어서 순서를 변경할 수도 있습니다. 그룹 이름과 순서는 gateway(`sessions.groups.*`)에 저장되므로 브라우저를 바꾸어도 유지되지만, 접힘 상태는 브라우저 프로필에 저장됩니다. 그룹 헤더에도 그룹 이름 변경, 새 그룹, 그룹 삭제 항목이 있는 메뉴(케밥 버튼 또는 오른쪽 클릭)가 있습니다. 그룹의 이름을 변경하거나 그룹을 삭제하면 보관된 세션을 포함한 모든 구성원 세션이 서버 측에서 업데이트되며, 그룹을 삭제해도 세션은 유지되고 채팅으로 다시 이동합니다. 세션 목록 헤더의 유일한 **+**는 새 세션 페이지를 엽니다(아래 참조). 정렬 컨트롤에는 그룹화 전환 옵션도 있습니다. 그룹화(기본값) 또는 없음 중에서 선택하여 하나의 평면 목록으로 표시할 수 있으며(**고정됨**은 계속 별도로 유지됨), 선택 사항은 현재 브라우저 프로필에 저장됩니다. **사용량**, **자동화**, **Plugins**는 기본적으로 고정되어 있습니다. **더 보기**를 펼치면 다른 모든 대상으로 이동할 수 있습니다. 더 보기 아래에서 **고정 항목 편집**을 선택하거나 탐색 영역을 오른쪽 클릭하여 대상을 고정 또는 고정 해제하고 기본값을 복원할 수 있습니다. 고정 항목 집합과 더 보기의 펼침 상태는 현재 브라우저 프로필에 저장되며 새로고침 후에도 유지됩니다. ## 새 세션 페이지 사이드바 세션 목록 헤더의 **+**는 `/new`에서 전체 페이지 초안을 엽니다. 첫 번째 메시지를 보낼 때까지는 아무것도 생성되지 않습니다. 메시지 상자 위의 대상 행에서 세션이 작업할 위치를 선택합니다. 에이전트(다중 에이전트 구성), 실행이 수행되는 위치(**Gateway · 로컬** 또는 `system.run`을 노출하는 페어링된 Node, `operator.admin` 필요), 폴더(기본값은 에이전트 작업 공간이며, 다른 절대 Gateway 경로에는 `operator.admin`과 워크트리가 필요함), 선택적 **워크트리** 전환 옵션과 기본 브랜치 선택기(`worktrees.branches`에서 제공되므로 가져오기가 발생하지 않음), 선택적 워크트리 이름(브랜치는 `openclaw/`이 됨)을 지정할 수 있습니다. 폴더 칩의 찾아보기 버튼은 관리자 전용 `fs.listDir` 메서드가 지원하는 인라인 디렉터리 선택기를 엽니다. 최상위 수준에는 Gateway와 알려진 모든 Node가 표시됩니다. 오프라인 Node와 디렉터리 탐색을 지원하지 않는 Node도 계속 표시되지만 비활성화됩니다. Gateway를 선택하면 현재 폴더 또는 Gateway 홈에서 시작합니다. 해당 기능을 지원하는 Node를 선택하면 그 Node의 호스트 파일 시스템을 탐색하고 실행을 해당 Node에 바인딩하며, 선택한 절대 Node 경로를 직접 사용합니다(관리형 워크트리는 계속 Gateway에서만 사용할 수 있음). 제출하면 첫 번째 메시지와 함께 `sessions.create`를 호출하므로 동일한 왕복 과정에서 실행이 시작되고 UI는 새 세션의 채팅으로 이동합니다. Gateway가 세션을 생성했지만 첫 번째 전송을 거부한 경우 채팅은 새로고침 후에도 프롬프트와 오류를 유지합니다. **재시도**를 누르면 다른 세션을 생성하는 대신 이미 생성된 세션을 통해 메시지를 전송합니다. **설정** 내부의 전용 사이드바는 설정 섹션을 빠르게 찾을 수 있는 **설정 검색** 필드로 시작합니다. 사이드바 상단의 **검색** 필드는 명령 팔레트(⌘K)를 엽니다. 사이드바 헤더에서 OpenClaw 브랜드를 클릭하면 비어 있는 새 세션 시작 화면이 열립니다. 실패했거나 기한이 지난 Cron 작업, 만료가 임박했거나 만료된 모델 인증처럼 조치가 필요한 항목이 있으면 사이드바 바닥글 위에 작은 주의 칩이 나타나며, 클릭하면 해당 항목을 관리하는 페이지로 이동합니다. 작은 바닥글에는 연결 상태, **설정**, **문서**, 모바일 페어링, 밝게/어둡게/시스템 색상 모드 전환 옵션이 함께 배치됩니다. gateway가 `main` 이외의 브랜치에 있는 소스 체크아웃에서 실행되는 경우에는 바닥글에 해당 브랜치 이름도 빨간색으로 표시되어 릴리스가 아닌 gateway임을 한눈에 알 수 있습니다(릴리스 설치에서는 절대 표시되지 않음). Shift-Command-Comma를 누르면 브라우저의 Command-Comma 단축키를 재정의하지 않고 **설정**을 엽니다. 사이드바 헤더에는 접기 전환 옵션(⌘B)도 있습니다. 사이드바를 접으면 전체 너비 작업 공간을 사용할 수 있도록 완전히 숨겨지며, 떠 있는 펼치기 컨트롤이나 ⌘B를 사용하면 다시 표시됩니다. macOS 앱에서는 이 전환 옵션을 제목 표시줄에 네이티브 방식으로 배치합니다. 데스크톱에서는 사이드바가 유일한 탐색 UI이며 상단 표시줄은 없습니다. 좁은 뷰포트에서는 사이드바가 서랍 전환 옵션, 브랜드, 명령 팔레트 검색이 포함된 작은 헤더 행 뒤의 슬라이드 오버 서랍으로 바뀝니다. macOS 앱에서는 해당 헤더 행이 제목 표시줄의 여백을 창 컨트롤 옆에 있는 하나의 작은 스트립으로 통합합니다. 탐색에는 일반 브라우저 기록을 사용하므로 브라우저의 뒤로/앞으로 버튼으로 기록을 이동할 수 있습니다. macOS 앱에는 창 컨트롤 옆에 네이티브 사이드바 전환 옵션과 트랙패드 쓸기 제스처가 추가되며, 사이드바가 펼쳐져 있을 때는 오른쪽 가장자리에 뒤로/앞으로 버튼이, 접혀 있을 때는 네이티브 검색(명령 팔레트) 및 새 세션 버튼이 표시됩니다. ## 현재 가능한 작업 - Gateway WS(`chat.history`, `chat.send`, `chat.abort`, `chat.inject`)를 통해 모델과 채팅합니다. - 채팅 기록을 새로고침할 때 메시지별 텍스트 제한이 적용된 한정된 최근 범위를 요청하므로, 대규모 세션에서도 채팅을 사용할 수 있게 되기 전에 브라우저가 전체 대화 기록 페이로드를 렌더링할 필요가 없습니다. - 공개 GitHub 이슈 또는 풀 리퀘스트 링크 위에 포인터를 올리거나 키보드로 포커스를 맞추면 상태, 제목, 작성자, 최근 활동, 댓글, 변경 통계를 표시합니다. 연결된 Gateway는 UI에서 원격 Gateway를 사용하는 경우를 포함해 링크 대상을 변경하지 않고 공개 메타데이터를 가져와 캐시합니다. Gateway는 먼저 저장소가 공개 상태인지 확인한 후 사용 가능한 경우 `GH_TOKEN` 또는 `GITHUB_TOKEN`을 사용합니다. 그렇지 않으면 더 긴 캐시 기간과 함께 GitHub의 익명 API를 사용합니다. - 브라우저 실시간 세션을 통해 대화합니다. 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`을 통해 전달하고, 활성 실행의 음성 조정은 `talk.client.steer` 또는 `talk.session.steer`를 통해 라우팅합니다. - 채팅에서 도구 호출과 실시간 도구 출력 카드를 스트리밍합니다(에이전트 이벤트). 도구 활동은 종류를 인식하는 행으로 렌더링됩니다. 셸 명령은 구문이 강조 표시된 명령과 터미널 스타일 출력을 표시하고, 지원되는 편집 및 쓰기 호출은 제한된 인라인 차이, 사용 가능한 경우 줄 번호, `+added -removed` 통계를 표시합니다. 연속 호출은 "명령 13개 실행, 파일 6개 읽음, 파일 9개 편집"과 같은 요약으로 접힙니다. 실행 중에는 가장 최근에 실행 중인 호출의 이름이 그룹 헤더에 표시됩니다. 행을 펼치면 나머지 인수와 원시 출력을 확인할 수 있습니다. - 복잡한 도구 호출(긴 셸 명령, 인수가 많은 Plugin 도구)을 위한 선택적 AI 목적 제목입니다. `gateway.controlUi.toolTitles: true`로 활성화할 수 있으며 기본값은 꺼짐입니다. 제목은 표준 유틸리티 모델 라우팅을 통해 일괄 처리되는 `chat.toolTitles` 메서드에서 가져옵니다. 다른 유틸리티 작업과 마찬가지로 운영자가 제공자를 선택한 명시적 `utilityModel`을 먼저 사용하고, 없으면 세션 제공자가 선언한 소형 모델 기본값을 사용하며, 에이전트별로 gateway 측에 캐시합니다. 이 선택적 기능이 꺼져 있거나 사용할 수 있는 저비용 모델이 없으면 행은 결정론적 레이블을 유지하며 모델 호출은 발생하지 않습니다. - 모델이 제안한 임시 후속 작업을 시작하거나 닫습니다. 수락된 제안은 제안된 프롬프트가 포함된 새로운 관리형 워크트리 세션을 엽니다. - 기존 `session.tool`/도구 이벤트 전달에서 가져온 실시간 도구 활동을 브라우저 로컬에서 우선 삭제 처리하여 요약하는 활동 탭입니다. - 채널: 기본 제공 채널과 번들/외부 Plugin 채널의 상태, QR 로그인, 채널별 구성(`channels.status`, `web.login.*`, `config.patch`)을 제공합니다. - 채널 검사 새로고침은 느린 제공자 검사가 완료될 때까지 이전 스냅샷을 계속 표시하며, 검사 또는 감사가 UI 시간 예산을 초과하면 부분 스냅샷임을 표시합니다. - 세션: 기본적으로 구성된 에이전트의 세션을 나열하고, 자주 사용하는 세션을 고정하고, 이름을 변경하고, 비활성 세션을 보관하거나 복원하고, 구성에서 제거된 에이전트의 오래된 세션 키를 대체 처리하며, 세션별 모델/사고/빠른 응답/상세 출력/추적/추론 재정의를 적용합니다(`sessions.list`, `sessions.patch`). 고정된 세션은 고정되지 않은 최근 세션보다 위에 정렬됩니다. 보관된 세션은 세션 페이지의 보관된 항목 보기에 표시되며 대화 기록이 유지됩니다. 마지막으로 읽은 이후 활동이 있는 세션의 행에는 읽지 않음 점과 읽지 않음/읽음으로 표시 작업(`sessions.patch { unread }`)이 표시되며, 대화 기록을 새 세션으로 분기하는 포크 작업(`sessions.create { parentSessionKey, fork: true }`)도 제공됩니다. 표 위의 개요 타일은 불러온 목록(세션 수, 실시간 실행, 읽지 않은 세션, 총 토큰)을 요약합니다. 각 행에는 종류 글리프와 실시간 실행 점이 표시되고, 상태는 일반 점과 레이블로 렌더링되며, 세션에서 토큰 및 컨텍스트 크기를 보고하면 토큰 열에 컨텍스트 창 사용량 측정기가 표시됩니다. 행 관리 작업은 사이드바의 세션 메뉴와 동일한 행별 메뉴(케밥 버튼 또는 오른쪽 클릭)에 있으며, 행 서랍에는 다른 세션 세부 정보와 함께 에이전트 런타임 및 실행 시간이 표시됩니다. - 세션 그룹화: 그룹화 기준 컨트롤은 사용자 지정 그룹, 채널, 종류, 에이전트 또는 날짜에 따라 세션 표를 섹션으로 구성합니다. 사용자 지정 그룹은 `sessions.patch`(`category`)를 통해 세션별로 유지되므로 메시지 채널(Discord, Telegram, WhatsApp, ...)에서 시작된 세션도 분류할 수 있습니다. 행을 섹션으로 끌거나 행별 그룹 선택기를 사용하여 그룹을 할당하고, 새 그룹 작업으로 그룹을 생성할 수 있습니다. - 메모리(에이전트 페이지의 탭이며 선택된 에이전트로 범위가 제한됨): Dreaming 상태, 활성화/비활성화 전환 옵션, 꿈 일기 리더(`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)를 제공합니다. - 자동화(Cron 작업): 자동화/실행 기록 탭 전환 위에 상태 카드(자동화 수, 실패 수, 스케줄러 상태, 다음 실행 시각)가 표시됩니다. 자동화 탭에는 필터링 가능한 표(전체/활성/일시 중지, 검색, 일정 및 마지막 실행 필터, 행별 작업 메뉴)로 작업이 나열되고 그 아래에 시작 제안이 표시되며, 실행 기록 탭에는 모든 자동화의 최근 실행이 표시됩니다(`cron.*`). - 작업: 연결된 세션과 취소 기능이 포함된, 현재 활성 상태 및 최근 백그라운드 작업의 실시간 원장입니다(`tasks.*`). - 플러그인: 설치된 항목과 선별된 스토어를 탐색하고, ClawHub를 검색하며, 플러그인 코드를 설치 및 제거하고, 설치된 플러그인을 활성화 또는 비활성화합니다(`plugins.*`). MCP 서버 행에서는 구성 메서드를 통해 `mcp.servers`를 편집합니다. - Skills: 상태 확인, 활성화/비활성화, 설치, API 키 업데이트를 수행합니다(`skills.*`). - 기기: 하나의 인벤토리에 페어링된 기기 레코드, Node 카탈로그, 실시간 접속 상태가 통합됩니다(`device.pair.list`, `node.list`, `system-presence`). Gateway 호스트는 맨 앞에 고정되며, 페어링된 클라이언트에는 연결 상태, 역할, 토큰, 기능, 명령이 표시됩니다. 중복 페어링은 펼칠 수 있는 그룹으로 축소되며, **오래된 항목 N개 정리**는 관리자가 확인한 오프라인 중복 항목 중 자동 승인된 항목(무음 로컬, 신뢰할 수 있는 CIDR 또는 SSH 검증)이나 승인 출처 기록보다 오래된 항목을 일괄 제거합니다. 항목을 제거할 수 있고(`node.pair.remove`, `device.pair.remove`), 기기 페어링 및 Node 재승인은 인라인으로 처리되며(`device.pair.*`, `node.pair.approve`/`reject`), 동일한 카드에서 모바일 설정 코드도 생성할 수 있습니다. - 실행 승인: `exec host=gateway/node`에 대한 Gateway 또는 Node 허용 목록과 확인 정책을 편집합니다(`exec.approvals.*`). - `~/.openclaw/openclaw.json`을 조회/편집합니다(`config.get`, `config.set`). - 프로필: 기본 에이전트의 ID와 전체 기간 사용량 통계(누적 토큰, 최고 사용일, 가장 긴 세션, 활동 연속 기록, 연간 토큰 히트맵, 가장 많이 사용한 도구, 채널 주요 정보)를 보여주는 설정 페이지입니다(`usage.cost`, `sessions.usage`). - MCP에는 읽기 전용 서버 행(전송 방식, 활성화 상태, OAuth/필터/병렬 처리 요약), 일반적인 운영자 명령, 범위가 지정된 `mcp` 구성 편집기가 포함된 전용 설정 페이지가 있습니다. 서버 추가, 활성화/비활성화, 제거는 플러그인 페이지에서 수행합니다. - 모델 제공자: 구성된 모든 모델 제공자의 브랜드 아이콘, 인증 상태(`models.authStatus`), 모델 가용성(`models.list`), 제공자가 보고하는 경우 실시간 요금제/할당량/결제 데이터(`usage.status`), 최근 30일간의 로컬 세션 지출(`sessions.usage`)을 나열하는 설정 페이지입니다. 새로 고침 작업은 자격 증명 상태와 제공자 사용량을 다시 읽습니다. - 연결: 대시보드 자체의 Gateway 연결(WebSocket URL, Gateway 토큰, 비밀번호, 기본 세션 키)과 최신 핸드셰이크 스냅샷(상태, 가동 시간, 틱 간격, 마지막 채널 새로 고침)을 관리하는 **연결** 아래의 설정 페이지입니다. 오프라인 로그인 관문은 연결이 끊긴 경우를 처리하며, 이 페이지에서는 연결된 상태에서 연결 설정을 편집합니다. - 유효성 검사와 함께 적용하고 재시작한 다음(`config.apply`), 마지막 활성 세션을 깨웁니다. - 쓰기에는 동시 편집 내용을 덮어쓰지 않도록 기본 해시 보호가 포함됩니다. - 쓰기(`config.set`/`config.apply`/`config.patch`)는 제출된 구성 페이로드의 참조에 대해 활성 SecretRef 해석을 사전 점검합니다. 제출된 활성 참조 중 해석되지 않은 항목은 쓰기 전에 거부됩니다. - 양식 저장 시 저장된 구성에서 복원할 수 없는 오래된 마스킹 자리표시자는 폐기하지만, 여전히 저장된 비밀에 매핑되는 마스킹된 값은 보존합니다. - 스키마 및 양식 렌더링은 `config.schema` / `config.schema.lookup`에서 가져옵니다. 여기에는 필드 `title`/`description`, 일치하는 UI 힌트, 바로 아래 자식 요약, 중첩된 객체/와일드카드/배열/컴포지션 노드의 문서 메타데이터와, 사용 가능한 경우 플러그인 및 채널 스키마가 포함됩니다. 원시 JSON 편집기는 스냅샷이 안전하게 원시 형식으로 왕복 변환될 수 있을 때만 사용할 수 있으며, 그렇지 않으면 Control UI가 양식 모드를 강제합니다. - 원시 JSON 편집기의 "저장된 상태로 재설정"은 평탄화된 스냅샷을 다시 렌더링하는 대신 원시 작성 형태(서식, 주석, `$include` 레이아웃)를 보존하므로, 스냅샷이 안전하게 왕복 변환될 수 있는 경우 재설정 후에도 외부 편집 내용이 유지됩니다. - 구조화된 SecretRef 객체 값은 양식의 텍스트 입력란에서 읽기 전용으로 렌더링되어, 실수로 객체가 문자열로 손상되는 것을 방지합니다. - 세션에서 파생된 토큰 및 예상 비용 분석은 제공자 결제와 별도로 유지됩니다. - 제공자 카드는 `usage.status`를 호출하고 구성된 제공자 플러그인이 보고하는 실시간 요금제 이름, 할당량 기간, 잔액, 지출, 예산을 표시합니다. - 제공자 사용량 조회 실패는 세션/비용 대시보드를 차단하지 않습니다. 사용할 수 없는 제공자 카드는 자체 오류 상태를 표시합니다. - 디버그: 상태/상태 점검/모델 스냅샷, 이벤트 로그, 수동 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 정확한 시각/분산 옵션, 에이전트 모델/사고 재정의, 최선형 전달 전환이 포함됩니다. - 양식 유효성 검사는 필드 수준 오류와 함께 인라인으로 수행되며, 잘못된 값이 있으면 수정할 때까지 저장 버튼이 비활성화됩니다. - 전용 베어러 토큰을 전송하려면 `cron.webhookToken`을 설정하십시오. 생략하면 인증 헤더 없이 Webhook이 전송됩니다. - `cron.webhook`은 더 이상 권장되지 않는 레거시 대체 경로입니다. 아직 `notify: true`를 사용하는 저장된 작업을 명시적인 작업별 Webhook 또는 완료 전달로 마이그레이션하려면 `openclaw doctor --fix`를 실행하십시오. ## MCP 페이지 전용 MCP 페이지는 `mcp.servers` 아래의 OpenClaw 관리 MCP 서버를 위한 운영자 보기입니다. 이 페이지 자체에서는 MCP 전송을 시작하지 않습니다. 저장된 구성을 검사하고 편집한 다음, 실시간 서버 증명이 필요할 때 `openclaw mcp doctor --probe`를 사용하십시오. 일반적인 워크플로: 1. 사이드바에서 **MCP**를 여십시오. 2. 요약 카드에서 전체, 활성화됨, OAuth, 필터링된 서버 수를 확인하십시오. 3. 각 서버 행에서 전송 방식, 활성화 상태, 인증, 필터, 제한 시간, 명령 힌트를 검토하십시오. 4. `mcp.servers`를 대화형으로 쓰는 유일한 페이지인 **플러그인** 페이지에서 서버를 관리(추가, 활성화/비활성화, 제거)하십시오. 여기의 행 목록은 해당 페이지로 연결됩니다. 5. 서버 정의, 헤더, TLS/mTLS 경로, OAuth 메타데이터, 도구 필터, Codex 프로젝션 메타데이터를 위한 범위가 지정된 `mcp` 구성 섹션을 편집하십시오. 6. 구성 쓰기에는 **저장**을 사용하고, 실행 중인 Gateway가 변경된 구성을 적용해야 할 때는 **저장 및 게시**를 사용하십시오. 7. 정적 진단, 실시간 증명 또는 캐시된 런타임 폐기를 위해 터미널에서 `openclaw mcp status --verbose`, `openclaw mcp doctor --probe` 또는 `openclaw mcp reload`를 실행하십시오. 이 페이지는 렌더링 전에 자격 증명이 포함된 URL 형태의 값을 마스킹하고, 명령 스니펫에서 서버 이름을 따옴표로 묶어 공백이나 셸 메타문자가 있어도 복사한 명령이 작동하도록 합니다. 전체 CLI 및 구성 참조: [MCP](/ko/cli/mcp). ## 활동 탭 활동 탭은 로그 및 디버그 옆의 **설정 › 시스템**에 있습니다. 이는 Chat 도구 카드를 구동하는 것과 동일한 Gateway `session.tool` / 도구 이벤트 스트림에서 파생된, 일시적인 브라우저 로컬 실시간 도구 활동 관찰기입니다. 별도의 Gateway 이벤트 계열, 엔드포인트, 영구 활동 저장소, 메트릭 피드 또는 외부 관찰자 스트림을 추가하지 않습니다. 활동 항목에는 정제된 요약과 마스킹 및 잘린 출력 미리보기만 유지됩니다. 도구 인수 값은 활동 상태에 저장되지 않습니다. UI는 인수가 숨겨져 있음을 표시하고 인수 필드 수만 기록합니다. 메모리 내 목록은 현재 브라우저 탭을 따르고 Control UI 내에서 페이지를 이동해도 유지되며, 페이지를 다시 로드하거나 세션을 전환하거나 **지우기**를 실행하면 초기화됩니다. ## 운영자 터미널 도킹 가능한 운영자 터미널은 기본적으로 비활성화되어 있습니다. 활성화하려면 `gateway.terminal.enabled: true`를 설정하고 Gateway를 재시작하십시오. 터미널에는 `operator.admin` 연결이 필요하며 활성 에이전트 작업 공간에서 호스트 PTY를 엽니다. 새 탭은 현재 선택된 채팅 에이전트를 따릅니다. 터미널은 제한되지 않은 호스트 셸이며 Gateway 프로세스 환경을 상속합니다. 신뢰할 수 있는 운영자 배포에서만 활성화하십시오. OpenClaw는 `sandbox.mode: "all"`인 에이전트의 터미널 세션을 거부합니다. 활성 에이전트를 해당 모드로 변경하면 기존 터미널 세션과 진행 중인 터미널 세션이 종료됩니다. **Ctrl + backtick**을 사용하여 도크를 전환하십시오. 레이아웃은 아래쪽 및 오른쪽 도킹을 지원하고 브라우저 뷰포트에 맞춰 크기가 조정되며 여러 셸 탭을 유지합니다. `gateway.terminal.enabled` 및 선택적 `gateway.terminal.shell` 재정의에 대해서는 [Gateway 구성](/ko/gateway/configuration-reference#gateway)을 참조하십시오. 세션은 연결이 끊겨도 유지됩니다. 페이지 새로 고침, 노트북 절전 또는 일시적인 네트워크 끊김이 발생하면 세션을 종료하는 대신 Gateway에서 분리하며, 동일한 브라우저 탭이 다시 연결될 때 최근 출력이 재생되면서 세션에 재연결됩니다. 분리된 세션은 `gateway.terminal.detachedSessionTimeoutSeconds` 후에 종료됩니다(기본값 300초. `0`은 연결 해제 시 종료를 복원합니다). `terminal.list`는 연결 가능한 세션을 표시하고, `terminal.attach`는 세션 하나를 인계하며(tmux 스타일 인계), `terminal.text`는 연결하지 않고 세션의 최근 출력을 일반 텍스트로 읽습니다. 이는 에이전트/도구를 위한 기능입니다. 터미널은 `/?view=terminal`에서 터미널 전용 전체 화면 문서로도 사용할 수 있습니다. iOS 및 Android 앱은 저장된 Gateway 자격 증명을 재사용하여 이 페이지를 터미널 화면에 삽입합니다. 사용 가능 여부에는 동일한 `gateway.terminal.enabled` 및 `operator.admin` 관문이 적용되며, 연결된 Gateway가 터미널을 제공하지 않으면 페이지에 알림이 표시됩니다. ## 브라우저 패널 Control UI에는 Gateway가 제어하는 브라우저(에이전트가 [브라우저 도구](/ko/tools/browser-control)를 통해 조작하는 것과 동일한 브라우저)를 일반 웹 브라우저에서 렌더링하는 도킹 가능한 브라우저 패널이 포함되어 있으며, 네이티브 웹뷰가 필요하지 않습니다. 연결된 Gateway가 `operator.admin` 연결에 `browser.request`를 알리면 표시되며, 세션 작업 공간 레일의 지구본 버튼으로 전환합니다. 패널은 탭, 편집 가능한 URL 표시줄, 뒤로/앞으로/새로 고침, 브라우저에서 열기 기능과 함께 실시간 페이지 스냅샷을 표시하고, 오른쪽이나 아래쪽에 도킹되며, 클릭, 휠 스크롤, 기본적인 입력을 원격 페이지로 전달합니다. 두 가지 캡처 모드가 에이전트용 페이지 컨텍스트를 패키징합니다: - **주석 달기(연필)**: 페이지 위에 자유롭게 표시를 그립니다. **채팅으로 보내기**를 사용하면 그린 선을 스크린샷에 합성하고, 이미지를 활성 채팅 작성기에 첨부하며, 에이전트가 사용자가 정확히 무엇에 원을 표시했는지 알 수 있도록 페이지 URL, 제목, 표시된 각 영역을 설명하는 프롬프트를 미리 입력합니다. - **검사(포인터)**: 마우스 커서를 올리면 커서 아래 요소의 정보(선택자, 접근성 이름, 역할, 크기)를 볼 수 있습니다. 클릭하면 동일한 작성기 흐름을 통해 해당 요소의 세부 정보와 강조 표시된 스크린샷을 전송합니다. 검사, 마우스 휠 스크롤, 뒤로/앞으로 이동에는 `browser.evaluateEnabled`가 필요합니다(기본적으로 활성화됨). macOS 앱은 대시보드에서 클릭한 링크에 대해 네이티브 링크 브라우저 사이드바를 유지합니다. 브라우저 패널은 여기에서도 작동하며, 다른 모든 플랫폼에서는 이 패널을 사용하여 페이지에 주석을 답니다. ## 채팅 동작 - `chat.send`은 **비차단 방식**입니다. 즉시 `{ runId, status: "started" }`로 확인 응답을 보내고, 응답은 `chat` 이벤트를 통해 스트리밍됩니다. 신뢰할 수 있는 Control UI 클라이언트는 로컬 진단을 위한 선택적 ACK 타이밍 메타데이터도 받을 수 있습니다. - 채팅 업로드는 이미지와 동영상이 아닌 파일을 허용합니다. 이미지는 네이티브 이미지 경로를 유지하며, 그 외 파일은 관리형 미디어로 저장되고 기록에 첨부 파일 링크로 표시됩니다. - 동일한 `idempotencyKey`으로 다시 전송하면 실행 중에는 `{ status: "in_flight" }`를, 완료 후에는 `{ status: "ok" }`를 반환합니다. - `chat.history` 응답은 UI 안전을 위해 크기가 제한됩니다. 트랜스크립트 항목이 너무 크면 Gateway가 긴 텍스트 필드를 잘라내고, 용량이 큰 메타데이터 블록을 생략하며, 크기 제한을 초과한 메시지를 자리표시자(`[chat.history omitted: message too large]`)로 대체할 수 있습니다. - `chat.history`에서 표시되는 어시스턴트 메시지가 잘린 경우, 사이드 리더는 필요에 따라 `sessionKey`별 `chat.message.get`, 활성 `agentId`, 트랜스크립트 `messageId`를 통해 표시용으로 정규화된 전체 트랜스크립트 항목을 가져올 수 있습니다. Gateway가 여전히 추가 내용을 반환할 수 없으면 리더는 잘린 미리보기를 조용히 반복하는 대신 명시적인 사용 불가 상태를 표시합니다. - 어시스턴트가 생성한 이미지는 관리형 미디어 참조로 영구 저장되고 인증된 Gateway 미디어 URL을 통해 다시 제공되므로, 새로고침 시 원시 base64 이미지 페이로드가 채팅 기록 응답에 계속 남아 있을 필요가 없습니다. - `chat.history`을 렌더링할 때 Control UI는 표시되는 어시스턴트 텍스트에서 표시 전용 인라인 지시문 태그(예: `[[reply_to_*]]` 및 `[[audio_as_voice]]`), 일반 텍스트 도구 호출 XML 페이로드(`...`, `...`, `...`, `...` 및 잘린 도구 호출 블록 포함), 유출된 ASCII/전각 모델 제어 토큰을 제거합니다. 표시되는 전체 텍스트가 정확한 무응답 토큰 `NO_REPLY` / `no_reply` 또는 Heartbeat 확인 토큰 `HEARTBEAT_OK`뿐인 어시스턴트 항목은 생략합니다. - 활성 전송 중과 최종 기록 새로고침 시 `chat.history`이 잠시 이전 스냅샷을 반환하더라도 채팅 뷰는 로컬의 낙관적 사용자/어시스턴트 메시지를 계속 표시합니다. Gateway 기록이 최신 상태를 따라잡으면 정식 트랜스크립트가 해당 로컬 메시지를 대체합니다. - 실시간 `chat` 이벤트는 전달 상태이며, `chat.history`는 영구 세션 트랜스크립트에서 다시 구성됩니다. 도구 완료 이벤트 후 Control UI는 기록을 다시 불러오고 소규모 낙관적 후행 부분만 병합합니다. 트랜스크립트 경계는 [WebChat](/ko/web/webchat)에 설명되어 있습니다. - `chat.inject`은 세션 트랜스크립트에 어시스턴트 메모를 추가하고 UI 전용 업데이트를 위해 `chat` 이벤트를 브로드캐스트합니다(에이전트 실행 및 채널 전달 없음). - 사이드바는 로드된 모든 활성 세션을 에이전트 섹션별로 고정/채널/작업/사용자 지정/채팅 버킷에 나열하며, 초안 대화 상자를 여는 단일 새 세션 작업을 제공합니다. 표시된 행을 열어도 강조 표시만 이동합니다. 사용자 지정 그룹은 접거나 드래그하여 순서를 변경할 수 있으며, 세션을 그룹 또는 채팅에 놓을 수 있습니다. 그룹 이름과 순서는 Gateway를 통해 동기화되지만 접힘 상태는 브라우저에 유지됩니다. 새 대시보드 세션에는 명령이 아닌 첫 메시지를 바탕으로 간결한 제목이 비동기적으로 생성되며, 명시적으로 지정한 이름은 절대 대체되지 않습니다. 이 별도 모델 호출을 저비용 모델로 라우팅하려면 `agents.defaults.utilityModel`(또는 `agents.list[].utilityModel`)을 설정하십시오. 다른 에이전트 섹션을 펼치면 열려 있는 채팅을 벗어나지 않고 해당 에이전트의 세션을 탐색할 수 있습니다. - 세션 검색은 명령 팔레트(⌘K 또는 사이드바 상단의 Search 필드)에 있습니다. 검색어를 입력하면 에이전트 전체에서 제한된 수의 일치 페이지를 탐색하고, 내부 하위/Cron 행을 필터링하며, 탐색 명령 옆에 표시 가능한 일치 항목을 나열합니다. 세션 페이지에는 필터가 포함된 전체 검색 가능 목록이 유지됩니다. - 각 사이드바 행은 직접 고정 기능과 함께 읽지 않음 상태, 이름 변경, 포크, 그룹화, 보관, 삭제를 위한 전체 컨텍스트 메뉴를 제공합니다. 여러 행을 선택하면(Cmd/Ctrl-클릭, 범위는 Shift-클릭) 읽지 않음 상태, 그룹화, 보관, 삭제를 포함하는 일괄 메뉴가 표시됩니다. 선택한 모든 세션을 보관할 수 있는 경우에만 일괄 보관/삭제가 활성화됩니다. 활성 실행과 에이전트의 기본 세션은 보관할 수 없습니다. 현재 선택한 세션을 보관하거나 삭제하면 채팅이 해당 에이전트의 기본 세션으로 다시 전환됩니다. - macOS 앱에서 OpenClaw 마크는 사이드바 행을 차지하지 않고 창 컨트롤 옆의 비어 있는 네이티브 제목 표시줄 영역을 사용합니다. - 데스크톱 너비에서는 채팅 컨트롤이 하나의 간결한 행에 유지되며 트랜스크립트를 아래로 스크롤하는 동안 접힙니다. 위로 스크롤하거나 맨 위로 돌아가거나 맨 아래에 도달하면 컨트롤이 복원됩니다. - 연속된 동일한 텍스트 전용 메시지는 개수 배지가 있는 하나의 말풍선으로 렌더링됩니다. 이미지, 첨부 파일, 도구 출력 또는 Canvas 미리보기가 포함된 메시지는 접지 않습니다. - 세션의 체크아웃이 GitHub 저장소의 기본값이 아닌 브랜치에 있으면 채팅 뷰가 작성기 위에 풀 리퀘스트 칩을 고정합니다. 각 칩에는 PR 번호, 저장소, 브랜치, 변경 줄 수, CI 표시, 초안/병합됨/종료됨 상태가 표시되며 PR로 연결됩니다. 행에는 최대 2개의 칩이 표시되며, 라이브(열림/초안) PR이 먼저 표시됩니다. "Show more" 버튼을 누르면 접힌 병합됨/종료됨 기록이 나타납니다. CI 표시는 통과/실패/실행 중/건너뜀 검사 수와 PR의 검사 페이지 링크가 있는 작은 CI 모니터링 팝오버를 엽니다. 감지는 서버 측에서 `controlUi.sessionPullRequests`을 통해 실행되며, 설정된 경우 Gateway의 `GH_TOKEN`/`GITHUB_TOKEN`를 재사용합니다. GitHub API 속도 제한에 도달하면 칩은 마지막으로 알려진 상태를 유지하고 상태가 오래되었을 수 있다는 경고를 표시합니다. 칩을 닫으면 현재 브라우저 프로필에서 해당 세션의 칩이 숨겨집니다. PR이 아직 없으면 행에 브랜치 자체가 표시됩니다. 저장소, 브랜치 이름, 기본 브랜치 병합 기준점과 비교한 차이의 +/− 크기(커밋된 작업과 커밋되지 않은 작업)를 보여 주며, GitHub의 새 풀 리퀘스트 페이지를 여는 Create PR 버튼도 제공합니다. 푸시된 브랜치에 비교할 커밋이 생기면 행이 표시되고, 열려 있거나 초안 상태인 PR이 존재하면 자동으로 숨겨집니다. 브랜치 행은 로컬 git 정보만 사용하므로 GitHub 속도 제한 중에도 계속 사용할 수 있으며 동일한 오래된 상태 경고가 표시됩니다. 제한이 재설정될 때까지 "PR을 찾을 수 없음"이라는 결과를 신뢰할 수 없기 때문입니다. - 세션 차이 패널에는 세션 체크아웃이 실제로 변경한 내용이 표시됩니다. 브랜치 버튼(워크스페이스 레일 헤더, 분할 창 헤더 또는 단일 창 채팅의 플로팅 버튼)을 누르면 체크아웃의 기본 브랜치 병합 기준점과 비교한 브랜치, 커밋되지 않은 작업, 추적되지 않은 작업의 파일별 차이를 보여 주는 상세 패널이 열립니다. 여기에는 상태 점, 이름 변경 화살표, 파일별 +/− 개수, 접을 수 있는 파일, 헝크 사이의 "N unmodified lines" 표시가 포함됩니다. 차이는 `sessions.diff` Gateway 메서드(`operator.read` 범위)를 통해 서버 측에서 계산됩니다. 바이너리 파일과 크기 제한을 초과한 파일은 통계 전용 항목으로 축소되며, 연결된 Gateway가 `sessions.diff`을 알릴 때만 버튼이 표시됩니다. - 각 채팅 창의 세션 워크스페이스 레일에는 세션 파일, 프로젝트 파일, 아티팩트가 나열됩니다. 기본적으로 창의 오른쪽 가장자리에 도킹됩니다. 헤더를 드래그하거나 도킹 버튼을 사용하여 아래쪽으로 이동할 수 있으며, 이 선택은 현재 브라우저 프로필에 저장됩니다. 접힌 레일은 공간을 전혀 차지하지 않습니다. ⇧⌘B, 분할 창 헤더의 파일 토글 또는 단일 창 채팅의 플로팅 파일 버튼으로 다시 여십시오. 두 버튼 모두 변경된 파일 수 배지를 표시합니다. 별도의 파일, 도구 및 Canvas 상세 패널에는 영향을 주지 않습니다. - 채팅의 파일 참조, 펼쳐진 읽기/편집/쓰기 도구 카드의 파일 경로 또는 워크스페이스 레일의 파일 행을 클릭하면 파일 상세 패널이 열립니다. 이 패널은 구문 강조, 줄 번호, 줄로 이동, 파일 내 검색, 복사 작업 및 외부 편집기에서 열기 메뉴를 제공하는 CodeMirror 기반 코드 뷰입니다. Gateway가 `operator.admin` 연결에 `sessions.files.set`을 알리면 패널에 변경 상태 추적 및 Cmd/Ctrl-S 저장 기능이 있는 편집 모드가 추가됩니다. 저장하지 않은 초안은 명시적으로 저장하거나 폐기할 때까지 현재 브라우저 탭에서 파일, 패널 및 세션을 이동해도 유지됩니다. 저장은 `sessions.files.get`이 반환한 콘텐츠 해시를 사용하는 비교 후 교환 방식으로 수행됩니다. 파일을 불러온 후 디스크에서 파일이 변경된 경우(예: 에이전트가 계속 작업한 경우) 패널에 Reload(최신 콘텐츠 사용) 및 Overwrite(로컬 편집 유지) 작업이 포함된 충돌 알림이 표시됩니다. 쓰기에는 읽기와 동일한 fs 안전 워크스페이스 보호 기능(경로 포함 여부 확인, 심볼릭 링크/하드 링크 거부, 256 KB UTF-8 제한)이 적용되며 기존 파일만 덮어씁니다. 편집기는 파일을 생성하거나 삭제하지 않습니다. - 각 채팅 창의 백그라운드 작업 레일에는 현재 에이전트의 백그라운드 작업과 하위 에이전트가 나열됩니다(`tasks.list`은 에이전트별 범위이며 `task` 이벤트로 실시간 유지). 실행 중인 작업에는 실시간 경과 시간 타이머, 도구 사용 횟수, 현재 사용 중인 도구 및 중지 컨트롤이 표시됩니다. 접을 수 있는 완료 섹션에는 실행 시간이 추가되며, View transcript 링크는 해당 작업의 하위 세션을 창에서 엽니다. 분할 창 헤더의 활동 토글 또는 단일 창 채팅의 플로팅 활동 버튼으로 여십시오. 작업 스냅샷은 미리 로드되므로 레일을 먼저 열지 않아도 두 버튼 모두 실행 중인 작업 수 배지를 표시합니다. 작업 페이지에는 에이전트 전체의 전체 원장이 계속 제공됩니다. - 워크스페이스 레일, 백그라운드 작업 레일 및 상세 패널은 창 전체가 아니라 각 창의 자체 너비에 맞게 조정됩니다. 좁은 창이나 컴팩트한 창에서는 두 레일 모두 하단 스트립으로 표시됩니다. 창이 넓어질 때까지 측면 도킹 컨트롤은 숨겨지며, 한 열만 들어갈 수 있는 경우 워크스페이스 레일이 측면 슬롯을 우선 사용합니다. 상세 패널은 스레드와 같은 행을 공유하는 대신 가로 크기 조절 핸들과 함께 스레드 아래에 쌓입니다. 휴대전화 크기의 뷰포트에서는 상세 패널이 계속 전체 화면으로 열립니다. - 채팅 헤더의 모델 및 추론 선택기는 `sessions.patch`을 통해 활성 세션을 즉시 패치합니다. 이는 한 번의 전송에만 적용되는 옵션이 아니라 지속되는 세션 재정의입니다. - **분할 보기:** 오른쪽 상단의 플로팅 토글 행(세션 차이, 백그라운드 작업 및 세션 파일 토글 옆)에서 연 다음, 공간이 허용하는 만큼 활성 창을 오른쪽이나 아래쪽으로 분할하십시오. 각 창에는 자체 세션, 트랜스크립트, 작성기 및 도구 스트림이 있습니다. - 사이드바에서 세션을 채팅으로 드래그하여 창에서 여십시오. 애니메이션 드롭 미리보기가 영역 사이를 부드럽게 이동하며 결과에 레이블을 표시합니다. 새 창이 차지할 정확한 절반에는 "Split", 전체 창에는 "Open here"가 표시됩니다. 단일 창 모드에서도 드롭할 수 있습니다. - 활성 분할 창이 사이드바 선택과 URL을 결정합니다. 각 창에는 세션 제목과 워크스페이스 레일, 분할, 닫기 컨트롤이 포함된 자체 헤더 행이 있습니다. 구분선을 사용해 열과 세로로 쌓인 창의 크기를 조절할 수 있으며, 브라우저는 새로고침 후에도 레이아웃을 로컬에 저장합니다. - 좁은 화면에서는 분할 보기가 레이아웃을 유지하지만 닫기 컨트롤이 있는 헤더를 포함하여 활성 창만 렌더링합니다. - 동일한 세션의 모델 선택기 변경 사항이 아직 저장 중일 때 메시지를 보내면 작성기는 `chat.send`을 호출하기 전에 해당 세션 패치가 완료되기를 기다리므로 선택한 모델로 전송됩니다. - `/new`을 입력하면 새 채팅과 동일한 새 대시보드 세션이 생성되고 해당 세션으로 전환됩니다. 단, `session.dmScope: "main"`가 구성되어 있고 현재 상위 세션이 에이전트의 기본 세션인 경우에는 기본 세션을 제자리에서 재설정합니다. `/reset`을 입력하면 현재 세션에 대한 Gateway의 명시적 제자리 재설정이 유지됩니다. - 채팅 모델 선택기는 Gateway에 구성된 모델 뷰를 요청합니다. `agents.defaults.models`이 있으면 해당 허용 목록이 선택기를 결정하며, 공급자 범위 카탈로그를 동적으로 유지하는 `provider/*` 항목도 포함됩니다. 그렇지 않으면 선택기에 명시적인 `models.providers.*.models` 항목과 사용 가능한 인증이 있는 공급자가 표시됩니다. 전체 카탈로그는 `view: "all"`이 포함된 디버그 `models.list` RPC를 통해 계속 사용할 수 있습니다. - 최신 Gateway 세션 사용량 보고서에 현재 컨텍스트 토큰이 포함되면 채팅 작성기 도구 모음에 사용 비율을 나타내는 작은 컨텍스트 사용량 링이 표시됩니다. 링을 열면 현재 컨텍스트 창, 최근 실행의 토큰 수와 예상 총비용, 제공자/모델 ID, 그리고 보고된 경우 최근 제공자 응답의 입력/출력/캐시 비용 분석을 확인할 수 있습니다. 컨텍스트 압력이 높아지면 링이 경고 스타일로 전환되며, 권장 Compaction 수준에서는 일반 세션 Compaction 경로를 실행하는 간결한 버튼이 표시됩니다. 오래된 토큰 스냅샷은 Gateway가 최신 사용량을 다시 보고할 때까지 숨겨집니다. Talk 모드는 등록된 실시간 음성 제공자를 사용합니다. `talk.realtime.provider: "openai"`와 함께 `openai` API 키 프로필, `talk.realtime.providers.openai.apiKey` 또는 `OPENAI_API_KEY`를 사용하여 OpenAI를 구성하십시오. OpenAI Realtime은 공개 Platform API를 사용하며 Platform API 키가 필요합니다. Codex OAuth 로그인은 이 기능의 요구 사항을 충족하지 않습니다. `talk.realtime.provider: "google"`과 함께 `talk.realtime.providers.google.apiKey`를 사용하여 Google을 구성하십시오. 브라우저에는 표준 제공자 API 키가 전달되지 않습니다. OpenAI에는 WebRTC용 임시 Realtime 클라이언트 비밀이 전달되고, Google Live에는 브라우저 WebSocket 세션용으로 제약된 일회용 Live API 인증 토큰이 전달되며, 지침과 도구 선언은 Gateway에 의해 토큰에 고정됩니다. 백엔드 실시간 브리지만 제공하는 제공자는 Gateway 릴레이 전송을 통해 실행되므로 자격 증명과 공급업체 소켓은 서버 측에 유지되고 브라우저 오디오는 인증된 Gateway RPC를 통해 이동합니다. Realtime 세션 프롬프트는 Gateway에서 구성하며, `talk.client.create`는 호출자가 제공하는 지침 재정의를 허용하지 않습니다. 영구적인 제공자, 모델, 음성, 전송 방식, 추론 수준, 정확한 VAD 임계값, 무음 지속 시간 및 접두부 패딩 기본값은 **Settings → Communications → Talk**에 있으며, 이를 변경하려면 `operator.admin` 액세스 권한이 필요합니다. Gateway 릴레이를 구성하면 백엔드 릴레이 경로가 강제됩니다. WebRTC를 구성하면 세션이 클라이언트 소유로 유지되며, 제공자가 브라우저 세션을 만들 수 없는 경우 릴레이로 자동 대체되지 않고 실패합니다. Talk 컨트롤은 작성기 도구 모음의 마이크 버튼입니다. 펼침 메뉴에는 **System default**와 USB, Bluetooth 및 가상 입력을 포함하여 브라우저에 노출된 모든 마이크가 표시됩니다. 선택한 장치 ID는 브라우저 로컬에만 유지되며 Gateway로 전송되지 않습니다. 해당 장치가 사라지면 Talk는 다른 마이크에서 조용히 녹음하는 대신 다른 입력을 선택하도록 요청합니다. Talk가 활성 상태이면 마이크 버튼이 실시간 입력 레벨 미터를 표시하는 필 모양으로 바뀝니다. 이를 클릭하면 음성 입력이 중지되고, 마우스 포인터를 올리면 중지 글리프가 표시됩니다. 실시간 도구 호출이 `talk.client.toolCall`을 통해 구성된 더 큰 모델에 요청하는 동안 화면 읽기 프로그램은 `Connecting voice input...`, `Listening...` 또는 `Asking OpenClaw...`를 알립니다. 실행 중인 에이전트 응답을 중지하는 기능은 필 옆의 별도 사각형 **Stop** 컨트롤로 유지됩니다. 유지관리자 라이브 스모크 테스트: `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`는 OpenAI 백엔드 WebSocket 브리지, 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 연결이 끊겨도 로그아웃되지 않습니다. 클라이언트가 백오프(800 ms에서 최대 15 s)로 자동 재시도하는 동안 대시보드는 계속 표시되며, 상단 표시줄 아래에는 주황색의 떠 있는 "Gateway connection lost — Reconnecting…" 필이 표시됩니다. 연결이 복구될 때까지 실시간 업데이트와 실시간/세션 작업이 일시 중지됩니다. 필의 **Retry now**를 누르면 즉시 연결을 시도합니다. 채팅은 계속 편집할 수 있습니다. 일반 텍스트와 첨부 파일 전송은 현재 탭의 Gateway/세션 범위 브라우저 저장소에 보관되고 재연결 대기 상태로 표시되며, Gateway가 복구되면 자동으로 전송됩니다. 오프라인 상태에서는 실시간 컨트롤과 슬래시 명령을 사용할 수 없습니다. 이 브라우저에 이미 자격 증명(구성된 토큰/비밀번호 또는 승인된 장치 토큰)이 있으면 최초 열기 및 새로고침 시 로그인 화면이 잠깐 나타나는 대신, 연결이 설정되는 동안 작은 OpenClaw 애니메이션 표시가 나타납니다. 로그인 화면은 자격 증명이 아직 저장되지 않았거나 Gateway가 자격 증명을 명시적으로 거부할 때(잘못된 토큰/비밀번호, 취소된 페어링)에만 나타납니다. 이러한 상태는 기다리는 대신 사용자의 입력이 필요합니다. ## PWA 설치 및 웹 푸시 Control UI에는 `manifest.webmanifest`와 서비스 워커가 포함되어 있으므로 최신 브라우저에서 독립 실행형 PWA로 설치할 수 있습니다. 웹 푸시를 사용하면 탭이나 브라우저 창이 열려 있지 않아도 Gateway가 설치된 PWA를 깨워 알림을 표시할 수 있습니다. OpenClaw 업데이트 직후 페이지에 **Protocol mismatch**가 표시되면 먼저 `openclaw dashboard`로 대시보드를 다시 열고 강력 새로고침하십시오. 여전히 실패하면 대시보드 오리진의 사이트 데이터를 삭제하거나 비공개 브라우저 창에서 테스트하십시오. 이전 탭이나 브라우저 서비스 워커 캐시로 인해 업데이트 전 Control UI 번들이 최신 Gateway에 계속 연결될 수 있습니다. | 구성 요소 | 기능 | | ----------------------------------------------------- | ------------------------------------------------------------------ | | `ui/public/manifest.webmanifest` | PWA 매니페스트입니다. 접근 가능해지면 브라우저에서 "Install app"을 제공합니다. | | `ui/public/sw.js` | `push` 이벤트와 알림 클릭을 처리하는 서비스 워커입니다. | | `push/vapid-keys.json` (OpenClaw 상태 디렉터리 아래) | 웹 푸시 페이로드 서명에 사용되는 자동 생성 VAPID 키 쌍입니다. | | `push/web-push-subscriptions.json` | 영구 저장된 브라우저 구독 엔드포인트입니다. | 키를 고정하려는 경우(다중 호스트 배포, 비밀 순환 또는 테스트) Gateway 프로세스에서 환경 변수를 통해 VAPID 키 쌍을 재정의하십시오. - `OPENCLAW_VAPID_PUBLIC_KEY` - `OPENCLAW_VAPID_PRIVATE_KEY` - `OPENCLAW_VAPID_SUBJECT`(기본값: `https://openclaw.ai`) Control UI는 다음과 같은 범위 제한 Gateway 메서드를 사용하여 브라우저 구독을 등록하고 테스트합니다. - `push.web.vapidPublicKey`는 활성 VAPID 공개 키를 가져옵니다. - `push.web.subscribe`는 `endpoint`와 `keys.p256dh`/`keys.auth`를 등록합니다. - `push.web.unsubscribe`는 등록된 엔드포인트를 제거합니다. - `push.web.test`는 호출자의 구독으로 테스트 알림을 전송합니다. 웹 푸시는 iOS APNS 릴레이 경로(릴레이 기반 푸시는 [구성](/ko/gateway/configuration) 참조) 및 네이티브 모바일 페어링을 대상으로 하는 `push.test` 메서드와 독립적입니다. ## 호스팅된 임베드 어시스턴트 메시지는 `[embed ...]` 단축 코드를 사용하여 호스팅된 웹 콘텐츠를 인라인으로 렌더링할 수 있습니다. iframe 샌드박스 정책은 `gateway.controlUi.embedSandbox`로 제어됩니다. 번들 Canvas Plugin은 도구 호출에서 독립형 SVG 또는 HTML을 직접 렌더링하는 [`show_widget`](/ko/tools/show-widget)도 제공합니다. 브라우저는 `inline-widgets` Gateway 기능을 알리고, 생성된 Canvas 문서는 채팅 기록이 다시 로드된 후에도 계속 사용할 수 있습니다. 채널에서 시작된 실행에는 이 도구가 제공되지 않습니다. 호스팅된 임베드 내에서 스크립트 실행을 비활성화합니다. 오리진 격리를 유지하면서 대화형 임베드를 허용합니다. 일반적으로 독립형 브라우저 게임/위젯에 충분합니다. 의도적으로 더 강한 권한이 필요한 동일 사이트 문서에 대해 `allow-scripts`에 더해 `allow-same-origin`을 추가합니다. ```json5 { gateway: { controlUi: { embedSandbox: "scripts", }, }, } ``` 임베드된 문서에 동일 오리진 동작이 실제로 필요한 경우에만 `trusted`를 사용하십시오. 에이전트가 생성하는 대부분의 게임과 대화형 캔버스에는 `scripts`가 더 안전합니다. 절대 외부 `http(s)` 임베드 URL은 기본적으로 차단됩니다. `[embed url="https://..."]`가 타사 페이지를 로드하도록 허용하려면 `gateway.controlUi.allowExternalEmbedUrls: true`를 설정하십시오. ## 채팅 메시지 너비 채팅 대화 기록은 작성기에 맞춰 정렬된 중앙의 읽기 쉬운 프레임을 사용합니다. 어시스턴트 및 도구 출력은 왼쪽 정렬을 유지하고 사용자 말풍선은 해당 프레임 안에서 오른쪽 정렬을 유지합니다. 와이드 모니터 배포에서는 `gateway.controlUi.chatMessageMaxWidth`를 설정하여 번들 CSS를 수정하지 않고 대화 기록 너비를 재정의할 수 있습니다. ```json5 { gateway: { controlUi: { chatMessageMaxWidth: "min(1280px, 82%)", }, }, } ``` 값은 브라우저에 전달되기 전에 검증됩니다. 지원되는 형식에는 `960px` 또는 `82%` 같은 일반 길이 및 백분율과, 제약 조건이 적용된 `min(...)`, `max(...)`, `clamp(...)`, `calc(...)`, `fit-content(...)` 너비 표현식이 포함됩니다. ## Tailnet 액세스(권장) Gateway를 루프백에 유지하고 Tailscale Serve가 HTTPS로 프록시하도록 하십시오. ```bash openclaw gateway --tailscale serve ``` `https:///`(또는 구성된 `gateway.controlUi.basePath`)을 여십시오. 기본적으로 `gateway.auth.allowTailscale`이 `true`이면 Control UI/WebSocket Serve 요청은 Tailscale ID 헤더(`tailscale-user-login`)를 통해 인증할 수 있습니다. OpenClaw는 `tailscale whois`로 `x-forwarded-for` 주소를 확인하고 이를 헤더와 대조하여 ID를 검증하며, 요청이 Tailscale의 `x-forwarded-*` 헤더와 함께 루프백에 도달한 경우에만 이를 허용합니다. 브라우저 장치 ID를 사용하는 Control UI 운영자 세션의 경우 검증된 이 Serve 경로는 장치 페어링 왕복 과정도 건너뜁니다. 장치가 없는 브라우저와 노드 역할 연결에는 계속 일반 장치 검사가 적용됩니다. Serve 트래픽에도 명시적인 공유 비밀 자격 증명을 요구하려면 `gateway.auth.allowTailscale: false`를 설정한 다음 `gateway.auth.mode: "token"` 또는 `"password"`를 사용하십시오. 이 비동기 Serve ID 경로에서는 동일한 클라이언트 IP 및 인증 범위에서 발생한 인증 실패 시도들이 속도 제한 쓰기 전에 직렬화됩니다. 따라서 동일한 브라우저에서 잘못된 재시도가 동시에 발생하면 두 개의 단순 불일치가 병렬로 경합하는 대신 두 번째 요청에 `retry later`가 표시될 수 있습니다. 토큰 없는 Serve 인증은 Gateway 호스트를 신뢰할 수 있다고 가정합니다. 신뢰할 수 없는 로컬 코드가 해당 호스트에서 실행될 수 있다면 토큰/비밀번호 인증을 요구하십시오. ```bash openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)" ``` `http://:18789/`(또는 구성된 `gateway.controlUi.basePath`)을 여십시오. 일치하는 공유 비밀을 UI 설정에 붙여 넣으십시오(`connect.params.auth.token` 또는 `connect.params.auth.password`로 전송됨). ## 안전하지 않은 HTTP 일반 HTTP(`http://` 또는 `http://`)로 대시보드를 열면 브라우저가 **안전하지 않은 컨텍스트**에서 실행되어 WebCrypto를 차단합니다. 기본적으로 OpenClaw는 장치 ID가 없는 Control UI 연결을 **차단**합니다. 문서화된 예외는 다음과 같습니다. - `gateway.controlUi.allowInsecureAuth=true`를 사용하는 localhost 전용 안전하지 않은 HTTP 호환성 - `gateway.auth.mode: "trusted-proxy"`를 통한 성공적인 운영자 Control UI 인증 - 비상용 `gateway.controlUi.dangerouslyDisableDeviceAuth=true` **권장 해결 방법:** HTTPS(Tailscale Serve)를 사용하거나 `https:///`(Serve) 또는 Gateway 호스트의 `http://127.0.0.1:18789/`에서 UI를 로컬로 여십시오. ```json5 { gateway: { controlUi: { allowInsecureAuth: true }, bind: "tailnet", auth: { mode: "token", token: "replace-me" }, }, } ``` `allowInsecureAuth`는 로컬 호환성 토글일 뿐입니다. - 비보안 HTTP 컨텍스트에서 localhost Control UI 세션이 기기 ID 없이 진행할 수 있게 합니다. - 페어링 검사를 우회하지 않습니다. - 원격(non-localhost) 기기 ID 요구 사항을 완화하지 않습니다. ```json5 { gateway: { controlUi: { dangerouslyDisableDeviceAuth: true }, bind: "tailnet", auth: { mode: "token", token: "replace-me" }, }, } ``` `dangerouslyDisableDeviceAuth`는 Control UI 기기 ID 검사를 비활성화하며 보안을 심각하게 저하시킵니다. 비상 사용 후 신속히 되돌리십시오. - 신뢰할 수 있는 프록시 인증에 성공하면 기기 ID 없이 **운영자** Control UI 세션을 허용할 수 있습니다. - 이는 Node 역할 Control UI 세션에는 적용되지 **않습니다**. - 동일 호스트의 루프백 리버스 프록시는 여전히 신뢰할 수 있는 프록시 인증을 충족하지 않습니다. [신뢰할 수 있는 프록시 인증](/ko/gateway/trusted-proxy-auth)을 참조하십시오. HTTPS 설정 지침은 [Tailscale](/ko/gateway/tailscale)을 참조하십시오. ## 콘텐츠 보안 정책 Control UI에는 엄격한 `img-src` 정책이 적용됩니다. **동일 출처** 자산, `data:` URL 및 로컬에서 생성된 `blob:` URL만 허용됩니다. 원격 `http(s)` 및 프로토콜 상대 이미지 URL은 브라우저에서 거부되며 네트워크 가져오기 요청도 발생하지 않습니다. 실제로는 다음과 같이 동작합니다. - 상대 경로(예: `/avatars/`)에서 제공되는 아바타와 이미지는 계속 렌더링됩니다. 여기에는 UI가 가져온 후 로컬 `blob:` URL로 변환하는 인증된 아바타 경로도 포함됩니다. - 인라인 `data:image/...` URL은 계속 렌더링됩니다. - Control UI에서 생성한 로컬 `blob:` URL은 계속 렌더링됩니다. - GitHub 링크 미리보기 아바타는 Gateway가 GitHub의 고정 아바타 호스트에서 가져와 크기가 제한된 `data:` URL로 반환합니다. 운영자의 브라우저는 원격 아바타 호스트에 접속하지 않습니다. - 채널 메타데이터가 내보낸 원격 아바타 URL은 Control UI의 아바타 헬퍼에서 제거되고 기본 제공 로고/배지로 대체됩니다. 따라서 침해되었거나 악의적인 채널이 운영자의 브라우저에서 임의의 원격 이미지 가져오기를 강제할 수 없습니다. 이 정책은 항상 활성화되며 구성할 수 없습니다. ## 아바타 경로 인증 Gateway 인증이 구성된 경우 Control UI 아바타 엔드포인트에는 나머지 API와 동일한 Gateway 토큰이 필요합니다. - `GET /avatar/`는 인증된 호출자에게만 아바타 이미지를 반환합니다. `GET /avatar/?meta=1`도 동일한 규칙에 따라 아바타 메타데이터를 반환합니다. - 두 경로 모두 인증되지 않은 요청을 거부합니다(동일 계열의 어시스턴트 미디어 경로와 일치). 따라서 그 밖의 부분이 보호되는 호스트에서 아바타 경로를 통해 에이전트 ID가 유출되지 않습니다. - Control UI는 아바타를 가져올 때 Gateway 토큰을 전달자 헤더로 전달하며, 인증된 blob URL을 사용하여 대시보드에서 이미지가 계속 렌더링되도록 합니다. Gateway 인증을 비활성화하면(공유 호스트에서는 권장하지 않음) Gateway의 나머지 부분과 마찬가지로 아바타 경로도 인증되지 않은 상태가 됩니다. ## 어시스턴트 미디어 경로 인증 Gateway 인증이 구성된 경우 어시스턴트의 로컬 미디어 미리보기는 2단계 경로를 사용합니다. - `GET /__openclaw__/assistant-media?meta=1&source=`에는 일반적인 Control UI 운영자 인증이 필요합니다. 브라우저는 사용 가능 여부를 확인할 때 Gateway 토큰을 전달자 헤더로 전송합니다. - 성공한 메타데이터 응답에는 해당 소스 경로로 범위가 제한된 수명이 짧은 `mediaTicket`이 포함됩니다. - 브라우저에서 렌더링되는 이미지, 오디오, 비디오 및 문서 URL은 활성 Gateway 토큰이나 비밀번호 대신 `mediaTicket=`을 사용합니다. 티켓은 빠르게 만료되며 다른 소스에 대한 권한을 부여할 수 없습니다. 이를 통해 재사용 가능한 Gateway 자격 증명을 노출된 미디어 URL에 포함하지 않으면서도 브라우저 네이티브 미디어 요소와 호환되는 미디어 렌더링을 유지합니다. ## 승인 링크 운영자 승인 알림은 예약된 `${controlUiBasePath}/approve/{approvalId}` 네임스페이스에서 제공되는 독립형 승인 문서로 딥 링크할 수 있습니다(예: `/approve/`, 또는 기본 경로가 구성된 경우 `/openclaw/approve/`). URL은 승인 수명 동안 안정적으로 유지되며 본인의 기기 간에 안전하게 전달할 수 있습니다. 이 URL은 승인을 식별할 뿐, 승인 권한을 부여하지는 않습니다. - 한 세그먼트인 `/approve/` 네임스페이스는 **모든** HTTP 메서드에 대해 Plugin HTTP 경로보다 우선하도록 Gateway가 예약합니다. 따라서 Plugin 경로가 승인 문서를 가리거나 가로챌 수 없습니다. - 승인 문서를 열려면 나머지 Control UI와 동일한 Gateway 인증(토큰/비밀번호, Tailscale Serve ID 또는 신뢰할 수 있는 프록시 ID)이 필요합니다. 자격 증명은 승인 URL에 절대 포함되지 않습니다. - Control UI 제공이 비활성화된 경우 네임스페이스 요청은 Plugin 핸들러로 넘어가지 않고 `404`를 반환합니다. - 승인 문서에서 로그인한 상태는 해당 페이지에서만 일시적으로 유지됩니다. 동일한 브라우저의 전체 Control UI에 저장된 Gateway 선택 또는 설정을 덮어쓰지 않습니다. Gateway는 `dist/control-ui`에서 정적 파일을 제공합니다. ```bash pnpm ui:build ``` 선택적 절대 기본 경로(고정 자산 URL): ```bash OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build ``` 로컬 개발(별도의 개발 서버): ```bash pnpm ui:dev ``` 그런 다음 UI가 Gateway WS URL(예: `ws://127.0.0.1:18789`)을 가리키도록 설정하십시오. ## 빈 Control UI 페이지 브라우저에서 빈 대시보드가 로드되고 DevTools에 유용한 오류가 표시되지 않는다면 확장 프로그램이나 일찍 실행된 콘텐츠 스크립트가 JavaScript 모듈 앱의 평가를 차단했을 수 있습니다. 정적 페이지에는 시작 후 ``이 등록되지 않을 때 표시되는 일반 HTML 복구 패널이 포함되어 있습니다. 브라우저 환경을 변경한 후 패널의 **Try again** 작업을 사용하거나, 다음을 확인한 후 수동으로 다시 로드하십시오. - 모든 페이지에 코드를 삽입하는 확장 프로그램, 특히 `` 콘텐츠 스크립트가 있는 확장 프로그램을 비활성화하십시오. - 비공개 창, 깨끗한 브라우저 프로필 또는 다른 브라우저를 사용해 보십시오. - Gateway를 계속 실행한 상태에서 브라우저를 변경한 후 동일한 대시보드 URL을 확인하십시오. ## 디버깅/테스트: 개발 서버 + 원격 Gateway Control UI는 정적 파일로 구성됩니다. WebSocket 대상은 구성할 수 있으며 HTTP 출처와 달라도 됩니다. 로컬에서 Vite 개발 서버를 사용하지만 Gateway는 다른 위치에서 실행할 때 유용합니다. ```bash pnpm ui:dev ``` ```text http://localhost:5173/?gatewayUrl=ws%3A%2F%2F%3A18789 ``` 선택적 일회성 인증(필요한 경우): ```text http://localhost:5173/?gatewayUrl=wss%3A%2F%2F%3A18789#token= ``` - `gatewayUrl`은 로드 후 localStorage에 저장되고 URL에서 제거됩니다. - `gatewayUrl`을 통해 전체 `ws://` 또는 `wss://` 엔드포인트를 전달하는 경우 브라우저가 쿼리 문자열을 올바르게 파싱하도록 값을 URL 인코딩하십시오. - 가능하면 `token`은 URL 프래그먼트(`#token=...`)를 통해 전달해야 합니다. 프래그먼트는 서버로 전송되지 않으므로 요청 로그 및 Referer 유출을 방지합니다. 레거시 `?token=` 쿼리 매개변수도 호환성을 위해 한 번 가져오지만, 대체 수단으로만 사용되며 부트스트랩 직후 즉시 제거됩니다. - `password`는 메모리에만 보관됩니다. - `gatewayUrl`이 설정되면 UI는 구성 또는 환경 자격 증명으로 대체하지 않습니다. `token`(또는 `password`)을 명시적으로 제공하십시오. 명시적 자격 증명이 없으면 오류입니다. - Gateway가 TLS(Tailscale Serve, HTTPS 프록시 등) 뒤에 있는 경우 `wss://`를 사용하십시오. - 클릭재킹을 방지하기 위해 `gatewayUrl`은 최상위 창(임베드되지 않은 창)에서만 허용됩니다. - 공개 비루프백 Control UI 배포에서는 `gateway.controlUi.allowedOrigins`를 명시적으로 설정해야 합니다(전체 출처). 루프백, RFC1918/링크 로컬, `.local`, `.ts.net` 또는 Tailscale CGNAT 호스트에서 가져오는 비공개 동일 출처 LAN/Tailnet 로드는 Host 헤더 대체를 활성화하지 않아도 허용됩니다. - Gateway 시작 시 유효한 런타임 바인드 및 포트에서 `http://localhost:` 및 `http://127.0.0.1:` 같은 로컬 출처를 시드할 수 있지만, 원격 브라우저 출처에는 여전히 명시적인 항목이 필요합니다. - 엄격하게 통제된 로컬 테스트 외에는 `gateway.controlUi.allowedOrigins: ["*"]`를 사용하지 마십시오. 이는 "현재 사용 중인 호스트와 일치"한다는 의미가 아니라 모든 브라우저 출처를 허용한다는 의미입니다. - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true`는 Host 헤더 출처 대체 모드를 활성화하지만, 위험한 보안 모드입니다. ```json5 { gateway: { controlUi: { allowedOrigins: ["http://localhost:5173"], }, }, } ``` 원격 액세스 설정에 대한 자세한 내용은 [원격 액세스](/ko/gateway/remote)를 참조하십시오. ## 관련 문서 - [대시보드](/ko/web/dashboard) — Gateway 대시보드 - [상태 검사](/ko/gateway/health) — Gateway 상태 모니터링 - [TUI](/ko/web/tui) — 터미널 사용자 인터페이스 - [WebChat](/ko/web/webchat) — 브라우저 기반 채팅 인터페이스