2026 OpenClaw sur Mac VPS avec Docker : jeton Gateway, reseau conteneur CLI et runbook de blocage du jumelage

1. Points douloureux : double jeton, loopback, jumelage, bind, uid

Les flux Docker officiels supposent quun humain clique dans le meme espace de noms reseau que les scripts. Sur un Mac VPS sans operateur, les pannes se regroupent en cinq familles :

1. Ecrasement silencieux par variable : OPENCLAW_GATEWAY_TOKEN dans le conteneur peut primer sur gateway.auth.token dans openclaw.json, donc lUI affiche un jeton que le gateway ne valide pas.
2. Loopback CLI en stacks separees : la CLI vise par defaut ws://127.0.0.1:18789, soit le conteneur CLI, pas le gateway ; ECONNREFUSED ou fermetures 1006 ressemblent a des flaps reseau.
3. Deadlocks de jumelage : avec gateway.bind=lan, tableau de bord et CLI attendent mutuellement une approbation ; sans ordre ecrit vous tournez sur 1008.
4. Semantique bind contre realite bridge : loopback contredit les objectifs inter-conteneurs ; passer a lan sans mettre a jour lURL CLI laisse des logs listen OK mais pas de WebSocket complet.
5. Derive UID des volumes : images souvent en uid 1000 ; chemins crees en root sur l hote cassent la persistance et amplifient la confusion sur les jetons.

Sur Mac VPS sans ecran, aucun navigateur local ne masque la mauvaise config : chaque retry WebSocket est dans les logs et launchd redemarre les conteneurs meme pendant un jumelage. Lisez docker compose logs -f openclaw-gateway et la CLI comme une seule chronologie. Si vous figez les images par digest, notez digest et empreinte du jeton sur le ticket de changement pour eviter quun rollback ressuscite un ancien modele dauth. Si le tableau de bord depasse loopback, croisez ce texte avec le guide de durcissement sur lexposition du gateway pour traiter la derive des jetons comme un sujet de rayon dexplosion, pas seulement Docker.

2. Table de triage : symptome, cause, premiere commande

Collez la table dans votre modele dincident ; en phase politique, lisez aussi le guide de durcissement sur lexposition.

Quand la table dit de grep les deux sources, faites-le : recherche OPENCLAW_GATEWAY_TOKEN dans le depot, inspection de openclaw.json via docker compose exec openclaw-gateway cat /chemin/openclaw.json (adapter le chemin), diff avec la section env du compose. Avec un gestionnaire de secrets, verifiez la valeur resolue a lexecution, pas seulement le template Git. Pour 1008, notez si le tableau de bord et la CLI montrent des etats pending inverses : cela pointe souvent vers un mauvais GATEWAY_URL ou des cookies fractionnes plutot quune vraie panne dautorisation.

3. Runbook en cinq etapes jusquaux controles astreinte

1. Geler le secret : huit premiers caracteres du jeton et digest image sur le ticket.
2. Aligner les doubles sources : avant compose up, comparer en lecture seule gateway.auth.token et OPENCLAW_GATEWAY_TOKEN dans chaque definition de conteneur.
3. Corriger les espaces de noms : privilegier network_mode: service:openclaw-gateway pour la CLI ; si bridge obligatoire, fixer GATEWAY_URL=ws://openclaw-gateway:18789 et tester le DNS depuis un shell jetable docker compose run.
4. Casser le jumelage : dans le conteneur gateway, openclaw dashboard --no-open, completer lURL avec jeton, puis depuis la CLI devices approve en consignant la sequence dans le ticket.
5. Sonder et launchd : depuis l hote, curl /healthz et /readyz avec timeouts courts ; refleter les memes tests dans un plist SuccessfulExit pour eviter les faux verts pendant que le WS est bas. Limites de ressources : article Compose 7x24 sur ce site.

Esquisse Compose minimale (fusionner avec les templates amont avant prod) :

