openclaw browser

Zarządzaj powierzchnią sterowania przeglądarką OpenClaw i uruchamiaj akcje przeglądarki (cykl życia, profile, karty, migawki, zrzuty ekranu, nawigacja, wprowadzanie danych, emulacja stanu i debugowanie).

Powiązane:

• Narzędzie przeglądarki + API: Narzędzie przeglądarki

Typowe flagi

• --url <gatewayWsUrl>: adres URL WebSocket Gateway (domyślnie z konfiguracji).
• --token <token>: token Gateway (jeśli wymagany).
• --timeout <ms>: limit czasu żądania (ms).
• --expect-final: czekaj na końcową odpowiedź Gateway.
• --browser-profile <name>: wybierz profil przeglądarki (domyślnie z konfiguracji).
• --json: dane wyjściowe czytelne maszynowo (tam, gdzie obsługiwane).

Szybki start (lokalnie)

openclaw browser profilesopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

Agenci mogą uruchomić tę samą kontrolę gotowości za pomocą browser({ action: "doctor" }).

Szybkie rozwiązywanie problemów

Jeśli start kończy się błędem not reachable after start, najpierw rozwiąż problem z gotowością CDP. Jeśli start i tabs działają, ale open lub navigate kończy się niepowodzeniem, płaszczyzna sterowania przeglądarką jest zdrowa, a przyczyną błędu jest zwykle polityka SSRF dla nawigacji.

Minimalna sekwencja:

openclaw browser --browser-profile openclaw doctoropenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw tabsopenclaw browser --browser-profile openclaw open https://example.com

Szczegółowe wskazówki: Rozwiązywanie problemów z przeglądarką

Cykl życia

openclaw browser statusopenclaw browser doctoropenclaw browser doctor --deepopenclaw browser startopenclaw browser start --headlessopenclaw browser stopopenclaw browser --browser-profile openclaw reset-profile

Uwagi:

• doctor --deep dodaje sondę migawki na żywo. Jest przydatne, gdy podstawowa gotowość CDP jest zielona, ale chcesz dowodu, że bieżącą kartę można zbadać.
• W przypadku profili attachOnly i zdalnych profili CDP openclaw browser stop zamyka aktywną sesję sterowania i czyści tymczasowe nadpisania emulacji nawet wtedy, gdy OpenClaw nie uruchomił samodzielnie procesu przeglądarki.
• W przypadku lokalnie zarządzanych profili openclaw browser stop zatrzymuje uruchomiony proces przeglądarki.
• openclaw browser start --headless dotyczy tylko tego żądania uruchomienia i tylko wtedy, gdy OpenClaw uruchamia lokalnie zarządzaną przeglądarkę. Nie przepisuje browser.headless ani konfiguracji profilu i nie ma efektu dla już działającej przeglądarki.
• Na hostach Linux bez DISPLAY ani WAYLAND_DISPLAY lokalnie zarządzane profile działają automatycznie w trybie headless, chyba że OPENCLAW_BROWSER_HEADLESS=0, browser.headless=false lub browser.profiles.<name>.headless=false jawnie żąda widocznej przeglądarki.

Jeśli brakuje polecenia

Jeśli openclaw browser jest nieznanym poleceniem, sprawdź plugins.allow w ~/.openclaw/openclaw.json.

Gdy plugins.allow jest obecne, jawnie wymień wbudowany Plugin przeglądarki, chyba że konfiguracja ma już główny blok browser:

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

Jawny główny blok browser, na przykład browser.enabled=true lub browser.profiles.<name>, również aktywuje wbudowany Plugin przeglądarki przy restrykcyjnej liście dozwolonych Pluginów.

Powiązane: Narzędzie przeglądarki

Profile

Profile to nazwane konfiguracje routingu przeglądarki. W praktyce:

• openclaw: uruchamia lub dołącza do dedykowanej instancji Chrome zarządzanej przez OpenClaw (izolowany katalog danych użytkownika).
• user: steruje istniejącą, zalogowaną sesją Chrome przez Chrome DevTools MCP.
• niestandardowe profile CDP: wskazują lokalny lub zdalny punkt końcowy CDP.

openclaw browser profilesopenclaw browser create-profile --name work --color "#FF5A36"openclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name remote --cdp-url https://browser-host.example.comopenclaw browser delete-profile --name work

Użyj konkretnego profilu:

openclaw browser --browser-profile work tabs

Karty

openclaw browser tabsopenclaw browser tab new --label docsopenclaw browser tab label t1 docsopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://docs.openclaw.ai --label docsopenclaw browser focus docsopenclaw browser close t1

