Browserautomatisierung

Automatisieren Sie Browserinteraktionen über die browse-CLI mit Claude.

Einrichtungsprüfung

Stellen Sie vor der Ausführung von Browserbefehlen sicher, dass die CLI verfügbar ist:

which browse || npm install -g browse

Umgebungsselektion (Lokal vs. Remote)

Die CLI unterstützt explizite Umgebungsflags pro Befehl. Wenn Sie nichts unternehmen, wechselt die nächste Sitzung standardmäßig zu Browserbase, wenn BROWSERBASE_API_KEY festgelegt ist, andernfalls bleibt sie lokal.

Lokaler Modus

• browse open <url> --local</url> startet einen sauberen, isolierten lokalen Browser
• browse open <url> --auto-connect</url> verbindet sich mit einem bereits laufenden, debugbaren Chrome; verwenden Sie --local, wenn kein debugbarer Chrome verfügbar ist
• browse open <url> --cdp <port></port></url> verbindet sich mit einem bestimmten CDP-Ziel
• Geeignet für: Entwicklung, localhost, vertrauenswürdige Websites und reproduzierbare Durchläufe

Remote-Modus (Browserbase)

• browse open <url> --remote</url> startet eine Browserbase-Sitzung
• Ohne lokales Flag ist Browserbase auch der Standard, wenn BROWSERBASE_API_KEY festgelegt ist
• Bietet: Browserbase-Identität, verifizierte Browser, automatische CAPTCHA-Lösung, Residential-Proxys, Sitzungspersistenz
• Verwenden Sie den Remote-Modus, wenn: die Zielwebsite Bot-Erkennung, CAPTCHAs, IP-Ratenbegrenzung, Cloudflare-Schutz erfordert oder geospezifischen Zugriff benötigt
• Erhalten Sie Anmeldeinformationen unter https://browserbase.com/settings

Wann welchen Modus wählen

• Wiederholbare lokale Tests / sauberer Zustand: browse open <url> --local</url>
• Wiederverwendung Ihrer lokalen Anmeldeinformationen/Cookies: browse open <url> --auto-connect</url>
• Einfaches Surfen (Dokumente, Wikis, öffentliche APIs): Lokaler Modus ist ausreichend
• Geschützte Websites (Login-Wände, CAPTCHAs, Anti-Scraping): Verwenden Sie den Remote-Modus
• Wenn der lokale Modus mit Bot-Erkennung oder Zugriff verweigert fehlschlägt: Wechseln Sie zum Remote-Modus

Befehle

Die meisten Treiberbefehle funktionieren nach dem Start des Daemons über lokale, Remote- und CDP-Sitzungen hinweg.

Navigation

browse open <url>                        # Zur URL gehen
browse open <url> --local                # Zur URL in einem sauberen lokalen Browser gehen
browse open <url> --remote               # Zur URL in einer Browserbase-Sitzung gehen
browse reload                            # Aktuelle Seite neu laden
browse back                              # In der Historie zurückgehen
browse forward                           # In der Historie vorwärtsgehen
</url></url></url>

Seitenzustand (Snapshot gegenüber Screenshot bevorzugen)

browse snapshot                          # Accessibility-Baum mit Element-Referenzen abrufen (schnell, strukturiert)
browse screenshot --path <path>          # Visuellen Screenshot erstellen (langsam, verwendet Vision-Token)
browse get url                           # Aktuelle URL abrufen
browse get title                         Seitentitel abrufen
browse get text                # Textinhalt abrufen (verwenden Sie "body" für gesamten Text)
browse get html                # HTML-Inhalt des Elements abrufen
browse get value               # Wert des Formularfelds abrufen
</path>

Verwenden Sie browse snapshot als Ihre Standardmethode zum Verständnis des Seitenzustands – er gibt den Accessibility-Baum mit Element-Referenzen zurück, die Sie zur Interaktion verwenden können. Verwenden Sie browse screenshot nur, wenn Sie visuellen Kontext benötigen (Layout, Bilder, Debugging).

Interaktion

browse click <ref>                       # Element nach Referenz aus Snapshot anklicken (z. B., @0-5)
browse type <text>                       # Text in fokussiertes Element eingeben
browse fill  <value>           # Eingabefeld füllen; fügen Sie --press-enter hinzu, wenn Enter benötigt wird
browse select  <values...>     Dropdown-Option(en) auswählen
browse press <key>                       # Taste drücken (Enter, Tab, Escape, Cmd+A, etc.)
browse mouse drag <fromx><fromy><tox><toy>  # Von einem Punkt zu einem anderen ziehen
browse mouse scroll <x><y><deltax><deltay>  # An Koordinaten scrollen
browse highlight               Element auf Seite hervorheben
browse is visible              Prüfen, ob Element sichtbar ist
browse is checked              Prüfen, ob Element markiert ist
browse wait <type> [arg]                 Warten auf: Laden, Selektor, Timeout
</type></deltay></deltax></y></x></toy></tox></fromy></fromx></key></values...></value></text></ref>

