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

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

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

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

• Окремий профіль браузера з назвою openclaw (за замовчуванням із помаранчевим акцентом).
• Детерміноване керування вкладками (перегляд списку/відкриття/фокусування/закриття).
• Дії агента (клацання/введення/перетягування/вибір), знімки стану, знімки екрана, PDF-файли.
• Профілі на базі Playwright зберігають результати прямих переходів до вкладень у керованому каталозі завантажень і повертають метадані { url, suggestedFilename, path } після перевірки політики кінцевої URL-адреси.
• Дії агента на базі Playwright повертають масив downloads із такими самими керованими метаданими, коли дія негайно запускає одне або кілька завантажень.
• Вбудована навичка browser-automation, яка навчає агентів циклу відновлення для знімків стану, стабільних вкладок, застарілих посилань і перешкод, що потребують ручного втручання, коли плагін браузера ввімкнено.
• Необов’язкова підтримка кількох профілів (openclaw, work, remote, ...).

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

У macOS можна явно скопіювати файли cookie із системного профілю браузера сімейства Chrome до окремого керованого профілю. Керований браузер і надалі використовує власний каталог даних користувача; копіюються лише вибрані файли cookie, а локальне сховище та IndexedDB не переносяться. Команди імпорту й обмеження наведено в розділі Профілі або в довіднику CLI openclaw browser.

Швидкий початок

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.enabled вимкнено; див. Конфігурація і Керування плагіном.

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

Керування плагіном

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Профілі: openclaw, user, chrome

• openclaw: керований ізольований браузер (розширення не потрібне).
• user: вбудований профіль підключення Chrome DevTools MCP до вашого реального сеансу Chrome із виконаним входом. Під час першого підключення OpenClaw Chrome показує блокувальний запит «Allow remote debugging?», тому хтось має перебувати біля комп’ютера.
• chrome: вбудований профіль розширення Chrome для вашого реального сеансу Chrome із виконаним входом. Працює з телефона, коли за комп’ютером нікого немає, оскільки керує вкладками через розширення браузера OpenClaw, а не через порт віддаленого налагодження, тому запит «Allow remote debugging?» не з’являється.

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

• За замовчуванням: використовуйте ізольований браузер openclaw.
• Надавайте перевагу profile="chrome" (розширенню), коли важливі наявні сеанси з виконаним входом, а користувач перебуває не біля комп’ютера (Telegram, WhatsApp тощо).
• Надавайте перевагу profile="user" (Chrome MCP), коли важливі наявні сеанси з виконаним входом, а користувач перебуває біля комп’ютера, щоб підтвердити запит на підключення.
• profile є явним перевизначенням, коли потрібен певний режим браузера.

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

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

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

