2026 OpenClaw planification multi-agents : matrice sessions_spawn runtime=acp vs subagent, triage streamTo et échec handshake ACP 1008 Runbook

Six erreurs d'interprétation fréquentes (les reconnaître avant de changer runtime)

1. runtime=acp par défaut sans bridge ACP : le canal principal répond, chaque spawn renvoie ACP_TURN_FAILED—cause : acpx non enregistré ou queue owner hors ligne, pas le quota modèle.
2. streamTo / resumeSessionId sous runtime=subagent : champs réservés à la continuation ACP ; subagent passe par RPC Gateway intégré—paramètres invalides ou champs silencieusement ignorés.
3. Tout 1008 = problème Docker pairing : en Compose voir l'article trustedProxies ; sur acp bare-metal, 1008 = souvent version handshake ou course au démarrage bridge.
4. Tester spawn avant reload post-upgrade : CLI neuf, Gateway ancien processus—stacks acp/subagent divergent. Aligner d'abord l'échelle d'acceptation.
5. Ignorer la sonde acpx sous Windows : extensions provider ralentissent le démarrage ; handshake avant bridge prêt. Utiliser OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE.
6. Mélanger Completions et Responses sans vérifier streamTo : le routage 2026 infère streamTo pour Responses ; pas pour Completions—spawn « cassé » = forme API + runtime.

En 2026, upstream scinde sessions_spawn en deux runtimes exclusifs. runtime=acp dialogue avec acpx externe via bridge ACP et supporte streamTo pour renvoyer la sortie sub-agent vers l'UI principale. runtime=subagent lance un sous-agent léger dans le Gateway—latence moindre, sans acpx, sans champs de continuation ACP.

Mauvais runtime + champs invalides = « fausse complexité » la plus coûteuse en astreinte. Aligner le chemin d'abord, puis modèles et allowlist outils (triage tools.profile).

Traitez chaque spawn comme un contrat de planification archivé : runtime, besoin de streaming UI, Completions vs Responses, chemin de repli. Sans contrat, « hier OK, aujourd'hui non » reste inexplicable—les changements touchent templates ou forme API, rarement le binaire Gateway.

Les équipes qui omettent ce contrat passent des heures sur les prompts alors que le JSON porte encore streamTo: "main" sur un chemin subagent copié d'un exemple acp. La correction est structurelle.

Autre schéma 2026 : template Cursor IDE acp déployé tel quel sur Gateway headless subagent—spawn intermittent quand acpx tourne localement, échec en CI. Instabilité apparente, pas panne d'infrastructure.

Avant outage bridge severity-1 : un spawn de la dernière heure exigeait-il la sémantique acp ? Recherche batch sans UI → subagent souvent le fix permanent.

runtime=acp vs runtime=subagent : quel stack

Règle : streaming UI, reprendre session ACP, aligner acpx Cursor/IDE → acp. Boucle Gateway, faible dépendance, acp indisponible → subagent. Quatre formes de tâches courantes en production.

En doute, sonde subagent d'une ligne d'abord. Si elle passe, la pile de planification Gateway est saine—l'échec vient d'acp ou de la config des champs.

streamTo / resumeSessionId : champs acp uniquement—triage mauvaise config

Beaucoup de « paramètres corrects, sub-agent vide » viennent d'une contamination champs/runtime. Le chemin subagent retire ou rejette les champs ACP. Template avec streamTo: "main" et runtime=subagent → erreur RPC générique—inspecter le JSON d'appel.

Sous runtime=acp, resumeSessionId continue une session acpx ; streamTo dirige le flux de tokens vers l'UI Control ou la cible canal.

Le routage Responses 2026 peut inférer streamTo ; Completions non. Migration Responses→Completions sans mise à jour template : « avant streaming, maintenant silencieux en arrière-plan »—régression API + runtime, pas upgrade.

Expérience de stripping : copier le JSON en échec, retirer streamTo/resumeSessionId, runtime=subagent, retester. Succès immédiat → acp ou mauvaise config. Échec persistant → pairing, token ou surface outils. Étape 4 du runbook.

Documenter le JSON avant/après dans le ticket pour la relève.

Auditer les templates : chercher streamTo hors blocs acp. Lint sur runtime=subagent plus champs ACP attrape la dérive avant déploiement.

Streaming UI obligatoire et stripping casse l'UX → ne pas forcer subagent durablement ; prioriser réparation bridge ou topologie.

// acp : streaming UI + reprise optionnelle
{
  "tool": "sessions_spawn",
  "runtime": "acp",
  "task": "Rechercher les prix concurrents et produire un tableau",
  "streamTo": "main",
  "resumeSessionId": "acp-sess-abc123"
}

// subagent : boucle Gateway—pas de streamTo
{
  "tool": "sessions_spawn",
  "runtime": "subagent",
  "task": "Renommer en lot les fichiers sous logs/"
}

// mauvaise config fréquente
{
  "runtime": "subagent",
  "streamTo": "main"
}

