Vous faites déjà tourner OpenClaw Gateway sur un petit VPS Ubuntu/Debian, mais dès que vous activez des capacités navigateur nécessitant Chromium, les journaux affichent l’absence d’affichage, un exécutable introuvable ou des erreurs de bac à sable. Cet article s’adresse aux équipes qui traitent le Linux sans bureau comme Gateway de production : sept points pour mettre à nu les hypothèses sur DISPLAY / Xvfb / browser.executablePath, un tableau comparatif du tampon virtuel versus un vrai écran, puis un runbook reproductible en six étapes (dépendances, Xvfb, environnement, validation de config, systemd/Docker, test minimal), avec le découpage par rapport aux articles installation multiplateforme, dépannage « not ready » et observabilité.
La documentation suppose souvent une pile d’affichage ; en production, c’est plutôt un VPS headless. Les sept points ci-dessous transforment le débat « installer Chrome suffit » en tableau de risques signable.
Penser que le processus Gateway hérite de DISPLAY depuis le shell :Sans Environment= systemd, les processus navigateur peuvent rester sans affichage.
Pointer browser.executablePath vers un chemin desktop :Les conteneurs ou images minimales ont d’autres chemins ; symptômes type spawn ENOENT.
Ignorer polices et dépendances ICU :Sans paquets de polices, le rendu peut échouer silencieusement ou expirer ; le Gateway semble « bloqué ».
Exécuter la sandbox navigateur en root :Chromium peut dégrader ou refuser la sandbox ; préférer un utilisateur dédié non privilégié, comme dans l’article durcissement.
Ne pas figer l’ordre de démarrage Xvfb / Gateway :Courses : premier appel d’outil échoue, retry « guérit » ; difficile à reproduire.
Budgéter la RAM navigateur avec les appels modèle :Sur petites machines Chromium OOM souvent avant le LLM.
Ne lire que les logs Gateway, pas les codes de sortie des enfants :Un navigateur qui crash apparaît comme timeout d’outil ; aligner les chronologies avec openclaw logs et le journal système.
Cause commune : le navigateur est vu comme un plugin optionnel plutôt qu’un runtime avec chaîne de dépendances OS. Par rapport à l’article poignée MCP : MCP couvre découverte d’outils et sessions ; ici on boucle sur binaire navigateur + pile d’affichage.
Si vous combinez Docker production et systemd bare-metal, notez dans la topologie qui démarre DISPLAY et Xvfb pour éviter deux orchestrateurs sur le même numéro d’écran.
Pas de solution universelle : vous échangez reproductibilité contre surface de dépannage.
| Dimension | Xvfb + DISPLAY | Affichage physique / VNC | Chromium --headless seul (sans Xvfb) |
|---|---|---|---|
| Empreinte des dépendances | Maintenir Xvfb, numéro d’écran, paquets de polices | Session, résolution, fenêtres avec intervention humaine | Comportement headless dépend de la version ; dérive après upgrade |
| Reproductibilité | Élevée : systemd ou compose figent les variables d’environnement | Moyenne : session bureau et verrouillage | Moyenne à élevée : selon distro et sandbox |
| Signaux de triage | Clairs : DISPLAY, logs Xvfb, stderr Chromium | Plus complexes : état GUI, invites de permission | Sporadiques : chemins GPU/ANGLE sans GPU |
| Cas d’usage typiques | Petit VPS, captures / automatisation seulement | Flux GUI lourds ou popups de signature | Chaîne d’outils validée en headless sur cette build |
Ici « reproductible » signifie : la même unité systemd ou le même fichier compose relèvent encore proprement Xvfb + Gateway + navigateur sur un VPS vierge.
Avec l’article not ready : si le Gateway n’écoute pas stablement, ne superposez pas encore la couche navigateur ou les logs se contaminent.
Ordre : pile d’affichage, puis Gateway, puis outils. Commandes type Debian/Ubuntu ; adaptez les noms de paquets.
Installer Chromium et les polices :apt install pour chromium ou google-chrome-stable plus fonts-noto et assimilés.
Installer Xvfb :Vérifier que Xvfb :99 -screen 0 1920x1080x24 démarre manuellement sans conflit de socket.
Exporter DISPLAY :DISPLAY=:99 dans le même environnement que Gateway ; systemd Environment=DISPLAY=:99, bloc environment Docker.
Renseigner browser.executablePath :Aligner avec which chromium ou le chemin paquet ; après changement lancer openclaw doctor.
Figer l’ordre systemd ou compose :Xvfb prêt avant Gateway ; politique de redémarrage et logs pour Xvfb.
Acceptation minimale :Gateway sain : un outil navigateur qui n’ouvre que about:blank ; journaux sans erreur sandbox/affichage avant d’ouvrir le trafic.
# 手动验证（维护窗）： 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）
Conseil : --no-sandbox est pour diagnostics limités ; en production revenir à un utilisateur non-root, moindre privilège et networkPolicy.
Avec observabilité : garder stderr Xvfb et Chromium sur le même ticket ; « Gateway vert, outils rouges » n’implique pas le backend modèle.
Pour le canal on-call. Si codes de fermeture WebSocket, voir gateway closed (1000).
cannot open display : DISPLAY et Xvfb vivants. executablePath ENOENT : chemin et même binaire monté dans le conteneur. zygote / sandbox : utilisateur non privilégié et paramètres noyau avant drapeaux de diagnostic temporaires.
Attention : ne laissez pas des drapeaux de sandbox permissifs en production ; après diagnostic, revenir en arrière, tracer le changement et satisfaire l’audit.
Sous Docker vérifier /dev/shm et la taille SHM : trop petit, Chromium quitte par intermittence.
Champs pour l’alignement niveau 2 ; anonymiser avant envoi externe.
/etc/os-release, uname -r, version majeure Chromium.ss -lxn | grep X11 ou équivalent.dmesg avec OOM killer.N’attacher le Gateway qu’à un portable qui dort rend la pile d’affichage et le réseau instables ; un VPS minimal OOM souvent quand navigateur et modèle cohabitent. Pour un macOS ou une couche de calcul dédiée, durable et contractuelle avec OpenClaw, un Mac distant dédié est en général plus stable. Face au bricolage matériel, la location cloud Mac Mini NodeMini clarifie SSH fixe, paliers disque et profils de nœuds reproductibles ; fiches et tarifs : tarifs Mac Mini, mise en route : centre d’aide, série via la catégorie OpenClaw.
Une fois la couche navigateur stable, étiqueter la cause racine dans le journal des changements pour le prochain upgrade Chromium.
DISPLAY pointe-t-il vers un Xvfb à l’écoute ; browser.executablePath correspond-il au binaire ; systemd/Docker injectent-ils DISPLAY et polices ? Capacité : tarifs Mac Mini et centre d’aide.
« not ready » : ports, mémoire, timeouts, ordre de démarrage conteneur ; ici : sous-système navigateur et affichage. Sinon comparer not ready et closed (1000).
Par la catégorie OpenClaw : installation, Docker, systemd, sécurité, observabilité, MCP ; aide : centre d’aide.