API sterowania przeglądarką

Informacje o konfiguracji, ustawieniach i rozwiązywaniu problemów znajdziesz w sekcji Przeglądarka. Ta strona jest dokumentacją referencyjną dla lokalnego kontrolnego interfejsu HTTP API, CLI openclaw browser oraz wzorców skryptowania (migawki, referencje, oczekiwania, przepływy debugowania).

Kontrolny interfejs API (opcjonalny)

Tylko na potrzeby lokalnych integracji Gateway udostępnia niewielki interfejs HTTP API przez loopback. Ten samodzielny serwer jest opcjonalny — ustaw zmienną środowiskową OPENCLAW_EAGER_BROWSER_CONTROL_SERVER=1 w środowisku usługi Gateway i zrestartuj Gateway, zanim punkty końcowe HTTP staną się dostępne. Bez tej zmiennej środowisko wykonawcze sterowania przeglądarką nadal działa przez CLI i narzędzia agenta, ale nic nie nasłuchuje na kontrolnym porcie loopback.

• Stan/uruchomienie/zatrzymanie: GET /, POST /start, POST /stop
• Karty: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
• Migawka/zrzut ekranu: GET /snapshot, POST /screenshot
• Akcje: POST /navigate, POST /act
• Hooki: POST /hooks/file-chooser, POST /hooks/dialog
• Pobieranie: POST /download, POST /wait/download
• Uprawnienia: POST /permissions/grant
• Debugowanie: GET /console, POST /pdf
• Debugowanie: GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
• Sieć: POST /response/body
• Stan: GET /cookies, POST /cookies/set, POST /cookies/clear
• Stan: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
• Ustawienia: POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

Wszystkie punkty końcowe akceptują ?profile=<name>. POST /start?headless=true żąda jednorazowego uruchomienia bez interfejsu graficznego dla lokalnych zarządzanych profili bez zmieniania utrwalonej konfiguracji przeglądarki; profile attach-only, zdalnego CDP i istniejącej sesji odrzucają to nadpisanie, ponieważ OpenClaw nie uruchamia tych procesów przeglądarki.

Dla punktów końcowych kart targetId jest nazwą pola zgodności. Preferuj przekazywanie suggestedTargetId z GET /tabs lub POST /tabs/open; etykiety i uchwyty tabId takie jak t1 też są akceptowane. Surowe identyfikatory celu CDP i unikatowe surowe prefiksy identyfikatorów celu nadal działają, ale są ulotnymi uchwytami diagnostycznymi.

Jeśli skonfigurowano uwierzytelnianie Gateway ze współdzielonym sekretem, trasy HTTP przeglądarki również wymagają uwierzytelnienia:

• Authorization: Bearer <gateway token>
• x-openclaw-password: <gateway password> lub uwierzytelnianie HTTP Basic z tym hasłem

Uwagi:

• Ten samodzielny interfejs API przeglądarki przez loopback nie używa nagłówków tożsamości trusted-proxy ani Tailscale Serve.
• Jeśli gateway.auth.mode to none lub trusted-proxy, te trasy przeglądarki przez loopback nie dziedziczą tych trybów niosących tożsamość; pozostaw je wyłącznie na loopback.

Kontrakt błędów /act

POST /act używa ustrukturyzowanej odpowiedzi błędu dla walidacji na poziomie trasy i niepowodzeń zasad:

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

Aktualne wartości code:

• ACT_KIND_REQUIRED (HTTP 400): brakuje kind albo jest nierozpoznane.
• ACT_INVALID_REQUEST (HTTP 400): ładunek akcji nie przeszedł normalizacji lub walidacji.
• ACT_SELECTOR_UNSUPPORTED (HTTP 400): selector został użyty z nieobsługiwanym rodzajem akcji.
• ACT_EVALUATE_DISABLED (HTTP 403): evaluate (lub wait --fn) jest wyłączone przez konfigurację.
• ACT_TARGET_ID_MISMATCH (HTTP 403): najwyższego poziomu albo wsadowe targetId koliduje z celem żądania.
• ACT_EXISTING_SESSION_UNSUPPORTED (HTTP 501): akcja nie jest obsługiwana dla profili istniejącej sesji.

Inne awarie środowiska wykonawczego mogą nadal zwracać { "error": "<message>" } bez pola code.

Wymaganie Playwright

Niektóre funkcje (navigate/act/migawka AI/migawka roli, zrzuty ekranu elementów, PDF) wymagają Playwright. Jeśli Playwright nie jest zainstalowany, te punkty końcowe zwracają czytelny błąd 501.

