Brauzer (openclaw tomonidan boshqariladi)
OpenClaw agent boshqaradigan maxsus Chrome/Brave/Edge/Chromium profilini ishga tushirishi mumkin. U shaxsiy brauzeringizdan ajratilgan va Gateway ichidagi kichik lokal boshqaruv xizmati orqali (faqat loopback) boshqariladi. Boshlovchilar uchun ko‘rinish:- Buni agentlar uchun alohida brauzer deb tasavvur qiling.
openclawprofili shaxsiy brauzer profilingizga tegmaydi.- Agent xavfsiz muhitda tablarni ochishi, sahifalarni o‘qishi, bosishi va matn kiritishi mumkin.
- Standart
chromeprofili tizimdagi standart Chromium brauzeridan kengaytma relayi orqali foydalanadi; izolyatsiyalangan boshqariladigan brauzer uchunopenclawga o‘ting.
Nimalarga ega bo‘lasiz
- openclaw nomli alohida brauzer profili (standartda to‘q sariq aksent).
- Deterministik tab boshqaruvi (ro‘yxatlash/ochish/fokuslash/yopish).
- Agent harakatlari (bosish/kiritish/sudrash/tanlash), snapshotlar, skrinshotlar, PDFlar.
- Ixtiyoriy ko‘p-profilli qo‘llab-quvvatlash (
openclaw,work,remote, …).
Tezkor boshlash
Profillar: openclaw va chrome
openclaw: boshqariladigan, izolyatsiyalangan brauzer (kengaytma talab qilinmaydi).chrome: tizim brauzeringizga kengaytma relayi (OpenClaw kengaytmasi tabga ulangan bo‘lishi kerak).
browser.defaultProfile: "openclaw" ni sozlang.
Konfiguratsiya
- Brauzer sozlamalari
~/.openclaw/openclaw.jsonda joylashgan.
- The browser control service binds to loopback on a port derived from
gateway.port(default:18791, which is gateway + 2). The relay uses the next port (18792). - If you override the Gateway port (
gateway.portorOPENCLAW_GATEWAY_PORT), the derived browser ports shift to stay in the same “family”. cdpUrldefaults to the relay port when unset.remoteCdpTimeoutMsapplies to remote (non-loopback) CDP reachability checks.remoteCdpHandshakeTimeoutMsapplies to remote CDP WebSocket reachability checks.attachOnly: truemeans “never launch a local browser; only attach if it is already running.”color+ per-profilecolortint the browser UI so you can see which profile is active.- Default profile is
chrome(extension relay). UsedefaultProfile: "openclaw"for the managed browser. - Auto-detect order: system default browser if Chromium-based; otherwise Chrome → Brave → Edge → Chromium → Chrome Canary.
- Local
openclawprofiles auto-assigncdpPort/cdpUrl— set those only for remote CDP.
Use Brave (or another Chromium-based browser)
If your system default browser is Chromium-based (Chrome/Brave/Edge/etc), OpenClaw uses it automatically. Setbrowser.executablePath to override
auto-detection:
CLI example:
Local vs remote control
- Local control (default): the Gateway starts the loopback control service and can launch a local browser.
- Remote control (node host): run a node host on the machine that has the browser; the Gateway proxies browser actions to it.
- Remote CDP: set
browser.profiles.<name>.cdpUrl(orbrowser.cdpUrl) to attach to a remote Chromium-based browser. In this case, OpenClaw will not launch a local browser.
- Query tokens (e.g.,
https://provider.example?token=<token>) - HTTP Basic auth (e.g.,
https://user:[email protected])
/json/* endpoints and when connecting
to the CDP WebSocket. Prefer environment variables or secrets managers for
tokens instead of committing them to config files.
Node browser proxy (zero-config default)
If you run a node host on the machine that has your browser, OpenClaw can auto-route browser tool calls to that node without any extra browser config. This is the default path for remote gateways. Notes:- The node host exposes its local browser control server via a proxy command.
- Profiles come from the node’s own
browser.profilesconfig (same as local). - Disable if you don’t want it:
- On the node:
nodeHost.browserProxy.enabled=false - On the gateway:
gateway.nodes.browser.mode="off"
- On the node:
Browserless (hosted remote CDP)
Browserless is a hosted Chromium service that exposes CDP endpoints over HTTPS. You can point a OpenClaw browser profile at a Browserless region endpoint and authenticate with your API key. Example:- Replace
<BROWSERLESS_API_KEY>with your real Browserless token. - Choose the region endpoint that matches your Browserless account (see their docs).
13. Xavfsizlik
Key ideas:- Browser control is loopback-only; access flows through the Gateway’s auth or node pairing.
- Agar brauzer boshqaruvi yoqilgan bo‘lsa va auth sozlanmagan bo‘lsa, OpenClaw ishga tushganda
gateway.auth.tokenni avtomatik yaratadi va uni konfiguratsiyaga saqlaydi. - Keep the Gateway and any node hosts on a private network (Tailscale); avoid public exposure.
- Treat remote CDP URLs/tokens as secrets; prefer env vars or a secrets manager.
- Prefer HTTPS endpoints and short-lived tokens where possible.
- Avoid embedding long-lived tokens directly in config files.
Profiles (multi-browser)
OpenClaw supports multiple named profiles (routing configs). Profiles can be:- openclaw-managed: a dedicated Chromium-based browser instance with its own user data directory + CDP port
- remote: an explicit CDP URL (Chromium-based browser running elsewhere)
- extension relay: your existing Chrome tab(s) via the local relay + Chrome extension
- The
openclawprofile is auto-created if missing. - The
chromeprofile is built-in for the Chrome extension relay (points athttp://127.0.0.1:18792by default). - Local CDP ports allocate from 18800–18899 by default.
- Deleting a profile moves its local data directory to Trash.
?profile=<name>; the CLI uses --browser-profile.
Chrome extension relay (use your existing Chrome)
OpenClaw can also drive your existing Chrome tabs (no separate “openclaw” Chrome instance) via a local CDP relay + a Chrome extension. Full guide: Chrome extension Flow:- The Gateway runs locally (same machine) or a node host runs on the browser machine.
- A local relay server listens at a loopback
cdpUrl(default:http://127.0.0.1:18792). - You click the OpenClaw Browser Relay extension icon on a tab to attach (it does not auto-attach).
- The agent controls that tab via the normal
browsertool, by selecting the right profile.
Sandboxed sessions
If the agent session is sandboxed, thebrowser tool may default to target="sandbox" (sandbox browser).
Chrome extension relay takeover requires host browser control, so either:
- run the session unsandboxed, or
- set
agents.defaults.sandbox.browser.allowHostControl: trueand usetarget="host"when calling the tool.
Setup
- Load the extension (dev/unpacked):
- Chrome →
chrome://extensions→ enable “Developer mode” - “Load unpacked” → select the directory printed by
openclaw browser extension path - Pin the extension, then click it on the tab you want to control (badge shows
ON).
- Use it:
- CLI:
openclaw browser --browser-profile chrome tabs - Agent tool:
browserwithprofile="chrome"
- This mode relies on Playwright-on-CDP for most operations (screenshots/snapshots/actions).
- Detach by clicking the extension icon again.
Isolation guarantees
- Dedicated user data dir: never touches your personal browser profile.
- Dedicated ports: avoids
9222to prevent collisions with dev workflows. - Deterministic tab control: target tabs by
targetId, not “last tab”.
Browser selection
When launching locally, OpenClaw picks the first available:- Chrome
- Brave
- Edge
- Chromium
- Chrome Canary
browser.executablePath.
Platforms:
- macOS: checks
/Applicationsand~/Applications. - Linux: looks for
google-chrome,brave,microsoft-edge,chromium, etc. - Windows: checks common install locations.
Control API (optional)
For local integrations only, the Gateway exposes a small loopback HTTP API:- Status/start/stop:
GET /,POST /start,POST /stop - Tabs:
GET /tabs,POST /tabs/open,POST /tabs/focus,DELETE /tabs/:targetId - Snapshot/screenshot:
GET /snapshot,POST /screenshot - Actions:
POST /navigate,POST /act - Hooks:
POST /hooks/file-chooser,POST /hooks/dialog - Downloads:
POST /download,POST /wait/download - Debugging:
GET /console,POST /pdf - Debugging:
GET /errors,GET /requests,POST /trace/start,POST /trace/stop,POST /highlight - Network:
POST /response/body - State:
GET /cookies,POST /cookies/set,POST /cookies/clear - State:
GET /storage/:kind,POST /storage/:kind/set,POST /storage/:kind/clear - Settings:
POST /set/offline,POST /set/headers,POST /set/credentials,POST /set/geolocation,POST /set/media,POST /set/timezone,POST /set/locale,POST /set/device
?profile=<name>.
Agar gateway auth sozlangan bo‘lsa, brauzer HTTP marshrutlari ham auth talab qiladi:
Authorization: Bearer <gateway token>x-openclaw-password: <gateway password>yoki shu parol bilan HTTP Basic auth
Playwright requirement
Some features (navigate/act/AI snapshot/role snapshot, element screenshots, PDF) require Playwright. If Playwright isn’t installed, those endpoints return a clear 501 error. ARIA snapshots and basic screenshots still work for openclaw-managed Chrome. For the Chrome extension relay driver, ARIA snapshots and screenshots require Playwright. If you seePlaywright is not available in this gateway build, install the full
Playwright package (not playwright-core) and restart the gateway, or reinstall
OpenClaw with browser support.
Docker Playwright install
If your Gateway runs in Docker, avoidnpx playwright (npm override conflicts).
Use the bundled CLI instead:
PLAYWRIGHT_BROWSERS_PATH (for example,
/home/node/.cache/ms-playwright) and make sure /home/node is persisted via
OPENCLAW_HOME_VOLUME or a bind mount. See Docker.
How it works (internal)
High-level flow:- A small control server accepts HTTP requests.
- It connects to Chromium-based browsers (Chrome/Brave/Edge/Chromium) via CDP.
- For advanced actions (click/type/snapshot/PDF), it uses Playwright on top of CDP.
- When Playwright is missing, only non-Playwright operations are available.
CLI quick reference
All commands accept--browser-profile <name> to target a specific profile.
All commands also accept --json for machine-readable output (stable payloads).
Basics:
openclaw browser statusopenclaw browser startopenclaw browser stopopenclaw browser tabsopenclaw browser tabopenclaw browser tab newopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://example.comopenclaw browser focus abcd1234openclaw browser close abcd1234
openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref 12openclaw browser screenshot --ref e12openclaw browser snapshotopenclaw browser snapshot --format aria --limit 200openclaw browser snapshot --interactive --compact --depth 6openclaw browser snapshot --efficientopenclaw browser snapshot --labelsopenclaw browser snapshot --selector "#main" --interactiveopenclaw browser snapshot --frame "iframe#main" --interactiveopenclaw browser console --level erroropenclaw browser errors --clearopenclaw browser requests --filter api --clearopenclaw browser pdfopenclaw browser responsebody "**/api" --max-chars 5000
openclaw browser navigate https://example.comopenclaw browser resize 1280 720openclaw browser click 12 --doubleopenclaw browser click e12 --doubleopenclaw browser type 23 "hello" --submitopenclaw browser press Enteropenclaw browser hover 44openclaw browser scrollintoview e12openclaw browser drag 10 11openclaw browser select 9 OptionA OptionBopenclaw browser download e12 report.pdfopenclaw browser waitfordownload report.pdfopenclaw browser upload /tmp/openclaw/uploads/file.pdfopenclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'openclaw browser dialog --acceptopenclaw browser wait --text "Done"openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"openclaw browser evaluate --fn '(el) => el.textContent' --ref 7openclaw browser highlight e12openclaw browser trace startopenclaw browser trace stop
openclaw browser cookiesopenclaw browser cookies set session abc123 --url "https://example.com"openclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set theme darkopenclaw browser storage session clearopenclaw browser set offline onopenclaw browser set headers --json '{"X-Debug":"1"}'openclaw browser set credentials user passopenclaw browser set credentials --clearopenclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"openclaw browser set geo --clearopenclaw browser set media darkopenclaw browser set timezone America/New_Yorkopenclaw browser set locale en-USopenclaw browser set device "iPhone 14"
uploadvadialogqurollantiruvchi chaqiruvlar; tanlovchi/dialogni ishga tushiradigan bosish/pressdan oldin ularni ishga tushiring.- Yuklab olish va trace chiqish yo‘llari OpenClaw vaqtinchalik ildiz kataloglari bilan cheklangan:
- traces:
/tmp/openclaw(zaxira:${os.tmpdir()}/openclaw) - downloads:
/tmp/openclaw/downloads(zaxira:${os.tmpdir()}/openclaw/downloads)
- traces:
- Upload yo‘llari OpenClaw vaqtinchalik uploads ildiz katalogi bilan cheklangan:
- uploads:
/tmp/openclaw/uploads(zaxira:${os.tmpdir()}/openclaw/uploads)
- uploads:
uploadfayl kiritish maydonlarini--input-refyoki--elementorqali to‘g‘ridan-to‘g‘ri ham sozlashi mumkin.snapshot:--format ai(Playwright o‘rnatilganida standart): raqamli referenslar (aria-ref="<n>") bilan AI snapshotni qaytaradi.--format aria: accessibility daraxtini qaytaradi (referenslar yo‘q; faqat tekshirish uchun).--efficient(yoki--mode efficient): ixcham rol snapshot preseti (interaktiv + ixcham + chuqurlik + pastroq maxChars).- Standart konfiguratsiya (faqat tool/CLI): chaqiruvchi rejimni uzatmasa samarali snapshotlardan foydalanish uchun
browser.snapshotDefaults.mode: "efficient"ni o‘rnating (qarang: Gateway configuration). - Rol snapshot parametrlari (
--interactive,--compact,--depth,--selector)ref=e12kabi referenslar bilan rolga asoslangan snapshotni majburiy qiladi. --frame "<iframe selector>"rol snapshotlarini iframe ichida cheklaydi (e12kabi rol referenslari bilan juftlashadi).--interactiveinteraktiv elementlarning tekis, tanlash oson ro‘yxatini chiqaradi (harakatlarni boshqarish uchun eng yaxshisi).-
--labelsfaqat viewport uchun overlay qilingan ref yorliqlari bilan skrinshot qo‘shadi (MEDIA:<path>ni chiqaradi).
click/type/va boshqalarsnapshotdan olinganrefni talab qiladi (raqamli12yoki rol referensie12). Harakatlar uchun CSS selektorlar ataylab qo‘llab-quvvatlanmaydi.
Snapshotlar va referenslar
Referenslar xatti-harakati:-
Referenslar navigatsiyalar orasida barqaror emas; agar biror narsa ishlamasa,
snapshotni qayta ishga tushiring va yangi referensdan foydalaning.- Chiqish: raqamli referenslarni o‘z ichiga olgan matnli snapshot.
- Harakatlar:
openclaw browser click 12,openclaw browser type 23 "hello". - Ichki tomondan, referens Playwright’ning
aria-reforqali aniqlanadi.
-
Agar rol snapshot
--framebilan olingan bo‘lsa, keyingi rol snapshotigacha rol referenslari o‘sha iframe doirasida qoladi.- Chiqish:
[ref=e12](va ixtiyoriy[nth=1]) bilan rolga asoslangan ro‘yxat/daraxt. - Harakatlar:
openclaw browser click e12,openclaw browser highlight e12. - Ichki tomondan, referens
getByRole(...)orqali aniqlanadi (takrorlar uchunnth()bilan). - Ustma-ust qo‘yilgan
e12yorliqlari bilan ko‘rinish oynasi skrinshotini qo‘shish uchun--labelsni qo‘shing.
- Chiqish:
- Referenslar navigatsiyalar orasida barqaror emas; agar biror narsa ishlamasa,
snapshotni qayta ishga tushiring va yangi referensdan foydalaning. - Agar rol snapshot
--framebilan olingan bo‘lsa, keyingi rol snapshotigacha rol referenslari o‘sha iframe doirasida qoladi.
Kutish kuchaytmalari
Faqat vaqt/matn emas, ko‘proq narsalarni ham kutishingiz mumkin:- URLni kutish (Playwright tomonidan qo‘llab-quvvatlanadigan globlar):
openclaw browser wait --url "**/dash"
- Yuklanish holatini kutish:
openclaw browser wait --load networkidle
-
- JS predikati bajarilishini kuting:
openclaw browser wait --fn "window.ready===true"
-
- Selektor ko‘rinadigan bo‘lishini kuting:
openclaw browser wait "#main"
- Bularni birlashtirish mumkin:
20. JSON chiqishi
- Harakat muvaffaqiyatsiz bo‘lganda (masalan, “ko‘rinmaydi”, “qat’iy rejim buzilishi”, “ustini yopib qo‘yilgan”):
-
openclaw browser snapshot --interactive -
click <ref>/type <ref>dan foydalaning (interaktiv rejimda rolga asoslangan ref’larni afzal ko‘ring)
-
- Agar baribir ishlamasa: Playwright nimani nishonga olayotganini ko‘rish uchun
openclaw browser highlight <ref>
- Agar baribir ishlamasa: Playwright nimani nishonga olayotganini ko‘rish uchun
-
- Agar sahifa g‘alati tutsa:
openclaw browser errors --clearopenclaw browser requests --filter api --clear
-
- Chuqur nosozliklarni aniqlash uchun: treys yozib oling:
openclaw browser trace start-
- muammoni qayta yuzaga keltiring
-
openclaw browser trace stop(TRACE:<path>ni chiqaradi)
20) JSON chiqishi
-
--jsonskriptlash va tuzilmaviy vositalar uchun mo‘ljallangan. - Misollar:
- JSON’dagi rol snapshotlari
refshamda kichikstatsblokini (lines/chars/refs/interactive) o‘z ichiga oladi, shunda vositalar yuklama hajmi va zichligini baholay oladi.
25. Holat va muhit sozlamalari
- Bular “saytni X kabi tutishga majbur qilish” ish jarayonlari uchun foydali:
- Linux’ga xos muammolar (ayniqsa snap Chromium) uchun Browser troubleshooting ga qarang.
-
- Saqlash:
storage local|session get|set|clear
- Saqlash:
-
- Oflayn:
set offline on|off
- Oflayn:
-
- Sarlavhalar:
set headers --json '{"X-Debug":"1"}'(yoki--clear)
- Sarlavhalar:
-
- HTTP basic autentifikatsiya:
set credentials user pass(yoki--clear)
- HTTP basic autentifikatsiya:
-
- Geolokatsiya:
set geo <lat> <lon> --origin "https://example.com"(yoki--clear)
- Geolokatsiya:
- Media:
set media dark|light|no-preference|none -
- Vaqt zonasi / til sozlamasi:
set timezone ...,set locale ...
- Vaqt zonasi / til sozlamasi:
-
- Qurilma / viewport:
-
set device "iPhone 14"(Playwright qurilma presetlari)
set viewport 1280 720
38. Xavfsizlik va maxfiylik
- Agent brauzer avtomatlashtirish uchun bitta vosita oladi:
-
browser act kind=evaluate/openclaw browser evaluatevawait --fnsahifa kontekstida ixtiyoriy JavaScript’ni bajaradi. 41. Prompt injection buni boshqarishi mumkin. 42. Agar kerak bo‘lmasa,browser.evaluateEnabled=falsebilan o‘chirib qo‘ying.
-
- Login va anti-bot eslatmalari (X/Twitter va boshqalar) uchun Browser login + X/Twitter posting ga qarang.
-
- Gateway/node xostini yopiq saqlang (loopback yoki faqat tailnet).
-
- Masofaviy CDP endpointlari kuchli; ularni tunnel qiling va himoyalang.
46. Nosozliklarni bartaraf etish
- Linux’ga xos muammolar (ayniqsa snap Chromium) uchun Browser troubleshooting ga qarang.
48. Agent vositalari + boshqaruv qanday ishlaydi
- Agent brauzer avtomatlashtirish uchun bitta vosita oladi:
browser— status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
- Qanday xaritalanadi:
-
browser snapshotbarqaror UI daraxtini qaytaradi (AI yoki ARIA).
-
browser actsnapshotdagirefID’lardan foydalanib bosish/yozish/sudrash/tanlashni amalga oshiradi.
-
browser screenshotpiksellarni ushlaydi (butun sahifa yoki element).
-
browserqabul qiladi:
-
profile— nomlangan brauzer profilini tanlash uchun (openclaw, chrome yoki remote CDP).
-
target(sandbox|host|node) — brauzer qayerda ishlashini tanlash uchun.
-
- Sandboxlangan sessiyalarda
target: "host"ishlashi uchunagents.defaults.sandbox.browser.allowHostControl=truetalab qilinadi.
- Sandboxlangan sessiyalarda
-
- Agar
targetko‘rsatilmasa: sandboxlangan sessiyalar sukut bo‘yichasandbox, sandbox bo‘lmagan sessiyalarhostbo‘ladi.
- Agar
-
- Agar brauzerga qodir node ulangan bo‘lsa, asbob avtomatik ravishda unga yo‘naltirishi mumkin, agar siz
target="host"yokitarget="node"ni qat’iy belgilamasangiz.
- Agar brauzerga qodir node ulangan bo‘lsa, asbob avtomatik ravishda unga yo‘naltirishi mumkin, agar siz
- Bu agentni deterministik qiladi va mo‘rt selektorlarning oldini oladi.