Peramban (dikelola oleh OpenClaw)

OpenClaw dapat menjalankan profil Chrome/Brave/Edge/Chromium khusus yang dikendalikan oleh agen. Profil ini terisolasi dari peramban pribadi Anda dan dikelola melalui layanan kontrol lokal kecil di dalam Gateway (hanya loopback).

Tampilan pemula:

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

# Yang Anda dapatkan

• Profil peramban terpisah bernama openclaw (aksen oranye secara default).
• Kontrol tab deterministik (daftar/buka/fokus/tutup).
• Tindakan agen (klik/ketik/seret/pilih), snapshot, tangkapan layar, PDF.
• Skills browser-automation bawaan yang mengajarkan agen loop pemulihan snapshot, tab stabil, ref kedaluwarsa, dan penghambat manual saat Plugin peramban diaktifkan.
• Dukungan multi-profil opsional (openclaw, work, remote, ...).

Peramban ini bukan peramban harian Anda. Ini adalah permukaan yang aman dan terisolasi untuk otomasi dan verifikasi agen.

# Mulai cepat

openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw doctor --deep
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

Jika Anda mendapatkan "Browser disabled", aktifkan di konfigurasi (lihat di bawah) dan mulai ulang Gateway.

Jika openclaw browser sama sekali tidak ada, atau agen mengatakan alat peramban tidak tersedia, lompat ke Perintah atau alat peramban hilang.

# Kontrol Plugin

Alat browser default adalah Plugin bawaan. Nonaktifkan untuk menggantinya dengan Plugin lain yang mendaftarkan nama alat browser yang sama:

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

Default memerlukan plugins.entries.browser.enabled dan browser.enabled=true. Menonaktifkan hanya Plugin akan menghapus CLI openclaw browser, metode gateway browser.request, alat agen, dan layanan kontrol sebagai satu unit; konfigurasi browser.* Anda tetap utuh untuk pengganti.

Perubahan konfigurasi peramban memerlukan mulai ulang Gateway agar Plugin dapat mendaftarkan ulang layanannya.

# Panduan agen

Catatan profil alat: tools.profile: "coding" menyertakan web_search dan web_fetch, tetapi tidak menyertakan alat browser lengkap. Jika agen atau sub-agen yang dibuat harus menggunakan otomasi peramban, tambahkan browser pada tahap profil:

{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

Untuk satu agen, gunakan agents.list[].tools.alsoAllow: ["browser"]. tools.subagents.tools.allow: ["browser"] saja tidak cukup karena kebijakan sub-agen diterapkan setelah pemfilteran profil.

Plugin peramban menyertakan dua tingkat panduan agen:

• Deskripsi alat browser membawa kontrak ringkas yang selalu aktif: pilih profil yang tepat, pertahankan ref pada tab yang sama, gunakan tabId/label untuk penargetan tab, dan muat Skills peramban untuk pekerjaan multi-langkah.
• Skills browser-automation bawaan membawa loop operasi yang lebih panjang: periksa status/tab terlebih dahulu, beri label pada tab tugas, ambil snapshot sebelum bertindak, ambil snapshot ulang setelah perubahan UI, pulihkan ref kedaluwarsa sekali, dan laporkan login/2FA/captcha atau penghambat kamera/mikrofon sebagai tindakan manual alih-alih menebak.

Skills bawaan Plugin tercantum dalam Skills yang tersedia bagi agen saat Plugin diaktifkan. Instruksi Skills lengkap dimuat sesuai permintaan, sehingga giliran rutin tidak membayar biaya token penuh.

# Perintah atau alat peramban hilang

Jika openclaw browser tidak dikenal setelah peningkatan, browser.request hilang, atau agen melaporkan alat peramban tidak tersedia, penyebab biasanya adalah daftar plugins.allow yang menghilangkan browser dan tidak ada blok konfigurasi root browser. Tambahkan ini:

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

Blok root browser eksplisit, misalnya browser.enabled=true atau browser.profiles.<name>, mengaktifkan Plugin peramban bawaan bahkan di bawah plugins.allow yang membatasi, sesuai dengan perilaku konfigurasi kanal. plugins.entries.browser.enabled=true dan tools.alsoAllow: ["browser"] tidak menggantikan keanggotaan allowlist secara mandiri. Menghapus plugins.allow sepenuhnya juga memulihkan default.

# Profil: openclaw vs user

• openclaw: peramban terkelola dan terisolasi (tidak memerlukan ekstensi).
• user: profil attach Chrome MCP bawaan untuk sesi Chrome Anda yang benar-benar sudah masuk.

Untuk panggilan alat peramban agen:

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

Atur browser.defaultProfile: "openclaw" jika Anda menginginkan mode terkelola secara default.

# Konfigurasi

Pengaturan peramban berada di ~/.openclaw/openclaw.json.

{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms)
    localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms)
    actionTimeoutMs: 60000, // default browser act timeout (ms)
    tabCleanup: {
      enabled: true, // default: true
      idleMinutes: 120, // set 0 to disable idle cleanup
      maxTabsPerSession: 8, // set 0 to disable the per-session cap
      sweepMinutes: 5,
    },
    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",
        headless: true,
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      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" },
    },
  },
}

