​

Browser (dikelola openclaw)

• Anggap ini sebagai browser terpisah yang hanya untuk agen.
• Profil openclaw tidak menyentuh profil browser pribadi Anda.
• Agen dapat membuka tab, membaca halaman, mengeklik, dan mengetik di jalur yang aman.
• Profil bawaan user terhubung ke sesi Chrome Anda yang nyata dan sudah login melalui Chrome MCP.

​

Yang Anda dapatkan

• Profil browser terpisah bernama openclaw (aksen oranye secara default).
• Kontrol tab deterministik (daftar/buka/fokus/tutup).
• Tindakan agen (klik/ketik/seret/pilih), snapshot, screenshot, PDF.
• Dukungan multi-profil opsional (openclaw, work, remote, …).

​

Mulai cepat

openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

​

Kontrol Plugin

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

• plugins.entries.browser.enabled tidak dinonaktifkan
• browser.enabled=true

​

Perintah atau tool browser hilang

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

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

• browser.enabled=true saja tidak cukup saat plugins.allow diatur.
• plugins.entries.browser.enabled=true saja juga tidak cukup saat plugins.allow diatur.
• tools.alsoAllow: ["browser"] tidak memuat Plugin browser bawaan. Itu hanya menyesuaikan kebijakan tool setelah Plugin sudah dimuat.
• Jika Anda tidak memerlukan allowlist Plugin yang ketat, menghapus plugins.allow juga akan memulihkan perilaku browser bawaan default.

• openclaw browser adalah perintah yang tidak dikenal.
• browser.request tidak ada.
• Agen melaporkan tool browser tidak tersedia atau hilang.

​

Profil: openclaw vs user

• openclaw: browser terkelola dan terisolasi (tidak memerlukan ekstensi).
• user: profil attach Chrome MCP bawaan untuk sesi Chrome nyata Anda yang sudah login.

• Default: gunakan browser openclaw yang terisolasi.
• Pilih profile="user" saat sesi login yang sudah ada penting dan pengguna berada di depan komputer untuk mengklik/menyetujui prompt attach apa pun.
• profile adalah override eksplisit saat Anda menginginkan mode browser tertentu.

​

Konfigurasi

{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // aktifkan hanya untuk akses jaringan privat tepercaya
      // allowPrivateNetwork: true, // alias lama
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // override lama satu profil
    remoteCdpTimeoutMs: 1500, // timeout HTTP CDP jarak jauh (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // timeout handshake WebSocket CDP jarak jauh (ms)
    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" },
      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" },
    },
  },
}

• Layanan kontrol browser bind ke loopback pada port yang diturunkan dari gateway.port (default: 18791, yaitu gateway + 2).
• Jika Anda meng-override port Gateway (gateway.port atau OPENCLAW_GATEWAY_PORT), port browser turunan akan bergeser agar tetap berada dalam “keluarga” yang sama.
• cdpUrl secara default menggunakan port CDP lokal terkelola saat tidak diatur.
• remoteCdpTimeoutMs berlaku untuk pemeriksaan keterjangkauan CDP jarak jauh (non-loopback).
• remoteCdpHandshakeTimeoutMs berlaku untuk pemeriksaan keterjangkauan WebSocket CDP jarak jauh.
• Navigasi/buka-tab browser dilindungi SSRF sebelum navigasi dan diperiksa ulang sebisa mungkin pada URL akhir http(s) setelah navigasi.
• Dalam mode SSRF ketat, discovery/probe endpoint CDP jarak jauh (cdpUrl, termasuk lookup /json/version) juga diperiksa.
• browser.ssrfPolicy.dangerouslyAllowPrivateNetwork nonaktif secara default. Set ke true hanya saat Anda memang mempercayai akses browser jaringan privat.
• browser.ssrfPolicy.allowPrivateNetwork tetap didukung sebagai alias lama untuk kompatibilitas.
• attachOnly: true berarti “jangan pernah meluncurkan browser lokal; hanya attach jika browser itu sudah berjalan.”
• color + color per profil memberi warna pada UI browser agar Anda dapat melihat profil mana yang aktif.
• Profil default adalah openclaw (browser mandiri yang dikelola OpenClaw). Gunakan defaultProfile: "user" untuk memilih browser pengguna yang sudah login.
• Urutan deteksi otomatis: browser default sistem jika berbasis Chromium; jika tidak maka Chrome → Brave → Edge → Chromium → Chrome Canary.
• Profil openclaw lokal otomatis menetapkan cdpPort/cdpUrl — set itu hanya untuk CDP jarak jauh.
• driver: "existing-session" menggunakan Chrome DevTools MCP alih-alih CDP mentah. Jangan set cdpUrl untuk driver tersebut.
• Set browser.profiles.<name>.userDataDir saat profil existing-session harus attach ke profil pengguna Chromium non-default seperti Brave atau Edge.

