openclaw browser

Kelola permukaan kontrol browser OpenClaw dan jalankan tindakan browser (siklus hidup, profil, tab, snapshot, tangkapan layar, navigasi, input, emulasi state, dan debugging).

Terkait:

• Tool browser + API: Tool browser

Flag umum

• --url <gatewayWsUrl>: URL WebSocket Gateway (default ke config).
• --token <token>: token Gateway (jika diperlukan).
• --timeout <ms>: batas waktu permintaan (ms).
• --expect-final: tunggu respons Gateway final.
• --browser-profile <name>: pilih profil browser (default dari config).
• --json: output yang dapat dibaca mesin (jika didukung).

Mulai cepat (lokal)

openclaw browser profilesopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

Agent dapat menjalankan pemeriksaan kesiapan yang sama dengan browser({ action: "doctor" }).

Pemecahan masalah cepat

Jika start gagal dengan not reachable after start, selesaikan kesiapan CDP terlebih dahulu. Jika start dan tabs berhasil tetapi open atau navigate gagal, bidang kontrol browser sehat dan kegagalan biasanya adalah kebijakan SSRF navigasi.

Urutan minimal:

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

Panduan terperinci: Pemecahan masalah browser

Siklus hidup

openclaw browser statusopenclaw browser doctoropenclaw browser doctor --deepopenclaw browser startopenclaw browser start --headlessopenclaw browser stopopenclaw browser --browser-profile openclaw reset-profile

Catatan:

• doctor --deep menambahkan probe snapshot langsung. Ini berguna ketika kesiapan CDP dasar sudah hijau tetapi Anda menginginkan bukti bahwa tab saat ini dapat diinspeksi.
• Untuk profil attachOnly dan CDP jarak jauh, openclaw browser stop menutup sesi kontrol aktif dan membersihkan override emulasi sementara bahkan ketika OpenClaw tidak meluncurkan proses browser itu sendiri.
• Untuk profil lokal terkelola, openclaw browser stop menghentikan proses browser yang dibuat.
• openclaw browser start --headless hanya berlaku untuk permintaan start tersebut dan hanya ketika OpenClaw meluncurkan browser lokal terkelola. Perintah ini tidak menulis ulang browser.headless atau config profil, dan tidak melakukan apa pun untuk browser yang sudah berjalan.
• Pada host Linux tanpa DISPLAY atau WAYLAND_DISPLAY, profil lokal terkelola berjalan headless secara otomatis kecuali OPENCLAW_BROWSER_HEADLESS=0, browser.headless=false, atau browser.profiles.<name>.headless=false secara eksplisit meminta browser terlihat.

Jika perintah tidak ada

Jika openclaw browser adalah perintah yang tidak dikenal, periksa plugins.allow di ~/.openclaw/openclaw.json.

Ketika plugins.allow ada, cantumkan Plugin browser bawaan secara eksplisit kecuali config sudah memiliki blok root browser:

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

Blok root browser eksplisit, misalnya browser.enabled=true atau browser.profiles.<name>, juga mengaktifkan Plugin browser bawaan di bawah allowlist Plugin yang restriktif.

Terkait: Tool browser

Profil

Profil adalah config routing browser bernama. Dalam praktiknya:

• openclaw: meluncurkan atau melampirkan ke instance Chrome khusus yang dikelola OpenClaw (direktori data pengguna terisolasi).
• user: mengontrol sesi Chrome Anda yang sudah login melalui Chrome DevTools MCP.
• profil CDP kustom: mengarah ke endpoint CDP lokal atau jarak jauh.

openclaw browser profilesopenclaw browser create-profile --name work --color "#FF5A36"openclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name remote --cdp-url https://browser-host.example.comopenclaw browser delete-profile --name work

Gunakan profil tertentu:

openclaw browser --browser-profile work tabs

Tab

openclaw browser tabsopenclaw browser tab new --label docsopenclaw browser tab label t1 docsopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://docs.openclaw.ai --label docsopenclaw browser focus docsopenclaw browser close t1