tabs zwraca najpierw suggestedTargetId, następnie stabilne tabId, takie jak t1, opcjonalną etykietę oraz surowe targetId. Agenci powinni przekazywać suggestedTargetId z powrotem do focus, close, migawek i akcji. Możesz przypisać etykietę za pomocą open --label, tab new --label lub tab label; etykiety, identyfikatory kart, surowe identyfikatory celów i unikalne prefiksy identyfikatorów celów są akceptowane. Pole żądania nadal nazywa się targetId ze względu na zgodność, ale akceptuje te odwołania do kart. Traktuj surowe identyfikatory celów jako uchwyty diagnostyczne, a nie trwałą pamięć agenta. Gdy Chromium zastępuje bazowy surowy cel podczas nawigacji lub wysłania formularza, OpenClaw utrzymuje stabilne tabId/etykietę przypięte do karty zastępczej, gdy może udowodnić dopasowanie. Surowe identyfikatory celów pozostają zmienne; preferuj suggestedTargetId.

Migawka / zrzut ekranu / akcje

Migawka:

openclaw browser snapshotopenclaw browser snapshot --urls

Zrzut ekranu:

openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref e12openclaw browser screenshot --labels

Uwagi:

• --full-page służy tylko do przechwytywania stron; nie można go łączyć z --ref ani --element.
• Profile existing-session / user obsługują zrzuty ekranu stron oraz zrzuty ekranu --ref z danych wyjściowych migawki, ale nie zrzuty ekranu CSS --element.
• --labels nakłada bieżące referencje migawki na zrzut ekranu. W profilach opartych na Playwright działa z --full-page (nakładka etykiet pełnej strony), --ref (nakładka etykiet wycinka elementu według referencji ARIA) oraz --element (nakładka etykiet wycinka elementu według selektora CSS); w trybach wycinka elementu etykiety są rzutowane względem elementu. Odpowiedź zawiera też tablicę annotations z ramką ograniczającą każdej referencji. Każdy element ma ref, number, role, opcjonalne name oraz box: {x, y, width, height}; współrzędne są w przestrzeni przechwyconego obrazu (viewport / pełna strona / względem elementu). Pole jest pomijane, gdy jest puste. Profile existing-session renderują nakładkę chrome-mcp na zrzutach ekranu stron, ale nie używają pomocnika projekcji Playwright i nie zawierają annotations; zrzuty ekranu CSS --element nie są tam obsługiwane. Bez Playwright lub chrome-mcp etykietowane zrzuty ekranu nie są dostępne. Poprzednie wydania ignorowały --full-page, --ref i --element w etykietowanych zrzutach ekranu Playwright i zawsze zwracały przechwycony viewport; etykietowane zrzuty ekranu teraz respektują te zakresy.
• snapshot --urls dołącza wykryte miejsca docelowe linków do migawek AI, aby agenci mogli wybierać bezpośrednie cele nawigacji zamiast zgadywać wyłącznie na podstawie tekstu linku.

Nawigacja/kliknięcie/pisanie (automatyzacja UI oparta na referencjach):

openclaw browser navigate https://example.comopenclaw browser click <ref>openclaw browser click-coords 120 340openclaw browser type <ref> "hello"openclaw browser press Enteropenclaw browser hover <ref>openclaw browser scrollintoview <ref>openclaw browser drag <startRef> <endRef>openclaw browser select <ref> OptionA OptionBopenclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'openclaw browser wait --text "Done"openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>openclaw browser evaluate --fn 'const title = document.title; return title;'openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'

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 evaluate --timeout-ms <ms>, gdy funkcja po stronie strony może potrzebować więcej czasu niż domyślny limit czasu evaluate.

Odpowiedzi akcji zwracają bieżące surowe targetId po zastąpieniu strony wywołanym akcją, gdy OpenClaw może udowodnić kartę zastępczą. Skrypty powinny nadal przechowywać i przekazywać suggestedTargetId/etykiety w długotrwałych przepływach pracy.

Pomocniki plików i okien dialogowych:

openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>openclaw browser upload media://inbound/file.pdf --ref <ref>openclaw browser waitfordownloadopenclaw browser download <ref> report.pdfopenclaw browser dialog --acceptopenclaw browser dialog --dismiss --dialog-id d1

