2026 OpenClaw Linux headless Docker : onboard bloqué, pending.json et dashboard --no-open, runbook de vérification

Lecture ~16 min · MACCOME

Si vous exécutez OpenClaw avec Docker uniquement sur un VPS Linux sans interface graphique—sans bureau, sans navigateur—et rencontrez un assistant ou onboard bloqué en pending, des journaux qui demandent d’ouvrir un navigateur local, ou un dashboard qui échoue sans DISPLAY, cet article fournit une échelle d’acceptation headless prête pour ticket : figer une piste compose et une source TOKEN unique, puis remplacer « j’ai vu la Control UI » par dashboard --no-open, gateway status/probe et des journaux structurés. Il complète le guide d’installation trois OS, la triage Windows Docker, le Linux systemd+Tunnel sans Docker et l’appairage Compose 1006/1008 ; les ancres production s’associent au Gateway dédié via transfert SSH local.

Six faux échecs sous Linux headless Docker pour OpenClaw

  1. Définir « ouvrir un navigateur » comme critère d’acceptation : sur hôtes headless, l’échec est souvent le script de test, pas le Gateway—utilisez des contrats CLI.
  2. Double piste onboard plus compose : deux entrées écrivent à moitié pending.json et les variables d’environnement—pending aléatoire ou dérive TOKEN (même racine que l’article d’appairage Compose).
  3. Absence de commutateurs silent/headless : l’assistant attend une interaction pendant que les checks restent « verts ».
  4. cgroup, pilote graphique et ulimits par défaut : les petits VPS déclenchent OOM ou épuisement de fd—lus à tort comme WebSocket 1006.
  5. MITM d’entreprise ou proxys transparents : les pulls d’images réussissent pendant que les poignées WebSocket cassent—vérifiez TLS et magasins de confiance.
  6. Copier les devoirs Windows sur Linux : WSL2 et Docker Desktop diffèrent du moteur Linux—suivez l’ordre « moteur avant métier » du triage doctor post-install.

La valeur headless est une surface d’attaque réduite et une automatisation plus forte ; si l’acceptation dépend encore d’un clic navigateur, vous n’avez que déplacé le chaos bureau dans SSH. En lisant le runbook Docker production, gardez tag d’image, hash compose et injection TOKEN sur le même ticket.

Si l’équipe maintient à la fois bare metal systemd et Docker, documentez la vérité par défaut : quel chemin est l’intégration CI image et quel chemin est la prod—les hôtes mélangés sont la classe la plus dure à déboguer.

Dimension Docker headless (cet article) Linux systemd + Tunnel (sans conteneurs)
Repro & upgrades Tags d’image et compose versionnent vite, rollback rapide Dépend des paquets distro et unit files ; personnalisation profonde, histoire image plus faible
Acceptation headless S’accorde naturellement avec --no-open et pilotes de journaux conteneur journald et sondes curl ; chemins différents de Docker
Espaces de noms réseau 1006/1008 souvent liés aux combinaisons bridge / publish Pile hôte ; les problèmes tombent souvent sur Tunnel et bind
Avec Mac distant dédié Le Gateway peut migrer vers un hôte dédié ; le portable reste CLI-only Même conclusion ; habitudes ops différentes
Mauvaise pratique courante Forks compose CI/prod sans labels Faire cohabiter mentalement Tunnel-gateway et Docker-gateway sur une même boîte
info

Note : Les conseils communautaires pour mettre silent à true dans pending.json afin de sauter les assistants bloquants doivent être recoupés avec la documentation OpenClaw actuelle avant de les figer dans les pipelines ; relancez une régression après upgrades pour éviter qu’un mode silent ne devienne un gel silencieux.