tabs mengembalikan suggestedTargetId terlebih dahulu, lalu tabId stabil seperti t1, label opsional, dan targetId mentah. Agent harus meneruskan suggestedTargetId kembali ke focus, close, snapshot, dan tindakan. Anda dapat menetapkan label dengan open --label, tab new --label, atau tab label; label, id tab, id target mentah, dan prefiks target-id unik semuanya diterima. Field permintaan tetap bernama targetId untuk kompatibilitas, tetapi menerima referensi tab ini. Perlakukan id target mentah sebagai handle diagnostik, bukan memori agent yang tahan lama. Ketika Chromium mengganti target mentah yang mendasari selama navigasi atau submit formulir, OpenClaw mempertahankan tabId/label stabil yang terpasang ke tab pengganti ketika dapat membuktikan kecocokannya. Id target mentah tetap volatil; utamakan suggestedTargetId.

Snapshot / tangkapan layar / tindakan

Snapshot:

openclaw browser snapshotopenclaw browser snapshot --urls

Tangkapan layar:

openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref e12openclaw browser screenshot --labels

Catatan:

• --full-page hanya untuk tangkapan halaman; ini tidak dapat digabungkan dengan --ref atau --element.
• Profil existing-session / user mendukung tangkapan layar halaman dan tangkapan layar --ref dari output snapshot, tetapi bukan tangkapan layar CSS --element.
• --labels menimpa ref snapshot saat ini pada tangkapan layar. Pada profil berbasis Playwright, ini bekerja dengan --full-page (overlay label seluruh halaman), --ref (overlay label klip elemen berdasarkan ref ARIA), dan --element (overlay label klip elemen berdasarkan selector CSS); dalam mode klip elemen, label diproyeksikan relatif terhadap elemen. Respons juga mencakup array annotations dengan kotak pembatas setiap ref. Setiap item memiliki ref, number, role, name opsional, dan box: {x, y, width, height}; koordinat berada dalam ruang gambar yang ditangkap (viewport / fullpage / relatif-elemen). Field dihilangkan saat kosong. Profil existing-session merender overlay chrome-mcp pada tangkapan layar halaman tetapi tidak menggunakan helper proyeksi Playwright dan tidak menyertakan annotations; tangkapan layar CSS --element tidak didukung di sana. Tanpa Playwright atau chrome-mcp, tangkapan layar berlabel tidak tersedia. Rilis sebelumnya mengabaikan --full-page, --ref, dan --element pada tangkapan layar Playwright berlabel dan selalu mengembalikan tangkapan viewport; tangkapan layar berlabel kini menghormati cakupan tersebut.
• snapshot --urls menambahkan tujuan tautan yang ditemukan ke snapshot AI agar agent dapat memilih target navigasi langsung alih-alih menebak dari teks tautan saja.

Navigasi/klik/ketik (otomasi UI berbasis ref):

openclaw browser navigate https://example.comopenclaw browser click <ref>openclaw browser click-coords 120 340openclaw browser type <ref> "hello"openclaw browser press Enteropenclaw browser hover <ref>openclaw browser scrollintoview <ref>openclaw browser drag <startRef> <endRef>openclaw browser select <ref> OptionA OptionBopenclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'openclaw browser wait --text "Done"openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>openclaw browser evaluate --fn 'const title = document.title; return title;'openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'

evaluate --fn menerima sumber fungsi, ekspresi, atau body statement. Body statement dibungkus sebagai fungsi async, jadi gunakan return untuk nilai yang ingin Anda dapatkan kembali. Gunakan evaluate --timeout-ms <ms> ketika fungsi sisi halaman mungkin membutuhkan waktu lebih lama daripada batas waktu evaluate default.

Respons tindakan mengembalikan targetId mentah saat ini setelah penggantian halaman yang dipicu tindakan ketika OpenClaw dapat membuktikan tab penggantinya. Skrip tetap harus menyimpan dan meneruskan suggestedTargetId/label untuk alur kerja jangka panjang.

Helper file + dialog:

openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>openclaw browser upload media://inbound/file.pdf --ref <ref>openclaw browser waitfordownloadopenclaw browser download <ref> report.pdfopenclaw browser dialog --acceptopenclaw browser dialog --dismiss --dialog-id d1

