127.0.0.1 — agents CI, pair VPN ou reverse proxy TLS. Objectif : ordre d'exécution reproductible avec Node 22 ou plus récent, script d'installation officiel ou npm install -g, variable OPENCLAW_GATEWAY_TOKEN injectée comme un SecretRef, puis openclaw doctor et openclaw config validate alignés sur la documentation amont. Enchaînements utiles : porte validate en CI, embarquement non interactif et journaux fusionnés, durcissement passerelle sur Mac distant.
Pourquoi l'écoute strictement locale complique l'automatisation sur Mac hébergé
Restreindre l'écoute à la boucle locale rassure en développement ; sur Mac partagé les appelants réels n'empruntent pas le même socket que votre shell interactif, et les journaux CI doivent prouver la présence du jeton dans le contexte du démon.
- PATH.
nvmou Brew dans le job, PATH minimal danslaunchd: le jeton exporté au clavier n'atteint pas le démon. - Surface. IP LAN sans doc sécurité amont : jeton vide ⇒ refus de démarrage voulu.
- Proxy. Mêmes sorties que npm ou PyPI : passerelle morte ⇒ webhooks et pré-tirages bloqués.
Matrice décisionnelle : périmètre d'écoute et profondeur d'authentification
| Modèle d'écoute | Usage typique | Jeton et réseau |
|---|---|---|
127.0.0.1 uniquement |
Boucles doctor et reverse proxy sur le même Mac |
Jeton si la doc impose Authorization vers la passerelle. |
| Interface tailnet ou VPN | Runners CI sur le même réseau overlay sans Internet public | Pare-feu, liste blanche, rotation si le tailnet change. |
| IP LAN non loopback | Webhooks depuis sous-réseaux de build adjacents | Jeton obligatoire, TLS en frontal si possible ; citez la doc officielle pour votre semver. |
Étapes minimales reproductibles (HowTo)
Étape 1 — Runtime. Node 22.14 LTS ou 24 ; première ligne du job : node -v.
Étape 2 — CLI. Suivez le script d'installation officiel documenté en amont (souvent un flux curl) ou npm install -g "openclaw@^…" avec plage semver validée par la sécurité. Journalisez command -v openclaw et openclaw --version juste après l'installation. Si Homebrew manque sur image vierge, capturez --verbose une fois puis figez Brew sur l'AMI ; détail dans embarquement non interactif.
node -v npm install -g "openclaw@^2026.3.0" command -v openclaw openclaw --version
Étape 3 — Dossiers. OPENCLAW_HOME et OPENCLAW_CONFIG_HOME uniques par job ou démon ; chmod 700.
Étape 4 — SecretRef. Reproduisez la sémantique d'un SecretRef Kubernetes : variables chiffrées dans GitHub Actions, GitLab ou Azure DevOps, ou bloc EnvironmentVariables du plist launchd pour un service persistant. Le nom stable OPENCLAW_GATEWAY_TOKEN relie le job CI au démon ; n'écrivez jamais la valeur en clair dans une PR ou un résumé de pipeline.
Étape 5 — Bind. Hors loopback seulement après sections passerelle, TLS et exposition de la doc officielle pour votre semver ; TLS en frontal ⇒ passerelle en 127.0.0.1 possible. Plist : unload puis load.
Étape 6 — Validate. openclaw doctor puis openclaw config validate ; voir porte validate CI.
export OPENCLAW_GATEWAY_TOKEN="$(cat "$RUNNER_TEMP/gw.token")"
openclaw doctor
openclaw config validate --config "$OPENCLAW_CONFIG_HOME/openclaw.json"
curl -fsS -o /dev/null -w "%{http_code}" \
-H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
"http://127.0.0.1:18789/v1/health"
Refus de démarrage sans authentification : indices de journal et lecture doc
Les combinaisons dangereuses sont refusées volontairement : traitez les messages stderr comme des garde-fous. Ouvrez la documentation officielle de la même semver que votre binaire : l'intitulé exact des erreurs peut varier entre versions mineures.
| Symptôme ou extrait | Cause probable | Action alignée sur la doc officielle |
|---|---|---|
Processus qui quitte juste après élargissement hors 127.0.0.1 |
OPENCLAW_GATEWAY_TOKEN vide alors qu'une exposition non loopback est active |
Secret depuis coffre, reload service, section security. |
| HTTP 401 sur routes outil ou santé depuis CI | En-tête Authorization: Bearer absent, mal orthographié ou jeton tronqué |
Schéma Authorization doc ; regénérez si copie tronquée. |
doctor OK en shell, refus côté démon |
Plist launchd sans la nouvelle variable |
Diff EnvironmentVariables, unload/load une fois. |
config validate signale des chemins JSON invalides |
Dérive d'un fichier édité à la main | Validate avant fusion ; archives contrôlées. |
Pare-feu : durcissement passerelle ; recoupez avec les release notes.
Liste de contrôle avant bascule en production
Imprimez ou collez cette liste dans le modèle de changement réseau ; chaque case doit être cochée par la personne qui détient le secret, pas par un bot anonyme.
- Node 22.14+ ou 24 tracé dans le journal de porte.
- Chemin
openclawidentique entre shell de debug etProgramArgumentsdu démon. OPENCLAW_GATEWAY_TOKENprésent dans le contexte d'écoute, absent des artefacts publics.- Pare-feu : uniquement les sous-réseaux documentés autorisés vers le port passerelle.
- Sorties
doctoretvalidatevertes dans un seul fichier versionné. curlsanté : code 200 avec jeton, 401 sans en-tête attendu.
Intérêt pour la CI et les pulls derrière proxy sur le même Mac
Colocaliser la passerelle sur le même Mac distant que les jobs qui exécutent npm ci, pip derrière miroir ou pré-tirages d'images réutilise la résolution DNS, le cache TLS et la politique de sortie déjà accordée pour les artefacts. Les webhooks vers OpenClaw et les étapes de dépendances voient une latence cohérente au lieu d'un saut inter-région vers une VM générique. Une sonde curl sur la santé avec en-tête Bearer valide échoue tôt lorsque le jeton ou le bind est incorrect, ce qui évite d'empiler des dizaines de minutes de timeouts sur le proxy de registre.
Synthèse et prochain pas commercial
Rappel : Node 22+, installateur ou npm -g, OPENCLAW_GATEWAY_TOKEN, bind hors loopback selon doc, doctor, validate. Pour un Apple Silicon stable : tarifs, achat, aide, Console, blog (pages publiques).
Mac distant pour passerelle OpenClaw jeton et pulls CI
Apple Silicon avec réseau prévisible pour passerelle, miroirs de registres et webhooks ; liens uniquement vers pages publiques MacPull.