2026 OpenClaw macOS natif : application officielle + CLI, OPENCLAW_STATE_DIR, TCC, LaunchAgent & double passerelle — runbook

Pourquoi une liste « macOS natif » à part, plutôt que tout reporter vers Docker ou la vue trois OS

1. La synchro modifie en silence la sémantique temporelle du répertoire d’état. Lorsque « Bureau et Documents » est synchronisé via iCloud ou que les projets vivent sur un volume cloud mappé, un OPENCLAW_STATE_DIR placé sous cet arbre produit des courses au lieu d’un comportement stable observé dans un conteneur Linux.
2. Le TCC s’attache à l’identité du binaire. Le openclaw lancé dans le Terminal et l’assistant du bundle officiel ne sont pas la même entité pour macOS ; après changement de chemin ou upgrade, les anciennes autorisations ne se réinjectent pas. Les symptômes côté skills ressemblent souvent à un blocage silencieux, pas à un HTTP 403.
3. Accessibilité et automatisation sont deux axes distincts. Beaucoup d’équipes n’activent que l’accessibilité et oublient AppleScript / OSA qui exigent l’automatisation (AppleEvents), ce qui oriente le troubleshooting dans la mauvaise direction.
4. L’enregistrement d’écran n’est pas l’accessibilité. Sans entrée « capture d’écran », les pipelines pixels attendent la première frame indéfiniment ; dans les journaux cela ressemble à un modèle lent alors que c’est une porte TCC.
5. launchd et démarrage interactif créent deux processus parents. S’ils écrivent le même état ou écoutent le même port, le motif typique est « healthcheck vert puis rouge » — en réalité plusieurs instances.
6. Autorité locale vs distante est un choix d’exploitation. Faire du portable le point d’entrée autoritaire accepte sommeil, Wi‑Fi de salle de réunion et split VPN comme sources aléatoires ; un Mac loué, sur secteur, trace une autre courbe de disponibilité.

L’installation multi-plateforme, les canaux de version et le déploiement restent dans le guide Windows / macOS / Linux ; la validation post-install, WSL2 voisin et le flux doctor dans l’article doctor & Gateway. Si votre cible est images et orchestration, le runbook Docker production reste le document maître — ce texte colmate le métal nu. Lisez en parallèle le guide coûts de location multi-régions pour ne pas corriger uniquement le logiciel sans la géographie.

Lors des revues, séparez problème de configuration et capacité plateforme : le premier doit se résumer à une ligne grâce au tableau symptômes ci-dessous en moins de 15 minutes ; le second mérite demande de fonctionnalité ou upgrade. Avant d’écrire « non reproductible », vérifiez : l’état est-il sur APFS local ? Les captures TCC sont-elles à jour pour cette version ? Le label LaunchAgent est-il unique ? Ces trois questions éliminent beaucoup de pseudo-mystique.

OPENCLAW_STATE_DIR : un numéro d’actif, pas « un dossier au hasard dans Home »

Déclarez la variable dans le profil shell approuvé ou le dictionnaire EnvironmentVariables du LaunchAgent et référencez dans votre CMDB « chemin → système métier → responsable ». Exemples : /usr/local/var/openclaw, /opt/openclaw/state ou une arborescence /Users/Shared/… non synchronisée ; l’essentiel est que le point de montage vu dans df -h ne soit pas intercepté par un agent de synchro cloud.

Si vous restez sous l’arbre utilisateur, évitez Mobile Documents, les placeholders de disques réseau et les redirections « Documents » imposées par MDM. Quand « collègue A OK, collègue B KO », la première action n’est pas une réinstallation mais la comparaison des OPENCLAW_STATE_DIR, nœuds de périphérique et charge inode.

Plusieurs comptes sur une même machine d’essai ne doivent pas partager informellement un même dossier d’état : verrous SQLite, cycle de vie des .sock et rotation des jetons explosent. Soit répertoires et identités de service séparés, soit architecture cluster documentée.

Table de tri des symptômes (les 15 premières minutes quand le téléphone sonne)

Chaque ligne doit avoir une responsabilité principale unique (client / plateforme macOS / service passerelle / réseau externe) pour éviter que cinq personnes éditent la même plist en SSH.

TCC : inclure Réglages Système dans la chaîne de release

L’accessibilité couvre le contrôle d’autres apps « comme un utilisateur assisté » ; l’automatisation (AppleEvents) autorise les scripts à envoyer des événements ; l’enregistrement d’écran ouvre le canal pixels. Sans l’un de ces trois pans, les skills semblent « attendre toujours » plutôt que lever une erreur explicite. Pour la voix, traitez le microphone comme un interrupteur explicite — ne réutilisez pas les hypothèses d’un conteneur Linux.

Après un upgrade majeur de macOS ou d’OpenClaw, planifiez 10 minutes de revue confidentialité : responsable + checklist + captures jointes au ticket de changement. Les déclarations orales sans capture ne tiennent pas en astreinte multi-fuseaux.

Dans les secteurs réglementés, ces captures alimentent l’audit « moindre privilège » : quel binaire, quand, avec quel ticket — au-delà d’une simple phrase de politique.

LaunchAgent et openclaw gateway start manuel : une seule « vérité officielle »

Le LaunchAgent vaut pour l’absence d’humain : reboot, redémarrage watchdog, courts trous réseau. Idéal sur Mac loués alimentés secteur à côté d’un runner CI ou d’un sidecar modèle. Le démarrage manuel reste le poste dev : quelqu’un regarde le terminal et sait qu’il dépanne, pas qu’il exploite.

