2026 OpenClaw : Docker Compose officiel sur Mac distant—image GHCR, volumes, port 18789 et validation de la console en VNC

Lorsque vous ne faites pas qu'essayer OpenClaw, mais que vous le faites tourner des semaines sur un Mac distant loué ou une poste dédiée, la question de la reproductibilité arrive vite : quelle version de Node était réellement active ? Quels paquets globaux ont été mis à jour ? Docker Compose avec l'image officielle ghcr.io/openclaw/openclaw réduit cette incertitude : vous figez un tag ou un digest, vous attachez la configuration et les données à des volumes nommés ou des montages bind, et vous documentez le port 18789 pour la console web comme le prévoit la documentation amont. Ce guide s'adresse aux opérateurs avancés : vous y trouverez une matrice de décision face à l'installation npm, une liste de pièges fréquents sur macOS, un parcours pas à pas avec un exemple de compose.yaml, et des arguments sur la façon dont la session VNC reste la surface la plus fiable pour navigateur et flux d'autorisation. Pour aller plus loin, consultez nos articles sur launchd et démon, SecretRef et audit des secrets, isolement multi-projets et erreurs courantes et dépannage.

1. Docker et npm : quand les conteneurs valent l'effort

En 2026, l'écosystème OpenClaw propose scripts shell, npm install -g et des images OCI sur la GitHub Container Registry. Pour un développeur qui change de branche chaque jour et attache un débogueur, l'installation native reste souvent la plus rapide : moins de couches, boucles courtes, outils locaux directement accessibles. Dès que plusieurs environnements coexistent sur un même compte utilisateur, ou qu'un Mac distant fourni par un hébergeur sert plusieurs missions, l'état global de Node devient un risque : un npm update prématuré peut décaler des interfaces de plugins, et les retours arrière sont pénibles à tracer.

Docker Compose formalise l'état cible : quelle image (idéalement tag fixe ou digest), quelles variables d'environnement via une .env non versionnée, quels répertoires survivent aux redémarrages grâce aux volumes. Dans les contextes réglementés, on épingle les digest et on revoit les changements via SBOM ou signatures de registre—plus simple à documenter qu'une pile Node bare metal. Un second gain est l'isolation réseau et ports : deux projets Compose nommés différemment peuvent coexister si les ports hôte et les noms de volumes sont distincts, ce qui complète notre guide multi-projets sur les conventions de dossiers et de clés API.

Sous macOS, les montages bind vers la VM de Docker Desktop ou Colima peuvent être plus lents que sur Linux. Placez les artefacts volumineux dans des volumes Docker nommés plutôt que sur des partages réseau lents. Vérifiez aussi les tags ARM ou Rosetta selon votre matériel. Si Compose n'est qu'un emballage, alignez-vous avec l'exploitation : mêmes métriques qu'en natif ? journaux sur stdout, fichiers dans le volume, ou les deux ? Sans cette clarification, vous déplacez la complexité au lieu de la réduire.

Enfin, tenez des runbooks de montée de version et de retour arrière : un docker compose pull suivi d'un redémarrage est vite tapé ; la compatibilité des schémas de configuration entre mineures relève des notes de version et parfois de guides de migration—pas du simple redémarrage. Lorsque SecretRef et l'audit entrent en jeu, Docker reste un transport ; la gouvernance suit les workflows décrits dans l'article SecretRef.

2. Cinq écueils après le passage à Compose

Même si le conteneur démarre, une deuxième vague d'erreurs apparaît souvent sous charge réelle. Les points ci-dessous sont issus de retours d'exploitation ; vérifiez toujours les drapeaux avec openclaw --help et le changelog amont.

1. UID/GID et droits sur volumes : si le processus tourne sans root dans le conteneur mais que le bind mount appartient à un autre utilisateur hôte, les écritures de configuration ou de logs échouent. Corrigez avec user: cohérent dans Compose ou un chown initial documenté.
2. Loopback et interface : la doc cite souvent le port 18789 pour la console. Si le service n'écoute que sur 127.0.0.1 dans le conteneur et que le mapping de ports est incorrect, tout semble mort depuis l'extérieur alors que curl fonctionne à l'intérieur. Dans une session VNC sur le Mac distant, ouvrez http://127.0.0.1:18789 comme l'utilisateur bureau—plus fiable que des chaînes de tunnels SSH.
3. onboard interactif sans TTY : les assistants qui attendent des entrées ou des callbacks navigateur échouent dans docker compose run non interactif. Utilisez un terminal avec TTY ou des modes non interactifs s'ils existent.
4. Double exécution avec launchd : si un openclaw gateway natif tourne déjà via LaunchAgent, le conteneur peut entrer en conflit sur les mêmes ports et chemins. Arrêtez explicitement le service natif avant de monter le stack.
5. Secrets dans les layers d'image ou lisibles par tous : les clés API n'ont pas leur place dans un Dockerfile versionné. Employez des magasins externes ou les flux SecretRef / openclaw secrets, avec permissions strictes sur hôte partagé.

