콘텐츠로 이동
OpenClaw

OpenClaw Control UI 설정: 1분 만에 연결 및 기기 페어링

새로운 도구를 설치하고 나서 설정 파일을 일일이 수정하거나, CLI 명령어를 외우느라 고생한 적 있으신가요? 복잡한 시스템을 관리할 때 직관적인 화면이 있으면 훨씬 편하죠. OpenClaw는 여러분의 워크플로우를 돕기 위해 브라우저에서 바로 사용할 수 있는 Control UI를 제공해요.

Control UI (브라우저)

섹션 제목: “Control UI (브라우저)”

Control UI는 Gateway에서 제공하는 가벼운 Vite + Lit 기반의 싱글 페이지 애플리케이션(SPA)이에요.

  • 기본 주소: http://<host>:18789/
  • 선택 사항: gateway.controlUi.basePath를 설정해 경로 접두사(예: /openclaw)를 지정할 수 있어요.

이 UI는 동일한 포트의 Gateway WebSocket과 직접 통신해요.

로컬에서 빠르게 열기

섹션 제목: “로컬에서 빠르게 열기”

Gateway가 현재 컴퓨터에서 실행 중이라면 다음 주소를 입력해 보세요.

페이지가 로드되지 않는다면 openclaw gateway 명령어로 Gateway를 먼저 실행해야 해요.

인증은 WebSocket 핸드셰이크 과정에서 다음 항목을 통해 이루어져요.

  • connect.params.auth.token
  • connect.params.auth.password

대시보드 설정 패널은 현재 브라우저 탭 세션과 선택한 Gateway URL에 대한 토큰을 유지해요. 비밀번호는 저장되지 않아요. 온보딩 시 기본적으로 Gateway 토큰이 생성되니, 처음 연결할 때 여기에 붙여넣으세요.

기기 페어링 (첫 연결)

섹션 제목: “기기 페어링 (첫 연결)”

새로운 브라우저나 기기에서 Control UI에 연결하면 Gateway는 일회성 페어링 승인을 요구해요. gateway.auth.allowTailscale: true 설정으로 동일한 Tailnet에 있더라도 보안을 위해 이 과정이 필요해요.

표시되는 메시지: “disconnected (1008): pairing required”

기기 승인 방법:

Terminal window
# List pending requests
openclaw devices list


# Approve by request ID
openclaw devices approve <requestId>

브라우저가 인증 정보(role/scopes/public key)를 변경하여 페어링을 재시도하면, 이전의 대기 요청은 무효화되고 새로운 requestId가 생성돼요. 승인하기 전에 openclaw devices list를 다시 실행해서 확인하세요.

한 번 승인된 기기는 기억되므로 다시 승인할 필요가 없어요. 기기를 해제하고 싶다면 openclaw devices revoke --device <id> --role <role> 명령어를 사용하세요. 토큰 교체나 해제에 대한 자세한 내용은 Devices CLI 문서를 참고해 주세요.

참고 사항:

  • 로컬 연결(127.0.0.1)은 자동으로 승인돼요.
  • 원격 연결(LAN, Tailnet 등)은 명시적인 승인이 필요해요.
  • 브라우저 프로필마다 고유한 기기 ID가 생성되므로, 브라우저를 바꾸거나 데이터를 삭제하면 다시 페어링해야 해요.

언어 지원

섹션 제목: “언어 지원”

Control UI는 브라우저 설정에 따라 첫 로드 시 언어를 자동으로 설정하며, 나중에 Access 카드의 언어 선택기에서 변경할 수 있어요.

  • 지원 언어: en, zh-CN, zh-TW, pt-BR, de, es
  • 영어 이외의 번역은 브라우저에서 지연 로딩(lazy-loaded)돼요.
  • 선택한 언어는 브라우저 저장소에 저장되어 다음 방문 시에도 유지돼요.
  • 번역 키가 없는 경우 영어로 표시돼요.

현재 가능한 기능

