L'assistant attend un processus Gateway joignable dans l'environnement réel de launchd, pas le succès apparent de install.sh dans votre terminal. Sur Mac cloud, ces deux mondes divergent presque systématiquement. La racine la plus fréquente : le CLI n'est pas dans le PATH de launchd — which openclaw pointe vers Homebrew en SSH, tandis que ProgramArguments référencent un autre préfixe ou un chemin relatif. L'assistant interroge la santé ; launchd ne relance rien de stable — Retry sans message actionnable.

Deuxième racine : l'agent est déjà en failed, l'UI n'affiche que « not ready ». Consultez launchctl list avant de cliquer Retry en boucle. Troisième racine : 18789 (ou votre port configuré) est occupé ou lié à localhost alors que la sonde part d'ailleurs — classique quand un gateway start manuel coexiste avec la plist, comme dans le guide double piste Node 22. Quatrième racine : EnvironmentVariables manquantes (jeton, OPENCLAW_*, WorkingDirectory), alignée sur token_missing.

Figez quatre lignes dans le ticket de changement : chemin absolu openclaw, label LaunchAgent, port d'écoute, code de sortie doctor. Chaque Retry sans ces lignes n'est pas reproductible — surtout quand plusieurs personnes mélangent Screen Sharing et SSH. Pour les journaux contenant des métadonnées personnelles, limitez la rétention et documentez finalité et accès conformément à vos obligations de protection des données.

Les tickets 2026.3.x confondent souvent « install.sh OK » avec la readiness Gateway. Séparez explicitement succès d'installation et succès de readiness. L'assistant interroge un endpoint health avec timeout court ; un Gateway stable après 45 secondes ressemble à une boucle Retry alors que launchd démarre encore. Mesurez avec un appel health unique et une fenêtre de 60 secondes avant de changer de région ou de palier.

Si l'équipe mélange l'app macOS et le CLI global, documentez qui possède le port 18789 : attache ou nouveau daemon — jamais les deux. Les écarts de version entre bundle et npm i -g openclaw produisent des installs verts et un assistant rouge. Alignez via alignement CLI avant un nouveau Retry. Sur hôte partagé, chaque session SSH reste suspecte tant que PATH login et non-login n'est pas identique.

Le workflow créatif sur Mac cloud reste pertinent : même quand l'assistant bloque, vos assets Xcode ou design ne doivent pas saturer le disque root — rotez /tmp/openclaw comme les logs de build. Apple Silicon unifié aide quand health et previews partagent la mémoire ; un M4 Pro devient logique si la pression mémoire se répète pendant l'acceptation.

Sur un Mac mini dédié, launchd ne charge pas le profil interactif comme votre shell : « ça marche dans le terminal » ne prouve pas la readiness pour l'assistant. Comparez ProgramArguments au binaire réellement exécuté par launchctl kickstart. Un écart de version Node entre install.sh et redémarrage nocturne reproduit le même symptôme — figez node -v et le préfixe npm global dans le ticket.

Quand plusieurs ingénieurs partagent SSH, imposez une règle : pas de Retry GUI pendant qu'une plist est ouverte. Exportez la sortie doctor en texte pour les parties prenantes qui exigent des captures — les screenshots omettent presque toujours le code de sortie launchd.

L'assistant graphique n'est pas obligatoire. Si vous opérez uniquement en SSH et tunnellez le tableau de bord, openclaw onboard --install-daemon puis doctor est souvent plus rapide et auditable — voir SSH sans tête. Gardez l'assistant quand des autorisations macOS, le trousseau ou un collègue non technique passent par Screen Sharing et que vous avez besoin d'une preuve visuelle d'acceptation.

Avant l'assistant, les shells login et non-login doivent voir le même Node et le même openclaw que la plist. Sur hôtes sans session GUI, Homebrew uniquement dans .zprofile laisse launchd avec /usr/bin:/bin. Validez avec openclaw gateway call health. Planifiez ensuite sondes channels une fois la readiness stabilisée.

Le parcours headless convient aux runbooks auditables : chaque étape laisse du texte attachable au ticket. L'assistant graphique convient au premier pairing Keychain. Ne mélangez pas les modèles de ticket « Retry assistant » et « install greenfield ». Après onboard --install-daemon, vérifiez que WorkingDirectory pointe vers ~/.openclaw, pas un chemin laptop obsolète. Avant de traiter l'assistant comme install neuve, lisez sauvegarde workspace si vous migrez.

