​

Browser (dikelola openclaw)

• Anggap ini sebagai browser terpisah, khusus 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 asli Anda yang 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, tangkapan layar, 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 ketika plugins.allow disetel.
• plugins.entries.browser.enabled=true saja juga tidak cukup ketika plugins.allow disetel.
• 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 memulihkan perilaku browser bawaan default.

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

​

Profil: openclaw vs user

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

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

​

Konfigurasi

{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // default mode jaringan tepercaya
      // allowPrivateNetwork: true, // alias lama
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // override profil tunggal lama
    remoteCdpTimeoutMs: 1500, // timeout HTTP CDP jarak jauh (md)
    remoteCdpHandshakeTimeoutMs: 3000, // timeout handshake WebSocket CDP jarak jauh (md)
    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 melakukan bind ke loopback pada port yang diturunkan dari gateway.port (default: 18791, yaitu gateway + 2).
• Jika Anda mengoverride port Gateway (gateway.port atau OPENCLAW_GATEWAY_PORT), port browser turunannya bergeser agar tetap berada dalam “keluarga” yang sama.
• cdpUrl default ke port CDP lokal yang dikelola saat tidak disetel.
• remoteCdpTimeoutMs berlaku untuk pemeriksaan keterjangkauan CDP jarak jauh (bukan loopback).
• remoteCdpHandshakeTimeoutMs berlaku untuk pemeriksaan keterjangkauan WebSocket CDP jarak jauh.
• Navigasi browser/buka-tab dilindungi SSRF sebelum navigasi dan diperiksa ulang sebisanya pada URL http(s) final setelah navigasi.
• Dalam mode SSRF ketat, penemuan/probe endpoint CDP jarak jauh (cdpUrl, termasuk lookup /json/version) juga diperiksa.
• browser.ssrfPolicy.dangerouslyAllowPrivateNetwork default ke true (model jaringan tepercaya). Setel ke false untuk penelusuran ketat hanya publik.
• browser.ssrfPolicy.allowPrivateNetwork tetap didukung sebagai alias lama untuk kompatibilitas.
• attachOnly: true berarti “jangan pernah meluncurkan browser lokal; hanya attach jika browser sudah berjalan.”
• color + color per profil memberi warna pada UI browser sehingga 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 mengalokasikan otomatis cdpPort/cdpUrl — setel itu hanya untuk CDP jarak jauh.
• driver: "existing-session" menggunakan Chrome DevTools MCP alih-alih CDP mentah. Jangan setel cdpUrl untuk driver itu.
• Setel 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 lainnya)

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 pada mesin yang memiliki browser; Gateway memproksikan tindakan browser ke host itu.
• CDP jarak jauh: setel browser.profiles.<name>.cdpUrl (atau browser.cdpUrl) untuk attach ke browser berbasis Chromium jarak jauh. Dalam hal 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 melepas override emulasi Playwright/CDP (viewport, skema warna, locale, timezone, mode offline, dan status serupa), meskipun tidak ada proses browser yang diluncurkan oleh OpenClaw

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

​

Proksi browser node (default tanpa config)

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

​

Browserless (CDP jarak jauh terhosting)