Profil Chrome terkelola menyimpan unduhan biasa yang dipicu klik ke direktori unduhan OpenClaw (/tmp/openclaw/downloads secara default, atau root temp yang dikonfigurasi). Gunakan waitfordownload atau download ketika agent perlu menunggu file tertentu dan mengembalikan path-nya; waiter eksplisit tersebut memiliki unduhan berikutnya. Unggahan menerima file dari root unggahan temp OpenClaw dan media masuk yang dikelola OpenClaw, termasuk referensi media://inbound/<id> dan media/inbound/<id> yang relatif sandbox. Ref media bersarang, traversal, dan path lokal arbitrer tetap ditolak. Ketika suatu tindakan membuka dialog modal, respons tindakan mengembalikan blockedByDialog dengan browserState.dialogs.pending; teruskan --dialog-id untuk menjawabnya secara langsung. Dialog yang ditangani di luar OpenClaw muncul di bawah browserState.dialogs.recent.

State dan penyimpanan

Viewport + emulasi:

openclaw browser resize 1280 720openclaw browser set viewport 1280 720openclaw browser set offline onopenclaw browser set media darkopenclaw browser set timezone Europe/Londonopenclaw browser set locale en-GBopenclaw browser set geo 51.5074 -0.1278 --accuracy 25openclaw browser set device "iPhone 14"openclaw browser set headers '{"x-test":"1"}'openclaw browser set credentials myuser mypass

Cookie + penyimpanan:

openclaw browser cookiesopenclaw browser cookies set session abc123 --url https://example.comopenclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set token abc123openclaw browser storage session clear

Debugging

openclaw browser console --level erroropenclaw browser pdfopenclaw browser responsebody "**/api"openclaw browser highlight <ref>openclaw browser errors --clearopenclaw browser requests --filter apiopenclaw browser trace startopenclaw browser trace stop --out trace.zip

Chrome yang ada melalui MCP

Gunakan profil bawaan user, atau buat profil existing-session Anda sendiri:

openclaw browser --browser-profile user tabsopenclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"openclaw browser create-profile --name chrome-port --driver existing-session --cdp-url http://127.0.0.1:9222openclaw browser --browser-profile chrome-live tabs

Path existing-session default adalah auto-connect Chrome MCP khusus host. Jika browser sudah berjalan dengan endpoint DevTools, teruskan --cdp-url agar Chrome MCP melampirkan ke endpoint tersebut. Untuk Docker, Browserless, atau setup jarak jauh lain yang tidak membutuhkan semantik Chrome MCP, gunakan profil CDP.

Batas existing-session saat ini:

• tindakan berbasis snapshot menggunakan ref, bukan selector CSS
• browser.actionTimeoutMs menetapkan default permintaan act yang didukung ke 60000 ms saat pemanggil menghilangkan timeoutMs; timeoutMs per panggilan tetap diutamakan.
• click hanya klik kiri
• type tidak mendukung slowly=true
• press tidak mendukung delayMs
• hover, scrollintoview, drag, select, fill, dan evaluate menolak penimpaan timeout per panggilan
• select hanya mendukung satu nilai
• wait --load networkidle tidak didukung pada profil sesi yang sudah ada (berfungsi pada CDP terkelola dan mentah/jarak jauh)
• unggahan file memerlukan --ref / --input-ref, tidak mendukung CSS --element, dan saat ini mendukung satu file dalam satu waktu
• hook dialog tidak mendukung --timeout
• tangkapan layar mendukung tangkapan halaman dan --ref, tetapi bukan CSS --element
• responsebody, intersepsi unduhan, ekspor PDF, dan tindakan batch masih memerlukan browser terkelola atau profil CDP mentah

Kontrol browser jarak jauh (proxy host node)

Jika Gateway berjalan di mesin yang berbeda dari browser, jalankan host node pada mesin yang memiliki Chrome/Brave/Edge/Chromium. Gateway akan mem-proxy tindakan browser ke node tersebut (tidak diperlukan server kontrol browser terpisah).

Gunakan gateway.nodes.browser.mode untuk mengontrol perutean otomatis dan gateway.nodes.browser.node untuk menetapkan node tertentu jika beberapa node terhubung.

Keamanan + penyiapan jarak jauh: Alat browser, Akses jarak jauh, Tailscale, Keamanan

Terkait

• Referensi CLI
• Browser