Chaque étape produit un artefact pour le ticket. Le bouton Retry ne remplace pas la triage.

which openclaw
openclaw --version
openclaw gateway status
openclaw doctor
launchctl list | grep -i openclaw
lsof -nP -iTCP:18789 -sTCP:LISTEN
openclaw gateway call health --url ws://127.0.0.1:18789 --timeout 5000

Rouvrez l'assistant seulement après l'étape 06 verte. Si l'étape 04 est rouge, ne relancez pas onboard --install-daemon à l'aveugle — retirez l'ancien label. La échelle de diagnostic classe les symptômes L1/L2 si plusieurs apparaissent ensemble.

Approfondissez l'étape 04 : journaux launchd autour du label et fichiers récents sous /tmp/openclaw. Cherchez « address already in use », ENOENT sur openclaw, erreurs de modules Node après upgrade. Si health échoue alors que lsof montre un listener, comparez bind 127.0.0.1 et 0.0.0.0 avec l'URL de l'assistant. Erreur cloud classique : Gateway manuel sur 18789 et agent configuré sur 18999 — les deux « tournent », readiness reste rouge.

L'étape 07 doit être un message métier ou une sonde channel, pas seulement un dashboard vert. Joignez un JSON d'une ligne de gateway status et l'heure de la première réponse OK. Répétez 03 et 06 quotidiennement en semaine d'acceptation. Pour auth distante après readiness locale, voir upgrade remote auth.

Sur Mac cloud KVMNODE, SSH fixe les changements, launchd fixe l'exécution. Screen Sharing montre l'assistant sans corriger automatiquement la plist. Notez si l'acceptation est VNC ou CLI — les post-mortems confondent les deux. Les fuseaux des six régions (SG, JP, KR, HK, US East, US West) impactent cron et rotation, pas la syntaxe Gateway ; séparez /tmp/openclaw et journaux persistants pour éviter un disque root plein en semaine d'acceptation.

Sans TTY, certaines étapes de l'assistant échouent silencieusement — basculez sur l'acceptation CLI. Plusieurs SSH sans gel à quatre lignes produisent le « ça marchait hier ». Gardez l'état hors dossiers de sync d'équipe, comme dans la ligne de base persistance. Alertez sur changement d'état Gateway plutôt que sur chaque poll de l'assistant.

Screen Sharing affiche l'assistant sans corriger la plist. Convenez qui édite en SSH et qui clique en GUI — un Retry pendant l'édition plist écrase l'état. Les crons health doivent utiliser le fuseau du nœud cloud, pas celui du laptop de l'opérateur. Si CI iOS ou runners partagent l'hôte, notez les pools de labels : un job nocturne peut binder 18789 et provoquer un Retry matinal sans lien apparent dans le ticket. Voir isolation same-pool.

Pour un premier passage assistant sans xcodebuild parallèle, un M4 proche en 16 Go suffit souvent si Git et artefacts sont continentaux et le workspace reste sous votre seuil. Choisissez M4 Pro à mémoire unifiée élevée si la même semaine d'acceptation mélange CI iOS, gros dépôts skills et Gateway sous pression mémoire, ou si le port 18789 entre en collision avec des runners.

Un Mac portable en veille est une mauvaise référence pour « l'assistant a marché chez moi » — les Mac cloud dédiés offrent des fenêtres launchd stables. Pour une readiness Gateway auditable, la location Mac mini KVMNODE reste le choix habituel : six régions, Apple Silicon, même langage PATH/plist que ce runbook. Tarifs sur page tarifs, guides au centre d'aide, commande via commander.

Les régions proches (SG, JP, KR, HK) réduisent souvent la RTT SSH sans changer les règles launchd. US East et US West conviennent si Git et artefacts sont déjà en Amérique du Nord. Comparez trois métriques en acceptation : redémarrages LaunchAgent, P95 latence health, croissance des logs. Préparez un tarball de ~/.openclaw avant un changement de région — l'assistant ne migre pas la mémoire seul.

Séparez en interne le modèle « Retry assistant » de « install greenfield ». Les tickets Retry exigent les quatre lignes de preuve et le JSON health ; le greenfield peut démarrer workspace vide. Ne les fusionnez pas dans le wiki — sinon les revues acceptent un agent vide par défaut et la mémoire curatée disparaît après le premier run cloud.