OpenClaw Control UI를 홈 네트워크에서 접속하기 (Windows + TLS + 기기 페어링)

8월 02, 2026

 

OpenClaw 대시보드(Control UI)를 Mac에서 실행 중인데, Windows PC(게이밍 랩탑 / VM 등)의 브라우저에서 접속하고 싶다면?
이 가이드는 홈 네트워크 전용으로 LAN 접속을 열고, 인증서 경고 없이, 토큰을 1회만 입력하고 자동 접속되도록 설정하는 전체 과정입니다.


내부port로 접속은 가능하지만, 매번 토큰이나 비밀번호를 입력해야 하는 번거로움이 있습니다. 이를 없애려면 윈도우에서는 인증서를 생성하고 tls로 접속하는 https 주소로 접속해야지 pwa앱으로 설정가능합니다. 



 

배경: 왜 이게 필요한가?

  • OpenClaw 게이트웨이는 기본적으로 127.0.0.1:18789(루프백)에서만 대시보드를 제공합니다.
  • 그대로는 다른 PC에서 접속이 불가능 → gateway.bind: "lan"으로 바인딩을 열어야 합니다.
  • 그런데 Control UI는 보안상 HTTPS 또는 localhost에서만 기기 인증(device identity)을 허용합니다. 평문 HTTP로 LAN 접속하면 control ui requires device identity (use HTTPS or localhost secure context) 오류가 납니다.
  • 그래서 TLS(자체서명 인증서)를 구성하고, 그 인증서를 Windows의 신뢰할 수 있는 루트 인증 기관에 설치하면 인증서 경고 페이지 없이 접속할 수 있습니다.
  • 추가로 기기 페어링을 승인하면 게이트웨이 토큰을 한 번만 입력하고 이후엔 자동 인증됩니다.

준비물

  • OpenClaw가 실행 중인 Mac (게이트웨이 호스트)
  • 같은 홈 네트워크(LAN)의 Windows PC 1대 이상
  • Windows에서 관리자 권한 (인증서 설치용)

1단계: 게이트웨이를 LAN에 바인딩

gateway.bind는 보호 경로라 CLI로 변경합니다.

# 백업 먼저
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak_lan
echo '{"gateway":{"bind":"lan"}}' | openclaw config patch --stdin

확인:

openclaw config get gateway.bind   # → lan
openclaw gateway status            # Dashboard: http://<Mac의 LAN IP>:18789/ 형태로 표시

⚠️ bind: "lan"은 0.0.0.0으로 리슨합니다. 홈 네트워크(사설 IP) 전용이며, 반드시 라우터 포트포워딩을 열지 마세요. 인증(토큰)이 없으면 비루프백 바인딩 자체가 거부됩니다.

2단계: SAN 포함 자체서명 인증서 생성

autoGenerate로 만들어진 인증서는 SAN(Subject Alternative Name)이 없어서 Chrome이 신뢰해도 호스트명 불일치로 계속 경고를 냅니다. 자신의 LAN IP를 SAN으로 포함한 인증서를 직접 생성합니다.

mkdir -p ~/.openclaw/gateway/tls && cd ~/.openclaw/gateway/tls
cat > cert.cnf <<'EOF'
[req]
distinguished_name = dn
x509_extensions = v3_req
prompt = no
[dn]
CN = openclaw-gateway
[v3_req]
subjectAltName = @alt_names
basicConstraints = critical,CA:TRUE
keyUsage = critical,digitalSignature,keyEncipherment,keyCertSign
extendedKeyUsage = serverAuth
[alt_names]
IP.1 = 192.168.1.10        # ← Mac의 LAN IP로 변경
IP.2 = 127.0.0.1
DNS.1 = localhost
DNS.2 = MacStudio.local      # ← Mac 호스트명
EOF
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout gateway-custom-key.pem -out gateway-custom-cert.pem \
  -days 3650 -config cert.cnf
chmod 600 gateway-custom-key.pem
# SAN 포함 확인
openssl x509 -in gateway-custom-cert.pem -noout -text | grep -A3 "Subject Alternative Name"

CA:TRUE + keyCertSign이 있어야 Windows의 신뢰할 수 있는 루트 인증 기관으로 설치됩니다.

3단계: TLS 설정 적용 + 게이트웨이 재시작

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak_tls
echo '{"gateway":{"tls":{"enabled":true,"autoGenerate":false,"certPath":"/Users/<USER>/.openclaw/gateway/tls/gateway-custom-cert.pem","keyPath":"/Users/<USER>/.openclaw/gateway/tls/gateway-custom-key.pem"}}}' \
  | openclaw config patch --stdin
openclaw gateway restart

재시작은 활성 세션이 있으면 턴 종료 후(또는 잠시 후) 적용됩니다. 재시작 후:

curl -sk -o /dev/null -w "%{http_code}\n" https://<LAN IP>:18789/   # → 200



이 시점부터 HTTP는 차단되고 HTTPS만 동작합니다.

