Webbläsare (openclaw-hanterad)
OpenClaw kan köra en dedikerad Chrome/Brave/Edge/Chromium-profil som agenten kontrollerar. Den är isolerad från din personliga webbläsare och hanteras genom en liten lokal kontrolltjänst inne i Gateway (loopback endast). Nybörjarvy:- Tänk på den som en separat, agent‑endast webbläsare.
- Profilen
openclawrör inte din personliga webbläsarprofil. - Agenten kan öppna flikar, läsa sidor, klicka och skriva i en säker zon.
- Standardprofilen
chromeanvänder systemets standard‑Chromium‑webbläsare via tilläggsreläet; växla tillopenclawför den isolerade hanterade webbläsaren.
Vad du får
- En separat webbläsarprofil med namnet openclaw (orange accent som standard).
- Deterministisk flikkontroll (lista/öppna/fokusera/stäng).
- Agentåtgärder (klicka/skriva/dra/välja), ögonblicksbilder, skärmdumpar, PDF:er.
- Valfritt stöd för flera profiler (
openclaw,work,remote, …).
Snabbstart
Profiler: openclaw vs chrome
openclaw: hanterad, isolerad webbläsare (inga tillägg krävs).chrome: tilläggsrelä till din systemwebbläsare (kräver att OpenClaw‑ tillägget är kopplat till en flik).
browser.defaultProfile: "openclaw" om du vill ha hanterat läge som standard.
Konfiguration
Webbläsarinställningar finns i~/.openclaw/openclaw.json.
- Webbläsarens kontrolltjänst binder till loopback på en port som härrör från
gateway.port(standard:18791, som är gateway + 2). Reläet använder nästa port (18792). - Om du åsidosätter Gateway‑porten (
gateway.portellerOPENCLAW_GATEWAY_PORT), flyttas de härledda webbläsarportarna för att stanna i samma ”familj”. cdpUrlanvänder som standard reläporten när den inte är satt.remoteCdpTimeoutMsgäller kontroller av fjärr‑CDP‑åtkomlighet (icke‑loopback).remoteCdpHandshakeTimeoutMsgäller kontroller av fjärr‑CDP WebSocket‑åtkomlighet.attachOnly: truebetyder ”starta aldrig en lokal webbläsare; anslut endast om den redan körs”.color+ per‑profilcolorfärgar webbläsar‑UI:t så att du ser vilken profil som är aktiv.- Standardprofilen är
chrome(förlängningsrelä). AnvänddefaultProfil: "openclaw"för den hanterade webbläsaren. - Automatisk detekteringsordning: systemets standardwebbläsare om Chromium‑baserad; annars Chrome → Brave → Edge → Chromium → Chrome Canary.
- Lokala
openclaw‑profiler tilldelar automatisktcdpPort/cdpUrl— sätt dem endast för fjärr‑CDP.
Använd Brave (eller annan Chromium‑baserad webbläsare)
Om din systemstandard webbläsare är Chromium-baserad (Chrome/Brave/Edge/etc), använder OpenClaw den automatiskt. Setbrowser.executablePath to override
auto-detection:
CLI‑exempel:
Lokal vs fjärrkontroll
- Lokal kontroll (standard): Gateway startar loopback‑kontrolltjänsten och kan starta en lokal webbläsare.
- Fjärrkontroll (node‑värd): kör en node‑värd på maskinen som har webbläsaren; Gateway proxyar webbläsaråtgärder till den.
- Fjärr-CDP: sätt
browser.profiles.<name>.cdpUrl(ellerbrowser.cdpUrl) till bifoga till en fjärrbaserad Chromium-baserad webbläsare. I detta fall kommer OpenClaw inte att starta en lokal webbläsare.
- Frågepolletter (t.ex.,
https://provider.exempel?token=<token>) - HTTP Basic auth (t.ex.,
https://user:[email protected])
/json/* slutpunkter och när du ansluter
till CDP WebSocket. Föredrar miljövariabler eller hemligheter chefer för
tokens istället för att överlåta dem till konfigurationsfiler.
Node‑webbläsarproxy (nollkonfig‑standard)
Om du kör en nod värd på maskinen som har din webbläsare, OpenClaw kan automatiskt dirigera webbläsarverktygets samtal till den noden utan någon extra webbläsarkonfiguration. Detta är standardsökvägen för fjärr-gateways. Noteringar:- Node‑värden exponerar sin lokala webbläsarkontrollserver via ett proxykommando.
- Profiler kommer från nodens egen
browser.profiles‑konfig (samma som lokalt). - Inaktivera om du inte vill ha det:
- På noden:
nodeHost.browserProxy.enabled=false - På gatewayen:
gateway.nodes.browser.mode="off"
- På noden:
Browserless (hostad fjärr‑CDP)
Browserless är en hostad krom tjänst som exponerar CDP-slutpunkter över HTTPS. Du kan peka en OpenClaw webbläsarprofil på en Webbläsarlös regionslutpunkt och autentisera med din API-nyckel. Exempel:- Ersätt
<BROWSERLESS_API_KEY>med din riktiga Browserless‑token. - Välj regionsendpoint som matchar ditt Browserless‑konto (se deras dokumentation).
Säkerhet
Grundidéer:- Webbläsarkontroll är endast loopback; åtkomst går via Gatewayns autentisering eller node‑parning.
- Håll Gateway och eventuella node‑värdar på ett privat nätverk (Tailscale); undvik publik exponering.
- Behandla fjärr‑CDP‑URL:er/tokens som hemligheter; föredra miljövariabler eller en hemlighetshanterare.
- Behandla fjärr‑CDP‑URL:er/tokens som hemligheter; föredra miljövariabler eller en hemlighetshanterare.
- Föredra HTTPS‑endpoints och kortlivade tokens där det är möjligt.
- Undvik att bädda in långlivade tokens direkt i konfigfiler.
Profiler (flera webbläsare)
OpenClaw stöder flera namngivna profiler (routingkonfigurationer). Profiler kan vara:- openclaw‑managed: en dedikerad Chromium‑baserad webbläsarinstans med egen användardatakatalog + CDP‑port
- remote: en explicit CDP‑URL (Chromium‑baserad webbläsare som körs någon annanstans)
- extension relay: dina befintliga Chrome‑flikar via det lokala reläet + Chrome‑tillägg
- Profilen
openclawskapas automatiskt om den saknas. - Profilen
chromeär inbyggd för Chrome‑tilläggsreläet (pekar påhttp://127.0.0.1:18792som standard). - Lokala CDP‑portar allokeras från 18800–18899 som standard.
- Att ta bort en profil flyttar dess lokala datakatalog till Papperskorgen.
?profile=<name>; CLI använder --browser-profile.
Chrome‑tilläggsrelä (använd din befintliga Chrome)
OpenClaw kan också styra dina befintliga Chrome‑flikar (ingen separat ”openclaw”‑Chrome‑instans) via ett lokalt CDP‑relä + ett Chrome‑tillägg. Fullständig guide: Chrome‑tillägg Flöde:- Gateway kör lokalt (samma maskin) eller en node‑värd körs på webbläsarmaskinen.
- En lokal reläserver lyssnar på en loopback
cdpUrl(standard:http://127.0.0.1:18792). - Du klickar på tilläggets ikon OpenClaw Browser Relay på en flik för att ansluta (det ansluter inte automatiskt).
- Agenten styr den fliken via det vanliga verktyget
browsergenom att välja rätt profil.
Sandboxade sessioner
Om agenten sessionen är sandlåda, “webbläsare” verktyget kan standard till “target=“sandbox”` (sandlåda webbläsare). Chrome extension relay takeover kräver värd webbläsarkontroll, så antingen:- kör sessionen utan sandbox, eller
- sätt
agents.defaults.sandbox.browser.allowHostControl: trueoch användtarget="host"när du anropar verktyget.
Konfigurering
- Ladda tillägget (dev/uppackat):
- Chrome →
chrome://extensions→ aktivera ”Developer mode” - ”Load unpacked” → välj katalogen som skrivs ut av
openclaw browser extension path - Fäst tillägget och klicka sedan på det på fliken du vill styra (märket visar
ON).
- Använd det:
- CLI:
openclaw browser --browser-profile chrome tabs - Agentverktyg:
browsermedprofile="chrome"
- Detta läge förlitar sig på Playwright‑on‑CDP för de flesta operationer (skärmdumpar/ögonblicksbilder/åtgärder).
- Koppla från genom att klicka på tilläggsikonen igen.
Isoleringsgarantier
- Dedikerad användardatakatalog: rör aldrig din personliga webbläsarprofil.
- Dedikerade portar: undviker
9222för att förhindra kollisioner med utvecklingsarbetsflöden. - Deterministisk flikkontroll: rikta flikar via
targetId, inte ”senaste fliken”.
Val av webbläsare
Vid lokal start väljer OpenClaw den första tillgängliga:- Chrome
- Brave
- Edge
- Chromium
- Chrome Canary
browser.executablePath.
Plattformar:
- macOS: kontrollerar
/Applicationsoch~/Applications. - Linux: letar efter
google-chrome,brave,microsoft-edge,chromium, etc. - Windows: kontrollerar vanliga installationsplatser.
Kontroll‑API (valfritt)
Endast för lokala integrationer exponerar Gateway ett litet loopback‑HTTP‑API:- Status/start/stop:
GET /,POST /start,POST /stop - Flikar:
GET /tabs,POST /tabs/open,POST /tabs/focus,DELETE /tabs/:targetId - Ögonblicksbild/skärmdump:
GET /snapshot,POST /screenshot - Åtgärder:
POST /navigate,POST /act - Hooks:
POST /hooks/file-chooser,POST /hooks/dialog - Nedladdningar:
POST /download,POST /wait/download - Felsökning:
GET /console,POST /pdf - Felsökning:
GET /errors,GET /requests,POST /trace/start,POST /trace/stop,POST /highlight - Nätverk:
POST /response/body - Tillstånd:
GET /cookies,POST /cookies/set,POST /cookies/clear - Tillstånd:
GET /storage/:kind,POST /storage/:kind/set,POST /storage/:kind/clear - Inställningar:
POST /set/offline,POST /set/headers,POST /set/credentials,POST /set/geolocation,POST /set/media,POST /set/timezone,POST /set/locale,POST /set/device
?profile=<name>.
Om gateway-autentisering är konfigurerad kräver webbläsarens HTTP-rutter också autentisering:
Authorization: Bearer <gateway token>x-openclaw-password: <gateway password>eller HTTP Basic-autentisering med det lösenordet
Playwright‑krav
Vissa funktioner (navigera/agera/AI-ögonblicksbilder/rollbilder, elementskärmdumpar, PDF) kräver Playwright. Om Playwright inte är installerat, dessa slutpunkter returnerar en tydlig 501 fel. ARIA ögonblicksbilder och grundläggande skärmbilder fungerar fortfarande för openclaw-managed Chrome. För Chrome-tilläggsrelä drivrutinen kräver ARIA-ögonblicksbilder och skärmbilder Playwright. Om du serPlaywright is not available in this gateway build, installera hela
Playwright‑paketet (inte playwright-core) och starta om gatewayen, eller installera om
OpenClaw med webbläsarstöd.
Docker‑installation av Playwright
Om din Gateway körs i Docker, undviknpx playwright (npm åsidosätta konflikter).
Använd den medföljande CLI istället:
PLAYWRIGHT_BROWSERS_PATH (till exempel,
/home/node/.cache/ms-playwright) och se till att /home/node är ihållande via
OPENCLAW_HOME_VOLUME eller ett bindfäste. Se Docker.
Hur det fungerar (internt)
Denna design håller agenten på ett stabilt, deterministiskt gränssnitt samtidigt som du kan byta lokala/fjärrwebbläsare och profiler.- En liten kontrollserver tar emot HTTP‑förfrågningar.
- Den ansluter till Chromium‑baserade webbläsare (Chrome/Brave/Edge/Chromium) via CDP.
- För avancerade åtgärder (klicka/skriva/ögonblicksbild/PDF) använder den Playwright ovanpå CDP.
- När Playwright saknas är endast icke‑Playwright‑operationer tillgängliga.
CLI‑snabbreferens
Alla kommandon accepterar--browser-profile <name> för att rikta en specifik profil.
Alla kommandon accepterar också --json för maskinläsbar utdata (stabila nyttolaster).
Inspektion:
openclaw browser statusopenclaw browser startopenclaw browser stopopenclaw browser tabsopenclaw browser 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 12openclaw browser screenshot --ref e12openclaw browser snapshotopenclaw browser snapshot --format aria --limit 200openclaw browser snapshot --interactive --compact --depth 6openclaw browser snapshot --efficientopenclaw browser snapshot --labelsopenclaw 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 --doubleopenclaw browser click e12 --doubleopenclaw 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 fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'openclaw browser dialog --acceptopenclaw 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 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 --json '{"X-Debug":"1"}'openclaw browser set credentials user passopenclaw browser set credentials --clearopenclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"openclaw browser set geo --clearopenclaw browser set media darkopenclaw browser set timezone America/New_Yorkopenclaw browser set locale en-USopenclaw browser set device "iPhone 14"
uploadochdialogär armerings‑anrop; kör dem före klick/tryck som utlöser väljaren/dialogen.- Nedladdnings- och trace-utdatavägar är begränsade till OpenClaw temp-rötter:
- traces:
/tmp/openclaw(reserv:${os.tmpdir()}/openclaw) - downloads:
/tmp/openclaw/downloads(reserv:${os.tmpdir()}/openclaw/downloads)
- traces:
- Uppladdningsvägar är begränsade till en temp-rot för uppladdningar i OpenClaw:
- uploads:
/tmp/openclaw/uploads(reserv:${os.tmpdir()}/openclaw/uploads)
- uploads:
uploadkan också sätta filinmatningar direkt via--input-refeller--element.snapshot:--format ai(standard när Playwright är installerat): returnerar en AI‑ögonblicksbild med numeriska refar (aria-ref="<n>").--format aria: returnerar tillgänglighetsträdet (inga refar; endast inspektion).--efficient(eller--mode efficient): kompakt roll‑ögonblicksbild‑preset (interaktiv + kompakt + djup + lägre maxChars).- Konfig‑standard (endast verktyg/CLI): sätt
browser.snapshotDefaults.mode: "efficient"för att använda effektiva ögonblicksbilder när anroparen inte anger ett läge (se Gateway‑konfiguration). - Alternativ för roll‑ögonblicksbild (
--interactive,--compact,--depth,--selector) tvingar en rollbaserad ögonblicksbild med refar somref=e12. --frame "<iframe selector>"begränsar roll‑ögonblicksbilder till en iframe (paras med rollrefar some12).--interactiveger en platt, lättplockad lista över interaktiva element (bäst för att driva åtgärder).--labelslägger till en skärmdump av endast viewporten med överlagrade refetiketter (skriver utMEDIA:<path>).
click/type/etc kräver enreffrånsnapshot(antingen numerisk12eller rollrefe12). CSS-selektorer stöds avsiktligt inte för åtgärder.
Ögonblicksbilder och refar
Ref‑beteende:-
Refar är inte stabila över navigeringar; om något misslyckas, kör
snapshotigen och använd en ny ref.- Utdata: en textögonblicksbild som inkluderar numeriska refar.
- Åtgärder:
openclaw browser click 12,openclaw browser type 23 "hello". - Internt löses refen via Playwrights
aria-ref.
-
Om roll‑ögonblicksbilden togs med
--frameär rollrefar begränsade till den iframen tills nästa roll‑ögonblicksbild.- Utdata: en rollbaserad lista/träd med
[ref=e12](och valfri[nth=1]). - Åtgärder:
openclaw browser click e12,openclaw browser highlight e12. - Internt löses refen via
getByRole(...)(plusnth()för dubbletter). - Lägg till
--labelsför att inkludera en viewport‑skärmdump med överlagradee12‑etiketter.
- Utdata: en rollbaserad lista/träd med
- Refar är inte stabila över navigeringar; om något misslyckas, kör
snapshotigen och använd en ny ref. - Om roll‑ögonblicksbilden togs med
--frameär rollrefar begränsade till den iframen tills nästa roll‑ögonblicksbild.
Vänt‑power‑ups
Dessa kan kombineras:- Vänta på URL (globs stöds av Playwright):
openclaw browser wait --url "**/dash"
- Vänta på laddningsläge:
openclaw browser wait --load networkidle
- Vänta på ett JS‑predikat:
openclaw browser wait --fn "window.ready===true"
- Vänta på att en selektor blir synlig:
openclaw browser wait "#main"
Felsökningsarbetsflöden
När en åtgärd misslyckas (t.ex. “inte synligt”, “strikt läge kränkning”, “täckt”):openclaw browser snapshot --interactive- Använd
click <ref>/type <ref>(föredra rollrefar i interaktivt läge) - Om det fortfarande misslyckas:
openclaw browser highlight <ref>för att se vad Playwright riktar in sig på - Om sidan beter sig konstigt:
openclaw browser errors --clearopenclaw browser requests --filter api --clear
- För djup felsökning: spela in en trace:
openclaw browser trace start- reproducera problemet
openclaw browser trace stop(skriver utTRACE:<path>)
JSON‑utdata
--json är för skriptning och strukturerade verktyg.
Roll‑ögonblicksbilder i JSON inkluderar refs plus ett litet stats‑block (rader/tecken/refar/interaktivt) så att verktyg kan resonera om payload‑storlek och täthet.
Tillstånds‑ och miljöreglage
Dessa är användbara för arbetsflöden av typen ”få webbplatsen att bete sig som X”:- Cookies:
cookies,cookies set,cookies clear - Lagring:
storage local|session get|set|clear - Offline:
set offline on|off - Håll Gateway/node‑värd privat (loopback eller endast tailnet).
- Fjärr‑CDP‑endpoints är kraftfulla; tunnla och skydda dem.
- Geolokalisering:
set geo <lat> <lon> --origin "https://example.com"(eller--clear) - Media:
set media dark|light|no-preference|none - Tidszon / språk:
set timezone ...,set locale ... - Enhet / viewport:
set device "iPhone 14"(Playwright‑enhetsförinställningar)set viewport 1280 720
Felsökning
- Webbläsarprofilen openclaw kan innehålla inloggade sessioner; behandla den som känslig.
browser act kind=evaluate/openclaw browser evaluateochwait --fnkör godtyckligt JavaScript i sidsammanhanget. Snabb injektion kan styra detta. Inaktivera det medbrowser.evaluateEnabled=falseom du inte behöver det.- För inloggningar och anti‑bot‑noteringar (X/Twitter, etc.), se Webbläsarinloggning + X/Twitter‑postning.
- Håll Gateway/node‑värd privat (loopback eller endast tailnet).
- Fjärr‑CDP‑endpoints är kraftfulla; tunnla och skydda dem.
Agentverktyg + hur kontroll fungerar
Agenten får ett verktyg för webbläsarautomation:Agentverktyg + hur kontroll fungerar
Hur det mappas:browser snapshotreturnerar ett stabilt UI‑träd (AI eller ARIA).
browser snapshotreturnerar ett stabilt UI‑träd (AI eller ARIA).browser actanvänder ögonblicksbildensref‑ID:n för att klicka/skriva/dra/välja.browser screenshotfångar pixlar (hel sida eller element).browseraccepterar:profileför att välja en namngiven webbläsarprofil (openclaw, chrome eller fjärr‑CDP).target(sandbox|host|node) för att välja var webbläsaren finns.- I sandboxade sessioner kräver
target: "host"agents.defaults.sandbox.browser.allowHostControl=true. - Om
targetutelämnas: sandboxade sessioner använder som standardsandbox, icke‑sandboxade sessioner använder som standardhost. - Om en webbläsarkapabel nod är ansluten kan verktyget autorouta till den om du inte fäster
target="host"ellertarget="node".