2026 — OpenClaw sur Mac physique distant : MCP en stdio et Streamable HTTP — tutoriel reproductible (spawn ENOENT, incompatibilité de version, timeouts d'outils + CLI + FAQ)

2. stdio vs Streamable HTTP : quel transport choisir ?

Choisissez le transport qui minimise les pièces mobiles sur l'hôte, puis passez à HTTP lorsqu'il faut partager un serveur ou terminer l'authentification au proxy.

3. Déploiement reproductible en sept étapes

1. Capturer l'identité — Noter l'utilisateur propriétaire d'OpenClaw, l'étiquette LaunchAgent/plist et le cwd issu de launchctl print ou de l'unité de service.
2. Rejouer stdio sans passerelle — En tant que cet utilisateur, exécuter /bin/bash -lc 'which node; node -v' puis la commande MCP exacte avec parité de fichier d'environnement.
3. Durcir la config stdio — Chemins absolus pour command, tableau args explicite, cwd optionnel et bloc env (voir JSON ci-dessous).
4. Voie HTTP optionnelle — Lier MCP HTTP sur 127.0.0.1, terminer TLS sur nginx/Caddy, vérifier avec curl -v que la négociation Accept est correcte.
5. Verrouillage de version — Épingler le SDK / paquet serveur MCP sur le même major.minor que la bibliothèque client dans OpenClaw ; consigner les deux dans le changelog.
6. Budget de timeouts — Mesurer le P95 de tools/call avec des entrées réalistes ; fixer l'attente client ≥ P95 × 1,5 avec un plafond dur.
7. Contrat de logs — Émettre une ligne JSON par initialize, tools/list et tools/call avec un identifiant de corrélation partagé.

Pour des flux d'agents 7j/7 qui survivent aux redémarrages, alignez ce runbook sur vos playbooks launchd existants (labels plist, parité PATH, redémarrage contrôlé) avant d'ajouter des serveurs MCP.

4. Fragments de configuration CLI (JSON illustratif)

Adaptez les clés au schéma OpenClaw ou hôte ; l'essentiel est d'utiliser des chemins absolus et des blocs d'environnement explicites.

{
  "mcpServers": {
    "repo-tools": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/usr/local/lib/mcp-servers/repo-tools/dist/main.js"],
      "cwd": "/Users/shared/mcp/repo-tools",
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/bin:/bin",
        "NODE_ENV": "production"
      }
    }
  }
}

{
  "mcpServers": {
    "legacy-npx": {
      "command": "/bin/bash",
      "args": ["-lc", "exec npx --yes @example/[email protected]"],
      "env": { "HOME": "/Users/shared" }
    }
  }
}

{
  "mcpServers": {
    "http-shared": {
      "url": "https://mcp.internal.example.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_EDGE_TOKEN}"
      }
    }
  }
}

5. Runbooks symptômes

5.1 spawn ENOENT (stdio)

5.2 Version de protocole / 406 (Streamable HTTP)

Comparez côte à côte les journaux de handshake client et serveur. Si le serveur attend text/event-stream mais que le proxy injecte gzip sans flush, les clients restent bloqués sur « incompatibilité de version » alors que les numéros de version semblent alignés.

5.3 Timeouts d'outils

Tracez trois minuteurs : (A) attente routeur/modèle, (B) deadline amont passerelle, (C) timeout de job interne au serveur MCP. Ajustez d'abord la couche la plus serrée, puis élargissez les adjacentes seulement si les traces prouvent une file d'attente.

Les opérations longues sur dépôts ou caches (comme les grosses synchronisations de dérivés) relèvent de la même discipline de timeouts que la 2026 — Gouvernance mondiale des caches de build iOS : Derived Data Xcode et dépendances — autorité monorégion ou nœuds Mac physiques régionaux ? (matrices + paramètres + FAQ) : évitez un seul appel bloquant quand un job asynchrone avec sondes convient mieux.

6. Chiffres à coller dans les docs SLO

• ~4 W — Consommation au repos d'un Mac mini Apple Silicon avec SSH et passerelles légères — utile pour le TCO face aux tours x86 beaucoup plus gourmandes au ralenti.
• 25 s — Plafond indicatif pour un P95 « rapide » de tools/call sur nœuds partagés ; au-delà, découpez les outils ou diffusez des résultats partiels plutôt que d'augmenter les timeouts sans fin.
• 600 s — Les outils de maintenance lourds (grands scans de dépôt) devraient passer en jobs asynchrones avec polling, pas en un seul appel MCP bloquant — sur le même principe que les longues opérations Git/npm en CI.

7. FAQ