# Gunakan Brave atau browser berbasis Chromium lainnya

Jika browser default sistem Anda berbasis Chromium (Chrome/Brave/Edge/dll.), OpenClaw menggunakannya secara otomatis. Atur browser.executablePath untuk menimpa deteksi otomatis. Nilai executablePath tingkat atas dan per profil menerima ~ untuk direktori home OS Anda:

openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

Atau atur di konfigurasi, per platform:

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

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

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

executablePath per profil hanya memengaruhi profil lokal yang dikelola yang diluncurkan OpenClaw. Profil existing-session dilampirkan ke browser yang sudah berjalan sebagai gantinya, dan profil CDP jarak jauh menggunakan browser di balik cdpUrl.

# 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 mem-proxy tindakan browser ke sana.
• CDP jarak jauh: atur browser.profiles.<name>.cdpUrl (atau browser.cdpUrl) untuk dilampirkan ke browser berbasis Chromium jarak jauh. Dalam kasus ini, OpenClaw tidak akan meluncurkan browser lokal.
• Untuk layanan CDP yang dikelola secara eksternal pada loopback (misalnya Browserless di Docker yang dipublikasikan ke 127.0.0.1), atur juga attachOnly: true. CDP loopback tanpa attachOnly diperlakukan sebagai profil browser lokal yang dikelola OpenClaw.
• headless hanya memengaruhi profil lokal yang dikelola yang diluncurkan OpenClaw. Itu tidak memulai ulang atau mengubah browser sesi yang sudah ada atau CDP jarak jauh.
• executablePath mengikuti aturan profil lokal yang dikelola yang sama. Mengubahnya pada profil lokal yang dikelola yang sedang berjalan menandai profil tersebut untuk restart/rekonsiliasi sehingga peluncuran berikutnya menggunakan biner baru.

Perilaku penghentian berbeda menurut mode profil:

• profil lokal yang dikelola: 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 status serupa), meskipun tidak ada proses browser yang diluncurkan oleh OpenClaw

URL CDP jarak jauh dapat menyertakan auth:

