gateway.bind=lan sans auth valide refuse le démarrage, OPENCLAW_GATEWAY_TOKEN n'existe que dans le shell interactif tandis que LaunchAgent ne le lit pas, et après modification de config on suppose que le rechargement hybrid remplace un restart complet lors d'un changement de bind. Ce guide propose une arborescence loopback vs lan, un tableau source unique pour .env et openclaw.json, six étapes avec bloc de commandes, la frontière gateway.reload.mode=hybrid vs restart manuel plus gateway.controlUi.allowedOrigins, et des bifurcations pour refusing to bind without auth, EADDRINUSE et unauthorized ; liens vers launchd token, upgrade et accès distant, gateway remote, échelle diagnostic et install-daemon.
loopback ou lan : décision de bind OpenClaw Gateway sur Mac cloud 2026
OpenClaw Gateway écoute par défaut sur loopback – adapté quand un ingénieur SSH sur le Mac cloud ouvre le dashboard localement, ou quand seuls CLI et launchd parlent au service. Dès qu'une Control UI sur un second portable, plusieurs clients remote ou des sondes intranet dans le même VPC doivent atteindre le port 18789 sans tunnel SSH, il faut passer gateway.bind de loopback à lan. OpenClaw 2026 resserre la ligne de sécurité : quitter 127.0.0.1 sans gateway.auth.token valide ou OPENCLAW_GATEWAY_TOKEN injecté, le processus refuse de démarrer – logs du type refusing to bind without auth. Ce n'est pas un bug : cela force à documenter surface d'écoute élargie et auth production dans le même ticket de changement.
Ne décidez pas seulement sur le ping : une personne seule devrait garder loopback plus ssh -L ou Tailnet (voir l'article tunnel) ; lan plus token vaut le coup quand des segments RFC1918 fixes accèdent directement ou que la Control UI doit ouvrir le WebSocket à travers des sous-réseaux. Les cinq points suivants condensent les erreurs d'interprétation en astreinte avant de toucher au routage modèle ou de réinstaller des channels.
Tunnel suffisant, lan forcé : le forward SSH local couvre le besoin ; changer bind agrandit la surface d'attaque et la dérive plist sans gain.
lan sans token : gateway.bind=lan est écrit mais gateway.auth.mode manque ou token vide – arrêt immédiat.
Token seulement en shell : export OPENCLAW_GATEWAY_TOKEN interactif OK, job LaunchAgent sans variable – boucle de restart launchd.
URL de sonde ≠ listen : après lan, curl sur 127.0.0.1 ou healthz sans Authorization – faux offline.
18789 public sans auth applicative : security group 0.0.0.0/0, token et controlUi.allowedOrigins absents – bruit scanner dans les logs.
Sans install-daemon terminé, parcourir d'abord le chemin daemon officiel et la check-list install jusqu'à ready en loopback sous openclaw gateway status --deep – sinon métadonnées superviseur et stratégie bind se mélangent dans un ticket.
Token .env et openclaw.json : source unique en production
En production, le secret ne doit pas coexister en clair dans openclaw.json, plist, chat et logs CI. OpenClaw 2026 recommande de tenir le token gateway dans ~/.openclaw/.env (ou chemin visible par launchd) comme OPENCLAW_GATEWAY_TOKEN ; openclaw.json ne déclare que gateway.bind, gateway.auth.mode, gateway.reload.mode et gateway.controlUi.allowedOrigins. Les EnvironmentVariables plist pointent vers le même répertoire d'état via OPENCLAW_STATE_DIR, évitant que user CI et home login lisent deux .env différents – même bifurcation que l'article launchd token, ici pour lan.
Ne mélangez pas la clé obsolète gateway.token avec gateway.auth.token : après upgrade le schéma ignore silencieusement les anciennes clés, dashboards en boucle unauthorized. Migration : reprendre les champs structure, régénérer le token sur le Mac cloud cible dans .env – ne pas copier d'anciens clairs.
| Champ / fichier | Recommandé | Interdit | Check LaunchAgent |
|---|---|---|---|
| ~/.openclaw/.env | OPENCLAW_GATEWAY_TOKEN=<hex>, chmod 600 | Git, sync, captures | WorkingDirectory = CLI |
| openclaw.json | gateway.bind: "lan", gateway.auth.mode: "token" | clair gateway.auth.token + .env | restart après bind |
| gateway.reload.mode | hybrid pour config souple | bind par SIGHUP seul | version après restart |
| controlUi.allowedOrigins | whitelist Origin navigateur remote | * en prod | tester avec token |
| plist EnvironmentVariables | PATH, OPENCLAW_STATE_DIR ; pas token clair | profils shell conflictuels | launchctl print vs deep status |
Secret en .env, politique en openclaw.json, superviseur lit le même répertoire – une bifurcation en moins, une classe 401 en moins.
Avec plusieurs clients remote, aligner URL WS et token dans les profils – voir répartition gateway remote. bind lan n'étend que l'adresse d'écoute, ne remplace pas Bearer ni politique Origin côté client.
Six étapes : stop, .env, bind lan, LaunchAgent, healthz, auth client
Les étapes supposent un gateway launchd en loopback sur Mac cloud KVMNODE. Avant la fenêtre de changement, sauvegarder openclaw.json, label plist et sortie openclaw --version – aligné avec rollback dans persistance 24/7. Tout exécuter sur l'hôte Gateway, pas modifier la config sur le portable en espérant un nœud distant.
Arrêter anciens processus : openclaw gateway stop, lsof -i :18789 sans debug – évite EADDRINUSE.
Écrire .env : token aléatoire dans ~/.openclaw/.env, chmod 600 ; ne pas echo en logs partagés.
bind et auth.mode : openclaw config set gateway.bind lan, gateway.auth.mode token, optionnel gateway.reload.mode hybrid.
Rafraîchir LaunchAgent : openclaw gateway install --force, puis gateway restart ; plist vs which openclaw.
healthz : Authorization: Bearer sur /healthz, pas seulement curl nu 200.
Client avec token : CLI remote ou Control UI même Bearer ; mode bind et rotation dans le ticket.
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
openclaw gateway stop 2>/dev/null || true
lsof -i :18789
TOKEN=$(openssl rand -hex 32)
echo "OPENCLAW_GATEWAY_TOKEN=${TOKEN}" > ~/.openclaw/.env
chmod 600 ~/.openclaw/.env
openclaw config set gateway.bind lan
openclaw config set gateway.auth.mode token
openclaw config set gateway.reload.mode hybrid
openclaw gateway install --force
openclaw gateway restart
curl -sS -o /dev/null -w "%{http_code}\n" \
-H "Authorization: Bearer ${TOKEN}" \
http://127.0.0.1:18789/healthz
openclaw gateway status --deep
Étape six : au moins deux chemins – openclaw channels probe si configuré, plus profil remote depuis un second poste – l'hôte dans l'URL WS doit être l'intranet du Mac cloud, pas 127.0.0.1. 401 remote avec local vert : token loopback en cache ou header Authorization manquant. split brain après force : d'abord alignement CLI.
Rechargement hybrid vs gateway restart : champs qui imposent redémarrage
gateway.reload.mode=hybrid permet hot-reload pour routage channels, règles agent souples et intervalles de sonde sans couper longtemps les WS – utile en journée avec ajustements Skills fréquents. Adresse bind, port, auth.mode et champs TLS durs exigent restart superviseur complet ; SIGHUP après changement bind crée des vues split : CLI lit nouvelle config, processus écoute encore l'ancien. Le tableau va dans le runbook avec échelle diagnostic L2 Runtime running · probe failed.
| Changement | hybrid suffit ? | Action | Signal |
|---|---|---|---|
| gateway.bind / port | non | gateway restart + deep status | lsof = config |
| gateway.auth.mode | non | restart ; rotater .env si besoin | healthz Bearer 200 |
| channels / routage | souvent oui | config + hybrid ou reload | channels probe vert |
| clés upstream modèle | souvent oui | hot ou restart court | message test ≠ 401 |
| controlUi.allowedOrigins | selon version ; prod : restart | modifier array, vider cache navigateur | pas d'erreur CORS remote |
Control UI remote exige en plus des Origins explicites dans gateway.controlUi.allowedOrigins. Ouvrir depuis https://ops.example.com contre 18789 impose cet Origin en whitelist – sinon échec WebSocket ou CORS malgré Bearer valide. lan, allowedOrigins et token sont trois variables indépendantes.
Valider dérive LaunchAgent après chaque bind ou force : gateway status --deep, launchctl print pour EnvironmentVariables, openclaw doctor. Dérive non résolue plus hybrid prolonge coexistence ancien processus et nouveau fichier – sondes cron clignotent. Probes de santé cron doivent lire la même .env et utiliser IP intranet en bind=lan.
Bifurcations d'erreurs, M4 vs M4 Pro et persistance Mac cloud
refusing to bind without auth : lan sans token – tableau §2, pas réinstaller OpenClaw.EADDRINUSE : 18789 occupé, lsof avant force.unauthorized : Bearer divergent ou launchd sans .env – launchd token.probe failed, Runtime running : URL sonde, bind et Authorization non alignés – échelle L2.
Port par défaut : healthchecks utilisent souvent 18789 ; lan expose le même port en interne – pare-feu minimal.
healthz : Bearer obligatoire en prod ; 200 nu ne prouve pas l'auth.
frontière hybrid : après bind/auth toujours deep status ; hybrid seulement pour channels.
Triage : doctor → deep status → .env et plist → healthz avec token → Origin client. Portable fermé tue l'écoute lan ; NAS sans parité launchd. Mac cloud KVMNODE dédié regroupe bind, rotation token, hybrid et cron dans un runbook auditable.
| SKU | lan + multi-client + CI | Conclusion |
|---|---|---|
| Mac Mini M4 16 Go | un gateway, peu de clients remote | défaut prod ; attention xcodebuild |
| M4 Pro 24 Go+ | CI iOS + Skills + sondes lan | si jitter 18789 en semaines de pic |
| Portable fermé | lan n'aide pas pour 7×24 | expérimentation seulement |
ClawBot WeChat, multi-client remote et CI nightly sur un hôte peuvent saturer 16 Go unified memory – réponses lentes sans échec auth ; voir isolation same-pool ou M4 Pro. Pour binds non-loopback auditables avec secrets .env et validation LaunchAgent, la location Mac Mini KVMNODE convient : six régions, hôte dédié, location jour à mois. Tarifs : page tarifs, aide : centre d'aide, commande : commander.