Sommaire
Pourquoi le loopback trompe sur un maillage
- Deux vérités pour un même port. Un opérateur tape
curl http://127.0.0.1:18789sur la console du Mac tandis que le démon n’écoute que sur10.x: le poste semble sain, la CI ou le bastion voit encore une erreur réseau. - SSH ne corrige pas les en-têtes. Un tunnel
-Lcorrect peut afficher une page ou un JSON d’erreur401si le jeton Bearer lu depuis un profil shell diffère du fichier sous/etc/openclaw/secrets.d. - Doctor en silos. Un
doctorvert sur un hôte masque une dérive de bind, de plist ou de version ; sans fusion JSON, l’équipe élargit les ACL au mauvais moment.
Cadrez le rythme de déploiement pour que chaque Mac du pool répète la même séquence (versions, labels LaunchDaemon, chemins secrets) avant d’ouvrir des tunnels ou des routes est-ouest ; évitez les promotions « à chaud » sans artefact JSON archivé.
Matrice d’exposition (résumé)
| Approche | Quand elle convient | Coût opérationnel |
|---|---|---|
| Loopback + LocalForward | Humains et scripts passent toujours par un bastion SSH maîtrisé | Tenir à jour les blocs Host et les cibles -L ; tunnels vivants |
| IP privée maillage + pare-feu | Automatisation est-ouest entre nœuds MeshMac sans Internet public | Règles pf ou ACL synchronisées par classe de machine |
| Écoute large + mTLS bordure | Un ingress central termine déjà les certificats clients | Audit lourd ; coupler validate JSON et rotation de jetons |
Parcours public : install, onboard, doctor
Alignez chaque hôte sur la doc officielle : Getting Started décrit l’installation rapide (curl … install.sh ou méthodes alternatives vers la page Install), la commande openclaw onboard --install-daemon et la vérification openclaw gateway status avec l’écoute sur le port 18789. Le détail du wizard CLI se trouve sous Onboarding (CLI). Pour les contrôles santé et non interactifs en CI, suivez CLI doctor (openclaw doctor, openclaw gateway doctor --json, options --non-interactive ; réservez --repair aux fenêtres approuvées).
Renforcez la posture réseau et fichier avec le guide passerelle fail-closed, validate JSON et anti-dérive : mêmes preuves machine avant et après changement d’adresse d’écoute.
Étapes minimales reproductibles
1. Ligne de base par Mac. Après install et onboard, joignez au ticket openclaw --version, la ligne Node recommandée par la doc, et une capture openclaw gateway doctor --json.
2. Écoute et secret. Si vous ouvrez l’est-ouest sans tunnel, liez l’IPv4 privée du maillage et filtrez au pare-feu. Placez OPENCLAW_GATEWAY_AUTH_TOKEN sous /etc/openclaw/secrets.d/gateway/ en 0440, groupe service ; évitez les jetons bruts dans les profils partagés .zshrc.
3. Validate sur le serveur. openclaw gateway validate --strict --json | tee "gw-validate-${MESH_NODE_ID}.json" — vérifiez ok, mesh_node_id et policy_revision comme avant tout durcissement proxy.
4. SSH LocalForward. Passerelle encore sur loopback sur le Mac : ssh -N -L 18789:127.0.0.1:18789 user@gw. Écoute uniquement sur IP maillée : -L 18789:10.0.0.12:18789. Ajoutez ServerAliveInterval dans ~/.ssh/config. Pour la passation affichage + shell, croisez la checklist Partage d’écran et SSH.
ssh -N -o ServerAliveInterval=30 \
-L 18789:127.0.0.1:18789 meshuser@gateway-a.meshmac.internal5. Preuve Bearer. Depuis le poste où le tunnel est actif, lisez le jeton comme le démon (par ex. via sudo cat …/auth_token sur l’hôte cible), puis appelez la route /health ou équivalent documenté.
TOKEN=$(ssh meshuser@gateway-a 'sudo cat /etc/openclaw/secrets.d/gateway/auth_token')
curl -fsS -H "Authorization: Bearer ${TOKEN}" http://127.0.0.1:18789/health6. Fusion doctor. Relancez openclaw gateway doctor --json sur chaque passerelle, normalisez avec jq -S, concaténez et différenciez binds et descripteurs de secrets — même discipline que le runbook journaux et Webhooks multi-nœuds pour une synthèse incident unique.
Tableau de dépannage : port 18789, jeton, service arrêté
| Focus | Contrôle rapide | Piste de correction |
|---|---|---|
| Port 18789 | lsof -nP -iTCP:18789 -sTCP:LISTEN sur le Mac ; comparez avec la partie droite du -L SSH |
Alignez l’adresse d’écoute YAML avec la cible du forward ; évitez de forwarder vers 127.0.0.1 si le démon n’écoute que sur 10.x |
| Jeton d’auth | curl -v montre 401 ; comparez launchctl getenv OPENCLAW_GATEWAY_AUTH_TOKEN au fichier secret |
Supprimez les exports dupliqués dans les profils ; rechargez le plist après rotation ; faites lire à l’automation le même chemin que le LaunchDaemon |
| Service non exécuté | launchctl print system/com.openclaw.gateway (ou votre label) ; dernières lignes de crash dans le journal unifié |
Corrigez d’abord les erreurs validate, restaurez un cliché YAML sain, puis réinstallez selon la doc ; enchaînez doctor jusqu’à des auditeurs sains dans le JSON |
Rappels portables
- Port : les exemples courants utilisent
18789; toute dérogation doit figurer dans l’inventaire et dans les blocsHostSSH. - Jetons : préférez une rotation documentée au partage prolongé de chaînes Bearer sur portables.
- Preuves : archivez les tableaux
doctorfusionnés à côté de l’identifiant d’incident pour des post-mortems rejouables.
Synthèse
Alignez install, onboard et doctor sur docs.openclaw.ai, figez l’écoute hors loopback derrière pare-feu réel, exécutez validate JSON avant les tunnels, utilisez SSH LocalForward vers 18789, validez les en-têtes Bearer, puis fusionnez doctor sur l’ensemble des passerelles MeshMac. Pages publiques sans compte : forfaits, tarifs, aide ; voir aussi le hub articles OpenClaw.
Quand les tunnels ne suffisent plus à l’échelle
Le LocalForward convient à une poignée d’ingénieurs ; il ne remplace pas la capacité mutualisée et homogène d’un pool. Comparez les forfaits Meshmac et les tarifs (consultation sans connexion), ouvrez le centre d’aide pour les schémas d’onboarding, l’accueil pour les classes matérielles, puis revenez au hub OpenClaw après ajout de nœuds afin que chaque passerelle répète la même séquence install → onboard → doctor.