{
  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 asli Anda.
• Pilih endpoint region yang sesuai dengan akun Browserless Anda (lihat dokumentasinya).
• Jika Browserless memberi Anda base URL HTTPS, Anda dapat mengubahnya menjadi wss:// untuk koneksi CDP langsung atau tetap menggunakan URL HTTPS dan biarkan OpenClaw menemukan /json/version.

​

Penyedia CDP WebSocket langsung

• Endpoint HTTP(S) — OpenClaw memanggil /json/version untuk menemukan URL debugger WebSocket, lalu terhubung.
• Endpoint WebSocket (ws:// / wss://) — OpenClaw terhubung langsung, melewati /json/version. Gunakan ini untuk layanan seperti Browserless, Browserbase, atau penyedia mana pun yang memberi Anda URL 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 dashboard Overview.
• Ganti <BROWSERBASE_API_KEY> dengan kunci API Browserbase asli Anda.
• Browserbase otomatis membuat sesi browser saat koneksi WebSocket dibuka, jadi tidak perlu langkah pembuatan sesi manual.
• Tingkat gratis mengizinkan satu sesi bersamaan dan satu jam browser per bulan. Lihat pricing untuk batas paket berbayar.
• Lihat dokumentasi Browserbase untuk referensi API lengkap, panduan SDK, dan contoh integrasi.

​

Keamanan

• Kontrol browser hanya loopback; akses mengalir melalui autentikasi Gateway atau pairing node.
• API HTTP browser loopback mandiri menggunakan autentikasi shared-secret saja: autentikasi bearer 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 autentikasi shared-secret yang dikonfigurasi, OpenClaw otomatis membuat gateway.auth.token saat startup dan menyimpannya ke config.
• OpenClaw tidak otomatis membuat token itu saat gateway.auth.mode sudah password, none, atau trusted-proxy.
• Simpan Gateway dan host node apa pun di jaringan pribadi (Tailscale); hindari eksposur publik.
• Perlakukan URL/token CDP jarak jauh sebagai rahasia; pilih env var atau secrets manager.

• Pilih endpoint terenkripsi (HTTPS atau WSS) dan token berumur pendek jika memungkinkan.
• 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 ada: profil Chrome Anda yang ada melalui koneksi otomatis Chrome DevTools MCP

• Profil openclaw dibuat otomatis jika belum ada.
• Profil user bersifat bawaan untuk attach existing-session Chrome MCP.
• Profil existing-session selain user bersifat opt-in; buat dengan --driver existing-session.
• Port CDP lokal dialokasikan dari 18800–18899 secara default.
• Menghapus profil 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 user bawaan menggunakan koneksi otomatis 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 menampilkan daftar tab browser Anda yang sudah terbuka
• snapshot mengembalikan ref dari tab live yang dipilih

• browser berbasis Chromium target versinya 144+
• remote debugging diaktifkan di halaman inspect browser itu
• browser menampilkan prompt persetujuan attach dan Anda menerimanya
• openclaw doctor memigrasikan config browser berbasis extension lama dan memeriksa bahwa Chrome terpasang secara lokal untuk profil koneksi otomatis 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, teruskan nama profil eksplisit tersebut.
• Pilih mode ini hanya saat pengguna sedang 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 --autoConnect Chrome DevTools MCP resmi di sini. Jika userDataDir disetel, OpenClaw meneruskannya untuk menargetkan direktori data pengguna Chromium eksplisit tersebut.
• Tangkapan layar existing-session mendukung tangkapan halaman dan tangkapan elemen --ref dari snapshot, tetapi tidak mendukung selector CSS --element.
• Tangkapan layar halaman existing-session berfungsi tanpa Playwright melalui Chrome MCP. Tangkapan layar elemen berbasis ref (--ref) juga berfungsi di sana, tetapi --full-page tidak dapat digabungkan dengan --ref atau --element.
• Tindakan existing-session masih lebih terbatas daripada jalur browser terkelola:
  • click, type, hover, scrollIntoView, drag, dan select memerlukan ref snapshot alih-alih selector CSS
  • click hanya untuk 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 dalam satu waktu, dan tidak mendukung penargetan CSS element.
• Hook dialog existing-session tidak mendukung override timeout.
• Beberapa fitur masih memerlukan jalur browser terkelola, termasuk tindakan batch, ekspor PDF, intersepsi download, dan responsebody.
• Existing-session bersifat lokal terhadap host. Jika Chrome berada di mesin lain atau namespace jaringan lain, gunakan CDP jarak jauh atau host node.

​

Jaminan isolasi

• Direktori data pengguna khusus: tidak pernah menyentuh profil browser pribadi Anda.
• Port khusus: menghindari 9222 untuk mencegah bentrokan dengan alur kerja dev.
• 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/tangkapan layar: GET /snapshot, POST /screenshot
• Tindakan: POST /navigate, POST /act
• Hook: POST /hooks/file-chooser, POST /hooks/dialog
• Download: 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
• Status: GET /cookies, POST /cookies/set, POST /cookies/clear
• Status: 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 header trusted-proxy atau identitas Tailscale Serve.
• Jika gateway.auth.mode adalah none atau trusted-proxy, rute browser loopback ini tidak mewarisi mode pembawa identitas tersebut; tetap pertahankan hanya loopback.

​

Persyaratan Playwright

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

• navigate
• act
• Snapshot AI / role snapshot
• Tangkapan layar elemen selector CSS (--element)
• Ekspor PDF browser penuh

​

Instalasi Playwright di Docker

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

​

Cara kerjanya (internal)

• Sebuah server kontrol kecil menerima permintaan HTTP.
• Server ini terhubung ke browser berbasis Chromium (Chrome/Brave/Edge/Chromium) melalui CDP.
• Untuk tindakan lanjutan (klik/ketik/snapshot/PDF), server ini 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. Ini menutup sesi kontrol aktif dan membersihkan 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 klik/tekan yang memicu chooser/dialog.
• Jalur output download dan trace dibatasi ke root temp OpenClaw:
  • trace: /tmp/openclaw (fallback: ${os.tmpdir()}/openclaw)
  • download: /tmp/openclaw/downloads (fallback: ${os.tmpdir()}/openclaw/downloads)
• Jalur upload dibatasi ke root upload temp OpenClaw:
  • upload: /tmp/openclaw/uploads (fallback: ${os.tmpdir()}/openclaw/uploads)
• upload juga dapat menyetel input file secara langsung 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): setel browser.snapshotDefaults.mode: "efficient" untuk menggunakan snapshot efisien saat pemanggil tidak meneruskan 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 (berpasangan dengan role ref seperti e12).
  • --interactive menghasilkan daftar datar elemen interaktif yang mudah dipilih (terbaik untuk mendorong tindakan).
  • --labels menambahkan tangkapan layar khusus viewport dengan label ref yang dioverlay (mencetak MEDIA:<path>).
• click/type/dll memerlukan ref dari snapshot (baik numerik 12 maupun role ref e12). Selector CSS 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 diresolusikan 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 diresolusikan melalui getByRole(...) (ditambah nth() untuk duplikat).
  • Tambahkan --labels untuk menyertakan tangkapan layar viewport dengan label e12 yang dioverlay.

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

​

Peningkatan wait

• Tunggu URL (glob didukung oleh Playwright):
  • openclaw browser wait --url "**/dash"
• Tunggu status load:
  • 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> (pilih 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

​

Kenop status dan environment

• Cookie: cookies, cookies set, cookies clear
• Storage: storage local|session get|set|clear
• Offline: set offline on|off
• Header: set headers --headers-json '{"X-Debug":"1"}' (legacy set headers --json '{"X-Debug":"1"}' tetap didukung)
• HTTP basic auth: set credentials user pass (atau --clear)
• Geolokasi: 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.
• Simpan Gateway/host node tetap privat (hanya loopback atau tailnet).
• Endpoint CDP jarak jauh sangat kuat; tunnel dan lindungi endpoint tersebut.

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

​

Pemecahan masalah

​

Tool agen + cara kerja kontrol

• 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 sandboxed, target: "host" memerlukan agents.defaults.sandbox.browser.allowHostControl=true.
  • Jika target dihilangkan: sesi sandboxed default ke sandbox, sesi non-sandbox default ke host.
  • Jika node yang mendukung browser terhubung, tool dapat otomatis diarahkan ke node itu kecuali Anda mengunci target="host" atau target="node".

​

Terkait

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