API kontrol peramban

Untuk penyiapan, konfigurasi, dan pemecahan masalah, lihat Peramban. 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=<name>. 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 <gateway token>
• x-openclaw-password: <gateway 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:

{ "error": "<message>", "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": "<message>" } 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:

OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh

Untuk image yang sudah ada, pasang melalui CLI bawaan sebagai gantinya:

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.

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 <name> untuk menargetkan profil tertentu, dan --json untuk output yang dapat dibaca mesin.

openclaw browser statusopenclaw browser startopenclaw browser start --headless # one-shot local managed headless launchopenclaw browser stop            # also clears emulation on attach-only/remote CDPopenclaw browser tabsopenclaw browser tab             # shortcut for current tabopenclaw browser tab newopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://example.comopenclaw browser focus abcd1234openclaw browser close abcd1234

openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref 12        # or --ref e12openclaw browser screenshot --labelsopenclaw browser snapshotopenclaw browser snapshot --format aria --limit 200openclaw browser snapshot --interactive --compact --depth 6openclaw browser snapshot --efficientopenclaw browser snapshot --labelsopenclaw browser snapshot --urlsopenclaw browser snapshot --selector "#main" --interactiveopenclaw browser snapshot --frame "iframe#main" --interactiveopenclaw browser console --level erroropenclaw browser errors --clearopenclaw browser requests --filter api --clearopenclaw browser pdfopenclaw browser responsebody "**/api" --max-chars 5000

openclaw browser navigate https://example.comopenclaw browser resize 1280 720openclaw browser click 12 --double           # or e12 for role refsopenclaw browser click-coords 120 340        # viewport coordinatesopenclaw browser type 23 "hello" --submitopenclaw browser press Enteropenclaw browser hover 44openclaw browser scrollintoview e12openclaw browser drag 10 11openclaw browser select 9 OptionA OptionBopenclaw browser download e12 report.pdfopenclaw browser waitfordownload report.pdfopenclaw browser upload /tmp/openclaw/uploads/file.pdfopenclaw browser upload media://inbound/file.pdfopenclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'openclaw browser dialog --acceptopenclaw browser dialog --dismiss --dialog-id d1openclaw browser wait --text "Done"openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"openclaw browser evaluate --fn '(el) => el.textContent' --ref 7openclaw 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 e12openclaw browser trace startopenclaw browser trace stop

openclaw browser cookiesopenclaw browser cookies set session abc123 --url "https://example.com"openclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set theme darkopenclaw browser storage session clearopenclaw browser set offline onopenclaw browser set headers --headers-json '{"X-Debug":"1"}'openclaw browser set credentials user pass            # --clear to removeopenclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"openclaw browser set media darkopenclaw browser set timezone America/New_Yorkopenclaw browser set locale en-USopenclaw 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/<id>, media/inbound/<id> 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="<n>").
• --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).
• --interactive, --compact, --depth, --selector memaksa snapshot peran dengan ref ref=e12. --frame "<iframe>" membatasi cakupan snapshot peran ke sebuah iframe.
• Dengan Playwright, --labels menambahkan screenshot dengan label ref yang ditumpangkan (mencetak MEDIA:<path>) plus array annotations dengan kotak pembatas setiap ref. Pada screenshot, label berbasis Playwright bekerja dengan --full-page, --ref, dan --element; pada snapshot, screenshot pendamping tetap hanya viewport. Profil existing-session/chrome-mcp merender label overlay pada screenshot halaman tetapi tidak mengembalikan annotations atau menggunakan helper proyeksi full-page/ref/element Playwright. Tanpa Playwright atau chrome-mcp, screenshot berlabel tidak tersedia.
• --urls menambahkan tujuan tautan yang ditemukan ke snapshot AI.

Snapshot dan ref

OpenClaw mendukung dua gaya "snapshot":

• Snapshot AI (ref numerik): openclaw browser snapshot (bawaan; --format ai)

  • Output: snapshot teks yang menyertakan ref numerik.
  • Tindakan: openclaw browser click 12, openclaw browser type 23 "hello".
  • Secara internal, ref diselesaikan melalui aria-ref Playwright.

• Snapshot peran (ref peran seperti e12): openclaw browser snapshot --interactive (atau --compact, --depth, --selector, --frame)

  • Output: daftar/pohon berbasis peran dengan [ref=e12] (dan opsional [nth=1]).
  • Tindakan: openclaw browser click e12, openclaw browser highlight e12.
  • Secara internal, ref diselesaikan melalui getByRole(...) (plus nth() untuk duplikat).
  • Tambahkan --labels untuk menyertakan screenshot dengan label e12 yang ditumpangkan. Pada profil berbasis Playwright, ini juga mengembalikan metadata kotak pembatas per ref (annotations[]).
  • Tambahkan --urls ketika teks tautan ambigu dan agen memerlukan target navigasi yang konkret.

