Fehlerbehebungsanleitung: Verschachtelte Agent-Sitzungen blockieren sich gegenseitig

Symptome

Wenn Sie mehrere Agent-Sitzungen gleichzeitig ausführen, können die folgenden Symptome auftreten:

• Verzögerte oder fehlende Antworten: Eine oder mehrere Agent-Sitzungen scheinen zu „einfrieren" oder reagieren deutlich langsamer als erwartet, selbst wenn die angeforderte Aufgabe einfach ist.
• Sitzungsübergreifende Blockierung: Eine langlaufende Aufgabe in einer Sitzung (z. B. ein ACP Claude Code-Lauf) verursacht Verzögerungen in völlig unabhängigen Sitzungen.
• Gateway-Timeouts: Fehlermeldungen in Protokollen, die auf lane wait exceeded: lane=nested waitedMs=XXXXX queueAhead=1 hinweisen.
• Discord-Zustellfehler: Assistant-Antworten, die während des Backlogs generiert wurden, werden niemals an Discord-Kanäle zugestellt.
• Inkonsistentes Verhalten: Einige Sitzungen antworten sofort, während andere minutenlang im Leerlauf sitzen, selbst wenn die zugrunde liegenden Aufgaben unabhängig voneinander sind.

Ursache

Die Ursache war ein einzelner globaler Warteschlangen-Engpass im verschachtelten Agent-Ausführungssystem.

Zuvor teilten alle verschachtelten Agent-Operationen über alle Sitzungen hinweg eine einzige Spur namens "nested" mit maxConcurrent=1. Das bedeutete:

1. Jede sessions_send, runAgentStep und ACP-Dispatch-Kommunikation konkurrierte um denselben Warteschlangeneintrag.
2. Wenn Sitzung A eine 10-minütige Aufgabe ausführte, mussten Sitzungen B, C und D dahinter in der Warteschlange warten.
3. Die Befehlswarteschlange behandelte jede verschachtelte Operation identisch, unabhängig davon, welche Sitzung sie ansprach.

Diese architektonische Einschränkung verursachte eine Blockierung am Anfang der Warteschlange, bei der eine einzelne langlaufende verschachtelte Operation alle anderen Agent-Sitzungen im Gateway blockieren konnte.

Schritt-für-Schritt-Lösung

Option 1: Upgrade auf die behobene Version (Empfohlen)

Aktualisieren Sie Ihre OpenClaw-Installation auf Version v2026.4.19-beta.2 oder höher.

Diese Version führt sitzungsspezifische verschachtelte Spuren ein, die verschachtelte Arbeit auf nested:<sessionKey> begrenzen, und ermöglicht so die parallele Ausführung über verschiedene Sitzungen hinweg, während Invarianten innerhalb jeder Sitzung gewahrt bleiben.

Option 2: Spurenkonfiguration überprüfen (Zur manuellen Verifizierung)

Wenn Sie überprüfen müssen, ob die Korrektur korrekt angewendet wurde, überprüfen Sie Ihre Gateway-Protokolle auf die verwendeten Spurnamen:

Vor der Korrektur würden Sie Protokolle wie diese sehen:

[agent:nested] Verarbeitung Sitzung A
[agent:nested] Verarbeitung Sitzung B

Nach der Korrektur sollten Sie bereichsbezogene Spurnamen sehen:

[agent:nested:session-A] Verarbeitung Sitzung A
[agent:nested:session-B] Verarbeitung Sitzung B

Option 3: Den Spuren-Zustand überprüfen

In Ihrer Gateway-Konfiguration sollte der Spuren-Zustand nun nach dem vollständigen sitzungsbezogenen Bezeichner und nicht nach der bloßen Zeichenfolge "nested" geschlüsselt sein. Jeder Eintrag sollte zeigen:

• nested:<sessionKey> für Standardsitzungen
• "nested" Fallback nur für Legacy-Cron-Pfade

Verifizierung

Um zu bestätigen, dass die Korrektur korrekt funktioniert:

1. Führen Sie mehrere gleichzeitige Sitzungen aus: Richten Sie zwei oder mehr Agent-Sitzungen ein, die verschachtelte Operationen empfangen können.

2. Lösen Sie eine langlaufende Aufgabe in einer Sitzung aus: Rufen Sie beispielsweise eine Aufgabe auf, die mehrere Minuten dauert.

3. Senden Sie eine schnelle Aufgabe an eine andere Sitzung: Während die lange Aufgabe läuft, senden Sie eine einfache Anfrage an eine andere Sitzung.

4. Überprüfen Sie die parallele Ausführung: Die zweite Sitzung sollte sofort antworten, ohne auf den Abschluss der ersten Sitzungsaufgabe zu warten.

5. Überprüfen Sie die Protokolle auf bereichsbezogene Spuren: Suchen Sie nach [agent:nested:<sessionKey>]-Präfixen in Ihren Gateway-Protokollen, die die sitzungsspezifische Spurenisolation bestätigen.

Erwartete Testergebnisse nach der Korrektur:

pnpm test src/agents/lanes.test.ts         # 13 Tests bestanden
pnpm test src/gateway/server.sessions-send.test.ts  # 14 Tests bestanden
pnpm test 'src/agents/**/*.test.ts'        # 3841 Tests bestanden

Häufige Fehler

Sitzungsschlüssel-Verarbeitung

• Leere oder nur Leerzeichen enthaltende Sitzungsschlüssel: Diese fallen auf die nichtbereichsbezogene "nested"-Spur zurück. Stellen Sie sicher, dass Ihre Sitzungsschlüssel vor dem Routing verschachtelter Operationen korrekt gefüllt sind.

• Legacy-Cron-Pfade: Cron-Integrationen, die resolveNestedAgentLane(lane) verwenden, verwenden weiterhin den nichtbereichsbezogenen Fallback. Dies ist beabsichtigt für die Abwärtskompatibilität.

Spurenname-Kollisionen

• Benutzerdefinierte Spurnamen: Wenn Sie benutzerdefinierte Spuren mit Namen wie "nested:something" haben, beachten Sie, dass diese von den systemgenerierten nested:<sessionKey>-Spuren distinct sind. Die Systemspur verwendet ein spezifisches Präfix-Muster, das dem bestehenden session:<key>-Muster entspricht.

Speicherüberlegungen

Die Spuren-Zustands-Map wächst jetzt mit neuen Sitzungsschlüsseln. Jeder Spuren-Zustandseintrag beträgt ungefähr 200 Bytes. Die realistische Obergrenze ist die Anzahl der aktiven Sitzungen, die bereits durch die Sitzungsverwaltung Ihres Gateways begrenzt ist. Eine zukünftige Verbesserung zum Aufraeumen inaktiver verschachtelter Spuren kann hinzugefügt werden, wenn dies zu einem Problem wird.

Unzugehörige Probleme

Zwei zugehörige Probleme, die im ursprünglichen Bericht erwähnt wurden, liegen außerhalb des Geltungsbereichs dieser Korrektur:

• Sitzungs-Zustellungskontext-Korruption
• Fehlen von Zustellungswiederholungs-/DLQ-Mechanismen

Dies sind architektonische Nachfolgearbeiten, die separat verfolgt werden.

Zugehörige Fehler

Betroffene Versionen

• Behoben in: v2026.4.19-beta.2
• Betroffene Versionen: v2026.4.14 und früher

Kompatibilität

Diese Korrektur ist vollständig abwärtskompatibel:

• Die AGENT_LANE_NESTED-Konstante wird weiterhin exportiert
• Aufrufer, die die Konstante weiterhin direkt übergeben, behalten ihr bestehendes (nichtbereichsbezogenes) Verhalten
• Keine Konfigurationsänderungen erforderlich
• Keine Migrationsschritte erforderlich

Die Korrektur stärkt die Sitzungsisolation, ohne bestehende Integrationen zu brechen.