Les équipes qui font tourner OpenClaw Gateway sur Docker / Compose perdent rarement le plus de temps à tirer les images : elles le perdent quand les redémarrages, upgrades ou docker compose down effacent l’appariement et la config, ou quand les répertoires Skills sont en lecture seule avec un flot de Permission denied qui ne correspond pas aux entrées réseau du dépannage officiel. Cet article complète la triage réseau Docker, la triage doctor post-installation, le runbook Docker production & Gateway et les opérations Mac distant sans présence : six pièges volumes/permissions, deux tableaux persistance vs anti-patterns, une matrice symptôme→commande→correctif, extraits inspect à copier-coller, un runbook en six étapes et trois métriques tableau de bord. Ordre de triage : d’abord volumes et UID/GID, puis réseau et reverse proxies.
Les images sont des gabarits immuables ; seul l’état écrit dans la couche inscriptible, les volumes anonymes ou des chemins non persistés disparaît. Capturez les signaux ci-dessous dans les tickets de changement et revoyez-les sur la même ligne que les révisions Compose et les tags d’image.
down -v ou les scripts de nettoyage suppriment les caches d’appariement même quand « rien n’a changé dans git ».user est un échec fréquent.:ro pour la « sécurité » bloque les caches de tokens ou l’état local attendu par l’exemple amont ; les échecs peuvent rester silencieux jusqu’au redémarrage.docker commit est tentant mais les upgrades ou changements de tag jettent quand même cette couche—éviter en production.Si la triage réseau montre encore un succès CLI intermittent mais un échec certain après redémarrage, revenez ici pour vérifier que les volumes nommés sont sur le disque attendu et que l’utilisateur processus peut écrire les Skills avant de toucher network_mode ou les proxies.
Les sous-chemins suivent votre image et la doc ; le tableau cadré trois questions d’ingénierie : survit au cycle de vie du conteneur, nécessite une sauvegarde, partagé en lecture seule ? Consignez les réponses dans le README et les playbooks d’astreinte.
| Classe | Contenu typiquement persisté | Schéma recommandé | Anti-pattern |
|---|---|---|---|
| Config & matériel secrets | Points de terminaison Gateway, choix de fournisseur, chemins des tokens de canal | Bind hôte ou volume nommé ; droits limités à l’utilisateur d’exécution | Cuire dans l’image ; stocker sous des répertoires nettoyés par des outils de sync |
| Exécution & appariement | État d’appariement d’appareil et restauration de session | Sous-arbre bind dédié ; tar avant upgrades | Volumes anonymes non documentés dans Compose ; un seul prune efface tout |
| Skills / extensions | Fichiers et scripts Skills de l’équipe | Bind à côté du repo ; chemins identiques en CI et prod | :ro alors que les caches d’exécution doivent être en écriture ; UID ne peut pas écrire |
| Journaux & tampons | Gros journaux, exports | Volume séparé ou chemin hôte avec rotation | Remplir la couche inscriptible jusqu’à l’OOM ou un FS lecture seule inattendu |
Pendant les contrôles, journalisez les ID d’image, noms de projet Compose et noms de volumes dans la même session shell pour simplifier les rollbacks ; réutilisez la page checklist de release du runbook production.
| Symptôme | Vérifier d’abord | Correctif typique | Si ça échoue encore |
|---|---|---|---|
Tout ressemble à une install fraîche après docker compose up | docker inspect Mounts vs chemins hôte attendus ; nettoyage récent -v | Binds explicites ou volumes nommés ; documenter si down peut utiliser -v | Vérifier que vous êtes dans le bon répertoire de projet Compose |
| Skills ignorés ou écritures en échec | id dans le conteneur vs propriété hôte ls -ln | Ajuster user, chmod ou aligner l’UID dans Dockerfile/point d’entrée | Confirmer que les montages ne sont pas :ro |
| Flux d’erreurs de permission | SELinux/AppArmor sur Linux ; partage de fichiers Docker Desktop sur macOS | Linux : évaluer labels ou :z selon la baseline sécurité ; macOS : ajouter les chemins au partage de fichiers | Écarter un disque lecture seule avant de rouvrir la triage réseau |
| Partiellement fonctionnel après bump d’image | Changements de schéma de config ; ancien répertoire de données encore monté | Suivre les notes de release ; sauvegarder avant upgrade | Lancer openclaw doctor contre les changements cassants documentés |
# 1) Les montages atteignent-ils les chemins hôte attendus ? (remplacer le conteneur)
docker inspect -f '{{ json .Mounts }}' <container> | jq .
# 2) Utilisateur d’exécution dans le conteneur (comparer à la propriété hôte)
docker exec -it <container> id
# 3) Projets Compose et volumes (éviter la dérive anonyme)
docker compose ls
docker volume ls | grep <project>
# 4) Exemple de sauvegarde bind avant upgrade (chemin selon convention d’équipe)
tar czf openclaw-state-$(date +%Y%m%d).tgz ./openclaw-data/
Note : Docker Desktop sur Mac distants garde en général les binds sous les répertoires home utilisateur ; les hôtes cloud Linux peuvent nécessiter d’autres lignes user et modèles de permissions. « Ça marche sur mon portable » n’équivaut pas à « ça marche sur des hôtes en pool ».
down -v détruit.openclaw doctor et les sondes de canaux pour éviter les faux négatifs.Permission denied / EACCES ; corréler aux upgrades Gateway indique souvent les montages, pas les fournisseurs.Tracer ces courbes à côté des métriques disque et logs de l’article Mac distant—les problèmes de volume apparaissent souvent comme disque qui dérape ou montages lecture seule avant les pics CPU.
Beaucoup d’équipes colocalisent Gateway et Skills sous un même arbre hôte en 2025–2026 ; sans quotas sur les sous-arbres purement logs, les logs peuvent remplir le bind et bloquer les écritures de config. Corriger la rotation ou scinder les volumes avant de recréer les conteneurs en boucle.
Distinguer aussi docker compose restart de down/up : le premier conserve en général les volumes déclarés ; le second, avec flags de nettoyage, change le sort des données—utiliser une antisèche de verbes partagée dans les runbooks.
Les permissions portable mono-utilisateur diffèrent des hôtes distants en pool avec connexions automatisées ; veille, utilitaires de sync et éditions manuelles des binds rendent « ça marchait hier » non reproductible. Faire tourner OpenClaw comme plan de contrôle 24/7 exige des chemins contractuels, des upgrades réversibles et des permissions auditables.
Les boucles d’apprentissage sur matériel perso vont bien, mais le coût production apparaît comme bruit de pagers et canaux morts. Des conteneurs scratch éphémères sans montages stables multiplient les domaines de défaillance lors des upgrades. Les équipes qui ont besoin de Gateways toujours disponibles, propices aux sauvegardes et portables convergent souvent plus vite vers des empreintes Mac cloud pro avec bare metal Apple Silicon et choix multi-régions que vers l’ajustement infini de Docker perso. MACCOME propose des locations Mac mini M4 / M4 Pro multi-régions plus une aide publique—commencez par le centre d’aide et les tarifs de location, puis le checkout régional.
Conseil de déploiement : exécuter les contrôles du tableau 2 sur la même classe d’hôte que en production (Docker Desktop vs Linux) avant de câbler canaux et modèles—éviter la dérive UID et chemins « local OK, cloud KO ».
Si vous utilisez aussi Kubernetes, les pods recyclent plus souvent que les stacks Compose : tout ce qui n’est pas soutenu par un PVC disparaît lors des mises à jour rolling—la même règle de persistance explicite s’applique, à vérifier avec kubectl describe pvc et les manifests de montage.
FAQ
En quoi est-ce différent de l’article de triage réseau Docker ?
Le réseau couvre connectivité et espaces de noms ; cet article couvre si les données sont sur disque et en écriture. Pour les points d’entrée d’installation, voir le guide d’installation trois plateformes. Accès et tarifs : centre d’aide et tarifs de location.
Doctor ou volumes en premier ?
Volumes et permissions d’abord, puis doctor, pour éviter les faux positifs quand les conteneurs sont sans cesse recréés. Les détails WSL2 restent dans l’article doctor post-installation.
Comment cela s’associe-t-il aux opérations Mac distant ?
L’article sur les opérations Mac distant traite launchd/systemd, les journaux et la triage des blocages ; le présent article traite la persistance Docker et l’écriture. Les deux vont dans la même revue de changement et le même index d’astreinte.