Sitzungsverwaltung

browse stop                              # Browser-Daemon stoppen
browse status                            # Daemon-Status und aufgelösten Modus prüfen
browse tab list                          Alle offenen Tabs auflisten
browse tab switch <index-or-target-id>   Zum Tab nach Index oder Ziel-ID wechseln
browse tab close [index-or-target-id]    Tab schließen
</index-or-target-id>

Typischer Arbeitsablauf

Wenn die Umgebung relevant ist, setzen Sie --local, --remote, --auto-connect oder --cdp <port></port> auf den ersten Browserbefehl.

1. browse open <url> --local</url> oder browse open <url> --remote</url> – Zur Seite navigieren
2. browse snapshot – Accessibility-Baum lesen, um Seitenstruktur zu verstehen und Element-Referenzen zu erhalten
3. browse click <ref></ref> / browse type <text></text> / browse fill <value></value> – Interaktion unter Verwendung von Referenzen aus dem Snapshot
4. browse snapshot – Bestätigen, dass die Aktion funktioniert hat
5. Schritte 3-4 bei Bedarf wiederholen
6. browse stop – Browser schließen, wenn fertig

Schnelles Beispiel

browse open https://example.com
browse snapshot                          # Seitenstruktur + Element-Referenzen anzeigen
browse click @0-5                        # Element mit Referenz 0-5 anklicken
browse get title
browse stop

Modusvergleich

Best Practices

1. Wählen Sie die lokale Strategie bewusst aus: Verwenden Sie browse open <url> --local</url> für sauberen Zustand, browse open <url> --auto-connect</url> für vorhandene lokale Anmeldeinformationen und browse open <url> --remote</url> für geschützte Websites
2. Führen Sie immer browse open zuerst vor der Interaktion aus
3. Verwenden Sie browse snapshot, um den Seitenzustand zu prüfen – er ist schnell und gibt Ihnen Element-Referenzen
4. Erstellen Sie nur Screenshots, wenn visueller Kontext benötigt wird (Layoutprüfungen, Bilder, Debugging)
5. Verwenden Sie Referenzen aus dem Snapshot zum Klicken/Interagieren – z. B., browse click @0-5
6. Führen Sie browse stop durch, wenn Sie fertig sind, um die Browsersitzung aufzuräumen und die Umgebungsüberschreibung zu löschen

Fehlerbehebung

• "Keine aktive Seite": Führen Sie browse stop aus, prüfen Sie dann browse status. Wenn immer noch "läuft" angezeigt wird, töten Sie den Zombie-Daemon mit pkill -f "browse.*daemon" und wiederholen Sie browse open
• Chrome nicht gefunden: Installieren Sie Chrome, verwenden Sie browse open <url> --auto-connect</url>, wenn Sie bereits einen debugbaren Chrome laufen haben, oder wechseln Sie zu browse open <url> --remote</url>
• Aktion fehlschlägt: Führen Sie browse snapshot aus, um verfügbare Elemente und ihre Referenzen zu sehen
• Browserbase fehlschlägt: Überprüfen Sie, ob der API-Schlüssel festgelegt ist

Wechseln zum Remote-Modus

Wechseln Sie zum Remote-Modus, wenn Sie erkennen: CAPTCHAs (reCAPTCHA, hCaptcha, Turnstile), Bot-Erkennungsseiten ("Prüfen Ihres Browsers..."), HTTP 403/429, leere Seiten auf Websites, die Inhalte haben sollten, oder wenn der Benutzer dies anfordert.

Wechseln Sie nicht für einfache Websites (Dokumente, Wikis, öffentliche APIs, localhost).

browse open <url> --local          # Sauberer, isolierter lokaler Browser
browse open <url> --auto-connect   # Mit vorhandenem debugbarem Chrome verbinden
browse open <url> --remote         # Browserbase-Sitzung
</url></url></url>

Modus-Flags werden angewendet, wenn eine Sitzung startet. Nach browse stop fällt der nächste Start auf die umgebungsvariablebasierte automatische Erkennung zurück. Verwenden Sie browse status, um den aufgelösten Modus und das Ziel zu untersuchen, während der Daemon läuft.

Für detaillierte Beispiele siehe EXAMPLES.md. Für die API-Referenz siehe REFERENCE.md.