Web Gateway 설정 및 Control UI 가이드

로컬에서 작업 중인 서비스를 외부에서 확인하거나 관리하고 싶을 때, 매번 포트 포워딩을 설정하고 보안을 고민하는 과정은 꽤나 번거롭습니다. 특히 브라우저 UI를 별도로 구성하고 API와 연결하다 보면 CORS 설정이나 인증 문제로 시간을 허비하기 일쑤죠.

이 가이드에서는 Gateway를 통해 브라우저에서 바로 사용할 수 있는 Control UI를 띄우고, 복잡한 설정 없이 안전하게 외부 접속을 구성하는 방법을 소개할게요.

필요한 것

• dist/control-ui 내의 정적 에셋
• Gateway WebSocket (기본 포트: 18789)
• pnpm (UI 빌드용)
• Tailscale (원격 접속 사용 시 선택 사항)

빠른 시작

5분 안에 Control UI를 실행하는 방법이에요.

1. UI 빌드하기: 먼저 UI 정적 파일을 생성해야 해요.

   pnpm ui:build

2. 설정 확인: gateway.controlUi.enabled가 true인지 확인하세요 (기본값입니다).
3. Gateway 실행:

   openclaw gateway

4. 접속: 브라우저에서 http://localhost:18789/에 접속하세요.

Tailscale로 안전하게 접속하기

가장 추천하는 방식은 Tailscale을 사용하는 거예요. 환경에 따라 세 가지 모드 중 선택할 수 있어요.

1. Integrated Serve (권장)

Gateway를 루프백에 유지하면서 Tailscale Serve가 프록시 역할을 수행하게 합니다.

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

설정 후 openclaw gateway를 실행하고 https://<magicdns>/로 접속하세요.

2. Tailnet bind + token

Tailscale 네트워크 인터페이스에 직접 바인딩하는 방식이에요. 이 경우 반드시 토큰 인증이 필요합니다.

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

접속 주소: http://<tailscale-ip>:18789/

3. Public internet (Funnel)

인터넷을 통해 완전히 공개해야 할 때 사용하세요.

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password" },
  },
}

Security 및 Webhooks

• 보안: Gateway 인증은 기본적으로 활성화되어 있습니다 (token/password 또는 Tailscale identity headers). 루프백 바인딩이라도 마법사(wizard)가 기본 토큰을 생성해요.
• Webhooks: hooks.enabled=true로 설정하면 동일한 HTTP 서버에서 webhook 엔드포인트를 사용할 수 있습니다.
• UI 보안: Control UI는 안티 클릭재킹 헤더를 전송하며, gateway.controlUi.allowedOrigins를 설정하지 않으면 동일 출처(same-origin)의 WebSocket 연결만 허용해요.

문제 해결

• UI가 로드되지 않나요?: pnpm ui:build를 실행했는지 확인해 보세요. dist/control-ui에 파일이 있어야 Gateway가 서빙할 수 있습니다.
• 인증 오류가 발생하나요?: 루프백이 아닌 다른 주소로 바인딩할 때는 반드시 gateway.auth 설정이나 환경 변수를 통해 공유 토큰 또는 패스워드를 설정해야 합니다.

더 궁금한 점이 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

• Control UI 상세 기능
• Gateway configuration 상세 설정
• Tailscale 연동 가이드
• 보안 설정 가이드