WSL2 + Windows + 원격 Chrome CDP 문제 해결

이 가이드에서 다루는 일반적인 분할 호스트 설정:

  • OpenClaw 게이트웨이가 WSL2 내부에서 실행
  • Chrome이 Windows에서 실행
  • 브라우저 제어가 WSL2/Windows 경계를 넘어야 함

또한 이슈 #39369의 계층적 장애 패턴을 다룹니다: 여러 독립적인 문제가 동시에 나타날 수 있으며, 이로 인해 잘못된 계층이 먼저 문제처럼 보일 수 있습니다.

먼저 올바른 브라우저 모드를 선택하세요

두 가지 유효한 패턴이 있습니다:

옵션 1: 원시 원격 CDP

WSL2에서 Windows Chrome CDP 엔드포인트를 가리키는 원격 브라우저 프로필을 사용합니다.

다음 경우에 선택하세요:

  • 브라우저 제어만 필요한 경우
  • Chrome 원격 디버깅을 WSL2에 노출하는 것이 편한 경우
  • Chrome 확장 프로그램 릴레이가 필요하지 않은 경우

옵션 2: Chrome 확장 프로그램 릴레이

기본 제공 chrome 프로필과 OpenClaw Chrome 확장 프로그램을 사용합니다.

다음 경우에 선택하세요:

  • 도구 모음 버튼으로 기존 Windows Chrome 탭에 연결하고 싶은 경우
  • 원시 --remote-debugging-port 대신 확장 프로그램 기반 제어를 원하는 경우
  • 릴레이 자체가 WSL2/Windows 경계를 넘어 접근 가능해야 하는 경우

네임스페이스 간에 확장 프로그램 릴레이를 사용하는 경우, browser.relayBindHost가 브라우저 및 Chrome 확장 프로그램에서 소개된 중요한 설정입니다.

동작하는 아키텍처

참조 구조:

  • WSL2가 127.0.0.1:18789에서 게이트웨이를 실행
  • Windows가 http://127.0.0.1:18789/에서 일반 브라우저로 제어 UI를 열음
  • Windows Chrome이 포트 9222에서 CDP 엔드포인트를 노출
  • WSL2가 해당 Windows CDP 엔드포인트에 접근 가능
  • OpenClaw가 WSL2에서 접근 가능한 주소로 브라우저 프로필을 지정

이 설정이 혼란스러운 이유

여러 장애가 겹칠 수 있습니다:

  • WSL2에서 Windows CDP 엔드포인트에 접근할 수 없음
  • 제어 UI가 비보안 출처에서 열림
  • gateway.controlUi.allowedOrigins가 페이지 출처와 일치하지 않음
  • 토큰 또는 페어링 누락
  • 브라우저 프로필이 잘못된 주소를 가리킴
  • 확장 프로그램 릴레이가 실제로 크로스 네임스페이스 접근이 필요한데 여전히 루프백 전용임

이 때문에 한 계층을 수정해도 다른 오류가 여전히 보일 수 있습니다.

제어 UI의 핵심 규칙

Windows에서 UI를 열 때는 의도적인 HTTPS 설정이 없는 한 Windows localhost를 사용하세요.

사용할 주소:

http://127.0.0.1:18789/

제어 UI에 LAN IP를 기본으로 사용하지 마세요. LAN 또는 tailnet 주소에서의 일반 HTTP는 CDP 자체와 무관한 비보안 출처/장치 인증 동작을 트리거할 수 있습니다. 제어 UI를 참조하세요.

계층별 검증

위에서 아래로 작업하세요. 건너뛰지 마세요.

계층 1: Windows에서 Chrome이 CDP를 제공하는지 확인

Windows에서 원격 디버깅을 활성화한 상태로 Chrome을 시작합니다:

chrome.exe --remote-debugging-port=9222

Windows에서 먼저 Chrome 자체를 확인합니다:

curl http://127.0.0.1:9222/json/version
curl http://127.0.0.1:9222/json/list

Windows에서 이것이 실패하면 아직 OpenClaw의 문제가 아닙니다.

계층 2: WSL2에서 해당 Windows 엔드포인트에 접근 가능한지 확인

WSL2에서 cdpUrl에 사용할 정확한 주소를 테스트합니다:

curl http://WINDOWS_HOST_OR_IP:9222/json/version
curl http://WINDOWS_HOST_OR_IP:9222/json/list

성공 시 결과:

  • /json/version이 Browser / Protocol-Version 메타데이터가 포함된 JSON을 반환
  • /json/list가 JSON을 반환 (페이지가 열려 있지 않으면 빈 배열도 정상)

실패하는 경우:

  • Windows가 아직 WSL2에 포트를 노출하지 않음
  • WSL2 측의 주소가 잘못됨
  • 방화벽 / 포트 포워딩 / 로컬 프록시가 아직 설정되지 않음