Triage échec handshake ACP : ACP_TURN_FAILED, 1008, queue owner

Quand runtime=acp échoue mais le chat principal fonctionne, router par empreinte log—ne pas mélanger avec « Gateway totalement muet ».

Capturer une tentative spawn avec horodatages alignés Gateway/acpx. Les échecs handshake durent souvent moins d'une seconde.

Commencer par le plus petit spawn acp reproductible, pas la tâche complète avec outils. Une sonde lecture seule d'une ligne isole le handshake des allowlist et de la latence modèle.

1008 sur acp seul corrèle souvent au décalage versions CLI/Gateway/acpx. Noter les trois versions avant rollback.

Windows et OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE

Sous Windows, extensions provider et Defender allongent le démarrage à froid acpx. spawn avant bridge → ACP_TURN_FAILED ou invalid handshake.

OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=1 (sémantique selon votre version OpenClaw) fait attendre une sonde santé acpx supplémentaire avant le premier spawn.

Si échec persistant : tâche subagent minimale sur la même machine pour prouver la pile Gateway, puis isoler acpx—ne pas confondre démarrage lent et obligation de rollback version.

Complément à la montée de version : là probe/ACP post-migration ; ici version stable, spawn ou handshake occasionnel. Chaîner : échelle d'acceptation verte, puis cette matrice.

Sous Windows, vérifier Controlled Folder Access—acpx démarre sans enregistrement bridge → queue owner unavailable. La sonde startup laisse le temps après I/O retardé par policy.

Documenter les variables probe dans la gestion de config, pas seulement en session PowerShell éphémère.

# Windows : prolonger sonde démarrage acpx (exemple)
$env:OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE = "1"
openclaw gateway status
openclaw gateway probe

# Sonde subagent minimale (sans streamTo)
# sessions_spawn via Control UI ou CLI, runtime=subagent

acp en panne : continuer réparation vs pin vs repli

Tout spawn acp rouge ne justifie pas un rollback. La surface d'impact oriente le choix.

Runbook en sept étapes : choisir, sonder, spawn, trier, replier, documenter

1. Geler le JSON d'appel : runtime, streamTo/resumeSessionId, Completions vs Responses.
2. Baseline Gateway : status + probe ; après upgrade un seul reload (montée de version).
3. Auto-contrôle choix : streaming UI → acp + streamTo ; arrière-plan → subagent, retirer champs ACP.
4. Sonde spawn minimale : subagent lecture seule une ligne ; OK = pile scheduling OK.
5. Spécifique acp : processus acpx + bridge ; Windows startup probe ; logs 1008 / queue owner.
6. Repli ou rollback : acp deux tours → repli subagent au ticket ; deux chemins morts → digest.
7. Métriques de clôture : taux succès spawn, ratio repli, MTTR ; memo runtime interne.

Étapes 3–4 en moins de cinq minutes avec logs accessibles. Plus de quinze minutes à l'étape 5 sans signal → escalade bridge, pas boucle acp aveugle.

Étape 6 explicite : « runtime=subagent temporaire, streaming UI bloqué jusqu'à acp ok »—évite tickets dupliqués sans sortie visible.

Trois métriques pour chaque ticket de changement

• Taux succès spawn (par runtime) : succès / total ; acp <95%, subagent OK → bridge avant changement modèle.
• Ratio repli acp→subagent : streaming UI ne doit pas vivre longtemps en repli ; >30%/semaine → pin ou migration topologie.
• Événements mauvaise config streamTo : streamTo/resume sur subagent ; cible production 0 (lint ou revue template).

Sur Gateway portable mélangeant acpx, veille et plugins, les échecs spawn passent pour « OpenClaw instable ». Mieux : Gateway autoritaire + acpx sur Mac distant alimenté en permanence ; poste local en forward SSH uniquement.

Revoir le taux succès spawn hebdomadaire par bucket runtime—un agrégat sain peut masquer acp à 70 % et subagent à 99 %.

Compteur mauvaise config streamTo : avertissements structurés si clés ACP sur subagent ; cible zéro en production.

Conclusion : le choix runtime est un contrat de planification

Itérer les prompts sans vérifier runtime et streamTo transforme un handshake ACP en illusion « multi-agent down ». Matrice, triage mauvaise config et repli subagent compressent l'astreinte en incidents sondés, avec repli et métriques.

Forcer le bridge acp sur portable Windows ou topologie Docker fragmentée a un coût : courses 1008, incohérence streamTo Completions/Responses, rayon de panne élargi.

Pour production 24/7, spawn ticketisable, chemins acp/subagent commutables : Mac mini MACCOME (M4 / M4 Pro)—guide multi-régions, topologie avec runbook Gateway SSH.

Garder ce runbook à côté des articles montée de version et Docker 1008. Mauvaise config runtime → pas rollback digest ; deux chemins morts après upgrade canal → pas marathon template streamTo.

Formation opérateurs : un spawn acp réussi avec streamTo et un subagent sans champs ACP sur le même Gateway—dix minutes évitent la plupart des erreurs de la section un.