​

Gunakan Brave (atau browser berbasis Chromium lain)

openclaw config set browser.executablePath "/usr/bin/google-chrome"

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

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

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

​

Kontrol lokal vs jarak jauh

• Kontrol lokal (default): Gateway memulai layanan kontrol loopback dan dapat meluncurkan browser lokal.
• Kontrol jarak jauh (host node): jalankan host node di mesin yang memiliki browser; Gateway mem-proxy tindakan browser ke host itu.
• CDP jarak jauh: set browser.profiles.<name>.cdpUrl (atau browser.cdpUrl) untuk attach ke browser berbasis Chromium jarak jauh. Dalam kasus ini, OpenClaw tidak akan meluncurkan browser lokal.

• profil terkelola lokal: openclaw browser stop menghentikan proses browser yang diluncurkan OpenClaw
• profil attach-only dan CDP jarak jauh: openclaw browser stop menutup sesi kontrol aktif dan melepaskan override emulasi Playwright/CDP (viewport, skema warna, locale, zona waktu, mode offline, dan state serupa), meskipun tidak ada proses browser yang diluncurkan oleh OpenClaw

• Token kueri (misalnya https://provider.example?token=<token>)
• HTTP Basic auth (misalnya https://user:pass@provider.example)

​

Proxy browser Node (default tanpa config)

• Host node mengekspos server kontrol browser lokalnya melalui perintah proxy.
• Profil berasal dari config browser.profiles milik node itu sendiri (sama seperti lokal).
• nodeHost.browserProxy.allowProfiles bersifat opsional. Biarkan kosong untuk perilaku lama/default: semua profil yang dikonfigurasi tetap dapat dijangkau melalui proxy, termasuk route buat/hapus profil.
• Jika Anda set nodeHost.browserProxy.allowProfiles, OpenClaw memperlakukannya sebagai batas least-privilege: hanya profil dalam allowlist yang dapat ditargetkan, dan route buat/hapus profil persisten diblokir pada permukaan proxy.
• Nonaktifkan jika Anda tidak menginginkannya:
  • Pada node: nodeHost.browserProxy.enabled=false
  • Pada gateway: gateway.nodes.browser.mode="off"

​

Browserless (CDP jarak jauh yang di-host)

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

• Ganti <BROWSERLESS_API_KEY> dengan token Browserless nyata Anda.
• Pilih endpoint region yang sesuai dengan akun Browserless Anda (lihat dokumen mereka).
• Jika Browserless memberi Anda URL dasar HTTPS, Anda dapat mengubahnya ke wss:// untuk koneksi CDP langsung atau tetap menggunakan URL HTTPS dan membiarkan OpenClaw menemukan /json/version.

​

Provider CDP WebSocket langsung

• Discovery HTTP(S) — http://host[:port] atau https://host[:port]. OpenClaw memanggil /json/version untuk menemukan URL debugger WebSocket, lalu terhubung. Tidak ada fallback WebSocket.
• Endpoint WebSocket langsung — ws://host[:port]/devtools/<kind>/<id> atau wss://... dengan path /devtools/browser|page|worker|shared_worker|service_worker/<id>. OpenClaw terhubung langsung melalui handshake WebSocket dan melewati /json/version sepenuhnya.
• Root WebSocket polos — ws://host[:port] atau wss://host[:port] tanpa path /devtools/... (misalnya Browserless, Browserbase). OpenClaw mencoba discovery HTTP /json/version terlebih dahulu (menormalkan skema ke http/https); jika discovery mengembalikan webSocketDebuggerUrl, URL itu digunakan, jika tidak OpenClaw akan fallback ke handshake WebSocket langsung pada root polos. Ini mencakup baik port debug jarak jauh gaya Chrome maupun provider yang hanya WebSocket.

​

Browserbase

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

• Daftar dan salin API Key Anda dari dasbor Overview.
• Ganti <BROWSERBASE_API_KEY> dengan API key Browserbase Anda yang asli.
• Browserbase otomatis membuat sesi browser saat koneksi WebSocket dibuat, jadi tidak diperlukan langkah pembuatan sesi manual.
• Tier gratis memungkinkan satu sesi bersamaan dan satu jam browser per bulan. Lihat pricing untuk batas paket berbayar.
• Lihat docs Browserbase untuk referensi API lengkap, panduan SDK, dan contoh integrasi.

​

Keamanan

• Kontrol browser hanya loopback; akses mengalir melalui auth Gateway atau pairing node.
• API HTTP browser loopback mandiri menggunakan hanya auth shared-secret: bearer auth token gateway, x-openclaw-password, atau HTTP Basic auth dengan password gateway yang dikonfigurasi.
• Header identitas Tailscale Serve dan gateway.auth.mode: "trusted-proxy" tidak mengautentikasi API browser loopback mandiri ini.
• Jika kontrol browser diaktifkan dan tidak ada auth shared-secret yang dikonfigurasi, OpenClaw otomatis menghasilkan gateway.auth.token saat startup dan menyimpannya ke config.
• OpenClaw tidak otomatis menghasilkan token itu ketika gateway.auth.mode sudah password, none, atau trusted-proxy.
• Simpan Gateway dan host node apa pun di jaringan privat (Tailscale); hindari eksposur publik.
• Perlakukan URL/token CDP jarak jauh sebagai rahasia; lebih baik gunakan env var atau secrets manager.

• Jika memungkinkan, pilih endpoint terenkripsi (HTTPS atau WSS) dan token berumur pendek.
• Hindari menyematkan token berumur panjang langsung di file config.

​

Profil (multi-browser)

• dikelola openclaw: instance browser berbasis Chromium khusus dengan direktori data pengguna + port CDP sendiri
• jarak jauh: URL CDP eksplisit (browser berbasis Chromium yang berjalan di tempat lain)
• sesi yang sudah ada: profil Chrome Anda yang sudah ada melalui auto-connect Chrome DevTools MCP

• Profil openclaw dibuat otomatis jika tidak ada.
• Profil user adalah bawaan untuk attach existing-session Chrome MCP.
• Profil existing-session bersifat opt-in selain user; buat dengan --driver existing-session.
• Port CDP lokal dialokasikan dari 18800–18899 secara default.
• Menghapus profil akan memindahkan direktori data lokalnya ke Trash.

​

Existing-session melalui Chrome DevTools MCP

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

• user

• Profil bawaan user menggunakan auto-connect Chrome MCP, yang menargetkan profil Google Chrome lokal default.

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

1. Buka halaman inspect browser tersebut untuk remote debugging.
2. Aktifkan remote debugging.
3. Biarkan browser tetap berjalan dan setujui prompt koneksi saat OpenClaw attach.

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

openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai

• status menampilkan driver: existing-session
• status menampilkan transport: chrome-mcp
• status menampilkan running: true
• tabs mencantumkan tab browser Anda yang sudah terbuka
• snapshot mengembalikan ref dari tab live yang dipilih

• browser berbasis Chromium target memiliki versi 144+
• remote debugging diaktifkan di halaman inspect browser tersebut
• browser menampilkan prompt persetujuan attach dan Anda menerimanya
• openclaw doctor memigrasikan config browser berbasis ekstensi lama dan memeriksa bahwa Chrome terpasang secara lokal untuk profil auto-connect default, tetapi tidak dapat mengaktifkan remote debugging di sisi browser untuk Anda

• Gunakan profile="user" saat Anda memerlukan status browser pengguna yang sudah login.
• Jika Anda menggunakan profil existing-session kustom, berikan nama profil eksplisit itu.
• Pilih mode ini hanya saat pengguna berada di depan komputer untuk menyetujui prompt attach.
• Gateway atau host node dapat menjalankan npx chrome-devtools-mcp@latest --autoConnect

• Jalur ini berisiko lebih tinggi daripada profil openclaw yang terisolasi karena dapat bertindak di dalam sesi browser Anda yang sudah login.
• OpenClaw tidak meluncurkan browser untuk driver ini; OpenClaw hanya attach ke sesi yang sudah ada.
• OpenClaw menggunakan alur resmi Chrome DevTools MCP --autoConnect di sini. Jika userDataDir diatur, OpenClaw meneruskannya untuk menargetkan direktori data pengguna Chromium eksplisit tersebut.
• Screenshot existing-session mendukung tangkapan halaman dan tangkapan elemen --ref dari snapshot, tetapi tidak mendukung selector CSS --element.
• Screenshot halaman existing-session bekerja tanpa Playwright melalui Chrome MCP. Screenshot elemen berbasis ref (--ref) juga berfungsi di sana, tetapi --full-page tidak dapat digabungkan dengan --ref atau --element.
• Tindakan existing-session masih lebih terbatas dibanding jalur browser terkelola:
  • click, type, hover, scrollIntoView, drag, dan select memerlukan ref snapshot alih-alih selector CSS
  • click hanya tombol kiri (tanpa override tombol atau modifier)
  • type tidak mendukung slowly=true; gunakan fill atau press
  • press tidak mendukung delayMs
  • hover, scrollIntoView, drag, select, fill, dan evaluate tidak mendukung override timeout per panggilan
  • select saat ini hanya mendukung satu nilai
• Existing-session wait --url mendukung pola exact, substring, dan glob seperti driver browser lainnya. wait --load networkidle belum didukung.
• Hook upload existing-session memerlukan ref atau inputRef, mendukung satu file sekali waktu, dan tidak mendukung penargetan CSS element.
• Hook dialog existing-session tidak mendukung override timeout.
• Beberapa fitur masih memerlukan jalur browser terkelola, termasuk batch actions, ekspor PDF, intersepsi unduhan, dan responsebody.
• Existing-session dapat attach pada host yang dipilih atau melalui node browser yang terhubung. Jika Chrome berada di tempat lain dan tidak ada node browser yang terhubung, gunakan CDP jarak jauh atau host node sebagai gantinya.

​

Jaminan isolasi

• Direktori data pengguna khusus: tidak pernah menyentuh profil browser pribadi Anda.
• Port khusus: menghindari 9222 untuk mencegah benturan dengan alur kerja pengembangan.
• Kontrol tab deterministik: targetkan tab berdasarkan targetId, bukan “tab terakhir”.

​

Pemilihan browser

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

• macOS: memeriksa /Applications dan ~/Applications.
• Linux: mencari google-chrome, brave, microsoft-edge, chromium, dll.
• Windows: memeriksa lokasi instalasi umum.

​

API kontrol (opsional)

• Status/start/stop: GET /, POST /start, POST /stop
• Tab: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
• Snapshot/screenshot: GET /snapshot, POST /screenshot
• Tindakan: POST /navigate, POST /act
• Hook: POST /hooks/file-chooser, POST /hooks/dialog
• Unduhan: POST /download, POST /wait/download
• Debugging: GET /console, POST /pdf
• Debugging: GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
• Jaringan: POST /response/body
• State: GET /cookies, POST /cookies/set, POST /cookies/clear
• State: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
• Pengaturan: POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

• Authorization: Bearer <gateway token>
• x-openclaw-password: <gateway password> atau HTTP Basic auth dengan password tersebut

• API browser loopback mandiri ini tidak menggunakan trusted-proxy atau header identitas Tailscale Serve.
• Jika gateway.auth.mode adalah none atau trusted-proxy, route browser loopback ini tidak mewarisi mode yang membawa identitas tersebut; tetap pertahankan hanya loopback.

​

Kontrak error /act

{ "error": "<message>", "code": "ACT_*" }

• ACT_KIND_REQUIRED (HTTP 400): kind tidak ada atau tidak dikenali.
• ACT_INVALID_REQUEST (HTTP 400): payload tindakan gagal dinormalisasi atau divalidasi.
• ACT_SELECTOR_UNSUPPORTED (HTTP 400): selector digunakan dengan jenis tindakan yang tidak didukung.
• ACT_EVALUATE_DISABLED (HTTP 403): evaluate (atau wait --fn) dinonaktifkan oleh config.
• ACT_TARGET_ID_MISMATCH (HTTP 403): targetId tingkat atas atau yang dibatch bertentangan dengan target request.
• ACT_EXISTING_SESSION_UNSUPPORTED (HTTP 501): tindakan tidak didukung untuk profil existing-session.

​

Persyaratan Playwright

• snapshot ARIA
• screenshot halaman untuk browser openclaw terkelola saat CDP WebSocket per-tab tersedia
• screenshot halaman untuk profil existing-session / Chrome MCP
• screenshot berbasis ref (--ref) untuk existing-session dari output snapshot

• navigate
• act
• snapshot AI / role snapshot
• screenshot elemen selector CSS (--element)
• ekspor PDF browser penuh

​

Instalasi Playwright Docker

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

​

Cara kerjanya (internal)

• Server kontrol kecil menerima request HTTP.
• Server itu terhubung ke browser berbasis Chromium (Chrome/Brave/Edge/Chromium) melalui CDP.
• Untuk tindakan lanjutan (click/type/snapshot/PDF), server itu menggunakan Playwright di atas CDP.
• Saat Playwright tidak tersedia, hanya operasi non-Playwright yang tersedia.

​

Referensi cepat CLI

• openclaw browser status
• openclaw browser start
• openclaw browser stop
• openclaw browser tabs
• openclaw browser tab
• openclaw browser tab new
• openclaw browser tab select 2
• openclaw browser tab close 2
• openclaw browser open https://example.com
• openclaw browser focus abcd1234
• openclaw browser close abcd1234

• openclaw browser screenshot
• openclaw browser screenshot --full-page
• openclaw browser screenshot --ref 12
• openclaw browser screenshot --ref e12
• openclaw browser snapshot
• openclaw browser snapshot --format aria --limit 200
• openclaw browser snapshot --interactive --compact --depth 6
• openclaw browser snapshot --efficient
• openclaw browser snapshot --labels
• openclaw browser snapshot --selector "#main" --interactive
• openclaw browser snapshot --frame "iframe#main" --interactive
• openclaw browser console --level error

• Untuk profil attach-only dan CDP jarak jauh, openclaw browser stop tetap merupakan perintah pembersihan yang tepat setelah pengujian. Perintah ini menutup sesi kontrol aktif dan menghapus override emulasi sementara alih-alih mematikan browser dasarnya.
• openclaw browser errors --clear
• openclaw browser requests --filter api --clear
• openclaw browser pdf
• openclaw browser responsebody "**/api" --max-chars 5000

• openclaw browser navigate https://example.com
• openclaw browser resize 1280 720
• openclaw browser click 12 --double
• openclaw browser click e12 --double
• openclaw browser type 23 "hello" --submit
• openclaw browser press Enter
• openclaw browser hover 44
• openclaw browser scrollintoview e12
• openclaw browser drag 10 11
• openclaw browser select 9 OptionA OptionB
• openclaw browser download e12 report.pdf
• openclaw browser waitfordownload report.pdf
• openclaw browser upload /tmp/openclaw/uploads/file.pdf
• openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
• openclaw browser dialog --accept
• openclaw browser wait --text "Done"
• openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
• openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
• openclaw browser highlight e12
• openclaw browser trace start
• openclaw browser trace stop

• 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 theme dark
• openclaw browser storage session clear
• openclaw browser set offline on
• openclaw browser set headers --headers-json '{"X-Debug":"1"}'
• openclaw browser set credentials user pass
• openclaw browser set credentials --clear
• openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
• openclaw browser set geo --clear
• openclaw browser set media dark
• openclaw browser set timezone America/New_York
• openclaw browser set locale en-US
• openclaw browser set device "iPhone 14"

• upload dan dialog adalah panggilan arming; jalankan keduanya sebelum click/press yang memicu chooser/dialog.
• Path output unduhan dan trace dibatasi ke root temp OpenClaw:
  • trace: /tmp/openclaw (fallback: ${os.tmpdir()}/openclaw)
  • unduhan: /tmp/openclaw/downloads (fallback: ${os.tmpdir()}/openclaw/downloads)
• Path upload dibatasi ke root upload temp OpenClaw:
  • upload: /tmp/openclaw/uploads (fallback: ${os.tmpdir()}/openclaw/uploads)
• upload juga dapat langsung mengatur input file melalui --input-ref atau --element.
• snapshot:
  • --format ai (default saat Playwright terpasang): mengembalikan snapshot AI dengan ref numerik (aria-ref="<n>").
  • --format aria: mengembalikan pohon aksesibilitas (tanpa ref; hanya untuk inspeksi).
  • --efficient (atau --mode efficient): preset role snapshot ringkas (interactive + compact + depth + maxChars lebih rendah).
  • Default config (hanya tool/CLI): set browser.snapshotDefaults.mode: "efficient" untuk menggunakan snapshot efisien saat pemanggil tidak memberikan mode (lihat Konfigurasi Gateway).
  • Opsi role snapshot (--interactive, --compact, --depth, --selector) memaksa role-based snapshot dengan ref seperti ref=e12.
  • --frame "<iframe selector>" membatasi role snapshot ke iframe (dipasangkan dengan role ref seperti e12).
  • --interactive menghasilkan daftar datar elemen interaktif yang mudah dipilih (terbaik untuk menjalankan tindakan).
  • --labels menambahkan screenshot hanya viewport dengan label ref terhampar (mencetak MEDIA:<path>).
• click/type/dll memerlukan ref dari snapshot (baik numerik 12 maupun role ref e12). Selector CSS memang sengaja tidak didukung untuk tindakan.

​

Snapshot dan ref

• Snapshot AI (ref numerik): openclaw browser snapshot (default; --format ai)
  • Output: snapshot teks yang menyertakan ref numerik.
  • Tindakan: openclaw browser click 12, openclaw browser type 23 "hello".
  • Secara internal, ref di-resolve melalui aria-ref milik Playwright.
• Role snapshot (role ref seperti e12): openclaw browser snapshot --interactive (atau --compact, --depth, --selector, --frame)
  • Output: daftar/pohon berbasis role dengan [ref=e12] (dan opsional [nth=1]).
  • Tindakan: openclaw browser click e12, openclaw browser highlight e12.
  • Secara internal, ref di-resolve melalui getByRole(...) (ditambah nth() untuk duplikasi).
  • Tambahkan --labels untuk menyertakan screenshot viewport dengan label e12 yang dihamparkan.

• Ref tidak stabil antar navigasi; jika sesuatu gagal, jalankan ulang snapshot dan gunakan ref yang baru.
• Jika role snapshot diambil dengan --frame, role ref dibatasi ke iframe tersebut sampai role snapshot berikutnya.

​

Peningkatan kemampuan wait

• Tunggu URL (glob didukung oleh Playwright):
  • openclaw browser wait --url "**/dash"
• Tunggu status pemuatan:
  • openclaw browser wait --load networkidle
• Tunggu predikat JS:
  • openclaw browser wait --fn "window.ready===true"
• Tunggu selector menjadi terlihat:
  • openclaw browser wait "#main"

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

​

Alur kerja debugging

1. openclaw browser snapshot --interactive
2. Gunakan click <ref> / type <ref> (lebih baik role ref dalam mode interactive)
3. Jika masih gagal: openclaw browser highlight <ref> untuk melihat apa yang ditargetkan Playwright
4. Jika halaman berperilaku aneh:
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. Untuk debugging mendalam: rekam trace:
   • openclaw browser trace start
   • reproduksi masalahnya
   • openclaw browser trace stop (mencetak TRACE:<path>)

​

Output JSON

openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json

​

Pengaturan state dan environment

• Cookies: cookies, cookies set, cookies clear
• Storage: storage local|session get|set|clear
• Offline: set offline on|off
• Headers: set headers --headers-json '{"X-Debug":"1"}' (bentuk lama set headers --json '{"X-Debug":"1"}' tetap didukung)
• HTTP basic auth: set credentials user pass (atau --clear)
• Geolocation: set geo <lat> <lon> --origin "https://example.com" (atau --clear)
• Media: set media dark|light|no-preference|none
• Timezone / locale: set timezone ..., set locale ...
• Device / viewport:
  • set device "iPhone 14" (preset perangkat Playwright)
  • set viewport 1280 720

​

Keamanan & privasi

• Profil browser openclaw dapat berisi sesi yang sudah login; perlakukan sebagai sesuatu yang sensitif.
• browser act kind=evaluate / openclaw browser evaluate dan wait --fn mengeksekusi JavaScript arbitrer dalam konteks halaman. Prompt injection dapat mengarahkan ini. Nonaktifkan dengan browser.evaluateEnabled=false jika Anda tidak membutuhkannya.
• Untuk login dan catatan anti-bot (X/Twitter, dll.), lihat Login browser + posting X/Twitter.
• Jaga Gateway/host node tetap privat (hanya loopback atau tailnet).
• Endpoint CDP jarak jauh sangat berkuasa; tunnel-kan dan lindungi.

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // allow eksak opsional
    },
  },
}

