Langsung ke konten utama

​
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:

​
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 profiles
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw 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 doctor
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com
Panduan terperinci: Pemecahan masalah browser

​
Siklus hidup

openclaw browser status
openclaw browser doctor
openclaw browser doctor --deep
openclaw browser start
openclaw browser start --headless
openclaw browser stop
openclaw 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 profiles
openclaw browser create-profile --name work --color "#FF5A36"
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name remote --cdp-url https://browser-host.example.com
openclaw browser delete-profile --name work
Gunakan profil tertentu: 
openclaw browser --browser-profile work tabs

​
Tab

openclaw browser tabs
openclaw browser tab new --label docs
openclaw browser tab label t1 docs
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://docs.openclaw.ai --label docs
openclaw browser focus docs
openclaw 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 snapshot
openclaw browser snapshot --urls
Tangkapan layar: 
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref e12
openclaw 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.com
openclaw browser click <ref>
openclaw browser click-coords 120 340
openclaw browser type <ref> "hello"
openclaw browser press Enter
openclaw browser hover <ref>
openclaw browser scrollintoview <ref>
openclaw browser drag <startRef> <endRef>
openclaw browser select <ref> OptionA OptionB
openclaw 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 waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept
openclaw 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 720
openclaw browser set viewport 1280 720
openclaw browser set offline on
openclaw browser set media dark
openclaw browser set timezone Europe/London
openclaw browser set locale en-GB
openclaw browser set geo 51.5074 -0.1278 --accuracy 25
openclaw browser set device "iPhone 14"
openclaw browser set headers '{"x-test":"1"}'
openclaw browser set credentials myuser mypass
Cookie + penyimpanan: 
openclaw browser cookies
openclaw browser cookies set session abc123 --url https://example.com
openclaw browser cookies clear
openclaw browser storage local get
openclaw browser storage local set token abc123
openclaw browser storage session clear

​
Debugging

openclaw browser console --level error
openclaw browser pdf
openclaw browser responsebody "**/api"
openclaw browser highlight <ref>
openclaw browser errors --clear
openclaw browser requests --filter api
openclaw browser trace start
openclaw 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 tabs
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw 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:9222
openclaw 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