Browser-Troubleshooting unter Linux lösen

Du kennst das: Du willst eigentlich nur dein Setup starten und die Browser-Automatisierung nutzen, aber Linux macht dir einen Strich durch die Rechnung. Oft liegt das Problem tief im System vergraben, etwa bei Berechtigungen oder der Art, wie Prozesse voneinander isoliert werden.

Besonders unter Distributionen wie Ubuntu führen Paket-Manager oft dazu, dass Tools nicht so kommunizieren können, wie sie eigentlich sollten. Wenn der Browser in einer Sandbox gefangen ist, erreicht OpenClaw die Schnittstelle nicht und bricht mit einer Fehlermeldung ab.

Voraussetzungen

• Ein Linux-System (z. B. Ubuntu)
• Zugriff auf die OpenClaw Konfigurationsdatei (~/.openclaw/openclaw.json)
• Root-Rechte für die Installation von Paketen

Schnellstart

Der schnellste Weg, um Browser-Probleme unter Linux zu umgehen, ist die Installation des offiziellen Google Chrome Pakets. Das vermeidet Konflikte mit Snap.

1. Google Chrome installieren: Lade das .deb Paket herunter und installiere es direkt:

   wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
   sudo dpkg -i google-chrome-stable_current_amd64.deb
   sudo apt --fix-broken install -y

2. Config aktualisieren: Trage den Pfad in deine ~/.openclaw/openclaw.json ein:

   {
     "browser": {
       "enabled": true,
       "executablePath": "/usr/bin/google-chrome-stable",
       "headless": true,
       "noSandbox": true
     }
   }

Fehlerbehebung

Problem: “Failed to start Chrome CDP on port 18800”

Wenn du diesen Fehler siehst, kann OpenClaw den Browser-Server nicht starten. Die Ursache ist meistens, dass Chromium als snap package installiert ist. Snap nutzt AppArmor, was den Zugriff von OpenClaw blockiert. Ein apt install chromium installiert unter Ubuntu oft nur einen Wrapper für Snap.

Lösung: Snap Chromium im Attach-Only Mode nutzen

Falls du kein Google Chrome installieren kannst, starte Chromium manuell und lass OpenClaw sich nur damit verbinden:

1. Config anpassen: Setze attachOnly auf true.

   {
     "browser": {
       "enabled": true,
       "attachOnly": true,
       "headless": true,
       "noSandbox": true
     }
   }

2. Chromium manuell starten:

   chromium-browser --headless --no-sandbox --disable-gpu \
     --remote-debugging-port=18800 \
     --user-data-dir=$HOME/.openclaw/browser/openclaw/user-data \
     about:blank &

3. Systemd Service (Optional): Erstelle eine Datei unter ~/.config/systemd/user/openclaw-browser.service:

   [Unit]
   Description=OpenClaw Browser (Chrome CDP)
   After=network.target
   
   [Service]
   ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.openclaw/browser/openclaw/user-data about:blank
   Restart=on-failure
   RestartSec=5
   
   [Install]
   WantedBy=default.target

   Aktivierung: systemctl --user enable --now openclaw-browser.service

Problem: “Chrome extension relay is running, but no tab is connected”

Das passiert, wenn du das chrome Profil nutzt. Es wird erwartet, dass die OpenClaw Extension in einem aktiven Tab läuft.

Lösungen:

• Nutze den verwalteten Browser: openclaw browser start --browser-profile openclaw
• Nutze das Extension Relay: Installiere die Extension, öffne einen Tab und klicke auf das Icon, um die Verbindung herzustellen.

Verifizierung

Ob alles korrekt läuft, kannst du mit diesen Befehlen prüfen:

# Status checken
curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'

# Browsing testen
curl -s -X POST http://127.0.0.1:18791/start
curl -s http://127.0.0.1:18791/tabs

Config Reference

Option	Beschreibung	Default
browser.enabled	Browser-Steuerung aktivieren	true
browser.executablePath	Pfad zur Binary (Chrome/Brave/Edge/Chromium)	auto-detected
browser.headless	Ohne GUI ausführen	false
browser.noSandbox	--no-sandbox Flag hinzufügen	false
browser.attachOnly	Nur an bestehenden Browser anhängen	false
browser.cdpPort	Chrome DevTools Protocol Port	18800

Hast du weitere Fragen zum Setup? Nutze den AI Setup Assistant.

Nächste Schritte

• Browser Extension Setup
• Configuration Guide