Pour déboguer, commencez par launchctl print gui/$(id -u) pour voir labels et derniers codes de sortie. Si vous devez lancer à la main, déchargez ou commentez proprement le LaunchAgent afin que les logs correspondent au PID sous vos yeux.

Maintenez deux blocs de commandes « mode dev » et « mode salle » dans la doc d’équipe et demandez dans le gabarit de PR sous quel mode la validation a été faite — sinon le piège « vert en local, rouge en prod » revient.

Passerelle locale vs distante : découpage des domaines de panne, pas du marketing

Locale attache la commande à la machine de l’humain : itération rapide, chemins de dialogue courts, mais hérite sommeil, VPN, bascule hotspot et apps de visioconférence qui monopolisent l’audio. Distante ancre sessions autoritaires et connexions longues sur hôte et sortie réseau fixes — bon choix pour entrée organisationnelle ou exécution 7×24.

La CLI peut rester identique ; ce qui change, c’est quel disque détient l’état principal, quelle interface porte la route par défaut et quel rack minimise la RTT vers ASC / grappe modèle. Consignez la carte dans le catalogue de services pour que la revue sécurité ne confonde pas « bac à sable portable » et « autorité au rack Singapour ».

Si les deux modes coexistent, utilisez des préfixes de nom d’hôte distincts en supervision pour ne pas fusionner deux séries Grafana dans une alerte « latence passerelle » trompeuse.

Sept étapes : de l’installation paquet aux preuves archivables

1. Canal et pin de version : même semver que la CI ; si vous choisissez app officielle ou CLI, documentez le chemin par défaut pour éviter la scission d’identité binaire.
2. Répertoire et droits : créer OPENCLAW_STATE_DIR, journaux, cache optionnel ; propriétaire = utilisateur d’exécution, pas un mélange root informel.
3. TCC en une passe : accessibilité, automatisation, enregistrement d’écran (micro si besoin) selon la liste des skills ; captures avant/après.
4. Déclarer la topologie : cette machine est-elle autoritaire ou simple client ? Adresse de liaison et politique de ports alignées sur les groupes de sécurité.
5. Choisir l’orchestration : LaunchAgent (salle) ou uniquement manuel (dev) — pas de zone grise prolongée.
6. Fumée canal minimal : plus petite surface d’intégration autorisée ; vérifier via liste de processus qu’un seul parent écoute.
7. Geler les preuves : joindre les sorties openclaw doctor et openclaw gateway status au changement avant bascule du trafic prod.

Pour recouper des symptômes multiplateformes, réutiliser l’article doctor / Gateway ; pour images et jeton single-source, privilégier le runbook Docker production afin de ne pas journaliser un problème cgroup comme un problème TCC.

#!/usr/bin/env bash
set -euo pipefail
# Sondage principalement en lecture seule — adapter les chemins au standard interne
export OPENCLAW_STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/Library/Application Support/OpenClawState-local}"
umask 077
mkdir -p "$OPENCLAW_STATE_DIR"
echo "OPENCLAW_STATE_DIR=$OPENCLAW_STATE_DIR"
command -v openclaw >/dev/null && openclaw doctor || echo "doctor: CLI hors PATH"
openclaw gateway status 2>/dev/null || echo "gateway: pas de réponse (normal si non démarré)"
launchctl print "gui/$(id -u)" 2>/dev/null | grep -i openclaw || echo "launchd: aucune étiquette openclaw (mode manuel pur possible)"

Trois indicateurs durs pour tableau de bord ou revue de changement

• Secondes entre démarrage à froid et premier gateway status sain : en régression, inspecter d’abord l’ordre des dépendances plist et les dialogues TCC bloqués, pas le runtime langage.
• Preuve df que OPENCLAW_STATE_DIR vit sur APFS local : stub FUSE ou synchro = non conforme.
• Nombre de processus parents en régime établi : plus d’un parent en continu déclenche une escalade ; les chevauchements courts (fenêtre de mise à niveau) doivent être horodatés dans le ticket.

Pas de ligne d’analyse cause racine sans sortie brute des commandes — sinon la prochaine astreinte réécoute la même histoire.

Pourquoi « bricoler un portable 7×24 » perd souvent contre un Mac cloud stable

Les portables sont optimisés mobilité : couvercle fermé = sommeil, profils énergie limitent la charge, les VPN d’entreprise détournent le trafic temps réel. Placer l’autorité là revient à lier votre SLA d’automatisation aux agendas et Wi‑Fi de réunion.

MACCOME Cloud Mac mini (M4 / M4 Pro) propose du Silicon Apple dédié, alimentation fixe et topologie disque prévisible ; LaunchAgent, jetons longue durée et sondes peuvent partager la même machine pendant que les portables restent clients légers. Croisez RTT et durées de bail avec le guide coûts & latence multi-régions pour éviter « la passerelle suit la personne ».

Synthèse : tickets macOS natifs ≠ tickets Docker

TCC, chemins synchronisés et launchd restent dans ce runbook ; cgroup, digest d’image et pont réseau dans le document Compose. Si un incident touche les deux mondes, scindez la chronologie en deux RCA parallèles — sinon il ne reste que le renvoi de balle.

Avant de clôturer la fenêtre de changement, relancez openclaw doctor et archivez la sortie avec le numéro de version ; si l’autorité doit être distante, écrivez explicitement que la validation n’a pas eu lieu en mode autorité portable — sinon un collègue réutilisera la mauvaise configuration.