• Token kueri (mis., https://provider.example?token=<token>)
• Auth HTTP Basic (mis., https://user:[email protected])

OpenClaw mempertahankan auth saat memanggil endpoint /json/* dan saat terhubung ke WebSocket CDP. Pilih variabel lingkungan atau pengelola rahasia untuk token alih-alih meng-commit-nya ke file konfigurasi.

# Proksi browser Node (default tanpa konfigurasi)

Jika Anda menjalankan host Node pada mesin yang memiliki browser, OpenClaw dapat mengalihkan otomatis pemanggilan alat browser ke Node tersebut tanpa konfigurasi browser tambahan. Ini adalah jalur default untuk Gateway jarak jauh.

Catatan:

• Host Node mengekspos server kontrol browser lokalnya melalui perintah proxy.
• Profil berasal dari konfigurasi 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 proxy, termasuk rute pembuatan/penghapusan profil.
• Jika Anda mengatur nodeHost.browserProxy.allowProfiles, OpenClaw memperlakukannya sebagai batas hak istimewa minimum: hanya profil dalam allowlist yang dapat ditargetkan, dan rute pembuatan/penghapusan 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)

Browserless adalah layanan Chromium yang di-host yang mengekspos URL koneksi CDP melalui HTTPS dan WebSocket. OpenClaw dapat menggunakan salah satu bentuk, tetapi untuk profil browser jarak jauh, opsi paling sederhana adalah URL WebSocket langsung dari dokumentasi koneksi Browserless.

Contoh:

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

Catatan:

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

# Docker Browserless pada host yang sama

Ketika Browserless di-host sendiri di Docker dan OpenClaw berjalan pada host, perlakukan Browserless sebagai layanan CDP yang dikelola secara eksternal:

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    profiles: {
      browserless: {
        cdpUrl: "ws://127.0.0.1:3000",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}

Alamat di browser.profiles.browserless.cdpUrl harus dapat dijangkau dari proses OpenClaw. Browserless juga harus mengiklankan endpoint terjangkau yang cocok; atur EXTERNAL Browserless ke basis WebSocket publik-ke-OpenClaw yang sama, seperti ws://127.0.0.1:3000, ws://browserless:3000, atau alamat jaringan Docker privat yang stabil. Jika /json/version mengembalikan webSocketDebuggerUrl yang menunjuk ke alamat yang tidak dapat dijangkau OpenClaw, HTTP CDP dapat terlihat sehat sementara lampiran WebSocket tetap gagal.

Jangan biarkan attachOnly tidak diatur untuk profil Browserless loopback. Tanpa attachOnly, OpenClaw memperlakukan port loopback sebagai profil browser lokal yang dikelola dan dapat melaporkan bahwa port sedang digunakan tetapi tidak dimiliki oleh OpenClaw.

# Penyedia CDP WebSocket langsung

Beberapa layanan browser yang di-host mengekspos endpoint WebSocket langsung alih-alih penemuan CDP berbasis HTTP standar (/json/version). OpenClaw menerima tiga bentuk URL CDP dan memilih strategi koneksi yang tepat secara otomatis:

• Penemuan 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 jalur /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 jalur /devtools/... (mis. Browserless, Browserbase). OpenClaw mencoba penemuan HTTP /json/version terlebih dahulu (menormalkan skema ke http/https); jika penemuan mengembalikan webSocketDebuggerUrl, URL tersebut digunakan, jika tidak OpenClaw fallback ke handshake WebSocket langsung di root polos. Jika endpoint WebSocket yang diiklankan menolak handshake CDP tetapi root polos yang dikonfigurasi menerimanya, OpenClaw fallback ke root tersebut juga. Ini memungkinkan ws:// polos yang diarahkan ke Chrome lokal tetap terhubung, karena Chrome hanya menerima upgrade WebSocket pada jalur per-target spesifik dari /json/version, sementara penyedia yang di-host tetap dapat menggunakan endpoint WebSocket root mereka ketika endpoint penemuan mereka mengiklankan URL berumur pendek yang tidak cocok untuk CDP Playwright.

# Browserbase

Browserbase adalah platform cloud untuk menjalankan browser headless dengan penyelesaian CAPTCHA bawaan, mode stealth, dan proksi residensial.

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

Catatan:

• Daftar dan salin API Key Anda dari dashboard Overview.
• Ganti <BROWSERBASE_API_KEY> dengan kunci API Browserbase asli Anda.
• Browserbase membuat sesi browser secara otomatis saat WebSocket terhubung, jadi tidak diperlukan langkah pembuatan sesi manual.
• Tier gratis mengizinkan satu sesi bersamaan dan satu jam browser per bulan. Lihat harga untuk batas paket berbayar.
• Lihat dokumentasi Browserbase untuk referensi API lengkap, panduan SDK, dan contoh integrasi.

# Keamanan

Ide utama:

• Kontrol peramban hanya untuk loopback; akses mengalir melalui autentikasi Gateway atau pemasangan node.
• API HTTP peramban loopback mandiri hanya menggunakan autentikasi rahasia bersama: autentikasi bearer token gateway, x-openclaw-password, atau autentikasi HTTP Basic dengan kata sandi gateway yang dikonfigurasi.
• Header identitas Tailscale Serve dan gateway.auth.mode: "trusted-proxy" tidak mengautentikasi API peramban loopback mandiri ini.
• Jika kontrol peramban diaktifkan dan tidak ada autentikasi rahasia bersama yang dikonfigurasi, OpenClaw menghasilkan token gateway khusus runtime untuk startup tersebut. Konfigurasikan gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN, atau OPENCLAW_GATEWAY_PASSWORD secara eksplisit jika klien membutuhkan rahasia yang stabil di seluruh restart.
• OpenClaw tidak menghasilkan token tersebut secara otomatis 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; utamakan env vars atau pengelola rahasia.

Kiat CDP jarak jauh:

• Utamakan endpoint terenkripsi (HTTPS atau WSS) dan token berumur pendek jika memungkinkan.
• Hindari menanamkan token berumur panjang langsung di file konfigurasi.

# Profil (multi-peramban)

OpenClaw mendukung beberapa profil bernama (konfigurasi perutean). Profil dapat berupa:

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

Default:

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

Semua endpoint kontrol menerima ?profile=<name>; CLI menggunakan --browser-profile.

# Sesi yang ada melalui Chrome DevTools MCP

OpenClaw juga dapat attach ke profil peramban berbasis Chromium yang sedang berjalan melalui server resmi Chrome DevTools MCP. Ini menggunakan ulang tab dan status login yang sudah terbuka di profil peramban tersebut.

Referensi resmi untuk latar belakang dan penyiapan:

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

Profil bawaan:

• user

Opsional: buat profil sesi yang ada kustom sendiri jika Anda menginginkan nama, warna, atau direktori data peramban yang berbeda.

Perilaku default:

• Profil bawaan user menggunakan koneksi otomatis Chrome MCP, yang menargetkan profil Google Chrome lokal default.

Gunakan userDataDir untuk Brave, Edge, Chromium, atau profil Chrome non-default. ~ diperluas ke direktori home OS Anda:

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

Lalu di peramban yang sesuai:

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

Halaman inspect umum:

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

Uji smoke attach langsung:

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

Tanda keberhasilan:

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

Hal yang perlu diperiksa jika attach tidak berfungsi:

• peramban berbasis Chromium target adalah versi 144+
• debugging jarak jauh diaktifkan di halaman inspect peramban tersebut
• peramban menampilkan prompt persetujuan attach dan Anda menerimanya
• openclaw doctor memigrasikan konfigurasi peramban lama berbasis Plugin dan memeriksa bahwa Chrome terinstal secara lokal untuk profil koneksi otomatis default, tetapi tidak dapat mengaktifkan debugging jarak jauh sisi peramban untuk Anda

Penggunaan agen:

• Gunakan profile="user" saat Anda membutuhkan status peramban pengguna yang sudah login.
• Jika Anda menggunakan profil sesi yang ada kustom, teruskan nama profil eksplisit tersebut.
• 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

Catatan:

• Jalur ini berisiko lebih tinggi daripada profil openclaw yang terisolasi karena dapat bertindak di dalam sesi peramban Anda yang sudah masuk.
• OpenClaw tidak meluncurkan peramban untuk driver ini; OpenClaw hanya attach.
• OpenClaw menggunakan alur resmi Chrome DevTools MCP --autoConnect di sini. Jika userDataDir diatur, nilai tersebut diteruskan untuk menargetkan direktori data pengguna itu.
• Sesi yang ada dapat attach pada host yang dipilih atau melalui node peramban yang terhubung. Jika Chrome berada di tempat lain dan tidak ada node peramban yang terhubung, gunakan CDP jarak jauh atau host node sebagai gantinya.

# Peluncuran Chrome MCP kustom

Timpa server Chrome DevTools MCP yang dijalankan per profil saat alur default npx chrome-devtools-mcp@latest bukan yang Anda inginkan (host offline, versi yang dipin, biner vendored):

Saat cdpUrl diatur pada profil sesi yang ada, OpenClaw melewati --autoConnect dan meneruskan endpoint ke Chrome MCP secara otomatis:

• http(s)://... → --browserUrl <url> (endpoint discovery HTTP DevTools).
• ws(s)://... → --wsEndpoint <url> (CDP WebSocket langsung).

Flag endpoint dan userDataDir tidak dapat digabungkan: saat cdpUrl diatur, userDataDir diabaikan untuk peluncuran Chrome MCP, karena Chrome MCP attach ke peramban yang sedang berjalan di balik endpoint, bukan membuka direktori profil.

# Jaminan isolasi

• Direktori data pengguna khusus: tidak pernah menyentuh profil peramban pribadi Anda.
• Port khusus: menghindari 9222 untuk mencegah bentrokan dengan alur kerja dev.
• Kontrol tab deterministik: tabs mengembalikan suggestedTargetId terlebih dahulu, lalu handle tabId stabil seperti t1, label opsional, dan targetId mentah. Agen sebaiknya menggunakan ulang suggestedTargetId; id mentah tetap tersedia untuk debugging dan kompatibilitas.

# Pemilihan peramban

Saat meluncurkan secara lokal, OpenClaw memilih yang pertama tersedia:

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

Anda dapat menimpanya dengan browser.executablePath.

Platform:

• macOS: memeriksa /Applications dan ~/Applications.
• Linux: memeriksa lokasi umum Chrome/Brave/Edge/Chromium di bawah /usr/bin, /snap/bin, /opt/google, /opt/brave.com, /usr/lib/chromium, dan /usr/lib/chromium-browser.
• Windows: memeriksa lokasi instalasi umum.

# API kontrol (opsional)

Untuk scripting dan debugging, Gateway mengekspos API kontrol HTTP khusus loopback kecil serta CLI openclaw browser yang sesuai (snapshot, ref, peningkatan wait, output JSON, alur kerja debug). Lihat API kontrol peramban untuk referensi lengkap.

# Pemecahan masalah

Untuk masalah khusus Linux (terutama snap Chromium), lihat Pemecahan masalah peramban.

Untuk penyiapan split-host WSL2 Gateway + Windows Chrome, lihat Pemecahan masalah WSL2 + Windows + CDP Chrome jarak jauh.

# Kegagalan startup CDP vs pemblokiran SSRF navigasi

Ini adalah kelas kegagalan yang berbeda dan menunjuk ke jalur kode yang berbeda.

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

Contoh umum:

• 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>
  • Port <port> is in use for profile "<name>" but not by openclaw saat layanan CDP eksternal loopback dikonfigurasi tanpa attachOnly: true
• Pemblokiran SSRF navigasi:
  • alur open, navigate, snapshot, atau pembukaan tab gagal dengan error kebijakan peramban/jaringan sementara start dan tabs masih berfungsi

Gunakan urutan minimal ini untuk memisahkan keduanya:

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

Cara membaca hasilnya:

• Jika start gagal dengan not reachable after start, pecahkan 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 peramban sudah aktif dan kegagalannya berada pada kebijakan navigasi atau halaman target.
• Jika start, tabs, dan open semuanya berhasil, jalur kontrol peramban terkelola dasar sehat.

Detail perilaku penting:

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

Panduan keamanan:

• Jangan melonggarkan kebijakan SSRF peramban secara default.
• Utamakan pengecualian host sempit seperti hostnameAllowlist atau allowedHostnames daripada akses jaringan privat yang luas.
• Gunakan dangerouslyAllowPrivateNetwork: true hanya di lingkungan tepercaya yang disengaja ketika akses peramban jaringan privat diperlukan dan telah ditinjau.

# Alat agen + cara kerja kontrol

Agen mendapatkan satu alat untuk otomasi browser:

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

Cara pemetaannya:

• browser snapshot mengembalikan pohon UI stabil (AI atau ARIA).
• browser act menggunakan ID ref snapshot untuk mengeklik/mengetik/menyeret/memilih.
• browser screenshot menangkap piksel (halaman penuh, elemen, atau ref berlabel).
• browser doctor memeriksa kesiapan Gateway, plugin, profil, browser, dan tab.
• 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 bersandbox, target: "host" memerlukan agents.defaults.sandbox.browser.allowHostControl=true.
  • Jika target dihilangkan: sesi bersandbox menggunakan default sandbox, sesi non-sandbox menggunakan default host.
  • Jika node berkemampuan browser terhubung, alat dapat merutekan otomatis ke node tersebut kecuali Anda menyematkan target="host" atau target="node".

Ini menjaga agen tetap deterministik dan menghindari selektor yang rapuh.

# Terkait

• Gambaran Umum Alat - semua alat agen yang tersedia
• Sandboxing - kontrol browser di lingkungan bersandbox
• Keamanan - risiko kontrol browser dan hardening