OpenClaw WSL2와 Windows Chrome 연결 및 CDP 설정 가이드

WSL2 환경에서 개발하다 보면 Windows 호스트에 설치된 브라우저를 제어해야 할 일이 자주 생기죠. 하지만 네트워크 경계가 나뉘어 있다 보니 설정이 꼬이기 쉽고, 문제가 생겨도 어디서부터 손을 대야 할지 막막할 때가 많아요. 특히 여러 문제가 겹쳐서 발생하면 엉뚱한 곳을 고치느라 시간을 허비하게 되기도 합니다.

이 가이드는 OpenClaw Gateway는 WSL2 내부에서 실행되고, Chrome은 Windows에서 실행되는 일반적인 분리형 호스트 설정을 다룹니다. issue #39369에서 발견된 것처럼 여러 독립적인 문제들이 동시에 나타나서 원인 파악이 힘든 상황을 해결하는 데 도움을 드릴게요.

먼저 적절한 브라우저 모드를 선택하세요

두 가지 유효한 패턴 중 하나를 선택할 수 있어요.

옵션 1: Raw remote CDP

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

이럴 때 선택하세요:

• 브라우저 제어 기능만 필요한 경우
• Chrome 원격 디버깅을 WSL2에 노출하는 것이 괜찮은 경우
• Chrome extension relay가 필요하지 않은 경우

옵션 2: Chrome extension relay

내장된 chrome 프로필과 OpenClaw Chrome extension을 함께 사용합니다.

이럴 때 선택하세요:

• 툴바 버튼을 사용해 기존 Windows Chrome 탭에 연결하고 싶은 경우
• raw --remote-debugging-port 대신 확장 프로그램 기반의 제어를 원하는 경우
• relay 자체가 WSL2/Windows 경계를 넘어 접근 가능해야 하는 경우

네임스페이스를 가로질러 extension relay를 사용하는 경우, Browser 및 Chrome extension에서 도입된 browser.relayBindHost 설정이 중요합니다.

작동 아키텍처

참조용 구조는 다음과 같습니다:

• WSL2는 127.0.0.1:18789에서 Gateway를 실행합니다.
• Windows는 일반 브라우저에서 http://127.0.0.1:18789/ 주소로 Control UI를 엽니다.
• Windows Chrome은 9222 포트에서 CDP 엔드포인트를 노출합니다.
• WSL2는 해당 Windows CDP 엔드포인트에 도달할 수 있어야 합니다.
• OpenClaw는 WSL2에서 접근 가능한 주소로 브라우저 프로필을 설정합니다.

이 설정이 헷갈리는 이유

여러 가지 실패 원인이 겹칠 수 있기 때문이에요:

• WSL2가 Windows CDP 엔드포인트에 도달하지 못함
• Control UI가 보안 컨텍스트(secure origin)가 아닌 곳에서 열림
• gateway.controlUi.allowedOrigins가 페이지 origin과 일치하지 않음
• token이나 pairing 정보가 누락됨
• 브라우저 프로필이 잘못된 주소를 가리킴
• 실제로 크로스 네임스페이스 접근이 필요한데 extension relay가 여전히 loopback 전용으로 설정됨

이런 이유들 때문에 한 계층을 수정해도 다른 에러가 여전히 남아 있어 해결되지 않은 것처럼 보일 수 있습니다.

Control UI를 위한 핵심 규칙

Windows에서 UI를 열 때는 별도의 HTTPS 설정을 한 게 아니라면 Windows localhost를 사용하세요.

다음 주소를 사용하세요:

http://127.0.0.1:18789/

Control UI 접속 시 LAN IP를 기본으로 사용하지 마세요. LAN이나 tailnet 주소에서 일반 HTTP를 사용하면 CDP 자체와는 무관한 보안 origin/기기 인증 문제가 발생할 수 있습니다. 자세한 내용은 Control 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: 올바른 브라우저 프로필 설정하기

Raw remote 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가 성공하기를 기대하기 전에 curl로 동일한 URL을 먼저 테스트하세요.

계층 4: Chrome extension relay를 사용하는 경우

브라우저가 실행되는 머신과 Gateway가 네임스페이스 경계로 나뉘어 있다면, relay에 loopback이 아닌 bind 주소가 필요할 수 있습니다.

예시:

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

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

• 기본 동작은 relay가 loopback 전용으로 유지되므로 더 안전합니다.
• 0.0.0.0은 노출 범위를 넓힙니다.
• Gateway 인증, node pairing 및 주변 네트워크를 프라이빗하게 유지하세요.

extension relay가 필요하지 않다면 위에 설명한 raw remote CDP 프로필을 권장합니다.

계층 5: Control UI 계층을 별도로 검증하기

Windows에서 UI를 엽니다:

http://127.0.0.1:18789/

그다음 아래 사항을 확인하세요:

• 페이지 origin이 gateway.controlUi.allowedOrigins에서 기대하는 값과 일치하는지 확인
• token 인증 또는 pairing이 올바르게 설정되었는지 확인
• 브라우저 문제인데 Control UI 인증 문제를 디버깅하고 있는 건 아닌지 확인

도움이 되는 페이지:

• Control UI

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

WSL2에서 실행하세요:

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

extension relay의 경우:

openclaw browser tabs --browser-profile chrome

정상적인 결과:

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

흔히 발생하는 오해하기 쉬운 에러

각 메시지를 계층별 단서로 활용하세요:

• control-ui-insecure-auth
  • UI origin / secure-context 문제이며, 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
  • extension relay 프로필이 선택되었지만, 아직 연결된 탭이 없습니다.

빠른 진단을 위한 체크리스트

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. Control UI: LAN IP 대신 http://127.0.0.1:18789/로 접속하고 있나요?
5. Extension relay 전용: browser.relayBindHost가 정말로 필요한 상황인가요? 필요하다면 명시적으로 설정했나요?

실무적인 핵심 요약

이 설정은 충분히 구현 가능합니다. 다만 어려운 점은 브라우저 전송, Control UI origin 보안, token/pairing, 그리고 extension-relay 토폴로지 문제가 사용자 입장에서는 모두 비슷해 보이지만 각각 독립적으로 발생할 수 있다는 것이죠.

확신이 서지 않을 때는 다음 순서를 따르세요:

• 첫째, Windows Chrome 엔드포인트가 로컬에서 작동하는지 확인합니다.
• 둘째, WSL2에서 동일한 엔드포인트에 접속되는지 확인합니다.
• 그 다음에 OpenClaw 설정이나 Control UI 인증을 디버깅하세요.

AI Setup Assistant

다음 단계

• Browser
• Chrome extension
• Control UI