메인 콘텐츠로 건너뛰기

​
웹 (Gateway)

Gateway는 Gateway WebSocket과 같은 포트에서 작은 브라우저용 Control UI(Vite + Lit)를 제공합니다.
  • 기본값: http://<host>:18789/
  • 선택적 접두사: gateway.controlUi.basePath 설정(예: /openclaw)
기능 자체는 Control UI에 정리되어 있습니다. 이 페이지는 바인드 모드, 보안, 외부에 노출되는 웹 인터페이스에 초점을 맞춥니다.

​
웹훅

hooks.enabled=true이면 Gateway는 같은 HTTP 서버에서 작은 webhook 엔드포인트도 노출합니다. 인증과 페이로드는 Gateway configuration → hooks를 참고하세요.

​
설정(기본 활성화)

Control UI는 자산(dist/control-ui)이 있으면 기본적으로 활성화됩니다. 설정으로 다음과 같이 제어할 수 있습니다. 
{
  gateway: {
    controlUi: { enabled: true, basePath: "/openclaw" }, // basePath optional
  },
}

​
Tailscale 접근

​
통합 Serve(권장)

Gateway는 loopback에만 바인드하고, Tailscale Serve가 이를 프록시하도록 둡니다. 
{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
  },
}
그런 다음 gateway를 시작합니다. 
openclaw gateway
다음 주소를 엽니다.
  • https://<magicdns>/ (또는 설정한 gateway.controlUi.basePath)

​
tailnet 바인드 + token

{
  gateway: {
    bind: "tailnet",
    controlUi: { enabled: true },
    auth: { mode: "token", token: "your-token" },
  },
}
그런 다음 gateway를 시작합니다(비-loopback 바인드에는 token이 필요). 
openclaw gateway
다음 주소를 엽니다.
  • http://<tailscale-ip>:18789/ (또는 설정한 gateway.controlUi.basePath)

​
공용 인터넷(Funnel)

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

​
보안 참고

  • Gateway auth는 기본적으로 필요합니다(token/password 또는 Tailscale identity headers).
  • 비-loopback 바인드는 여전히 공유 token/password(gateway.auth 또는 env)를 요구합니다.
  • 마법사는 기본적으로 gateway token을 생성합니다(loopback에서도 마찬가지).
  • UI는 connect.params.auth.token 또는 connect.params.auth.password를 전송합니다.
  • 비-loopback Control UI 배포에서는 gateway.controlUi.allowedOrigins를 명시적으로 설정해야 합니다(완전한 origin 값). 설정하지 않으면 기본적으로 gateway 시작이 거부됩니다.
  • gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true는 Host-header origin fallback 모드를 활성화하지만, 위험한 보안 약화입니다.
  • Serve 사용 시 gateway.auth.allowTailscale이 true이면 Tailscale identity headers로 Control UI/WebSocket 인증을 충족할 수 있습니다(token/password 불필요). HTTP API 엔드포인트는 여전히 token/password가 필요합니다. 명시적 자격 증명을 요구하려면 gateway.auth.allowTailscale: false로 설정하세요. 자세한 내용은 Tailscale 및 Security를 참고하세요. 이 토큰 없는 흐름은 gateway host가 신뢰된다는 전제를 둡니다.
  • gateway.tailscale.mode: "funnel"은 gateway.auth.mode: "password"를 요구합니다(공유 password).

​
UI 빌드

Gateway는 dist/control-ui에서 정적 파일을 제공합니다. 다음 명령으로 빌드합니다. 
pnpm ui:build # auto-installs UI deps on first run