Si network_mode: service:openclaw-gateway est impossible a cause dun sidecar partageant le namespace CLI, utilisez une URL interne explicite et verifiez depuis un conteneur jetable : docker compose run --rm busybox wget -qO- http://openclaw-gateway:18789/healthz (ou curl). Documentez le nom d hote attendu pour le DNS Docker ; les fautes de frappe expliquent souvent les rapports ca marchait sur mon portable. Ne supprimez les lignes dappareils obsoletes quapres export des logs et verification du workspace.

4. Faits citables : port, uid, sondes

• Port : ecoute par defaut 18789 ; les scripts de sante doivent frapper le listener, pas seulement docker ps.
• UID : utilisateur node souvent 1000 ; alignez les bind sur l hote pour eviter une persistance silencieusement cassee.
• Sondes : /healthz pour la liveness, /readyz plus proche de la readiness WebSocket ; ordre et timeouts dans le runbook.
• Synchronisation : un grand decalage hote-conteneur perturbe certificats et correlation de logs ; gardez NTP sain sur le VPS.
• Fenetre de mise a niveau : lors des bumps dimage, rejouez la checklist en cinq etapes ; docker ps vert ne vaut pas session CLI authentifiee.

Industrialisez ces verifications dans votre playbook chatops : chaque escalade doit porter empreinte du jeton, revision du compose et digest sur une ligne pour que le postmortem ne devine pas. Si vous envisagez du blue/green sur le gateway, documentez quel stack conserve encore danciennes lignes de jumelage afin deviter dapprouver des peripheriques contre la mauvaise URL. Pour la charge, utilisez les memes timeouts sur les endpoints de sante quen production ; des timeouts plus courts en test masquent des flakiness. Les fournisseurs Mac VPS avec bande passante dediee reduisent aussi le risque de limitation pendant de longues sessions WebSocket. Ne copiez jamais les jetons entre staging et production ; preferez des fichiers .env distincts avec suffixes explicites. Conservez un petit schema darchitecture montrant les namespaces gateway, CLI et sidecar pour que lastreinte ne se perde pas dans le bridge.

Ajoutez une mini liste de roles : qui peut lancer devices approve, qui peut faire tourner les jetons, et comment tracer cela dans un ticket chiffre. Sans ces roles, les approbations de jumelage echouent souvent vers des personnes sans console VPS, ce qui allonge le MTTR. Avec de linfrastructure-as-code pour Compose, validez les changements par diff statique contre la sortie docker compose config en cours d execution pour attraper les superpositions denvironnement avant fusion. Pendant les fenetres de maintenance longues, faites volontairement echouer les healthchecks pour verifier que launchd arrete reellement plutot que de rebooter le conteneur pendant que les clients gardent danciennes sessions. Conservez aussi les entetes de mise a niveau WebSocket dune poignee reussie comme reference pour detecter plus vite les regressions.

5. Ordre de lecture : Compose 7x24 et guides gateway natifs

Si redemarrages Compose, plafonds memoire et digests figes ne sont pas standardises, commencez par Compose 7x24 sante, mise a niveau, rollback. Quand la discussion porte sur qui detient la verite entre binaire gateway et CLI, ouvrez Runbook gateway install / bind / auth pour tracer la frontiere natif contre Docker. Une demo portable avec docker run ad hoc cache les problemes de jumelage et de jeton qui deviennent du bruit de pagere sur Mac VPS sans ecran. Docker ajoute une couche dabstraction par rapport au seul launchd, donc upgrades et exercices dincident coutent plus de temps mural. Pour des agents longue duree avec Apple Silicon dedie, sortie stable et concurrence previsible, louer des noeuds Mac cloud VPSMAC M4 reste le moyen le plus simple de garder binds, politiques plist et fichiers Compose dans une seule histoire operationnelle. Bouclez depuis le tableur vers lautomatisation avec le guide API Mac cloud quatre-vingt-dix secondes sur ce site.