Co nadal działa bez Playwright:

• Migawki ARIA
• Migawki dostępności w stylu ról (--interactive, --compact, --depth, --efficient), gdy dostępny jest WebSocket CDP dla danej karty. To mechanizm awaryjny do inspekcji i odkrywania referencji; Playwright pozostaje podstawowym silnikiem akcji.
• Zrzuty ekranu strony dla zarządzanej przeglądarki openclaw, gdy dostępny jest WebSocket CDP dla danej karty
• Zrzuty ekranu strony dla profili existing-session / Chrome MCP
• Zrzuty ekranu oparte na referencjach existing-session (--ref) z wyjścia migawki

Co nadal wymaga Playwright:

• navigate
• act
• Migawki AI zależne od natywnego formatu migawek AI Playwright
• Zrzuty ekranu elementów przez selektor CSS (--element)
• pełny eksport przeglądarki do PDF

Zrzuty ekranu elementów odrzucają też --full-page; trasa zwraca fullPage is not supported for element screenshots.

Jeśli widzisz Playwright is not available in this gateway build, spakowany Gateway nie ma podstawowej zależności środowiska wykonawczego przeglądarki. Zainstaluj ponownie lub zaktualizuj OpenClaw, a następnie zrestartuj Gateway. Dla Docker zainstaluj też binaria przeglądarki Chromium zgodnie z przykładem poniżej.

Instalacja Docker Playwright

Jeśli Twój Gateway działa w Docker, unikaj npx playwright (konflikty nadpisań npm). Dla niestandardowych obrazów wbuduj Chromium w obraz:

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

Dla istniejącego obrazu zainstaluj przez dołączone CLI:

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

Aby utrwalić pobrania przeglądarki, ustaw PLAYWRIGHT_BROWSERS_PATH (na przykład /home/node/.cache/ms-playwright) i upewnij się, że /home/node jest utrwalane przez OPENCLAW_HOME_VOLUME albo bind mount. OpenClaw automatycznie wykrywa utrwalone Chromium w Linux. Zobacz Docker.

Jak to działa (wewnętrznie)

Niewielki kontrolny serwer loopback przyjmuje żądania HTTP i łączy się z przeglądarkami opartymi na Chromium przez CDP. Zaawansowane akcje (click/type/snapshot/PDF) przechodzą przez Playwright na CDP; gdy brakuje Playwright, dostępne są tylko operacje niezależne od Playwright. Agent widzi jeden stabilny interfejs, podczas gdy lokalne/zdalne przeglądarki i profile mogą być swobodnie podmieniane pod spodem.

Szybka dokumentacja CLI

Wszystkie polecenia akceptują --browser-profile <name>, aby wskazać konkretny profil, oraz --json dla wyjścia czytelnego maszynowo.

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"

Uwagi:

• upload i dialog to wywołania uzbrajające; uruchom je przed kliknięciem/naciśnięciem, które wyzwala wybierak/okno dialogowe. Jeśli akcja otwiera modal, odpowiedź akcji zawiera blockedByDialog i browserState.dialogs.pending; przekaż to dialogId, aby odpowiedzieć bezpośrednio. Okna dialogowe obsłużone poza OpenClaw pojawiają się pod browserState.dialogs.recent.
• click/type/itd. wymagają ref z snapshot (numeryczne 12, referencja roli e12 lub używalna referencja ARIA ax12). Selektory CSS celowo nie są obsługiwane dla akcji. Użyj click-coords, gdy widoczna pozycja w obszarze widoku jest jedynym niezawodnym celem.
• Ścieżki pobierania i śledzenia są ograniczone do tymczasowych katalogów głównych OpenClaw: /tmp/openclaw{,/downloads} (mechanizm awaryjny: ${os.tmpdir()}/openclaw/...).
• upload akceptuje pliki z tymczasowego katalogu głównego przesyłania OpenClaw i zarządzane przez OpenClaw media przychodzące. Do zarządzanych mediów przychodzących można odwoływać się jako media://inbound/<id>, względnie wobec piaskownicy media/inbound/<id> albo przez rozwiązaną ścieżkę wewnątrz zarządzanego katalogu mediów przychodzących. Zagnieżdżone referencje mediów, traversal, symlinki, hardlinki i dowolne ścieżki lokalne nadal są odrzucane.
• upload może też ustawiać wejścia plików bezpośrednio przez --input-ref lub --element.