섹션 제목: “현재 가능한 기능”
  • Gateway WS를 통한 모델과 채팅 (chat.history, chat.send, chat.abort, chat.inject)
  • 채팅창에서 도구 호출 스트리밍 및 실시간 도구 출력 카드 표시 (agent events)
  • 채널 관리: WhatsApp/Telegram/Discord/Slack 및 플러그인 채널(Mattermost 등) 상태 확인, QR 로그인, 채널별 설정 (channels.status, web.login.*, config.patch)
  • 인스턴스: 현재 접속 목록 확인 및 새로고침 (system-presence)
  • 세션: 목록 확인 및 세션별 thinking/fast/verbose/reasoning 설정 덮어쓰기 (sessions.list, sessions.patch)
  • Cron 작업: 목록 확인, 추가, 수정, 실행, 활성화/비활성화 및 실행 기록 확인 (cron.*)
  • Skills: 상태 확인, 활성화/비활성화, 설치, API 키 업데이트 (skills.*)
  • Nodes: 목록 및 기능(caps) 확인 (node.list)
  • 실행 승인: Gateway 또는 Node 허용 목록 수정 및 exec host=gateway/node에 대한 정책 설정 (exec.approvals.*)
  • 설정: ~/.openclaw/openclaw.json 보기 및 수정 (config.get, config.set)
  • 설정 적용: 유효성 검사 후 적용 및 재시작 (config.apply), 마지막 활성 세션 깨우기
  • 설정 저장 시 base-hash 가드를 포함하여 동시 수정으로 인한 덮어쓰기 방지
  • 설정 저장(config.set/config.apply/config.patch) 전, 제출된 페이로드 내 SecretRef가 유효한지 미리 확인하며 해결되지 않은 참조는 거부돼요.
  • 설정 스키마 및 폼 렌더링: 플러그인과 채널 스키마를 포함하며, 안전한 왕복(round-trip)이 가능한 경우에만 Raw JSON 에디터 사용 가능
  • 스냅샷이 원본 텍스트를 안전하게 복원할 수 없는 경우, Control UI는 폼 모드를 강제하고 Raw 모드를 비활성화해요.
  • 구조화된 SecretRef 객체 값은 실수로 문자열로 변환되는 것을 막기 위해 폼 텍스트 입력창에서 읽기 전용으로 렌더링돼요.
  • 디버그: 상태/헬스체크/모델 스냅샷, 이벤트 로그, 수동 RPC 호출 (status, health, models.list)
  • 로그: Gateway 파일 로그 실시간 확인 및 필터링/내보내기 (logs.tail)
  • 업데이트: 패키지/git 업데이트 실행 및 재시작 보고서와 함께 재시작 (update.run)

Cron 작업 패널 참고 사항:

  • 개별 작업의 결과 전달은 기본적으로 요약 공지(announce summary)로 설정돼요. 내부 실행 전용을 원하면 ‘none’으로 바꿀 수 있어요.
  • 공지(announce)를 선택하면 채널/대상 필드가 나타나요.
  • Webhook 모드는 delivery.mode = "webhook"을 사용하며 delivery.to에 유효한 HTTP(S) URL을 설정해야 해요.
  • 메인 세션 작업의 경우 webhook과 none 전달 모드를 사용할 수 있어요.
  • 고급 편집 기능에는 실행 후 삭제, 에이전트 오버라이드 초기화, cron 정확도/지연 옵션, 모델 오버라이드 등이 포함돼요.
  • 폼 유효성 검사는 필드 단위로 실시간 처리되며, 잘못된 값이 있으면 저장 버튼이 비활성화돼요.
  • 전용 베어러 토큰을 보내려면 cron.webhookToken을 설정하세요. 생략하면 인증 헤더 없이 전송돼요.
  • 이전 버전 호환: notify: true가 설정된 기존 작업은 마이그레이션 전까지 cron.webhook을 계속 사용할 수 있어요.

Chat 동작 방식

섹션 제목: “Chat 동작 방식”
  • chat.send는 비차단(non-blocking) 방식이에요. 즉시 { runId, status: "started" }를 응답하고 결과는 chat 이벤트를 통해 스트리밍돼요.
  • 동일한 idempotencyKey로 다시 보내면 실행 중에는 { status: "in_flight" }, 완료 후에는 { status: "ok" }를 반환해요.
  • chat.history 응답은 UI 안정성을 위해 크기가 제한돼요. 내용이 너무 크면 Gateway가 텍스트를 자르거나 메타데이터를 생략하고 [chat.history omitted: message too large]라는 표시로 대체할 수 있어요.
  • chat.inject는 세션 기록에 어시스턴트 노트를 추가하고 UI 업데이트를 위한 chat 이벤트를 브로드캐스트해요. 이때 에이전트가 실행되거나 채널로 메시지가 전달되지는 않아요.
  • 중단 방법:
    • Stop 버튼 클릭 (chat.abort 호출)
    • /stop 입력 (또는 stop, stop action 등 중단 문구 입력)
    • chat.abort는 특정 세션의 모든 활성 실행을 중단하기 위해 { sessionKey }를 지원해요.
  • 중단 시 부분 저장:
    • 실행이 중단되어도 그때까지 생성된 텍스트는 UI에 표시될 수 있어요.
    • Gateway는 버퍼링된 출력이 있다면 중단된 부분까지의 텍스트를 기록에 저장해요.
    • 저장된 기록에는 중단 메타데이터가 포함되어 정상 완료된 응답과 구분할 수 있어요.

Tailnet 접속 (권장)

섹션 제목: “Tailnet 접속 (권장)”

통합 Tailscale Serve (권장 방식)

섹션 제목: “통합 Tailscale Serve (권장 방식)”

Gateway를 루프백에 유지하고 Tailscale Serve가 HTTPS 프록시 역할을 하게 하세요.

Terminal window
openclaw gateway --tailscale serve

접속 주소:

  • https://<magicdns>/ (또는 설정한 gateway.controlUi.basePath)

