​

WSL2 + Windows + remote Chrome CDP troubleshooting

• OpenClaw Gateway는 WSL2 내부에서 실행
• Chrome은 Windows에서 실행
• browser control이 WSL2/Windows 경계를 넘어야 함

​

Choose the right browser mode first

​

Option 1: Raw remote CDP

• browser control만 필요할 때
• Chrome remote debugging을 WSL2에 노출하는 데 익숙할 때
• Chrome extension relay가 필요 없을 때

​

Option 2: Chrome extension relay

• toolbar button으로 기존 Windows Chrome 탭에 attach하고 싶을 때
• raw --remote-debugging-port 대신 extension 기반 제어를 원할 때
• relay 자체도 WSL2/Windows 경계를 넘어 도달 가능해야 할 때

​

Working architecture

• WSL2가 127.0.0.1:18789에서 Gateway 실행
• Windows는 일반 브라우저로 http://127.0.0.1:18789/의 Control UI 열기
• Windows Chrome은 9222 포트에서 CDP endpoint 노출
• WSL2는 그 Windows CDP endpoint에 도달 가능
• OpenClaw는 WSL2에서 도달 가능한 주소를 browser profile에 사용

​

Why this setup is confusing

• WSL2가 Windows CDP endpoint에 도달하지 못함
• Control UI가 secure하지 않은 origin에서 열림
• gateway.controlUi.allowedOrigins가 page origin과 불일치
• token 또는 pairing이 없음
• browser profile이 잘못된 주소를 가리킴
• 실제로는 cross-namespace가 필요한데 extension relay가 여전히 loopback-only

​

Critical rule for the Control UI

​

Validate in layers

​

Layer 1: Verify Chrome is serving CDP on Windows

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

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

​

Layer 2: Verify WSL2 can reach that Windows endpoint

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

• /json/version이 Browser / Protocol-Version metadata가 포함된 JSON 반환
• /json/list가 JSON 반환(열린 page가 없으면 빈 배열이어도 정상)

• Windows가 아직 그 포트를 WSL2에 노출하지 않았거나
• WSL2 쪽에서 보는 주소가 잘못되었거나
• firewall / port forwarding / local proxying이 아직 안 됐습니다

​

Layer 3: Configure the correct browser profile

{
  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로 먼저 검증하세요

​

Layer 4: If you use the Chrome extension relay instead

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

• 기본 동작이 더 안전합니다. relay가 loopback-only로 남기 때문입니다.
• 0.0.0.0는 노출 표면을 넓힙니다.
• Gateway auth, node pairing, 주변 네트워크를 private하게 유지하세요.

​

Layer 5: Verify the Control UI layer separately

• page origin이 gateway.controlUi.allowedOrigins와 일치하는지
• token auth 또는 pairing이 올바르게 설정되어 있는지
• browser 문제를 디버깅한다고 생각하면서 사실은 Control UI auth 문제를 보고 있는 건 아닌지

• Control UI

​

Layer 6: Verify end-to-end browser control

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도 같은 profile에서 동작

​

Common misleading errors

• control-ui-insecure-auth
  • UI origin / secure-context 문제이지, CDP transport 문제는 아님
• token_missing
  • auth 설정 문제
• pairing required
  • device approval 문제
• Remote CDP for profile "remote" is not reachable
  • WSL2가 설정된 cdpUrl에 도달하지 못함
• gateway timeout after 1500ms
  • 대개 여전히 CDP reachability 또는 느리거나 응답 없는 remote endpoint 문제
• Chrome extension relay is running, but no tab is connected
  • extension relay profile을 선택했지만 attach된 탭이 아직 없음

​

Fast triage checklist

1. Windows: curl http://127.0.0.1:9222/json/version가 되는가?
2. WSL2: curl http://WINDOWS_HOST_OR_IP:9222/json/version가 되는가?
3. OpenClaw config: browser.profiles.<name>.cdpUrl이 WSL2에서 도달 가능한 정확한 주소를 쓰는가?
4. Control UI: LAN IP가 아니라 http://127.0.0.1:18789/로 열고 있는가?
5. extension relay 사용 시: 정말 browser.relayBindHost가 필요한가, 필요하다면 명시적으로 설정했는가?

​

Practical takeaway

• 먼저 Windows Chrome endpoint를 로컬에서 검증
• 그다음 같은 endpoint를 WSL2에서 검증
• 그 다음에야 OpenClaw config나 Control UI auth를 디버깅