2026 OpenClaw Multi-Agent-Scheduling: sessions_spawn runtime=acp vs subagent Entscheidungsmatrix, streamTo-Fehlkonfiguration und ACP-1008-Handshake Runbook

Sechs häufige Fehlinterpretationen (erkennen, bevor Sie runtime ändern)

1. Standard runtime=acp ohne ACP-Bridge: Hauptkanal chatet, jeder spawn liefert ACP_TURN_FAILED—Ursache ist nicht registriertes acpx oder offline queue owner, nicht Modellkontingent.
2. streamTo / resumeSessionId unter runtime=subagent: nur für ACP-Sitzungsfortsetzung; subagent nutzt Gateway-RPC, Fehlkonfiguration ergibt ungültige Parameter oder stille Feldverluste.
3. Jedes 1008 als Docker-Pairing: Compose siehe trustedProxies-Artikel; auf Bare-Metal-acp ist 1008 oft Handshake-Version oder Bridge-Race.
4. spawn testen vor reload nach Upgrade: CLI neu, Gateway alter Prozess—acp/subagent-Stacks spalten. Zuerst Abnahmeleiter, dann Scheduling.
5. acpx-Startup-Probe unter Windows ignorieren: Provider-Erweiterungen verzögern Start; Handshake vor Bridge bereit. OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE nutzen.
6. Completions/Responses gemischt ohne streamTo-Autofill: 2026-Routing inferiert streamTo bei Responses; Completions nicht—scheinbar kaputter spawn, tatsächlich API-Form plus runtime.

Upstream 2026 trennt sessions_spawn in zwei exklusive Runtimes. runtime=acp spricht über ACP-Bridge mit externem acpx, unterstützt streamTo für UI-Rückfluss. runtime=subagent startet leichten Sub-Agent im Gateway—weniger Latenz, kein acpx, keine ACP-Fortsetzungsfelder.

Falsche runtime plus ungültige Felder ist die zeitintensivste „Scheinkomplexität“ im Betrieb. Pfad zuerst, dann Modelle und Tool-Allowlist (tools.profile-Triage).

Archivieren Sie jeden spawn als Scheduling-Vertrag: runtime, UI-Rückfluss ja/nein, Completions vs Responses, Fallback (subagent/Rollback). Ohne Vertrag ist „gestern ging's, heute nicht“ schwer erklärbar—Änderungen liegen in Template-Feldern oder API-Form, selten am Gateway-Binary.

Für EU-Teams gilt Datenschutz auch bei spawn-Logs: eingefrorene Call-JSONs können Task-Inhalte und Session-IDs enthalten. Tickets nur mit redigierten Ausschnitten; vollständige Payloads nicht in Team-Chat oder unverschlüsselte Laufwerke. Verantwortlichen im Change-Ticket benennen.

Typisches 2026-Muster: Template aus Cursor-IDE-acp unverändert auf headless Gateway mit subagent-Batch—spawn scheitert intermittierend, wenn acpx lokal läuft, dann in CI. Scheinbare Instabilität statt Runtime-Mismatch.

Vor Severity-1-Bridge-Outage prüfen: brauchte ein spawn in der letzten Stunde acp-Semantik? Reine Hintergrund-Recherche ohne UI → subagent oft dauerhaft richtig, nicht nur Workaround.

runtime=acp vs runtime=subagent: welcher Stack

Merksatz: UI-Rückfluss, ACP-Sitzung fortsetzen, Cursor/IDE-acpx → acp. Gateway-intern, geringe Abhängigkeit, acp down → subagent. Tabelle: vier häufige Produktionsformen.

Bei Unsicherheit zuerst Einzeiler-subagent-Probe. Besteht sie, ist der Scheduling-Stack gesund—Fehler liegt bei acp oder Feldkonfiguration.

streamTo / resumeSessionId: nur acp—Fehlkonfiguration triagieren

Viele „Parameter stimmen, Sub-Agent leer“-Meldungen entstehen durch Feld-Runtime-Kreuzkontamination. subagent-Pfad strippt ACP-Felder. Template mit streamTo: "main" bei runtime=subagent liefert oft nur generischen RPC-Fehler—Call-JSON prüfen.