gateway.auth.allowTailscale이 true인 경우, Control UI/WebSocket 요청은 Tailscale ID 헤더(tailscale-user-login)를 통해 인증될 수 있어요. OpenClaw는 tailscale whois를 통해 주소를 확인하고 헤더와 일치하는지 검증해요. 보안을 위해 토큰이나 비밀번호 인증을 강제하려면 gateway.auth.allowTailscale: false로 설정하세요.

Tailnet 바인딩 + 토큰 사용

섹션 제목: “Tailnet 바인딩 + 토큰 사용”
Terminal window
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"

접속 주소:

  • http://<tailscale-ip>:18789/ (또는 설정한 gateway.controlUi.basePath)

UI 설정에 토큰을 붙여넣으세요. 이 토큰은 connect.params.auth.token으로 전송돼요.

비보안 HTTP

섹션 제목: “비보안 HTTP”

일반 HTTP(http://<lan-ip> 등)로 대시보드를 열면 브라우저가 비보안 컨텍스트로 실행되어 WebCrypto를 차단해요. 기본적으로 OpenClaw는 기기 식별 정보가 없는 Control UI 연결을 차단해요.

권장 해결책: HTTPS(Tailscale Serve)를 사용하거나 로컬에서 UI를 여세요.

  • https://<magicdns>/ (Serve 사용 시)
  • http://127.0.0.1:18789/ (Gateway 실행 호스트에서)

비보안 인증 토글 동작:

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

allowInsecureAuth는 로컬 호환성을 위한 토글이에요.

  • 비보안 HTTP 환경의 localhost 세션이 기기 식별 없이 진행되도록 허용해요.
  • 페어링 확인을 건너뛰지는 않아요.
  • 원격(localhost가 아닌) 기기의 식별 요구 사항을 완화하지 않아요.

비상용 설정 (주의):

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

dangerouslyDisableDeviceAuth는 기기 식별 확인을 완전히 비활성화하며 보안 수준을 크게 낮춰요. 비상시에만 사용하고 즉시 원복하세요.

HTTPS 설정 가이드는 Tailscale 문서를 확인해 보세요.

UI 빌드하기

섹션 제목: “UI 빌드하기”

Gateway는 dist/control-ui의 정적 파일을 제공해요. 직접 빌드하려면 다음 명령어를 사용하세요.

Terminal window
pnpm ui:build # auto-installs UI deps on first run

고정된 에셋 URL이 필요한 경우 절대 경로를 지정할 수 있어요.

Terminal window
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

로컬 개발을 위해 별도의 개발 서버를 띄우려면 다음과 같이 하세요.

Terminal window
pnpm ui:dev # auto-installs UI deps on first run

그 후 UI가 Gateway WS URL(예: ws://127.0.0.1:18789)을 바라보도록 설정하세요.

디버깅 및 테스트: 개발 서버와 원격 Gateway

섹션 제목: “디버깅 및 테스트: 개발 서버와 원격 Gateway”

Control UI는 정적 파일로 구성되며, WebSocket 대상은 HTTP 오리진과 다르게 설정할 수 있어요. 로컬에서 Vite 개발 서버를 실행하면서 Gateway는 다른 곳에서 실행 중일 때 유용해요.

  1. UI 개발 서버 시작: pnpm ui:dev
  2. 다음과 같은 URL로 접속:
http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789

일회성 인증이 필요한 경우:

http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-token>

참고 사항:

  • gatewayUrl은 로드 후 localStorage에 저장되고 URL에서 제거돼요.
  • 토큰은 가급적 URL 프래그먼트(#token=...)를 통해 전달하세요. 프래그먼트는 서버로 전송되지 않아 로그 유출을 방지할 수 있어요.
  • 비밀번호는 메모리에만 유지돼요.
  • gatewayUrl이 설정되면 UI는 환경 변수나 설정 파일의 인증 정보를 사용하지 않으므로 토큰이나 비밀번호를 명시적으로 제공해야 해요.
  • Gateway가 TLS(HTTPS 등) 뒤에 있다면 wss://를 사용하세요.
  • 클릭재킹 방지를 위해 gatewayUrl은 최상위 창에서만 허용돼요.
  • 루프백이 아닌 환경에 배포할 때는 gateway.controlUi.allowedOrigins를 명시적으로 설정해야 해요. ["*"] 설정은 테스트 환경 외에는 권장하지 않아요.

예시:

{
  gateway: {
    controlUi: {
      allowedOrigins: ["http://localhost:5173"],
    },
  },
}

원격 접속에 대한 자세한 내용은 Remote access 문서를 확인하세요.

관련 문서

섹션 제목: “관련 문서”
  • Dashboard — Gateway 대시보드
  • WebChat — 브라우저 기반 채팅 인터페이스
  • TUI — 터미널 사용자 인터페이스
  • Health Checks — Gateway 상태 모니터링

궁금한 점이 있거나 설정에 도움이 필요하면 언제든 물어봐 주세요!

AI Setup Assistant

OpenClaw

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.