--- read_when: - Pembuatan skrip atau debugging browser agen melalui API kontrol lokal - Mencari referensi CLI `openclaw browser` - Menambahkan otomatisasi browser kustom dengan snapshot dan ref summary: API kontrol browser OpenClaw, referensi CLI, dan tindakan scripting title: API kontrol peramban x-i18n: generated_at: "2026-06-27T18:15:56Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: ccfd1ec996b0fc211e2aefa0554e0fa5c7b0899ca981836134a3741b38bf7600 source_path: tools/browser-control.md workflow: 16 --- Untuk penyiapan, konfigurasi, dan pemecahan masalah, lihat [Peramban](/id/tools/browser). Halaman ini adalah referensi untuk API HTTP kontrol lokal, CLI `openclaw browser`, dan pola skrip (snapshot, ref, penantian, alur debug). ## API Kontrol (opsional) Hanya untuk integrasi lokal, Gateway mengekspos API HTTP loopback kecil. Server mandiri ini bersifat opsional — atur variabel lingkungan `OPENCLAW_EAGER_BROWSER_CONTROL_SERVER=1` di lingkungan layanan gateway dan mulai ulang gateway sebelum endpoint HTTP tersedia. Tanpa variabel ini, runtime kontrol peramban tetap bekerja melalui CLI dan alat agen, tetapi tidak ada yang mendengarkan pada port kontrol loopback. - Status/mulai/berhenti: `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` - Unduhan: `POST /download`, `POST /wait/download` - Izin: `POST /permissions/grant` - Debug: `GET /console`, `POST /pdf` - Debug: `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` Semua endpoint menerima `?profile=`. `POST /start?headless=true` meminta peluncuran headless satu kali untuk profil lokal terkelola tanpa mengubah konfigurasi peramban yang dipersistenkan; profil attach-only, CDP jarak jauh, dan existing-session menolak override itu karena OpenClaw tidak meluncurkan proses peramban tersebut. Untuk endpoint tab, `targetId` adalah nama bidang kompatibilitas. Utamakan meneruskan `suggestedTargetId` dari `GET /tabs` atau `POST /tabs/open`; label dan handle `tabId` seperti `t1` juga diterima. ID target CDP mentah dan prefiks ID target mentah yang unik tetap berfungsi, tetapi itu adalah handle diagnostik yang volatil. Jika autentikasi gateway dengan rahasia bersama dikonfigurasi, rute HTTP peramban juga memerlukan autentikasi: - `Authorization: Bearer ` - `x-openclaw-password: ` atau autentikasi HTTP Basic dengan kata sandi tersebut Catatan: - API peramban loopback mandiri ini **tidak** memakai header identitas trusted-proxy atau Tailscale Serve. - Jika `gateway.auth.mode` adalah `none` atau `trusted-proxy`, rute peramban loopback ini tidak mewarisi mode yang membawa identitas tersebut; pertahankan agar hanya loopback. ### Kontrak error `/act` `POST /act` menggunakan respons error terstruktur untuk validasi tingkat rute dan kegagalan kebijakan: ```json { "error": "", "code": "ACT_*" } ``` Nilai `code` saat ini: - `ACT_KIND_REQUIRED` (HTTP 400): `kind` hilang 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 konfigurasi. - `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` tingkat atas atau batch bertentangan dengan target permintaan. - `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): tindakan tidak didukung untuk profil existing-session. Kegagalan runtime lain mungkin tetap mengembalikan `{ "error": "" }` tanpa bidang `code`. ### Persyaratan Playwright Beberapa fitur (navigasi/tindakan/snapshot AI/snapshot peran, tangkapan layar elemen, PDF) memerlukan Playwright. Jika Playwright tidak terpasang, endpoint tersebut mengembalikan error 501 yang jelas. Yang tetap berfungsi tanpa Playwright: - Snapshot ARIA - Snapshot aksesibilitas bergaya peran (`--interactive`, `--compact`, `--depth`, `--efficient`) saat WebSocket CDP per tab tersedia. Ini adalah fallback untuk inspeksi dan penemuan ref; Playwright tetap menjadi mesin tindakan utama. - Tangkapan layar halaman untuk peramban `openclaw` terkelola saat WebSocket CDP per tab tersedia - Tangkapan layar halaman untuk profil `existing-session` / Chrome MCP - Tangkapan layar berbasis ref `existing-session` (`--ref`) dari output snapshot Yang tetap membutuhkan Playwright: - `navigate` - `act` - Snapshot AI yang bergantung pada format snapshot AI native Playwright - Tangkapan layar elemen selector CSS (`--element`) - ekspor PDF peramban penuh Tangkapan layar elemen juga menolak `--full-page`; rute mengembalikan `fullPage is not supported for element screenshots`. Jika Anda melihat `Playwright is not available in this gateway build`, Gateway terpaket kehilangan dependensi runtime peramban inti. Pasang ulang atau perbarui OpenClaw, lalu mulai ulang gateway. Untuk Docker, pasang juga binari peramban Chromium seperti ditunjukkan di bawah. #### Instalasi Playwright Docker Jika Gateway Anda berjalan di Docker, hindari `npx playwright` (konflik override npm). Untuk image kustom, masukkan Chromium ke dalam image: ```bash OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh ``` Untuk image yang sudah ada, pasang melalui CLI bawaan sebagai gantinya: ```bash docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` Untuk mempertahankan unduhan peramban, atur `PLAYWRIGHT_BROWSERS_PATH` (misalnya, `/home/node/.cache/ms-playwright`) dan pastikan `/home/node` dipersistenkan melalui `OPENCLAW_HOME_VOLUME` atau bind mount. OpenClaw mendeteksi Chromium yang dipersistenkan secara otomatis di Linux. Lihat [Docker](/id/install/docker). ## Cara kerjanya (internal) Server kontrol loopback kecil menerima permintaan HTTP dan terhubung ke peramban berbasis Chromium melalui CDP. Tindakan lanjutan (klik/ketik/snapshot/PDF) berjalan melalui Playwright di atas CDP; saat Playwright tidak ada, hanya operasi non-Playwright yang tersedia. Agen melihat satu antarmuka stabil sementara peramban dan profil lokal/jarak jauh dapat ditukar bebas di bawahnya. ## Referensi cepat CLI Semua perintah menerima `--browser-profile ` untuk menargetkan profil tertentu, dan `--json` untuk output yang dapat dibaca mesin. ```bash openclaw browser status openclaw browser start openclaw browser start --headless # one-shot local managed headless launch openclaw browser stop # also clears emulation on attach-only/remote CDP openclaw browser tabs openclaw browser tab # shortcut for current 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 ``` ```bash openclaw browser screenshot openclaw browser screenshot --full-page openclaw browser screenshot --ref 12 # or --ref e12 openclaw browser screenshot --labels 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 --urls openclaw browser snapshot --selector "#main" --interactive openclaw browser snapshot --frame "iframe#main" --interactive openclaw browser console --level error openclaw browser errors --clear openclaw browser requests --filter api --clear openclaw browser pdf openclaw browser responsebody "**/api" --max-chars 5000 ``` ```bash openclaw browser navigate https://example.com openclaw browser resize 1280 720 openclaw browser click 12 --double # or e12 for role refs openclaw browser click-coords 120 340 # viewport coordinates 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 upload media://inbound/file.pdf openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]' openclaw browser dialog --accept openclaw browser dialog --dismiss --dialog-id d1 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 evaluate --fn 'const title = document.title; return title;' openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }' openclaw browser highlight e12 openclaw browser trace start openclaw browser trace stop ``` ```bash 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 # --clear to remove openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com" openclaw browser set media dark openclaw browser set timezone America/New_York openclaw browser set locale en-US openclaw browser set device "iPhone 14" ``` Catatan: - `upload` dan `dialog` adalah panggilan **arming**; jalankan keduanya sebelum klik/tekan yang memicu pemilih/dialog. Jika suatu tindakan membuka modal, respons tindakan menyertakan `blockedByDialog` dan `browserState.dialogs.pending`; teruskan `dialogId` tersebut untuk merespons langsung. Dialog yang ditangani di luar OpenClaw muncul di bawah `browserState.dialogs.recent`. - `click`/`type`/dll. memerlukan `ref` dari `snapshot` (numerik `12`, ref peran `e12`, atau ref ARIA yang dapat ditindaklanjuti `ax12`). Selector CSS sengaja tidak didukung untuk tindakan. Gunakan `click-coords` saat posisi viewport yang terlihat adalah satu-satunya target yang andal. - Jalur unduhan dan trace dibatasi ke root temp OpenClaw: `/tmp/openclaw{,/downloads}` (fallback: `${os.tmpdir()}/openclaw/...`). - `upload` menerima file dari root unggahan temp OpenClaw dan media masuk yang dikelola OpenClaw. Media masuk terkelola dapat dirujuk sebagai `media://inbound/`, `media/inbound/` yang relatif terhadap sandbox, atau jalur yang di-resolve di dalam direktori media masuk terkelola. Ref media bertingkat, traversal, symlink, hardlink, dan jalur lokal arbitrer tetap ditolak. - `upload` juga dapat mengatur input file secara langsung melalui `--input-ref` atau `--element`. ID dan label tab stabil tetap bertahan dari penggantian raw-target Chromium saat OpenClaw dapat membuktikan tab penggantinya, seperti URL yang sama atau satu tab lama menjadi satu tab baru setelah pengiriman formulir. ID target mentah tetap volatil; utamakan `suggestedTargetId` dari `tabs` dalam skrip. Sekilas flag snapshot: - `--format ai` (bawaan dengan Playwright): snapshot AI dengan ref numerik (`aria-ref=""`). - `--format aria`: pohon aksesibilitas dengan ref `axN`. Saat Playwright tersedia, OpenClaw mengikat ref dengan ID DOM backend ke halaman live agar tindakan lanjutan dapat menggunakannya; jika tidak, perlakukan output sebagai hanya untuk inspeksi. - `--efficient` (atau `--mode efficient`): preset snapshot peran ringkas. Atur `browser.snapshotDefaults.mode: "efficient"` untuk menjadikannya bawaan (lihat [konfigurasi Gateway](/id/gateway/configuration-reference#browser)). - `--interactive`, `--compact`, `--depth`, `--selector` memaksa snapshot peran dengan ref `ref=e12`. `--frame "