Браузер (керований OpenClaw)

OpenClaw може запускати окремий профіль Chrome/Brave/Edge/Chromium, яким керує агент. Він ізольований від вашого особистого браузера й керується через невеликий локальний сервіс керування всередині Gateway (лише local loopback).

Погляд для початківців:

• Уявляйте це як окремий браузер лише для агента.
• Профіль openclaw не торкається вашого особистого профілю браузера.
• Агент може відкривати вкладки, читати сторінки, натискати й вводити текст у безпечному каналі.
• Вбудований профіль user під’єднується до вашої реальної сесії Chrome із виконаним входом через Chrome MCP.

Що ви отримуєте

• Окремий профіль браузера з назвою openclaw (типово з помаранчевим акцентом).
• Детерміноване керування вкладками (список/відкрити/фокус/закрити).
• Дії агента (натискання/введення/перетягування/вибір), знімки стану, скриншоти, PDF.
• Вбудований Skill browser-automation, який навчає агентів циклу відновлення для snapshot, stable-tab, stale-ref і manual-blocker, коли браузерний plugin увімкнено.
• Необов’язкову підтримку кількох профілів (openclaw, work, remote, ...).

Цей браузер не призначений для щоденного використання. Це безпечна, ізольована поверхня для автоматизації та перевірки агентом.

Швидкий старт

openclaw browser --browser-profile openclaw doctoropenclaw browser --browser-profile openclaw doctor --deepopenclaw browser --browser-profile openclaw statusopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

Якщо ви отримуєте "Browser disabled", увімкніть його в конфігурації (див. нижче) і перезапустіть Gateway.

Якщо openclaw browser повністю відсутня або агент каже, що браузерний інструмент недоступний, перейдіть до Відсутня команда або інструмент браузера.

Керування Plugin

Типовий інструмент browser є вбудованим plugin. Вимкніть його, щоб замінити іншим plugin, який реєструє ту саму назву інструмента browser:

{  plugins: {    entries: {      browser: {        enabled: false,      },    },  },}

Для типових значень потрібні і plugins.entries.browser.enabled, і browser.enabled=true. Вимкнення лише plugin прибирає CLI openclaw browser, метод gateway browser.request, інструмент агента й сервіс керування як єдине ціле; ваша конфігурація browser.* залишається недоторканою для заміни.

Зміни конфігурації браузера потребують перезапуску Gateway, щоб plugin міг повторно зареєструвати свій сервіс.

Настанови для агента

Примітка щодо профілю інструментів: tools.profile: "coding" містить web_search і web_fetch, але не містить повного інструмента browser. Якщо агент або створений субагент має використовувати браузерну автоматизацію, додайте browser на етапі профілю:

{  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

Для одного агента використовуйте agents.list[].tools.alsoAllow: ["browser"]. Лише tools.subagents.tools.allow: ["browser"] недостатньо, бо політика субагента застосовується після фільтрації профілю.

Браузерний plugin постачається з двома рівнями настанов для агента:

• Опис інструмента browser містить стислий постійно активний контракт: вибирати правильний профіль, утримувати refs у межах тієї самої вкладки, використовувати tabId/мітки для націлювання на вкладку й завантажувати браузерний Skill для багатоетапної роботи.
• Вбудований Skill browser-automation містить довший робочий цикл: спочатку перевірити status/tabs, позначити вкладки завдання, зробити snapshot перед дією, повторити snapshot після змін UI, один раз відновитися після stale refs і повідомляти про login/2FA/captcha або блокувальники camera/microphone як про ручну дію замість припущень.

Skills, вбудовані в plugin, перелічуються серед доступних Skills агента, коли plugin увімкнено. Повні інструкції Skill завантажуються на вимогу, тому звичайні ходи не сплачують повну вартість у токенах.

Відсутня команда або інструмент браузера

Якщо openclaw browser невідома після оновлення, browser.request відсутній або агент повідомляє, що браузерний інструмент недоступний, звична причина — список plugins.allow, який пропускає browser, і відсутній кореневий блок конфігурації browser. Додайте його:

{  plugins: {    allow: ["telegram", "browser"],  },}

Явний кореневий блок browser, наприклад browser.enabled=true або browser.profiles.<name>, активує вбудований браузерний plugin навіть за обмежувального plugins.allow, відповідно до поведінки конфігурації каналів. plugins.entries.browser.enabled=true і tools.alsoAllow: ["browser"] самі собою не замінюють членство в allowlist. Повне видалення plugins.allow також відновлює типову поведінку.

Профілі: openclaw проти user

• openclaw: керований, ізольований браузер (розширення не потрібне).
• user: вбудований профіль Chrome MCP attach для вашої реальної сесії Chrome із виконаним входом.

Для викликів браузерного інструмента агентом:

• Типово: використовуйте ізольований браузер openclaw.
• Віддавайте перевагу profile="user", коли важливі наявні сесії з виконаним входом і користувач перебуває за комп’ютером, щоб натиснути/схвалити будь-який attach prompt.
• profile — явне перевизначення, коли потрібен конкретний режим браузера.

Установіть browser.defaultProfile: "openclaw", якщо хочете керований режим за замовчуванням.

Конфігурація

Налаштування браузера містяться в ~/.openclaw/openclaw.json.

{  browser: {    enabled: true, // default: true    ssrfPolicy: {      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access      // allowPrivateNetwork: true, // legacy alias      // hostnameAllowlist: ["*.example.com", "example.com"],      // allowedHostnames: ["localhost"],    },    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)    localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms)    localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms)    actionTimeoutMs: 60000, // default browser act timeout (ms)    tabCleanup: {      enabled: true, // default: true      idleMinutes: 120, // set 0 to disable idle cleanup      maxTabsPerSession: 8, // set 0 to disable the per-session cap      sweepMinutes: 5,    },    defaultProfile: "openclaw",    color: "#FF4500",    headless: false,    noSandbox: false,    attachOnly: false,    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",    profiles: {      openclaw: { cdpPort: 18800, color: "#FF4500" },      work: {        cdpPort: 18801,        color: "#0066CC",        headless: true,        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",      },      user: {        driver: "existing-session",        attachOnly: true,        color: "#00AA00",      },      brave: {        driver: "existing-session",        attachOnly: true,        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",        color: "#FB542B",      },      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },    },  },}

Зір скриншотів (підтримка текстової моделі)

Коли основна модель є лише текстовою (без підтримки vision/мультимодальності), браузерні скриншоти повертають блоки зображень, які модель не може прочитати. Браузерні скриншоти повторно використовують наявну конфігурацію розуміння зображень, тому модель зображень, налаштована для розуміння медіа, може описувати скриншоти як текст без будь-яких специфічних для браузера налаштувань моделі.

{  tools: {    media: {      image: {        models: [          { provider: "bytedance", model: "doubao-seed-2.0-pro" },          // Add fallback candidates; first success wins          { provider: "openai", model: "gpt-4o" },        ],      },      // Shared media models also work when tagged for image support.      // models: [{ provider: "openai", model: "gpt-4o", capabilities: ["image"] }],    },  },  agents: {    defaults: {      // Existing image-model defaults are also honored.      // imageModel: { primary: "openai/gpt-4o" },    },  },}

Як це працює:

1. Агент викликає browser screenshot → зображення, як зазвичай, записується на диск.
2. Браузерний інструмент запитує наявний runtime розуміння зображень, чи може він описати скриншот за допомогою налаштованих медіамоделей зображень, спільних медіамоделей, типових значень image-model або image provider на основі автентифікації.
3. Модель vision повертає текстовий опис, який обгортається через wrapExternalContent (захист від prompt injection) і повертається агенту як текстовий блок замість блоку зображення.
4. Якщо розуміння зображень недоступне, пропущене або завершується помилкою, браузер повертається до повернення початкового блоку зображення.

Використовуйте наявні поля tools.media.image / tools.media.models для model fallbacks, timeouts, byte limits, profiles і налаштувань provider request.

Якщо активна основна модель уже підтримує vision і явна модель розуміння зображень не налаштована, OpenClaw зберігає звичайний результат зображення, щоб основна модель могла прочитати скриншот напряму.

Використання Brave або іншого браузера на базі Chromium

Якщо ваш системний браузер за замовчуванням базується на Chromium (Chrome/Brave/Edge/тощо), OpenClaw використовує його автоматично. Задайте browser.executablePath, щоб перевизначити автовиявлення. Значення executablePath верхнього рівня та профільні значення приймають ~ для домашнього каталогу вашої ОС:

openclaw config set browser.executablePath "/usr/bin/google-chrome"openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

Або задайте це в конфігурації для кожної платформи:

{browser: {executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",},}

{browser: {executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",},}

{browser: {executablePath: "/usr/bin/brave-browser",},}

Профільний executablePath впливає лише на локальні керовані профілі, які запускає OpenClaw. Профілі existing-session натомість підключаються до вже запущеного браузера, а віддалені CDP-профілі використовують браузер за cdpUrl.

Локальне та віддалене керування

• Локальне керування (за замовчуванням): Gateway запускає службу керування local loopback і може запускати локальний браузер.
• Віддалене керування (node host): запустіть node host на машині, де є браузер; Gateway проксіює дії браузера до нього.
• Віддалений CDP: задайте browser.profiles.<name>.cdpUrl (або browser.cdpUrl), щоб підключитися до віддаленого браузера на базі Chromium. У цьому випадку OpenClaw не запускатиме локальний браузер.
• Для зовнішньо керованих CDP-сервісів на loopback (наприклад Browserless у Docker, опублікований на 127.0.0.1) також задайте attachOnly: true. Loopback CDP без attachOnly розглядається як локальний профіль браузера, керований OpenClaw.
• headless впливає лише на локальні керовані профілі, які запускає OpenClaw. Він не перезапускає й не змінює браузери existing-session або віддалені CDP-браузери.
• executablePath дотримується того самого правила локального керованого профілю. Зміна його для запущеного локального керованого профілю позначає цей профіль для перезапуску/узгодження, щоб наступний запуск використав новий виконуваний файл.

Поведінка зупинки відрізняється залежно від режиму профілю:

• локальні керовані профілі: openclaw browser stop зупиняє процес браузера, який запустив OpenClaw
• профілі attach-only і віддалені CDP-профілі: openclaw browser stop закриває активний сеанс керування та звільняє перевизначення емуляції Playwright/CDP (viewport, колірну схему, локаль, часовий пояс, offline-режим і подібний стан), навіть якщо OpenClaw не запускав процес браузера

Віддалені CDP-URL можуть містити автентифікацію:

• Токени запиту (наприклад, https://provider.example?token=<token>)
• HTTP Basic auth (наприклад, https://user:pass@provider.example)

OpenClaw зберігає автентифікацію під час виклику кінцевих точок /json/* і під час підключення до CDP WebSocket. Для токенів надавайте перевагу змінним середовища або менеджерам секретів замість коміту їх у файли конфігурації.

Проксі браузера Node (zero-config за замовчуванням)

Якщо ви запускаєте node host на машині, де є ваш браузер, OpenClaw може автоматично маршрутизувати виклики інструментів браузера до цього вузла без додаткової конфігурації браузера. Це типовий шлях для віддалених gateway.

Примітки:

• Node host надає свій локальний сервер керування браузером через команду проксі.
• Профілі беруться з власної конфігурації browser.profiles вузла (так само, як локально).
• nodeHost.browserProxy.allowProfiles є необов’язковим. Залиште його порожнім для застарілої/типової поведінки: усі налаштовані профілі залишаються доступними через проксі, включно з маршрутами створення/видалення профілів.
• Якщо ви задаєте nodeHost.browserProxy.allowProfiles, OpenClaw розглядає це як межу найменших привілеїв: цільовими можуть бути лише профілі з allowlist, а сталі маршрути створення/видалення профілів блокуються на поверхні проксі.
• Вимкніть, якщо це не потрібно:
  • На вузлі: nodeHost.browserProxy.enabled=false
  • На gateway: gateway.nodes.browser.mode="off"

Browserless (хостований віддалений CDP)

Browserless — це хостований сервіс Chromium, який надає CDP URL-адреси підключення через HTTPS і WebSocket. OpenClaw може використовувати обидві форми, але для віддаленого профілю браузера найпростіший варіант — прямий WebSocket URL з документації Browserless щодо підключення.

Приклад:

{  browser: {    enabled: true,    defaultProfile: "browserless",    remoteCdpTimeoutMs: 2000,    remoteCdpHandshakeTimeoutMs: 4000,    profiles: {      browserless: {        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",        color: "#00AA00",      },    },  },}

Примітки:

• Замініть <BROWSERLESS_API_KEY> на ваш справжній токен Browserless.
• Оберіть регіональну кінцеву точку, що відповідає вашому обліковому запису Browserless (див. їхню документацію).
• Якщо Browserless надає базовий HTTPS URL, ви можете або перетворити його на wss:// для прямого CDP-підключення, або залишити HTTPS URL і дозволити OpenClaw виявити /json/version.

Browserless Docker на тому самому хості

Коли Browserless самостійно розміщений у Docker, а OpenClaw працює на хості, розглядайте Browserless як зовнішньо керований CDP-сервіс:

{  browser: {    enabled: true,    defaultProfile: "browserless",    profiles: {      browserless: {        cdpUrl: "ws://127.0.0.1:3000",        attachOnly: true,        color: "#00AA00",      },    },  },}

Адреса в browser.profiles.browserless.cdpUrl має бути доступною з процесу OpenClaw. Browserless також має рекламувати відповідну доступну кінцеву точку; задайте Browserless EXTERNAL на ту саму WebSocket-базу, публічну для OpenClaw, наприклад ws://127.0.0.1:3000, ws://browserless:3000 або стабільну приватну адресу мережі Docker. Якщо /json/version повертає webSocketDebuggerUrl, що вказує на адресу, недоступну для OpenClaw, CDP HTTP може виглядати справним, тоді як WebSocket-підключення все одно не вдасться.

Не залишайте attachOnly незаданим для loopback-профілю Browserless. Без attachOnly OpenClaw розглядає loopback-порт як локальний керований профіль браузера і може повідомити, що порт використовується, але не належить OpenClaw.

Прямі WebSocket CDP-провайдери

Деякі хостовані браузерні сервіси надають пряму WebSocket кінцеву точку, а не стандартне HTTP-виявлення CDP (/json/version). OpenClaw приймає три форми CDP URL і автоматично обирає правильну стратегію підключення:

• HTTP(S)-виявлення - http://host[:port] або https://host[:port]. OpenClaw викликає /json/version, щоб виявити WebSocket URL налагоджувача, а потім підключається. Без резервного WebSocket.
• Прямі WebSocket-кінцеві точки - ws://host[:port]/devtools/<kind>/<id> або wss://... зі шляхом /devtools/browser|page|worker|shared_worker|service_worker/<id>. OpenClaw підключається напряму через WebSocket handshake і повністю пропускає /json/version.
• Голі WebSocket-корені - ws://host[:port] або wss://host[:port] без шляху /devtools/... (наприклад, Browserless, Browserbase). OpenClaw спершу пробує HTTP виявлення /json/version (нормалізуючи схему до http/https); якщо виявлення повертає webSocketDebuggerUrl, використовується він, інакше OpenClaw переходить до прямого WebSocket handshake на голому корені. Якщо рекламована WebSocket-кінцева точка відхиляє CDP handshake, але налаштований голий корінь приймає його, OpenClaw також повертається до цього кореня. Це дозволяє голому ws://, спрямованому на локальний Chrome, усе одно підключитися, оскільки Chrome приймає WebSocket upgrades лише на конкретному цільовому шляху з /json/version, тоді як хостовані провайдери все ще можуть використовувати свою кореневу WebSocket-кінцеву точку, коли їхня кінцева точка виявлення рекламує короткоживучий URL, непридатний для Playwright CDP.

openclaw browser doctor використовує ту саму логіку спершу-виявлення, WebSocket-fallback, що й runtime attach, тому голий кореневий URL, який успішно підключається, не позначається діагностикою як недоступний.

Browserbase

Browserbase — це хмарна платформа для запуску headless-браузерів із вбудованим розв’язанням CAPTCHA, stealth-режимом і residential проксі.

{  browser: {    enabled: true,    defaultProfile: "browserbase",    remoteCdpTimeoutMs: 3000,    remoteCdpHandshakeTimeoutMs: 5000,    profiles: {      browserbase: {        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",        color: "#F97316",      },    },  },}

Примітки:

• Зареєструйтеся і скопіюйте свій API Key з панелі огляду.
• Замініть <BROWSERBASE_API_KEY> на свій справжній API-ключ Browserbase.
• Browserbase автоматично створює браузерну сесію під час підключення WebSocket, тому крок ручного створення сесії не потрібен.
• Безплатний рівень дозволяє одну одночасну сесію та одну браузерну годину на місяць. Див. ціни, щоб дізнатися ліміти платних планів.
• Див. документацію Browserbase, щоб отримати повний довідник API, посібники SDK та приклади інтеграції.

Notte

Notte — це хмарна платформа для запуску headless браузерів із вбудованим stealth, резидентними проксі та CDP-native Gateway WebSocket.

{  browser: {    enabled: true,    defaultProfile: "notte",    remoteCdpTimeoutMs: 3000,    remoteCdpHandshakeTimeoutMs: 5000,    profiles: {      notte: {        cdpUrl: "wss://us-prod.notte.cc/sessions/connect?token=<NOTTE_API_KEY>",        color: "#7C3AED",      },    },  },}

Примітки:

• Зареєструйтеся і скопіюйте свій API Key зі сторінки налаштувань консолі.
• Замініть <NOTTE_API_KEY> на свій справжній API-ключ Notte.
• Notte автоматично створює браузерну сесію під час підключення WebSocket, тому крок ручного створення сесії не потрібен. Сесію знищується, коли WebSocket відключається.
• Безплатний рівень дозволяє п’ять одночасних сесій і 100 браузерних годин протягом усього строку користування. Див. ціни, щоб дізнатися ліміти платних планів.
• Див. документацію Notte, щоб отримати повний довідник API, посібники SDK та приклади інтеграції.

Безпека

Ключові ідеї:

• Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або сполучення вузлів.
• Автономний loopback HTTP API браузера використовує лише автентифікацію спільним секретом: автентифікацію bearer токеном Gateway, x-openclaw-password або HTTP Basic auth із налаштованим паролем Gateway.
• Заголовки ідентичності Tailscale Serve та gateway.auth.mode: "trusted-proxy" не автентифікують цей автономний loopback API браузера.
• Якщо керування браузером увімкнено й автентифікацію спільним секретом не налаштовано, OpenClaw генерує лише runtime-токен Gateway для цього запуску. Налаштуйте gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN або OPENCLAW_GATEWAY_PASSWORD явно, якщо клієнтам потрібен стабільний секрет між перезапусками.
• OpenClaw не генерує цей токен автоматично, коли gateway.auth.mode уже має значення password, none або trusted-proxy.
• Тримайте Gateway і будь-які хости вузлів у приватній мережі (Tailscale); уникайте публічного доступу.
• Розглядайте віддалені CDP URL/токени як секрети; надавайте перевагу env vars або менеджеру секретів.

Поради щодо віддаленого CDP:

• Надавайте перевагу зашифрованим endpoint (HTTPS або WSS) і короткостроковим токенам, де це можливо.
• Уникайте вбудовування довгострокових токенів безпосередньо у конфігураційні файли.

Профілі (кілька браузерів)

OpenClaw підтримує кілька іменованих профілів (конфігурацій маршрутизації). Профілі можуть бути:

• openclaw-managed: виділений екземпляр браузера на базі Chromium із власним каталогом даних користувача + CDP-портом
• remote: явний CDP URL (браузер на базі Chromium, що працює в іншому місці)
• existing session: ваш наявний профіль Chrome через автоматичне підключення Chrome DevTools MCP

Типові значення:

• Профіль openclaw створюється автоматично, якщо його немає.
• Профіль user є вбудованим для приєднання до наявної сесії Chrome MCP.
• Профілі наявних сесій, окрім user, вмикаються явно; створюйте їх за допомогою --driver existing-session.
• Локальні CDP-порти типово виділяються з діапазону 18800-18899.
• Видалення профілю переміщує його локальний каталог даних до Кошика.

Усі контрольні endpoint приймають ?profile=<name>; CLI використовує --browser-profile.

Наявна сесія через Chrome DevTools MCP

OpenClaw також може приєднуватися до запущеного профілю браузера на базі Chromium через офіційний сервер Chrome DevTools MCP. Це повторно використовує вкладки та стан входу, які вже відкриті в цьому профілі браузера.

Офіційні довідкові матеріали та посилання для налаштування:

• Chrome for Developers: Use Chrome DevTools MCP with your browser session
• Chrome DevTools MCP README

Вбудований профіль:

• user

Необов’язково: створіть власний користувацький профіль наявної сесії, якщо вам потрібні інша назва, колір або каталог даних браузера.

Типова поведінка:

• Вбудований профіль user використовує автоматичне підключення Chrome MCP, яке націлюється на типовий локальний профіль Google Chrome.

Використовуйте userDataDir для Brave, Edge, Chromium або нетипового профілю Chrome. ~ розгортається до домашнього каталогу вашої ОС:

{  browser: {    profiles: {      brave: {        driver: "existing-session",        attachOnly: true,        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",        color: "#FB542B",      },    },  },}

Потім у відповідному браузері:

1. Відкрийте сторінку inspect цього браузера для віддаленого налагодження.
2. Увімкніть віддалене налагодження.
3. Залиште браузер запущеним і схваліть запит на підключення, коли OpenClaw приєднається.

Поширені сторінки inspect:

• Chrome: chrome://inspect/#remote-debugging
• Brave: brave://inspect/#remote-debugging
• Edge: edge://inspect/#remote-debugging

Smoke test живого приєднання:

openclaw browser --browser-profile user startopenclaw browser --browser-profile user statusopenclaw browser --browser-profile user tabsopenclaw browser --browser-profile user snapshot --format ai

Як виглядає успіх:

• status показує driver: existing-session
• status показує transport: chrome-mcp
• status показує running: true
• tabs перелічує ваші вже відкриті вкладки браузера
• snapshot повертає refs з вибраної живої вкладки

Що перевірити, якщо приєднання не працює:

• цільовий браузер на базі Chromium має версію 144+
• віддалене налагодження ввімкнено на сторінці inspect цього браузера
• браузер показав запит згоди на приєднання, і ви його прийняли
• якщо Chrome запущено з явним --remote-debugging-port, задайте browser.profiles.<name>.cdpUrl на цей endpoint DevTools замість покладання на автоматичне підключення Chrome MCP
• openclaw doctor мігрує стару конфігурацію браузера на основі розширення та перевіряє, що Chrome встановлено локально для типових профілів автоматичного підключення, але він не може увімкнути для вас віддалене налагодження з боку браузера

Використання агентом:

• Використовуйте profile="user", коли потрібен стан браузера користувача з виконаним входом.
• Якщо ви використовуєте користувацький профіль наявної сесії, передайте цю явну назву профілю.
• Обирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб схвалити запит на приєднання.
• Gateway або хост вузла може запускати npx chrome-devtools-mcp@latest --autoConnect

Примітки:

• Цей шлях має вищий ризик, ніж ізольований профіль openclaw, оскільки він може діяти всередині вашої сесії браузера з виконаним входом.
• OpenClaw не запускає браузер для цього драйвера; він лише приєднується.
• OpenClaw тут використовує офіційний потік Chrome DevTools MCP --autoConnect. Якщо задано userDataDir, його передають далі, щоб націлитися на цей каталог даних користувача.
• Наявна сесія може приєднуватися на вибраному хості або через підключений браузерний вузол. Якщо Chrome розміщено в іншому місці й браузерний вузол не підключено, використовуйте віддалений CDP або хост вузла натомість.

Користувацький запуск Chrome MCP

Перевизначте породжений сервер Chrome DevTools MCP для кожного профілю, коли типовий потік npx chrome-devtools-mcp@latest не відповідає вашим потребам (офлайн-хости, зафіксовані версії, вендорні бінарні файли):

Коли cdpUrl задано для профілю наявної сесії, OpenClaw пропускає --autoConnect і автоматично передає endpoint до Chrome MCP:

• http(s)://... → --browserUrl <url> (HTTP endpoint виявлення DevTools).
• ws(s)://... → --wsEndpoint <url> (прямий CDP WebSocket).

Прапорці endpoint і userDataDir не можна поєднувати: коли задано cdpUrl, userDataDir ігнорується для запуску Chrome MCP, оскільки Chrome MCP приєднується до запущеного браузера за endpoint, а не відкриває каталог профілю.

Гарантії ізоляції

• Виділений каталог даних користувача: ніколи не торкається вашого особистого профілю браузера.
• Виділені порти: уникає 9222, щоб запобігти конфліктам із dev workflows.
• Детерміноване керування вкладками: tabs повертає спочатку suggestedTargetId, потім стабільні handles tabId, як-от t1, необов’язкові мітки та raw targetId. Агенти мають повторно використовувати suggestedTargetId; raw ids залишаються доступними для налагодження та сумісності.

Вибір браузера

Під час локального запуску OpenClaw обирає перший доступний:

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

Можна перевизначити за допомогою browser.executablePath.

Платформи:

• macOS: перевіряє /Applications і ~/Applications.
• Linux: перевіряє поширені розташування Chrome/Brave/Edge/Chromium у /usr/bin, /snap/bin, /opt/google, /opt/brave.com, /usr/lib/chromium і /usr/lib/chromium-browser, а також Chromium, керований Playwright, у PLAYWRIGHT_BROWSERS_PATH або ~/.cache/ms-playwright.
• Windows: перевіряє поширені розташування встановлення.

Control API (необов’язково)

Для скриптів і налагодження Gateway надає невеликий loopback-only HTTP control API плюс відповідний CLI openclaw browser (snapshots, refs, посилені очікування, JSON-вивід, debug workflows). Див. Browser control API, щоб отримати повний довідник.

Усунення несправностей

Для проблем, специфічних для Linux (особливо snap Chromium), див. Усунення проблем із браузером.

Для конфігурацій WSL2 Gateway + Windows Chrome з розділеним хостом див. Усунення проблем WSL2 + Windows + віддалений Chrome CDP.

Помилка запуску CDP проти блокування SSRF під час навігації

Це різні класи помилок, і вони вказують на різні шляхи коду.

• Помилка запуску або готовності CDP означає, що OpenClaw не може підтвердити справність площини керування браузером.
• Блокування SSRF під час навігації означає, що площина керування браузером справна, але ціль навігації сторінки відхилено політикою.

Поширені приклади:

• Помилка запуску або готовності CDP:
  • Chrome CDP websocket for profile "openclaw" is not reachable after start
  • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
  • Port <port> is in use for profile "<name>" but not by openclaw, коли налаштовано зовнішню CDP-службу loopback без attachOnly: true
• Блокування SSRF під час навігації:
  • потоки open, navigate, створення знімка або відкриття вкладки завершуються помилкою політики браузера/мережі, тоді як start і tabs усе ще працюють

Використайте цю мінімальну послідовність, щоб відокремити одне від іншого:

openclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw tabsopenclaw browser --browser-profile openclaw open https://example.com

Як читати результати:

• Якщо start завершується помилкою not reachable after start, спочатку усуньте проблему готовності CDP.
• Якщо start успішний, але tabs завершується помилкою, площина керування все ще несправна. Розглядайте це як проблему доступності CDP, а не як проблему навігації сторінкою.
• Якщо start і tabs успішні, але open або navigate завершується помилкою, площина керування браузером запущена, а збій пов’язаний із політикою навігації або цільовою сторінкою.
• Якщо start, tabs і open усі успішні, базовий шлях керування керованим браузером справний.

Важливі деталі поведінки:

• Конфігурація браузера за замовчуванням використовує об’єкт політики SSRF із fail-closed, навіть якщо ви не налаштовуєте browser.ssrfPolicy.
• Для керованого профілю openclaw з local loopback перевірки справності CDP навмисно пропускають застосування доступності SSRF браузера для власної локальної площини керування OpenClaw.
• Захист навігації є окремим. Успішний результат start або tabs не означає, що пізніша ціль open або navigate дозволена.

Рекомендації з безпеки:

• Не послаблюйте політику SSRF браузера за замовчуванням.
• Надавайте перевагу вузьким виняткам для хостів, таким як hostnameAllowlist або allowedHostnames, замість широкого доступу до приватної мережі.
• Використовуйте dangerouslyAllowPrivateNetwork: true лише в навмисно довірених середовищах, де доступ браузера до приватної мережі потрібний і перевірений.

Інструменти агента + як працює керування

Агент отримує один інструмент для автоматизації браузера:

• browser - doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

Як це зіставляється:

• browser snapshot повертає стабільне дерево інтерфейсу (AI або ARIA).
• browser act використовує ідентифікатори ref зі знімка, щоб клацати/вводити/перетягувати/вибирати.
• browser screenshot захоплює пікселі (повна сторінка, елемент або позначені ref).
• browser doctor перевіряє готовність Gateway, Plugin, профілю, браузера та вкладки.
• browser приймає:
  • profile, щоб вибрати іменований профіль браузера (openclaw, chrome або віддалений CDP).
  • target (sandbox | host | node), щоб вибрати, де розміщено браузер.
  • У ізольованих сеансах target: "host" потребує agents.defaults.sandbox.browser.allowHostControl=true.
  • Якщо target пропущено: ізольовані сеанси за замовчуванням використовують sandbox, неізольовані сеанси за замовчуванням використовують host.
  • Якщо підключено вузол із підтримкою браузера, інструмент може автоматично маршрутизувати до нього, якщо ви не закріпите target="host" або target="node".

Це робить агента детермінованим і дає змогу уникати крихких селекторів.

Пов’язане

• Огляд інструментів - усі доступні інструменти агента
• Ізоляція - керування браузером в ізольованих середовищах
• Безпека - ризики керування браузером і посилення захисту