Unter runtime=acp setzt resumeSessionId acpx-Sitzung fort; streamTo leitet Token zum Control-UI-Ziel.

Responses-Routing 2026 kann streamTo inferieren; Completions nicht. Migration Responses→Completions ohne Template-Update: „früher Rückfluss, jetzt still im Hintergrund“—kein Upgrade-Bug, sondern API plus runtime.

Feld-Stripping-Experiment: fehlerhaftes JSON kopieren, streamTo/resumeSessionId entfernen, runtime=subagent, retry. Sofort ok → acp oder Fehlkonfiguration. Weiter rot → Pairing, Token oder Tool-Oberfläche. Runbook Schritt 4.

Vor/nach JSON im Ticket dokumentieren—Datenschutz: personenbezogene Task-Texte redigieren.

Templates auditieren: streamTo außerhalb acp-Blöcke suchen. Lint bei runtime=subagent plus ACP-Feldern fängt Regressionen vor Deploy.

UI-Rückfluss Pflicht und Stripping bricht UX → subagent nicht dauerhaft erzwingen; Bridge-Reparatur oder Topologie priorisieren.

// acp: UI-Rückfluss + optional resume
{
  "tool": "sessions_spawn",
  "runtime": "acp",
  "task": "Wettbewerberpreise recherchieren und Tabelle ausgeben",
  "streamTo": "main",
  "resumeSessionId": "acp-sess-abc123"
}

// subagent: Gateway-intern—kein streamTo
{
  "tool": "sessions_spawn",
  "runtime": "subagent",
  "task": "Dateien unter logs/ stapelweise umbenennen"
}

// häufige Fehlkonfiguration
{
  "runtime": "subagent",
  "streamTo": "main"
}

ACP-Handshake-Triage: ACP_TURN_FAILED, 1008, queue owner

Bei runtime=acp-Fail und funktionierendem Hauptchat nach Log-Fingerabdruck routen—nicht mit „Gateway komplett stumm“ vermischen.

Einen spawn-Versuch mit aligned Gateway/acpx-Zeitstempeln erfassen. Handshake-Fenster sind oft subsekundengenau.

Minimalen acp-spawn zuerst—nicht Voll-Task mit Tools. Einzeiler-Probe isoliert Handshake von Allowlist und Modell-Latenz. acp minimal rot, subagent minimal grün → Bridge/acpx, nicht Scheduling allgemein.

1008 nur auf acp korreliert oft mit Versions-Split CLI/Gateway/acpx. Alle drei Versionen im Ticket vor Rollback—nur Gateway pinnen bei altem acpx reproduziert 1008.

Windows und OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE

Provider-Erweiterungen und Defender verlängern acpx-Kaltstart. spawn vor Bridge → ACP_TURN_FAILED oder invalid handshake.

OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE=1 (Semantik laut OpenClaw-Doku) lässt Gateway vor erstem spawn eine zusätzliche acpx-Gesundheitsprobe warten.

Weiter rot: Minimale subagent-Aufgabe auf demselben Host—Scheduling-Stack intakt, dann acpx isolieren. Nicht langsamen Windows-Start mit Versions-Rollback verwechseln.

Abgrenzung zur Upgrade-Begleitung: dort probe/ACP nach Migration; hier stabile Version, nur spawn/Handshake. Erst Abnahmeleiter grün, dann diese Matrix—sonst Split-Brain wie streamTo-Fehler.

Unter Windows auch Controlled Folder Access prüfen—acpx startet, Bridge-Registrierung fehlt → queue owner unavailable. Startup-Probe gibt Zeit nach policy-verzögertem I/O.

Probe-Variablen im Config-Management dokumentieren, nicht nur in temporärer PowerShell—Service-Restart ohne Variable erklärt „gestern im Terminal ok“.

# Windows: acpx-Startup-Probe verlängern (Beispiel)
$env:OPENCLAW_ACPX_RUNTIME_STARTUP_PROBE = "1"
openclaw gateway status
openclaw gateway probe

