Усунення несправностей 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/version
curl.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 :9222
netsh interface portproxy show all
curl.exe http://127.0.0.1:9222/json/version
curl.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/version
curl 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.com
openclaw browser --browser-profile remote tabs

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

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

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

Повідомлення	Значення
`control-ui-insecure-auth`	проблема джерела інтерфейсу/безпечного контексту, а не транспорту CDP
`token_missing`	проблема конфігурації автентифікації
`pairing required`	проблема схвалення пристрою
`Remote CDP for profile "remote" is not reachable`	WSL2 не може звернутися до налаштованої `cdpUrl`
порожня відповідь CDP / `other side closed` через portproxy	невідповідність прослуховувача Windows або самозациклення; перевірте обидві сім’ї loopback-адрес і `netsh interface portproxy show all`
`Browser attachOnly is enabled and CDP websocket for profile "remote" is not reachable`	кінцева точка HTTP відповіла, але не вдалося відкрити WebSocket DevTools
застаріле вікно перегляду / перевизначення темного режиму / локалі / офлайн-режиму після віддаленого сеансу	виконайте `openclaw browser --browser-profile remote stop`, щоб закрити сеанс і звільнити кешоване з’єднання Playwright/CDP без перезапуску Gateway або зовнішнього браузера
перевищення часу очікування поблизу `remoteCdpTimeoutMs` (типово 1500 мс)	зазвичай це все ще проблема доступності CDP або повільна/недоступна віддалена кінцева точка
`Playwright page enumeration timed out after 3000ms`	з’єднання з віддаленим CDP встановлено, але читання його постійних вкладок зависло; граничний час дорівнює більшому зі значень `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs`
`No Chrome tabs found for profile="user"`	вибрано локальний профіль Chrome MCP, але локальні для хоста вкладки недоступні

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

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

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

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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