Усунення несправностей WSL2 + Windows + віддаленого Chrome CDP

У типовій конфігурації з розділеними хостами OpenClaw Gateway працює всередині WSL2, Chrome — у Windows, а керування браузером має перетинати межу WSL2/Windows. Одночасно можуть виникати кілька незалежних проблем (див. проблему #39369): транспорт CDP, безпека джерела Control UI та токен/сполучення можуть відмовляти незалежно один від одного, створюючи схожі помилки. Послідовно перевіряйте наведені нижче рівні замість того, щоб навмання визначати, який із них несправний.

Спочатку виберіть правильний режим браузера

Варіант 1: прямий віддалений CDP із WSL2 до Windows

Використовуйте профіль віддаленого браузера, спрямований із WSL2 на кінцеву точку CDP Chrome у Windows. Вибирайте цей варіант, коли Gateway залишається всередині WSL2, Chrome працює у Windows, а керування браузером має перетинати межу WSL2/Windows.

Варіант 2: локальний для хоста Chrome MCP

Використовуйте драйвер existing-session (профіль user) лише тоді, коли Gateway працює на тому самому хості, що й Chrome, вам потрібен локальний стан браузера з виконаним входом, вам не потрібен міжхостовий транспорт браузера та не потрібні responsebody, експорт PDF, перехоплення завантажень або пакетні дії (профілі Chrome MCP їх не підтримують).

Для WSL2 Gateway + Windows Chrome використовуйте прямий віддалений CDP. Chrome MCP є локальним для хоста, а не мостом між WSL2 і Windows.

Робоча архітектура

• WSL2 запускає Gateway на 127.0.0.1:18789
• Windows відкриває Control UI у звичайному браузері за адресою http://127.0.0.1:18789/
• Chrome у Windows надає кінцеву точку CDP на порту 9222
• WSL2 може звертатися до цієї кінцевої точки CDP у Windows
• OpenClaw спрямовує профіль браузера на адресу, доступну з WSL2

Критичне правило для Control UI

Коли інтерфейс відкривається з Windows, використовуйте localhost Windows, якщо у вас немає свідомо налаштованого HTTPS:

http://127.0.0.1:18789/

Не використовуйте IP-адресу локальної мережі за замовчуванням. Звичайний HTTP на адресі локальної мережі або tailnet може спричинити поведінку, пов’язану з небезпечним джерелом чи автентифікацією пристрою, яка не стосується самого CDP. Див. Control UI.

Перевіряйте за рівнями

Рухайтеся згори вниз; не перестрибуйте наперед. Виправлення одного рівня все одно може залишити видимою іншу помилку з нижчого рівня.

Рівень 1: переконайтеся, що Chrome надає CDP у Windows

chrome.exe --remote-debugging-port=9222 --user-data-dir="$env:LOCALAPPDATA\OpenClaw\ChromeCDP"

Chrome 136 і новіші ігнорують параметри командного рядка віддаленого налагодження для стандартного каталогу даних Chrome. Використовуйте окремий, нестандартний каталог даних, як показано вище. Див. опис зміни безпеки віддаленого налагодження у Chrome. Це не робить звичайний профіль Chrome із виконаним входом доступним для віддаленого керування.

Спочатку перевірте сам Chrome із Windows:

curl.exe http://127.0.0.1:9222/json/versioncurl.exe http://127.0.0.1:9222/json/list

Якщо це не працює, діагностуйте прослуховувачі Windows нижче. На цьому етапі проблема ще не в OpenClaw.

Діагностуйте IPv4 та IPv6, перш ніж змінювати portproxy

Chromium спочатку намагається прив’язати віддалене налагодження до 127.0.0.1 і переходить на [::1], лише якщо прив’язка IPv4 не вдається. Постійне правило v4tov4, що прослуховує 127.0.0.1:9222, може зайняти цю кінцеву точку до запуску Chrome. Тоді Chrome переходить на [::1]:9222, а старе правило переспрямовує трафік IPv4 назад на власний прослуховувач і повертає порожню відповідь.

Перевірте фактичні прослуховувачі та правила проксі у Windows замість того, щоб робити висновки на основі версії Chrome:

netstat -ano | findstr :9222netsh interface portproxy show allcurl.exe http://127.0.0.1:9222/json/versioncurl.exe http://[::1]:9222/json/version

Використовуйте tasklist /fi "PID eq <PID>" для кожного PID із netstat.

• Якщо chrome.exe відповідає на 127.0.0.1, видаліть усі правила portproxy, які також прослуховують 127.0.0.1:9222. Переспрямовуйте лише адресу адаптера Windows, доступну з WSL2, на 127.0.0.1.

• Якщо chrome.exe відповідає лише на [::1], спрямуйте доступний із WSL2 прослуховувач на ::1 за допомогою v4tov6 замість переспрямування на невикористовувану адресу IPv4:

  netsh interface portproxy add v4tov6 listenaddress=WINDOWS_HOST_OR_IP listenport=9222 connectaddress=::1 connectport=9222

Прив’яжіть прослуховувач до адреси адаптера, потрібної WSL2. Не відкривайте порт CDP на 0.0.0.0, адресі локальної мережі чи адресі tailnet: CDP надає контроль над сеансом браузера.

Рівень 2: переконайтеся, що WSL2 може звертатися до цієї кінцевої точки Windows

Із WSL2 перевірте точну адресу, яку плануєте використовувати в cdpUrl:

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

Успішний результат:

• /json/version повертає JSON із метаданими Browser / Protocol-Version
• /json/list повертає JSON (порожній масив допустимий, якщо немає відкритих сторінок)

Якщо це не працює, Windows ще не надає порт для WSL2, адреса неправильна для сторони WSL2 або відсутні брандмауер, переспрямування портів чи проксіювання. Виправте це, перш ніж змінювати конфігурацію OpenClaw.

Рівень 3: налаштуйте правильний профіль браузера

Спрямуйте OpenClaw на адресу, доступну з WSL2:

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

Примітки:

• використовуйте адресу, доступну з WSL2, а не ту, що працює лише у Windows
• залишайте attachOnly: true для браузерів із зовнішнім керуванням
• cdpUrl може мати схему http://, https://, ws:// або wss://
• використовуйте HTTP(S), якщо потрібно, щоб OpenClaw виявляв /json/version
• використовуйте WS(S) лише тоді, коли постачальник браузера надає пряму URL-адресу сокета DevTools
• перевірте ту саму URL-адресу за допомогою curl, перш ніж очікувати успішної роботи OpenClaw

Рівень 4: окремо перевірте рівень Control UI

Відкрийте http://127.0.0.1:18789/ із Windows, а потім перевірте:

• джерело сторінки відповідає очікуванню gateway.controlUi.allowedOrigins
• автентифікацію за токеном або сполучення налаштовано правильно
• ви не діагностуєте проблему автентифікації Control UI як проблему браузера

Корисна сторінка: Control UI.

Рівень 5: перевірте наскрізне керування браузером

Із WSL2:

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

Успішний результат:

• вкладка відкривається в Chrome у Windows
• browser tabs повертає ціль
• подальші дії (snapshot, screenshot, navigate) працюють із того самого профілю

Поширені оманливі помилки

Контрольний список швидкої діагностики

1. Windows: яка з адрес — 127.0.0.1 чи [::1] — відповідає на /json/version, і чи належить цей прослуховувач процесу chrome.exe?
2. WSL2: чи працює curl http://WINDOWS_HOST_OR_IP:9222/json/version?
3. Конфігурація OpenClaw: чи використовує browser.profiles.<name>.cdpUrl саме цю адресу, доступну з WSL2?
4. Control UI: чи відкриваєте ви http://127.0.0.1:18789/ замість IP-адреси локальної мережі?
5. Чи не намагаєтеся ви використовувати existing-session між WSL2 і Windows замість прямого віддаленого CDP?

Спочатку перевірте кінцеву точку Chrome у Windows локально, потім — ту саму кінцеву точку з WSL2, і лише після цього діагностуйте конфігурацію OpenClaw або автентифікацію Control UI.

Пов’язані матеріали

• Браузер
• Вхід у браузері
• Усунення проблем із браузером у Linux