Sie betreiben OpenClaw Gateway bereits auf einem kleinen Ubuntu/Debian-VPS, sobald Sie jedoch browsernahe Funktionen mit Chromium aktivieren, tauchen in den Logs Meldungen zu fehlendem Display, fehlender Binärdatei oder der Sandbox auf. Dieser Artikel richtet sich an Teams, die headless Linux als produktives Gateway einsetzen: sieben Prüfpunkte zu versteckten Annahmen rund um DISPLAY / Xvfb / browser.executablePath, eine Vergleichstabelle für virtuellen Framebuffer versus echten Bildschirm, dann ein sechsstufiges, reproduzierbares Runbook (Abhängigkeiten, Xvfb, Umgebung, Konfiguration validieren, systemd/Docker, Minimaltest) sowie die Abgrenzung zu plattformübergreifender Installation, „not ready“-Fehlersuche und Observability.
Viele Handbücher setzen einen Display-Stack voraus; in Produktion dominiert der headless VPS. Die folgenden sieben Punkte machen aus „Chrome installieren reicht“ eine Risikoliste, die Sie abzeichnen können.
Annahme, der Gateway-Prozess erbe DISPLAY aus der Shell:Fehlt Environment= in systemd, landen Browser-Kindprozesse dennoch ohne Display.
browser.executablePath zeigt auf Desktop-Pfade:Container oder Minimalimages nutzen andere Pfade; typisch sind spawn-ENOENT-Fehler.
Schriftarten und ICU werden ignoriert:Ohne Font-Pakete kann das Rendering leise scheitern oder hängen – der Gateway wirkt „eingefroren“.
Browser-Sandbox als root:Chromium degradiert oder verweigert die Sandbox; besser dedizierter, unprivilegierter Benutzer wie im Security-Hardening-Artikel.
Startreihenfolge Xvfb/Gateway nicht fixiert:Race Conditions: erster Tool-Aufruf scheitert, Retry „heilt“ – schwer reproduzierbar.
Browser-RAM und Modellaufrufe in einem Topf:Auf kleinen Maschinen stirbt Chromium oft vor dem LLM an OOM.
Nur Gateway-Logs, keine Kind-Exit-Codes:Browser-Abstürze wirken downstream als Tool-Timeouts; Zeitachsen mit openclaw logs und Journal abgleichen.
Gemeinsame Ursache: der Browser gilt als Plugin statt als Runtime mit Betriebssystem-Kette. Zum MCP-Handshake: MCP löst Tool-Discovery und Sessions; hier geht es um Browser-Binary + Display-Stack.
Betreiben Sie Docker-Produktion und Bare-Metal-systemd parallel, dokumentieren Sie im Topologiebild, wer DISPLAY und Xvfb startet, damit sich die Orchestratoren nicht um dieselbe Display-Nummer streiten.
Es gibt keine Universallösung: Sie tauschen Reproduzierbarkeit gegen Fehlersuchfläche ein.
| Dimension | Xvfb + DISPLAY | Physischer / VNC-Display | Nur Chromium --headless (ohne Xvfb) |
|---|---|---|---|
| Abhängigkeitsfläche | Xvfb-Prozess, Display-Nummer, Font-Pakete pflegen | Session, Auflösung, manuelle Eingriffe | Headless-Verhalten versionsabhängig; nach Upgrades driftet es |
| Reproduzierbarkeit | Hoch: systemd/Compose fixieren Umgebungsvariablen | Mittel: Desktop-Session und Sperrbildschirm | Mittel bis hoch: abhängig von Distro und Sandbox |
| Signale für Triage | Klar: DISPLAY, Xvfb-Logs, Chromium stderr | Komplexer: GUI-Zustand, Berechtigungsdialoge | Sporadisch: GPU/ANGLE-Pfade ohne GPU |
| Typischer Einsatz | Kleiner VPS, Screenshots/Automatisierung | GUI-lastige oder Signatur-Popup-Flows | Toolchain auf dieser Version headless verifiziert |
„Reproduzierbar“ meint hier: Dieselbe systemd-Unit oder dieselbe Compose-Datei bringt auf einem frischen VPS weiterhin zuverlässig Xvfb + Gateway + Browser hoch.
Zusammen mit not ready: lauscht der Gateway-Prozess noch nicht stabil, lagern Sie keine Browser-Triage darauf – sonst vermischen sich die Logs.
Reihenfolge: zuerst Display-Stack, dann Gateway, dann Tools. Befehle Debian/Ubuntu-artig; auf anderen Distros Paketnamen tauschen.
Chromium und Schriften installieren:apt install für chromium oder google-chrome-stable plus gängige Fonts wie fonts-noto.
Xvfb installieren:Xvfb :99 -screen 0 1920x1080x24 manuell startbar, ohne Socket-Konflikte.
DISPLAY exportieren:In derselben Umgebung wie Gateway DISPLAY=:99; systemd Environment=DISPLAY=:99, Docker-environment-Block.
browser.executablePath setzen:Mit which chromium oder Paketpfad abgleichen; nach Änderungen openclaw doctor ausführen.
Reihenfolge in systemd oder Compose fixieren:Xvfb vor Gateway; Restart-Policy und Logging für Xvfb.
Minimalabnahme:Nach Gateway-Health einen Tool-Aufruf nur zu about:blank; Logs frei von Sandbox-/Display-Fehlern, dann Last erhöhen.
# 手动验证（维护窗）： Xvfb :99 -screen 0 1920x1080x24 & export DISPLAY=:99 chromium --no-sandbox --disable-dev-shm-usage --headless=new --dump-dom about:blank >/tmp/blank.html # 然后以相同 DISPLAY 启动/重启 Gateway（systemd 或 docker compose）
Hinweis: --no-sandbox nur in abgegrenzter Diagnose; in Produktion unprivilegierter Benutzer, Least Privilege und networkPolicy.
Passend zur Observability: Xvfb- und Chromium-stderr im selben Ticket – „Gateway grün, Tools rot“ nicht dem Modell anlasten.
Für den On-Call-Channel. Bei WebSocket-Close-Codes zur gateway closed (1000)-Anleitung wechseln.
cannot open display: DISPLAY und lebendes Xvfb prüfen. executablePath ENOENT: Pfad und gemountete Binary im Container. zygote / sandbox: unprivilegierter User und Kernel-Parameter, dann temporäre Diagnose-Flags.
Achtung: permissive Sandbox-Flags nicht dauerhaft in Produktion; nach Diagnose Konfiguration zurücksetzen, Change dokumentieren und Prüfanforderungen berücksichtigen.
Unter Docker /dev/shm und Shared-Memory-Größe prüfen: zu klein, Chromium bricht intermittierend ab.
Felder für Second-Level-Abgleich; vor externem Versand anonymisieren.
/etc/os-release, uname -r, Chromium-Hauptversion.ss -lxn | grep X11 oder gleichwertig.dmesg mit OOM killer.Für Organisationen mit Bezug zur DSGVO ist eine nachvollziehbare Dokumentation sicherheitsrelevanter Konfigurationsänderungen (etwa Sandbox-Flags) sinnvoll, um Rechenschaftspflicht und Prüfungen zu unterstützen; dies ersetzt keine Rechtsberatung.
Gateway nur auf einem schlafenden Laptop zu betreiben macht Display und Netzwerk instabil; ein Minimal-VPS OOMt oft bei Browser plus Modell. Für eine langfristige, vertraglich saubere macOS- oder dedizierte Rechenebene mit OpenClaw ist ein dediziertes Remote-Mac meist stabiler. Gegenüber Bastel-Hardware bietet NodeMini Mac Mini Cloud-Miete feste SSH, klare Disk-Stufen und reproduzierbare Node-Profile; Spezifikationen unter Mac-Mini-Mietpreisen, Einstieg im Hilfezentrum, Serie über die Blog-Kategorie OpenClaw.
Ist die Browser-Schicht stabil, Root Cause im Änderungsprotokoll markieren – beim nächsten Chromium-Upgrade nicht erneut stolpern.
Zeigt DISPLAY auf ein lauschendes Xvfb; stimmt browser.executablePath mit der Binary überein; injizieren systemd/Docker DISPLAY und Fonts in den Gateway-Prozess? Kapazität: Mac-Mini-Mietpreise und Hilfezentrum.
„not ready“: Ports, Speicher, Timeouts, Container-Start; hier: Browser-Subsystem und Display. Weiterhin not ready und closed (1000) vergleichen.
Über die OpenClaw-Kategorie zu Installation, Docker, systemd, Security, Observability und MCP; Onboarding im Hilfezentrum.