Stabilne identyfikatory i etykiety kart przetrwają zastąpienie surowego celu Chromium, gdy OpenClaw może udowodnić kartę zastępczą, na przykład ten sam URL albo przejście pojedynczej starej karty w pojedynczą nową kartę po przesłaniu formularza. Surowe identyfikatory celu nadal są ulotne; w skryptach preferuj suggestedTargetId z tabs.

Skrót flag migawek:

• --format ai (domyślne z Playwright): migawka AI z liczbowymi odwołaniami (aria-ref="<n>").
• --format aria: drzewo dostępności z odwołaniami axN. Gdy Playwright jest dostępny, OpenClaw wiąże odwołania z backendowymi identyfikatorami DOM z aktywną stroną, aby kolejne akcje mogły ich używać; w przeciwnym razie traktuj wynik wyłącznie jako inspekcyjny.
• --efficient (lub --mode efficient): kompaktowy preset migawki ról. Ustaw browser.snapshotDefaults.mode: "efficient", aby stał się domyślny (zobacz konfiguracja Gateway).
• --interactive, --compact, --depth, --selector wymuszają migawkę ról z odwołaniami ref=e12. --frame "<iframe>" ogranicza migawki ról do elementu iframe.
• Z Playwright opcja --labels dodaje zrzut ekranu z nałożonymi etykietami odwołań (wypisuje MEDIA:<path>) oraz tablicę annotations z ramką ograniczającą każdego odwołania. Przy screenshot etykiety oparte na Playwright działają z --full-page, --ref i --element; przy snapshot dołączony zrzut ekranu pozostaje ograniczony do widoku. Profile existing-session/chrome-mcp renderują etykiety nakładki na zrzutach ekranu strony, ale nie zwracają annotations ani nie używają pomocnika projekcji pełnej strony/odwołania/elementu z Playwright. Bez Playwright lub chrome-mcp etykietowane zrzuty ekranu nie są dostępne.
• --urls dołącza wykryte miejsca docelowe linków do migawek AI.

Migawki i odwołania

OpenClaw obsługuje dwa style „migawek”:

• Migawka AI (liczbowe odwołania): openclaw browser snapshot (domyślne; --format ai)

  • Wynik: tekstowa migawka zawierająca liczbowe odwołania.
  • Akcje: openclaw browser click 12, openclaw browser type 23 "hello".
  • Wewnętrznie odwołanie jest rozwiązywane przez aria-ref Playwright.

• Migawka ról (odwołania ról, takie jak e12): openclaw browser snapshot --interactive (lub --compact, --depth, --selector, --frame)

  • Wynik: lista/drzewo oparte na rolach z [ref=e12] (i opcjonalnie [nth=1]).
  • Akcje: openclaw browser click e12, openclaw browser highlight e12.
  • Wewnętrznie odwołanie jest rozwiązywane przez getByRole(...) (oraz nth() dla duplikatów).
  • Dodaj --labels, aby dołączyć zrzut ekranu z nałożonymi etykietami e12. W profilach opartych na Playwright zwraca to także metadane ramek ograniczających dla każdego odwołania (annotations[]).
  • Dodaj --urls, gdy tekst linku jest niejednoznaczny, a agent potrzebuje konkretnych celów nawigacji.

• Migawka ARIA (odwołania ARIA, takie jak ax12): openclaw browser snapshot --format aria

  • Wynik: drzewo dostępności jako ustrukturyzowane węzły.
  • Akcje: openclaw browser click ax12 działa, gdy ścieżka migawki może powiązać odwołanie przez Playwright i backendowe identyfikatory DOM Chrome.

• Jeśli Playwright jest niedostępny, migawki ARIA nadal mogą być przydatne do inspekcji, ale odwołania mogą nie nadawać się do akcji. Wykonaj ponownie migawkę z --format ai lub --interactive, gdy potrzebujesz odwołań do akcji.

• Dowód Docker dla ścieżki awaryjnej raw-CDP: pnpm test:docker:browser-cdp-snapshot uruchamia Chromium z CDP, wykonuje browser doctor --deep i weryfikuje, że migawki ról zawierają adresy URL linków, elementy klikalne promowane przez kursor oraz metadane iframe.

Zachowanie odwołań:

• Odwołania nie są stabilne między nawigacjami; jeśli coś się nie powiedzie, uruchom ponownie snapshot i użyj świeżego odwołania.
• /act zwraca bieżący surowy targetId po zastąpieniu wywołanym akcją, gdy może udowodnić kartę zastępczą. W kolejnych poleceniach nadal używaj stabilnych identyfikatorów/etykiet kart.
• Jeśli migawka ról została wykonana z --frame, odwołania ról są ograniczone do tego iframe do następnej migawki ról.
• Nieznane lub nieaktualne odwołania axN kończą się szybko błędem zamiast przechodzić do selektora aria-ref Playwright. Gdy tak się stanie, uruchom świeżą migawkę na tej samej karcie.

