OpenClaw Gateway loopback jeton doctor status probe Mac distant

La passerelle OpenClaw aligne trois plans : l'écoute réelle (souvent 127.0.0.1 derrière un proxy), gateway.auth et les jetons RPC. Quand l'un dérive, on mélange symptômes : HTTP vert, RPC rouge, token_missing malgré un secret GitHub cohérent, operator.read absent après des redémarrages. Ce runbook impose une séquence unique — figer la config, prouver le loopback, normaliser l'auth, calmer le pairing, puis grille doctor / status / probe. Pour HMAC et callbacks publics, voyez Intégration des webhooks passerelle OpenClaw et GitHub : signature et horodatage ; pour le mode conteneur et les recoupements doctor sur la même machine, voyez OpenClaw : CLI conteneur Docker/Podman, montages et doctor sur passerelle Mac distant.

Règle d'or : une seule vérité pour l'URL que le processus passerelle croit être « la sienne », une seule table de secrets pour les appels sortants et entrants, et un seul cycle de redémarrage contrôlé avant de réactiver le pairing automatique. Toute exception doit être nommée dans le ticket d'incident, pas seulement dans un chat d'équipe.

1. Figez la preuve loopback avant de toucher aux jetons

Relevez l'adresse d'écoute dans openclaw.json ou l'environnement launchd (127.0.0.1, ::1, tailnet). Confrontez-la aux sondes et au reverse proxy : TLS terminé en HTTP vers localhost peut cacher une passerelle qui se croit publique. Testez depuis le même UID que le démon ; si direct échoue et proxy réussit, c'est un décalage socket/schéma, pas un secret GitHub. Ne touchez pas à gateway.auth tant que ce test n'est pas vert.

2. Réaligner gateway.auth sans casser les clients existants

Listez chaque client (CLI, CI, webhook, plugin) et son en-tête réel. Fixez un mode primaire plus des exceptions explicites pour les sondes. Alignez trousseau ou coffre sur le préfixe exact attendu par le middleware — espace ou fin de ligne parasite ⇒ 401 « fantômes ». Rotation : deux secrets pendant la fenêtre, puis retrait de l'ancien.

3. Tempête de redémarrage et pairing : couper la boucle

Si le superviseur redémarre à chaque sonde ratée, le pairing se réinscrit en boucle et invalide des jetons encore chauds. Coupez l'auto-restart, imposez un ThrottleInterval macOS, un seul redémarrage manuel après correctif. Surveillez le répertoire d'état : écritures concurrentes au boot ⇒ schéma à moitié migré et operator.read absent. Courbe plate : réactivez un pairing unique de référence.

4. token_missing sur RPC auto-invoqués : cherchez l'appelant, pas le réseau

Les RPC internes n'héritent pas toujours du contexte utilisateur. S'ils frappent l'URL publique au lieu du loopback documenté, le jeton manque ⇒ token_missing malgré des traces externes propres. Routez vers l'endpoint local ou un sous-jeton de service à portée étroite ; ajoutez un identifiant de corrélation bidirectionnel.

5. operator.read en panne : permissions, version de schéma et charge

Si operator.read échoue, vérifiez droits sur le volume de données et version de schéma CLI/démon. Sous charge — Mac haute RAM saturé par une longue inférence d'agent plus la passerelle — les verrous d'état expirent et imitent une panne d'auth. Réservez de la RAM à la passerelle, limitez les workers lourds, surveillez la pression mémoire unifiée.

6. Grille d'acceptation croisée doctor, status, probe

doctor : chemins, versions, secrets masqués. status : pairing, RPC, plugins. probe : trafic réel, TLS, en-têtes. Une ligne ne passe au vert que si les deux autres tiennent. Archivez les trois sorties dans le même ticket face au dernier lot vert.

  • doctor sans avertissement critique sur auth, chemins ou versions mixtes.
  • status : pairing stable, pas de compteur de redémarrage qui grimpe seul.
  • probe : codes HTTP et latences dans les seuils définis sur loopback et sur le chemin proxy.

En production, exécutez la grille dans l'ordre doctor puis status puis probe : un échec précoce évite d'attribuer à TLS ce qui n'est qu'un fichier de config mal relu. Journalisez l'horodatage et la révision Git du binaire pour corréler aux incidents « fantômes » nocturnes.

7. Scénario reproductible : agent long sur Mac haute RAM

Baseline verte seule ; puis charge agent (gros contexte, plugins) sans plafond. Mesurez latence sondes et timeouts operator.read / token_missing quand la mémoire serre. Revenez au vert en réintroduisant réseau, auth, pairing une variable à la fois pour distinguer bug et saturation.

Pourquoi un socle type Mac mini stabilise cette grille de diagnostic

Les passerelles gagnent avec une mémoire unifiée prévisible, un NVMe rapide et la pile réseau macOS. Le Mac mini ajoute faible consommation au repos, silence, launchd, Gatekeeper, SIP et FileVault — moins d'improvisation qu'un PC générique. Cohabitation passerelle + agents : la bande passante RAM compte ; le Mac mini M4 ancre loopback, jetons et sondes sans cycles de reboot inutiles.

Pour provisionner un hôte distant aligné sur ce runbook, ouvrez la page d'accueil Macstripe et choisissez région et RAM ; le Mac mini M4 reste un socle rentable avant votre prochaine fenêtre de pairing.