OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Web interfaces

웹

Gateway는 Gateway WebSocket과 동일한 포트에서 소규모 브라우저 제어 UI(Vite + Lit)를 제공합니다.

  • 기본값: http://<host>:18789/
  • gateway.tls.enabled: true인 경우: https://<host>:18789/
  • 선택적 접두사: gateway.controlUi.basePath를 설정합니다(예: /openclaw).

기능은 제어 UI에 설명되어 있습니다. 이 페이지에서는 바인드 모드, 보안 및 기타 웹 노출 인터페이스를 다룹니다.

구성(기본 활성화)

자산이 존재하면(dist/control-ui) 제어 UI는 기본적으로 활성화됩니다.

json5
{  gateway: {    controlUi: { enabled: true, basePath: "/openclaw" }, // basePath는 선택 사항  },}

Webhook

hooks.enabled=true이면 Gateway는 동일한 HTTP 서버에서 Webhook 엔드포인트도 노출합니다. 인증 및 페이로드에 관해서는 Gateway 구성 참조의 hooks를 참조하세요.

관리자 HTTP RPC

POST /api/v1/admin/rpc는 선택된 Gateway 제어 영역 메서드를 HTTP를 통해 노출합니다. 기본적으로 비활성화되어 있으며 admin-http-rpc Plugin이 활성화된 경우에만 등록됩니다. 인증 모델, 허용된 메서드 및 WebSocket API와의 비교에 관해서는 관리자 HTTP RPC를 참조하세요.

Tailscale 액세스

통합 Serve(권장)

Gateway를 local loopback에 유지하고 Tailscale Serve가 프록시하도록 합니다.

json5
{  gateway: {    bind: "loopback",    tailscale: { mode: "serve" },  },}

Gateway를 시작합니다.

bash
openclaw gateway

https://<magicdns>/(또는 구성한 gateway.controlUi.basePath)을 엽니다.

Tailnet 바인드 + 토큰

json5
{  gateway: {    bind: "tailnet",    controlUi: { enabled: true },    auth: { mode: "token", token: "your-token" },  },}

Gateway를 시작합니다(이 비-local loopback 예에서는 공유 비밀 토큰 인증을 사용합니다).

bash
openclaw gateway

http://<tailscale-ip>:18789/(또는 구성한 gateway.controlUi.basePath)을 엽니다.

공용 인터넷(Funnel)

json5
{  gateway: {    bind: "loopback",    tailscale: { mode: "funnel" },    auth: { mode: "password" }, // 또는 OPENCLAW_GATEWAY_PASSWORD  },}

tailscale.mode: "funnel"에는 gateway.auth.mode: "password"가 필요합니다. Serve와 Funnel 모두 gateway.bind: "loopback"이 필요합니다.

보안 참고 사항

  • Gateway 인증은 기본적으로 필요합니다. 활성화된 경우 토큰, 비밀번호, 신뢰할 수 있는 프록시 또는 Tailscale Serve ID 헤더를 사용합니다.
  • 비-local loopback 바인드에도 Gateway 인증이 필요합니다. 토큰/비밀번호 인증 또는 gateway.auth.mode: "trusted-proxy"가 설정된 ID 인식 역방향 프록시를 사용해야 합니다.
  • 온보딩 마법사는 기본적으로 공유 비밀 인증을 생성하며, local loopback에서도 일반적으로 Gateway 토큰을 생성합니다.
  • 공유 비밀 모드에서 UI는 WebSocket 핸드셰이크 중에 connect.params.auth.token 또는 connect.params.auth.password를 전송합니다.
  • gateway.tls.enabled: true이면 로컬 대시보드/상태 도우미가 https:// URL과 wss:// WebSocket URL을 렌더링합니다.
  • ID를 포함하는 모드(Tailscale Serve, trusted-proxy)에서는 공유 비밀 대신 요청 헤더를 통해 WebSocket 인증 검사가 충족됩니다.
  • 공개 비-local loopback 제어 UI 배포에서는 gateway.controlUi.allowedOrigins를 명시적으로 설정하세요(전체 오리진). local loopback, RFC1918/링크 로컬, .local, .ts.net 및 Tailscale CGNAT 호스트의 비공개 동일 오리진 로드는 이 설정 없이도 허용됩니다.
  • gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback: true는 Host 헤더 오리진 폴백을 활성화합니다. 이는 위험한 보안 수준 저하입니다.
  • Serve 사용 시 gateway.auth.allowTailscale: true이면 Tailscale ID 헤더가 제어 UI/WebSocket 인증을 충족합니다(토큰/비밀번호 불필요). HTTP API 엔드포인트는 Tailscale ID 헤더를 사용하지 않으며 항상 Gateway의 일반 HTTP 인증 모드를 따릅니다. Serve를 통해서도 명시적 자격 증명을 요구하려면 gateway.auth.allowTailscale: false를 설정하세요. 이 무토큰 흐름은 Gateway 호스트 자체를 신뢰한다고 가정합니다. Tailscale 및 보안을 참조하세요.

UI 빌드

Gateway는 dist/control-ui의 정적 파일을 제공합니다.

bash
pnpm ui:build
Was this useful?
On this page

On this page