Ulepszenia oczekiwania

Możesz oczekiwać nie tylko na czas/tekst:

• Oczekiwanie na URL (glob obsługiwane przez Playwright):
  • openclaw browser wait --url "**/dash"
• Oczekiwanie na stan ładowania:
  • openclaw browser wait --load networkidle
  • Obsługiwane w zarządzanych profilach openclaw oraz surowych/zdalnych profilach CDP. Profile user i existing-session odrzucają networkidle; użyj tam oczekiwań --url, --text, selektora lub --fn.
• Oczekiwanie na predykat JS:
  • openclaw browser wait --fn "window.ready===true"
• Oczekiwanie, aż selektor stanie się widoczny:
  • openclaw browser wait "#main"

Można je łączyć:

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

Przepływy debugowania

Gdy akcja się nie powiedzie (np. „niewidoczny”, „naruszenie trybu strict”, „zakryty”):

1. openclaw browser snapshot --interactive
2. Użyj click <ref> / type <ref> (preferuj odwołania ról w trybie interaktywnym)
3. Jeśli nadal się nie udaje: openclaw browser highlight <ref>, aby zobaczyć, w co celuje Playwright
4. Jeśli strona zachowuje się nietypowo:
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. Do głębokiego debugowania: nagraj ślad:
   • openclaw browser trace start
   • odtwórz problem
   • openclaw browser trace stop (wypisuje TRACE:<path>)

Wynik JSON

--json służy do skryptów i narzędzi strukturalnych.

Przykłady:

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

Migawki ról w JSON zawierają refs oraz mały blok stats (lines/chars/refs/interactive), aby narzędzia mogły wnioskować o rozmiarze i gęstości ładunku.

Stan i ustawienia środowiska

Są przydatne w przepływach typu „spraw, aby strona zachowywała się jak X”:

• Ciasteczka: cookies, cookies set, cookies clear
• Magazyn: storage local|session get|set|clear
• Offline: set offline on|off
• Nagłówki: set headers --headers-json '{"X-Debug":"1"}' (starsze set headers --json '{"X-Debug":"1"}' pozostaje obsługiwane)
• Podstawowe uwierzytelnianie HTTP: set credentials user pass (lub --clear)
• Geolokalizacja: set geo <lat> <lon> --origin "https://example.com" (lub --clear)
• Media: set media dark|light|no-preference|none
• Strefa czasowa / locale: set timezone ..., set locale ...
• Urządzenie / widok:
  • set device "iPhone 14" (presety urządzeń Playwright)
  • set viewport 1280 720

Bezpieczeństwo i prywatność

• Profil przeglądarki openclaw może zawierać zalogowane sesje; traktuj go jako wrażliwy.
• browser act kind=evaluate / openclaw browser evaluate oraz wait --fn wykonują dowolny JavaScript w kontekście strony. Prompt injection może tym sterować. Wyłącz to za pomocą browser.evaluateEnabled=false, jeśli tego nie potrzebujesz.
• openclaw browser evaluate --fn akceptuje źródło funkcji, wyrażenie lub ciało instrukcji. Ciała instrukcji są opakowywane jako funkcje asynchroniczne, więc użyj return dla wartości, którą chcesz otrzymać z powrotem. Użyj --timeout-ms <ms>, gdy funkcja po stronie strony może potrzebować więcej czasu niż domyślny limit czasu evaluate.
• Informacje o logowaniach i uwagach dotyczących ochrony przed botami (X/Twitter itd.) znajdziesz w logowanie w przeglądarce + publikowanie w X/Twitter.
• Utrzymuj host Gateway/node jako prywatny (loopback lub tylko tailnet).
• Zdalne punkty końcowe CDP są potężne; tuneluj je i chroń.

Przykład trybu strict (domyślnie blokuj prywatne/wewnętrzne miejsca docelowe):

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

Powiązane

• Przeglądarka - omówienie, konfiguracja, profile, bezpieczeństwo
• Logowanie w przeglądarce - logowanie do witryn
• Rozwiązywanie problemów z przeglądarką w systemie Linux
• Rozwiązywanie problemów z przeglądarką w WSL2 i zdalnym CDP w Windows