Runbook headless en six étapes : des images pullables au probe Gateway vert

  1. Geler une seule piste d’entrée : compose-only ou docker-setup officiel uniquement ; traitez l’autre comme référence en lecture seule.
  2. Valider moteur et disque : docker info, espace libre sur la racine données Docker, ulimit -n ; les tout petits VPS ajoutent swap ou plafonnent la concurrence avant les fonctionnalités.
  3. Gérer onboard / pending : appliquez les commutateurs headless documentés ; après changement, imprimez un hash des fichiers pending dans les journaux CI pour audit.
  4. Démarrer le Gateway et vérifier uniquement par CLI : openclaw gateway status → openclaw gateway probe (si disponible) → openclaw dashboard --no-open ; interdisez « je l’ai vu dans un navigateur » comme unique signal de succès.
  5. Lancer doctor et enregistrer les dérogations : alignez les champs avec la triage doctor post-install ; chaque dérogation a besoin d’un propriétaire et d’une échéance.
  6. Ajouter une régression : après rebuild conteneur, le même script doit passer en moins de 10 minutes ; sinon incident avec hash compose et digest image.
bash
# Exemple : contrôles CLI uniquement (adapter les noms de services compose)
docker compose ps
docker compose logs -f --tail=200 openclaw-gateway

openclaw gateway status || true
openclaw dashboard --no-open || true
openclaw doctor --yes || true

Trois métriques pour SLO ou notes d’astreinte (adapter à vos SKU)

  • Démarrage à froid jusqu’à première probe réussie (G2P) : médiane en minutes de compose up -d à première gateway probe réussie ; si la hausse hebdomadaire dépasse 40 % sans changement de tags image, vérifiez disque et fds avant d’accuser les modèles.
  • Étapes dépendantes du navigateur sur hôtes headless : cible zéro ; tout nouveau pas exigeant DISPLAY retourne vers produit ou profil compose dev-only.
  • Événements dual-Gateway : comptez doubles binds sur 18789 ou alertes TOKEN double source ; >0 pendant deux semaines doit déclencher une revue d’architecture selon l’article TOKEN double source.

Pourquoi « installer un bureau léger + VNC » ou « réessayer onboard jusqu’à la chance » est un mauvais compromis en 2026

Les bureaux légers élargissent la surface de patch et le coût d’audit de session ; le VNC public reste un motif à haut risque. Les retries onboard infinis cachent la dérive des champs dans la mémoire manuelle, pas dans l’automatisation.

Lorsque vous avez besoin d’un Gateway 7×24 auditable aligné sur CI pendant que Linux headless reste idéal pour essais en périphérie ou PoCs courts, placer le Gateway faisant autorité sur un Mac Apple Silicon distant dédié avec SSH forward ou politique tailnet documentée bat généralement les limites cgroup des petits VPS—MACCOME propose Mac mini (M4 / M4 Pro) dans six régions avec baux flexibles ; dimensionnez avec le guide public nœuds et baux avant engagement.

Clôture : l’acceptation headless vit dans DOCKER_GATEWAY.md, pas dans le chat

Livrez : version compose, digest image, politique silent/pending, exemples de sorties CLI, affirmation explicite « aucun navigateur requis ». Toute étape non rejouable sur un second hôte headless est une documentation incomplète.

Par rapport à la triage Windows Docker, rappelez-vous : même échelle, hôte et moteur différents ; ne mélangez pas chemins de journaux Docker Desktop et moteur Linux.

FAQ

L’onboard reste en pending sur un serveur sans interface graphique—ai-je besoin d’un bureau ?

En général non : utilisez les commutateurs headless et l’acceptation CLI ; vérifiez les champs pending.json avec la doc. Pour un Gateway de production sur nœuds dédiés, voir les tarifs de location Mac mini et commander un Mac mini cloud.

Linux Docker et systemd+Tunnel peuvent-ils partager une machine ?

Techniquement oui, mais sans environnements séparés la double vérité Gateway / TOKEN est fréquente. Documentez la valeur par défaut. Voir le runbook Tunnel et l’article d’appairage Compose.