OpenClaw 설정을 건드리기 전에 이것을 먼저 수정하세요.

계층 3: 올바른 브라우저 프로필 구성

원시 원격 CDP의 경우, WSL2에서 접근 가능한 주소로 OpenClaw를 설정합니다:

{
  browser: {
    enabled: true,
    defaultProfile: "remote",
    profiles: {
      remote: {
        cdpUrl: "http://WINDOWS_HOST_OR_IP:9222",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}

참고:

  • Windows에서만 동작하는 주소가 아닌 WSL2에서 접근 가능한 주소를 사용하세요
  • 외부에서 관리되는 브라우저에는 attachOnly: true를 유지하세요
  • OpenClaw가 성공하기를 기대하기 전에 동일한 URL을 curl로 테스트하세요

계층 4: 대신 Chrome 확장 프로그램 릴레이를 사용하는 경우

브라우저 머신과 게이트웨이가 네임스페이스 경계로 분리된 경우, 릴레이에 비루프백 바인드 주소가 필요할 수 있습니다.

예시:

{
  browser: {
    enabled: true,
    defaultProfile: "chrome",
    relayBindHost: "0.0.0.0",
  },
}

필요한 경우에만 사용하세요:

  • 기본 동작은 릴레이가 루프백 전용으로 유지되어 더 안전합니다
  • 0.0.0.0은 노출 범위를 확대합니다
  • 게이트웨이 인증, 노드 페어링 및 주변 네트워크를 비공개로 유지하세요

확장 프로그램 릴레이가 필요하지 않다면 위의 원시 원격 CDP 프로필을 사용하는 것이 좋습니다.

계층 5: 제어 UI 계층을 별도로 확인

Windows에서 UI를 엽니다:

http://127.0.0.1:18789/

그런 다음 확인합니다:

  • 페이지 출처가 gateway.controlUi.allowedOrigins에서 예상하는 것과 일치하는지
  • 토큰 인증 또는 페어링이 올바르게 구성되었는지
  • 브라우저 문제인 것처럼 제어 UI 인증 문제를 디버깅하고 있지 않은지

관련 페이지:

계층 6: 엔드투엔드 브라우저 제어 확인

WSL2에서:

openclaw browser open https://example.com --browser-profile remote
openclaw browser tabs --browser-profile remote

확장 프로그램 릴레이의 경우:

openclaw browser tabs --browser-profile chrome

성공 시 결과:

  • Windows Chrome에서 탭이 열림
  • openclaw browser tabs가 대상을 반환
  • 이후 액션(snapshot, screenshot, navigate)이 동일한 프로필에서 동작

자주 오해되는 오류

각 메시지를 계층별 단서로 취급하세요:

  • control-ui-insecure-auth
    • UI 출처 / 보안 컨텍스트 문제이며, CDP 전송 문제가 아님
  • token_missing
    • 인증 설정 문제
  • pairing required
    • 장치 승인 문제
  • Remote CDP for profile "remote" is not reachable
    • WSL2에서 구성된 cdpUrl에 접근할 수 없음
  • gateway timeout after 1500ms
    • 대부분 여전히 CDP 접근성 문제이거나 느린/접근 불가한 원격 엔드포인트
  • Chrome extension relay is running, but no tab is connected
    • 확장 프로그램 릴레이 프로필이 선택되었지만 아직 연결된 탭이 없음

빠른 진단 체크리스트

  1. Windows: curl http://127.0.0.1:9222/json/version이 동작하나요?
  2. WSL2: curl http://WINDOWS_HOST_OR_IP:9222/json/version이 동작하나요?
  3. OpenClaw 설정: browser.profiles.<name>.cdpUrl이 정확히 WSL2에서 접근 가능한 주소를 사용하나요?
  4. 제어 UI: LAN IP 대신 http://127.0.0.1:18789/를 열고 있나요?
  5. 확장 프로그램 릴레이만 해당: 실제로 browser.relayBindHost가 필요하며, 필요하다면 명시적으로 설정되어 있나요?

실용적 핵심 정리

이 설정은 보통 정상적으로 동작합니다. 어려운 부분은 브라우저 전송, 제어 UI 출처 보안, 토큰/페어링, 확장 프로그램 릴레이 토폴로지가 각각 독립적으로 실패할 수 있으면서 사용자 입장에서는 비슷하게 보인다는 것입니다.

의심스러울 때:

  • 먼저 Windows에서 Chrome 엔드포인트를 로컬로 확인
  • 그다음 WSL2에서 동일한 엔드포인트를 확인
  • 그런 후에야 OpenClaw 설정 또는 제어 UI 인증을 디버깅
다음
Overview
arrow_forward