​

Pemecahan masalah

​

Kegagalan startup CDP vs blok SSRF navigasi

• Kegagalan startup atau kesiapan CDP berarti OpenClaw tidak dapat mengonfirmasi bahwa control plane browser sehat.
• Blok SSRF navigasi berarti control plane browser sehat, tetapi target navigasi halaman ditolak oleh kebijakan.

• Kegagalan startup atau kesiapan CDP:
  • Chrome CDP websocket for profile "openclaw" is not reachable after start
  • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
• Blok SSRF navigasi:
  • alur open, navigate, snapshot, atau pembukaan tab gagal dengan error kebijakan browser/jaringan sementara start dan tabs tetap berfungsi

openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com

• Jika start gagal dengan not reachable after start, selesaikan masalah kesiapan CDP terlebih dahulu.
• Jika start berhasil tetapi tabs gagal, control plane masih tidak sehat. Perlakukan ini sebagai masalah keterjangkauan CDP, bukan masalah navigasi halaman.
• Jika start dan tabs berhasil tetapi open atau navigate gagal, control plane browser aktif dan kegagalan ada pada kebijakan navigasi atau halaman target.
• Jika start, tabs, dan open semuanya berhasil, jalur kontrol browser terkelola dasar dalam keadaan sehat.

• Config browser default ke objek kebijakan SSRF fail-closed bahkan saat Anda tidak mengonfigurasi browser.ssrfPolicy.
• Untuk profil terkelola loopback lokal openclaw, pemeriksaan kesehatan CDP sengaja melewati penegakan keterjangkauan SSRF browser untuk control plane lokal OpenClaw sendiri.
• Perlindungan navigasi terpisah. Hasil start atau tabs yang berhasil tidak berarti target open atau navigate berikutnya diizinkan.