# Minimale subagent-Probe (ohne streamTo)
# sessions_spawn über Control UI oder CLI, runtime=subagent

acp defekt: weiter reparieren vs Pin vs Fallback

Nicht jeder rote acp-spawn erfordert Rollback. Impact-Oberfläche entscheidet.

Sieben-Schritte-Runbook: wählen, sondieren, spawn, triagieren, fallback, dokumentieren

1. Call-JSON einfrieren: runtime, streamTo/resumeSessionId, Completions vs Responses.
2. Gateway-Baseline: status + probe; nach Upgrade genau ein reload (Upgrade-Begleitung).
3. Auswahl-Check: UI-Rückfluss → acp + streamTo; Hintergrund → subagent, ACP-Felder strippen.
4. Minimale spawn-Probe: subagent Einzeiler; ok = Scheduling ok.
5. acp-spezifisch: acpx + Bridge; Windows Startup-Probe; 1008/queue-owner-Logs.
6. Fallback/Rollback: acp zwei Runden → subagent im Ticket; beide tot → Digest.
7. Abschluss-KPIs: spawn-Erfolgsrate, Fallback-Anteil, MTTR; Runtime-Memo aktualisieren.

Schritte 3–4 unter fünf Minuten bei zugänglichen Logs. Über 15 Minuten in Schritt 5 ohne neues Signal → Bridge-Owner eskalieren, nicht acp blind wiederholen—MTTR-Noise und Modell-Rate-Limits.

Schritt 6 explizit: „temporär runtime=subagent, UI-Rückfluss blockiert bis acp ok“—verhindert Duplikat-Tickets ohne sichtbare Sub-Agent-Ausgabe.

Drei KPIs fürs Change-Ticket

• spawn-Erfolgsrate (pro runtime): Erfolge/Gesamt; acp <95%, subagent ok → Bridge vor Modellwechsel.
• acp→subagent-Fallback-Anteil: UI-Rückfluss dauerhaft auf Fallback >30%/Woche → Pin oder Topologie.
• streamTo-Fehlkonfiguration: streamTo/resume auf subagent; Ziel 0 (Lint/Template-Review, Datenschutz-Audit).

Auf Laptop-Gateways mit acpx, Deckel zu und vielen Plugins wirkt spawn instabil. Besser: autoritatives Gateway + acpx auf Remote-Mac mit Dauerstrom; Laptop nur SSH-Forward—Logs auf einem Knoten, Datenschutz-by-Design auf dediziertem Volume.

spawn-Erfolgsrate wöchentlich pro runtime-Bucket—Aggregat kann acp bei 70% und subagent bei 99% verbergen.

streamTo-Fehlkonfig-Zähler: strukturierte Warnung bei ACP-Feldern auf subagent; Ziel 0—Template-Drift oder Agent erfindet Felder.

Fazit: Runtime-Auswahl ist Scheduling-Vertrag

Prompts drehen ohne runtime/streamTo-Check vergrößert ACP-Handshake zu „Multi-Agent tot“. Matrix, Fehlkonfig-Triage und subagent-Fallback komprimieren Betrieb auf gesonderte, fallback-gestützte Minuten-Events.

acp auf Windows-Laptop oder getrennten Containern kostet: Race-1008, streamTo-Inkonsistenz, größerer Störungsradius. Für 7×24, ticketierbare spawn, umschaltbare acp/subagent: MACCOME Mac mini (M4 / M4 Pro)—Multi-Region-Leitfaden, Topologie mit SSH-Runbook.

Runbook neben Upgrade-Begleitung und Docker-1008 im Wiki. Runtime-Fehlkonfig → kein Digest-Rollback; beide Pfade nach Channel-Upgrade rot → keine streamTo-Template-Marathon. Matrizen erzwingen diese Trennung früh.

Neue Operatoren: ein erfolgreicher acp-spawn mit streamTo und ein subagent-spawn ohne ACP-Felder am selben Gateway—zehn Minuten Übung verhindert die meisten Fehlinterpretationen aus Abschnitt eins.