Zarządzane profile Chrome zapisują zwykłe pobrania wywołane kliknięciem w katalogu pobrań OpenClaw (/tmp/openclaw/downloads domyślnie albo skonfigurowanym głównym katalogu tymczasowym). Użyj waitfordownload lub download, gdy agent musi poczekać na konkretny plik i zwrócić jego ścieżkę; te jawne oczekiwania przejmują następne pobranie. Przesyłanie akceptuje pliki z głównego katalogu tymczasowych przesłań OpenClaw oraz zarządzanych przez OpenClaw przychodzących multimediów, w tym referencje media://inbound/<id> i względne względem piaskownicy media/inbound/<id>. Zagnieżdżone referencje multimediów, przechodzenie po katalogach i dowolne ścieżki lokalne pozostają odrzucane. Gdy akcja otwiera modalne okno dialogowe, odpowiedź akcji zwraca blockedByDialog z browserState.dialogs.pending; przekaż --dialog-id, aby odpowiedzieć bezpośrednio. Okna dialogowe obsłużone poza OpenClaw pojawiają się w browserState.dialogs.recent.

Stan i przechowywanie

Viewport + emulacja:

openclaw browser resize 1280 720openclaw browser set viewport 1280 720openclaw browser set offline onopenclaw browser set media darkopenclaw browser set timezone Europe/Londonopenclaw browser set locale en-GBopenclaw browser set geo 51.5074 -0.1278 --accuracy 25openclaw browser set device "iPhone 14"openclaw browser set headers '{"x-test":"1"}'openclaw browser set credentials myuser mypass

Ciasteczka + pamięć:

openclaw browser cookiesopenclaw browser cookies set session abc123 --url https://example.comopenclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set token abc123openclaw browser storage session clear

Debugowanie

openclaw browser console --level erroropenclaw browser pdfopenclaw browser responsebody "**/api"openclaw browser highlight <ref>openclaw browser errors --clearopenclaw browser requests --filter apiopenclaw browser trace startopenclaw browser trace stop --out trace.zip

Istniejący Chrome przez MCP

Użyj wbudowanego profilu user albo utwórz własny profil existing-session:

openclaw browser --browser-profile user tabsopenclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"openclaw browser create-profile --name chrome-port --driver existing-session --cdp-url http://127.0.0.1:9222openclaw browser --browser-profile chrome-live tabs

Domyślna ścieżka existing-session to automatyczne połączenie Chrome MCP tylko z hosta. Jeśli przeglądarka już działa z punktem końcowym DevTools, przekaż --cdp-url, aby Chrome MCP dołączył zamiast tego do tego punktu końcowego. W przypadku Dockera, Browserless lub innych zdalnych konfiguracji, w których semantyka Chrome MCP nie jest potrzebna, użyj profilu CDP.

Obecne ograniczenia existing-session:

• akcje sterowane snapshotami używają referencji, a nie selektorów CSS
• browser.actionTimeoutMs domyślnie ustawia obsługiwane żądania act na 60000 ms, gdy wywołujący pominą timeoutMs; timeoutMs dla pojedynczego wywołania nadal ma pierwszeństwo.
• click obsługuje tylko kliknięcie lewym przyciskiem
• type nie obsługuje slowly=true
• press nie obsługuje delayMs
• hover, scrollintoview, drag, select, fill i evaluate odrzucają nadpisania limitu czasu dla pojedynczego wywołania
• select obsługuje tylko jedną wartość
• wait --load networkidle nie jest obsługiwane w profilach istniejących sesji (działa w zarządzanych i surowych/zdalnych CDP)
• przesyłanie plików wymaga --ref / --input-ref, nie obsługuje CSS --element i obecnie obsługuje jeden plik naraz
• hooki dialogów nie obsługują --timeout
• zrzuty ekranu obsługują przechwytywanie strony i --ref, ale nie CSS --element
• responsebody, przechwytywanie pobierania, eksport PDF i akcje wsadowe nadal wymagają zarządzanej przeglądarki lub surowego profilu CDP

Zdalne sterowanie przeglądarką (proxy hosta node)

Jeśli Gateway działa na innym komputerze niż przeglądarka, uruchom host node na komputerze, który ma Chrome/Brave/Edge/Chromium. Gateway będzie przekazywać akcje przeglądarki do tego węzła (osobny serwer sterowania przeglądarką nie jest wymagany).

Użyj gateway.nodes.browser.mode, aby kontrolować automatyczne trasowanie, oraz gateway.nodes.browser.node, aby przypiąć konkretny węzeł, jeśli podłączonych jest wiele.

Bezpieczeństwo i konfiguracja zdalna: Narzędzie przeglądarki, Dostęp zdalny, Tailscale, Bezpieczeństwo

Powiązane

• Dokumentacja CLI
• Przeglądarka