• Jangan melonggarkan kebijakan SSRF browser secara default.
• Pilih pengecualian host yang sempit seperti hostnameAllowlist atau allowedHostnames daripada akses jaringan privat yang luas.
• Gunakan dangerouslyAllowPrivateNetwork: true hanya di environment yang memang tepercaya, tempat akses browser jaringan privat diperlukan dan telah ditinjau.

• start berhasil
• tabs berhasil
• open http://internal.example gagal

• start gagal dengan not reachable after start
• tabs juga gagal atau tidak dapat dijalankan

​

Tool agen + cara kontrol bekerja

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

• browser snapshot mengembalikan pohon UI yang stabil (AI atau ARIA).
• browser act menggunakan ID ref dari snapshot untuk klik/ketik/seret/pilih.
• browser screenshot menangkap piksel (halaman penuh atau elemen).
• browser menerima:
  • profile untuk memilih profil browser bernama (openclaw, chrome, atau CDP jarak jauh).
  • target (sandbox | host | node) untuk memilih tempat browser berada.
  • Dalam sesi sandbox, target: "host" memerlukan agents.defaults.sandbox.browser.allowHostControl=true.
  • Jika target dihilangkan: sesi sandbox default ke sandbox, sesi non-sandbox default ke host.
  • Jika node yang mampu menjalankan browser terhubung, tool dapat merutekan otomatis ke node tersebut kecuali Anda menetapkan target="host" atau target="node".

​

Terkait

• Ikhtisar Tools — semua tool agen yang tersedia
• Sandboxing — kontrol browser di environment sandbox
• Keamanan — risiko dan hardening kontrol browser