{  browser: {    enabled: true, // типове значення: true    evaluateEnabled: true, // типове значення: true; false вимикає act:evaluate (довільний JS)    ssrfPolicy: {      // dangerouslyAllowPrivateNetwork: true, // вмикайте лише для довіреного доступу до приватної мережі      // hostnameAllowlist: ["*.example.com", "example.com"],      // allowedHostnames: ["localhost"],    },    // cdpUrl: "http://127.0.0.1:18792", // застаріле перевизначення для одного профілю    remoteCdpTimeoutMs: 1500, // час очікування HTTP віддаленого CDP (мс)    remoteCdpHandshakeTimeoutMs: 3000, // час очікування рукостискання WebSocket віддаленого CDP (мс)    localLaunchTimeoutMs: 15000, // час очікування виявлення локального керованого Chrome (мс)    localCdpReadyTimeoutMs: 8000, // час очікування готовності CDP після локального запуску керованого браузера (мс)    actionTimeoutMs: 60000, // стандартний час очікування дії браузера (мс)    tabCleanup: {      enabled: true, // типове значення: true      idleMinutes: 120, // установіть 0, щоб вимкнути очищення неактивних вкладок      maxTabsPerSession: 8, // установіть 0, щоб вимкнути обмеження на кількість вкладок у сеансі      sweepMinutes: 5,    },    // snapshotDefaults: { mode: "efficient" }, // стандартний режим знімка стану, коли викликач його не вказує    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" },    },  },}

browser.snapshotDefaults.mode: "efficient" змінює стандартний режим вилучення snapshot, коли викликач не передає явно snapshotFormat або mode; параметри знімків стану для окремих викликів наведено в розділі API керування браузером.

Візуальний аналіз знімків екрана (підтримка лише текстових моделей)

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

{  tools: {    media: {      image: {        models: [          { provider: "bytedance", model: "doubao-seed-2.0-pro" },          // Додайте резервних кандидатів; використовується перший успішний          { provider: "openai", model: "gpt-4o" },        ],      },      // Спільні моделі медіафайлів також працюють, якщо позначені як такі, що підтримують зображення.      // models: [{ provider: "openai", model: "gpt-4o", capabilities: ["image"] }],    },  },  agents: {    defaults: {      // Наявні стандартні налаштування моделі зображень також враховуються.      // imageModel: { primary: "openai/gpt-4o" },    },  },}

Як це працює:

1. Агент викликає browser screenshot, і зображення, як зазвичай, зберігається на диск.
2. Інструмент браузера запитує наявне середовище розуміння зображень, чи може воно описати знімок екрана за допомогою налаштованих медіамоделей зображень, спільних медіамоделей, стандартних налаштувань моделей зображень або постачальника зображень із підтримкою автентифікації.
3. Модель із підтримкою зору повертає текстовий опис, який обгортається в wrapExternalContent (захист від ін’єкції підказок) і повертається агенту як текстовий блок замість блоку зображення.
4. Якщо розуміння зображень недоступне, пропущене або завершується помилкою, браузер натомість повертає початковий блок зображення.

Блоки зображень знімків екрана є приватними результатами інструмента: агент може їх переглядати, але OpenClaw не прикріплює їх автоматично до відповідей у каналах. Щоб поділитися знімком екрана, попросіть агента явно надіслати його за допомогою інструмента повідомлень.

Використовуйте наявні поля tools.media.image / tools.media.models для резервних моделей, часу очікування, обмежень байтів, профілів і налаштувань запитів до постачальника.

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

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

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

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

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

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

Браузерний проксі вузла (типово без налаштування)

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

Примітки:

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

Browserless (розміщений віддалений CDP)

Browserless — це розміщена служба Chromium, яка надає URL-адреси підключення CDP через HTTPS і WebSocket. OpenClaw може використовувати обидва формати, але для профілю віддаленого браузера найпростішим варіантом є пряма URL-адреса WebSocket із документації 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 надає базову URL-адресу HTTPS, її можна або перетворити на wss:// для прямого підключення CDP, або зберегти URL-адресу HTTPS і дозволити 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 невстановленим для профілю Browserless із кільцевою адресою. Без attachOnly OpenClaw розглядає порт кільцевого інтерфейсу як локальний керований профіль браузера й може повідомляти, що порт використовується, але не належить OpenClaw.

Постачальники прямого CDP через WebSocket

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

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

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

Browserbase

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

{  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, тому створювати сеанс вручну не потрібно.
• Поточні обмеження безкоштовного рівня та платні плани наведено на сторінці цін.
• Повну довідку з API, посібники з SDK та приклади інтеграції див. в документації Browserbase.

Notte

Notte — це хмарна платформа для запуску безголових браузерів із вбудованим приховуванням, резидентськими проксі-серверами та нативним для CDP шлюзом 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.
• Поточні обмеження безкоштовного рівня та платні плани наведено на сторінці цін.
• Повну довідку з API, посібники з SDK та приклади інтеграції див. в документації Notte.

Безпека

Основні положення:

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

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

• За можливості віддавайте перевагу зашифрованим кінцевим точкам (HTTPS або WSS) і короткочасним токенам.
• Не вбудовуйте довгострокові токени безпосередньо у файли конфігурації.
• Тримайте Gateway і всі хости вузлів у приватній мережі (Tailscale); уникайте загальнодоступного доступу.
• Розглядайте віддалені URL-адреси й токени CDP як секрети; віддавайте перевагу змінним середовища або засобу керування секретами.

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

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

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

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

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

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

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

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

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

• Chrome для розробників: використання Chrome DevTools MCP із сеансом браузера
• README Chrome DevTools MCP

Вбудований профіль: 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. Відкрийте сторінку перевірки цього браузера для віддаленого налагодження.
2. Увімкніть віддалене налагодження.
3. Не закривайте браузер і підтвердьте запит на підключення, коли OpenClaw приєднуватиметься.

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

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

Швидка перевірка підключення наживо:

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 повертає посилання з вибраної активної вкладки

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

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

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

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

Примітки:

• Цей шлях має вищий ризик, ніж ізольований профіль openclaw, оскільки він може виконувати дії в сеансі браузера, у якому здійснено вхід.
• OpenClaw не запускає браузер для цього драйвера, а лише підключається до нього.
• Тут OpenClaw використовує офіційний процес --autoConnect Chrome DevTools MCP. Якщо задано userDataDir, його передано для вибору цього каталогу даних користувача.
• Режим наявного сеансу може підключатися на вибраному хості або через підключений браузерний Node. Якщо Chrome працює в іншому місці й браузерний Node не підключено, використовуйте натомість віддалений CDP або хост Node.
• Цілі Chrome MCP і посилання знімків обмежено одним підпроцесом MCP. Після перезапуску цього процесу знову виконайте browser tabs, явно виберіть нову ціль перед роботою з конкретною ціллю та створіть новий знімок перед використанням посилань. Кожне посилання дійсне лише для своєї цілі та останнього знімка. Старі псевдоніми не переносяться до замінної вкладки, навіть якщо її URL збігається.
• Наразі Chrome DevTools MCP спрямовує інструменти сторінки за локальним для процесу числовим ідентифікатором сторінки. Обмежені процесом дескриптори запобігають повторному використанню після заміни підпроцесу, але заміна контексту браузера в межах процесу між сусідніми викликами інструментів усе ще може перенаправити дію на іншу ціль. Для повністю атомарного спрямування потрібна підтримка стабільних ідентифікаторів цілей в інструментах сторінки на стороні залежності.

Власний запуск Chrome MCP

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

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

• http(s)://... → --browserUrl <url> (кінцева точка HTTP-виявлення DevTools).
• ws(s)://... → --wsEndpoint <url> (прямий WebSocket CDP).

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

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

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

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

Під час локального запуску 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: перевіряє поширені місця інсталяції.

API керування (необов’язково)

Для написання сценаріїв і налагодження Gateway надає невеликий HTTP API керування, доступний лише через інтерфейс зворотного зв’язку, а також відповідний CLI openclaw browser (знімки, посилання, розширені можливості очікування, виведення JSON, процеси налагодження). Повний довідник наведено в розділі API керування браузером.

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

Проблеми, характерні для Linux (особливо snap-версії Chromium), описано в розділі Усунення несправностей браузера.

Налаштування з Gateway у WSL2 та Chrome у Windows на різних хостах описано в розділі Усунення несправностей WSL2 + Windows + віддаленого CDP Chrome.

Помилка запуску 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 з інтерфейсом зворотного зв’язку налаштовано без 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 із забороною в разі невизначеності, навіть якщо browser.ssrfPolicy не налаштовано.
• Для локального керованого профілю openclaw з інтерфейсом зворотного зв’язку перевірки справності CDP навмисно пропускають перевірку доступності за політикою SSRF браузера для власної локальної площини керування OpenClaw.
• Захист навігації працює окремо. Успішний результат start або tabs не означає, що наступну ціль open або navigate дозволено.

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

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

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

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

• browser — діагностика/стан/запуск/зупинка/вкладки/відкриття/фокусування/закриття/знімок/знімок екрана/навігація/дія

Відповідність:

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

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

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

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