• Snapshot ARIA (ref ARIA seperti ax12): openclaw browser snapshot --format aria

  • Output: pohon aksesibilitas sebagai node terstruktur.
  • Tindakan: openclaw browser click ax12 bekerja saat jalur snapshot dapat mengikat ref melalui Playwright dan ID DOM backend Chrome.

• Jika Playwright tidak tersedia, snapshot ARIA masih dapat berguna untuk inspeksi, tetapi ref mungkin tidak dapat ditindaklanjuti. Ambil snapshot ulang dengan --format ai atau --interactive saat Anda memerlukan ref tindakan.

• Bukti Docker untuk jalur fallback raw-CDP: pnpm test:docker:browser-cdp-snapshot memulai Chromium dengan CDP, menjalankan browser doctor --deep, dan memverifikasi snapshot peran menyertakan URL tautan, elemen dapat diklik yang dinaikkan dari kursor, dan metadata iframe.

Perilaku ref:

• Ref tidak stabil di antara navigasi; jika sesuatu gagal, jalankan ulang snapshot dan gunakan ref baru.
• /act mengembalikan targetId mentah saat ini setelah penggantian yang dipicu tindakan saat dapat membuktikan tab pengganti. Tetap gunakan ID/label tab stabil untuk perintah lanjutan.
• Jika snapshot peran diambil dengan --frame, ref peran dicakup ke iframe tersebut hingga snapshot peran berikutnya.
• Ref axN yang tidak dikenal atau usang gagal cepat alih-alih jatuh ke selector aria-ref Playwright. Jalankan snapshot baru pada tab yang sama saat itu terjadi.

Peningkatan wait

Anda dapat menunggu lebih dari sekadar waktu/teks:

• Tunggu URL (glob didukung oleh Playwright):
  • openclaw browser wait --url "**/dash"
• Tunggu status muat:
  • openclaw browser wait --load networkidle
  • Didukung pada profil openclaw terkelola dan profil CDP raw/remote. Profil user dan existing-session menolak networkidle; gunakan wait --url, --text, selector, atau --fn di sana.
• Tunggu predikat JS:
  • openclaw browser wait --fn "window.ready===true"
• Tunggu selector menjadi terlihat:
  • openclaw browser wait "#main"

Ini dapat digabungkan:

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

Alur kerja debug

Saat tindakan gagal (misalnya "not visible", "strict mode violation", "covered"):

1. openclaw browser snapshot --interactive
2. Gunakan click <ref> / type <ref> (utamakan ref peran dalam mode interaktif)
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 debug mendalam: rekam trace:
   • openclaw browser trace start
   • reproduksi masalah
   • openclaw browser trace stop (mencetak TRACE:<path>)

Output JSON

--json ditujukan untuk scripting dan tooling terstruktur.

Contoh:

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

Snapshot peran dalam JSON menyertakan refs plus blok stats kecil (lines/chars/refs/interactive) agar tool dapat menalar ukuran dan kepadatan payload.

Kenop status dan lingkungan

Ini berguna untuk alur kerja "buat situs berperilaku seperti X":

• 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)
• Autentikasi dasar HTTP: 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
• Zona waktu / locale: set timezone ..., set locale ...
• Perangkat / viewport:
  • set device "iPhone 14" (preset perangkat Playwright)
  • set viewport 1280 720

Keamanan dan privasi

• Profil browser openclaw dapat berisi sesi yang sudah login; perlakukan sebagai 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.
• openclaw browser evaluate --fn menerima sumber fungsi, ekspresi, atau body statement. Body statement dibungkus sebagai fungsi async, jadi gunakan return untuk nilai yang ingin Anda dapatkan kembali. Gunakan --timeout-ms <ms> saat fungsi sisi halaman mungkin membutuhkan waktu lebih lama daripada timeout evaluate bawaan.
• Untuk catatan login dan anti-bot (X/Twitter, dll.), lihat Login browser + posting X/Twitter.
• Jaga host Gateway/node tetap privat (loopback atau khusus tailnet).
• Endpoint CDP remote sangat kuat; tunnel dan lindungi endpoint tersebut.

Contoh strict-mode (blokir tujuan privat/internal secara bawaan):

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

Terkait

• Browser - ikhtisar, konfigurasi, profil, keamanan
• Login browser - masuk ke situs
• Pemecahan masalah Browser Linux
• Pemecahan masalah Browser WSL2