Sur les Mac distants partagés, des problèmes organisationnels s'ajoutent : un second stack « rapide » avec le nom de projet par défaut, des ports hôte déjà pris, ou le même dossier hôte monté deux fois. Tenez un registre interne : noms de projet, ports attendus, responsables—comme les règles de compartiments du guide multi-projets.

3. Matrice : bare metal, un stack Compose, plusieurs projets

La matrice est volontairement simple : en pratique, on combine souvent Compose pour la passerelle et des CLI locales en CI. L'essentiel est un journal homogène de version, chemins de config et secrets pour accélérer l'analyse post-incident après snapshot ou upgrade majeur. Avec plusieurs stacks, les tableaux de bord doivent afficher ID de conteneur, tag d'image et nom de projet pour que les alertes restent actionnables.

Enfin, tracez explicitement qui est responsable du cycle de vie des images : sans propriétaire, latest devient une roulette et les correctifs de sécurité tardent. Un calendrier de revue trimestrielle—même léger—réduit les écarts entre ce que vous croyez déployer et ce qui tourne réellement sur le Mac distant.

4. Mise en œuvre : dossier, fichier Compose, onboard, service

Voici un squelette pédagogique. Les environnements de production ajoutent healthchecks, limites de ressources, pilotes de logs et souvent un reverse proxy TLS. Vérifiez les noms de champs avec le dépôt officiel ; les notes de version mentionnent souvent des changements de variables. Avant le premier up, un docker compose config détecte tôt les fautes YAML et la substitution de variables lorsque plusieurs fichiers env_file sont en jeu.

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    ports:
      - "18789:18789"
    volumes:
      - openclaw_config:/root/.openclaw
      - ./workspace:/workspace
    restart: unless-stopped
volumes:
  openclaw_config:

Ajoutez environment: ou une .env hors dépôt. Préférez un tag explicite à :latest si votre équipe l'exige. En environnement contraint, épinglez le digest. Après le premier démarrage réussi, confrontez docker compose ps et docker inspect à votre documentation interne—les écarts de ports ou de montages sont une cause fréquente de tickets.

5. Références, sauvegardes et checklist

• Nom de projet Compose et ports hôte sans collision avec d'autres mandants sur le même Mac.
• Écriture volume OK ; la rotation des journaux ne vide pas silencieusement tout le flux.
• Interface web et passerelle cohérentes après reboot de l'hôte.
• Secrets uniquement par canaux contrôlés—pas de clair dans l'historique shell ou des fichiers world-readable.
• Modifications de Compose relues ; dérive entre dépôt et stack détectée.

6. FAQ et liens avec le reste du corpus OpenClaw

Question : faut-il faire démarrer docker compose par launchd à l'ouverture de session ? C'est possible, mais il faut trancher : soit launchd exécute docker compose up -d dans un répertoire fixe, soit vous vous appuyez sur restart: unless-stopped et le démarrage du démon Docker—voir la checklist launchd. Évitez qu'un binaire natif et un conteneur écrivent la même arborescence de configuration.

Question : comment empêcher deux projets de lire les mêmes clés API ? L'isolement par répertoires et variables reste la base ; le conteneur ne remplace pas la politique. Suivez la checklist multi-projets et ajoutez SecretRef lorsque vous retirez les littéraux de config.

Question : le conteneur démarre mais les appels modèle échouent—par où commencer ? Ordre conseillé : réseau, authentification, configuration ; l'article dépannage structure les symptômes. Pour chaque incident, notez horodatage, tag d'image et extraits de logs utiles à l'escalade.

Question : avez-vous encore besoin d'un Mac si tout est conteneurisé ? Beaucoup d'étapes sont portables, mais macOS diffère de Linux-CI sur permissions, trousseau et chemins. Si votre cible est un Mac distant, validez-y—pas seulement sur le runner. VNCMac propose des instances locatives et des guides de connexion pour ce scénario.

Conclusion : reproductibilité dans le conteneur, visibilité via VNC

Docker Compose formalise le « qu'est-ce qui tourne ici ? » de façon machine-lisible ; la VNC sur Mac distant apporte le « que voit l'humain ? » pour navigateur, dialogues et presse-papiers. Acheter du matériel dédié pour un besoin ponctuel est souvent disproportionné ; le SSH sans bureau masque la dernière ligne. VNCMac comble cet écart avec des Mac isolés et des parcours de connexion clairs, pour investir votre temps dans l'automatisation et l'observabilité plutôt que dans l'achat ad hoc de machines. Après chaque upgrade majeur, refaites un court test fumée en VNC, un échantillon de logs, puis validez pour l'équipe.