4단계: Windows에 인증서 신뢰 등록 (PC마다 1회)

  1. Mac의 ~/.openclaw/gateway/tls/gateway-custom-cert.pem을 Windows로 복사 (RustDesk, NAS, USB 등)
  2. 확장자를 **.crt**로 변경 (예: gateway-custom-cert.crt)
  3. 설치 방법 2가지 중 선택:
    방법 A — GUI:
    더블클릭 → 인증서 설치... → 로컬 컴퓨터 → 모든 인증서를 다음 저장소에 저장 → 신뢰할 수 있는 루트 인증 기관 → 다음 → 마침
    방법 B — PowerShell (관리자):
Import-Certificate -FilePath "C:\path\gateway-custom-cert.crt" -CertStoreLocation Cert:\LocalMachine\Root

설치 확인:

Get-ChildItem Cert:\LocalMachine\Root | Where-Object {$_.Subject -like "*openclaw*"}
  1. Chrome 완전 종료 후 재시작 (또는 PC 재부팅) — 모든 chrome.exe 프로세스가 종료되어야 반영됩니다.
    이제 https://<LAN IP>:18789/ 접속 시 인증서 경고 페이지 없이 바로 로그인 화면이 나옵니다.

5단계: 접속 + 토큰 1회 + 기기 페어링 승인

  1. Windows 브라우저에서 https://<LAN IP>:18789/ 접속
  2. 게이트웨이 토큰 1회 입력 (~/.openclaw/openclaw.json의 gateway.auth.token 또는 openclaw gateway status 참고)
  3. 새 기기라면 페어링 승인이 필요합니다 — Mac 터미널에서:
openclaw devices list # Pending 요청 확인
openclaw devices approve <requestId> # 승인
  1. 승인되면 게이트웨이가 기기 토큰을 발급 → 이후 접속은 토큰 입력 없이 자동 인증됩니다.

💡 Control UI는 게이트웨이 토큰을 브라우저에 저장하지 않습니다(메모리 전용). 자동 인증의 핵심은 기기 페어링입니다. 페어링된 기기는 기기 토큰으로 자동 접속돼요. (따라서 토큰을 매번 입력하지 않으려면 HTTPS + 페어링 구성이 필수입니다 — 평문 HTTP에서는 기기 인증이 동작하지 않아요.)

6단계: (선택) PWA로 설치

  • PWA 설치는 HTTPS 전용입니다. 위 구성(HTTPS + 신뢰된 인증서)이면 주소창 오른쪽 ⋮ → "OpenClaw Control 앱 설치" 로 설치할 수 있습니다.
  • 독립 창에서 열리고, 기기 페어링이 유지되므로 앱처럼 바로 자동 접속됩니다.

보안 주의사항 (꼭 지키세요)

  • ✅ 홈 네트워크 전용: bind: "lan"은 사설 IP 대역에서만 도달 가능. WireGuard VPN으로 외부에서 접속할 때도 "홈 네트워크 멤버"로 들어오는 것.
  • 🚫 포트포워딩 금지 — 라우터에서 18789 포트를 인터넷에 열지 마세요.
  • 🚫 Tailscale Serve/Funnel 등 공개 노출 금지 (홈 네트워크 전용 요구 시)
  • ✅ 토큰 인증 유지 — 비루프백 바인딩은 인증 없이는 시작되지 않습니다.
  • ✅ 새 기기(새 브라우저/새 PC)마다 페어링 승인 필요 — openclaw devices list로 관리.
  • 자체서명 인증서는 개인/내부용입니다. 공개 서비스라면 정식 CA(Let's Encrypt 등)를 사용하세요.

트러블슈팅

증상원인/해결
control ui requires device identityHTTP로 접속 중. HTTPS로 접속하세요.
NET::ERR_CERT_AUTHORITY_INVALID인증서가 신뢰 루트에 설치 안 됨 → 4단계 다시, Chrome 완전 재시작
NET::ERR_CERT_COMMON_NAME_INVALID인증서에 LAN IP가 SAN에 없음 → 2단계에서 IP.<n>에 자기 IP 넣고 재생성
pairing required: device is not approved yetopenclaw devices list → openclaw devices approve <requestId> (pending은 5분 만료, 브라우저 재시도 시 갱신)
접속마다 토큰 입력페어링이 꺼져 있음 → dangerouslyDisableDeviceAuth: false 확인
PWA 설치 메뉴가 안 보임HTTP로 접속 중 → HTTPS로 접속해야 PWA 설치 가능

최종 설정 요약 (openclaw.json)

{
  gateway: {
    mode: "local",
    bind: "lan",
    auth: { mode: "token", token: "..." },
    tls: {
      enabled: true,
      autoGenerate: false,
      certPath: "/Users/<USER>/.openclaw/gateway/tls/gateway-custom-cert.pem",
      keyPath: "/Users/<USER>/.openclaw/gateway/tls/gateway-custom-key.pem"
    },
    controlUi: {
      allowInsecureAuth: false,
      dangerouslyDisableDeviceAuth: false   // 기기 페어링 활성(자동 인증) — false 유지
    }
  }
}




댓글 쓰기 · 수정

0 댓글