Jeder Entwickler, der mit Claude Code arbeitet, kennt diesen Moment: Im Terminal erscheint eine Zeile mit der Aufschrift „Symbioting… (3m 12s · ↓ 5.7k tokens)“, der Fortschrittsbalken scheint eingefroren zu sein und minutenlang gibt es keine neue Ausgabe. Man tippt frustriert ein „Bist du noch da?“, und plötzlich erwacht Claude zum Leben und führt die Aufgabe nahtlos fort.
Diese unheimliche Erfahrung des „Hängensbleibens mit Wiederbelebung durch Nachricht“ wirkt wie Magie, ist aber in Wahrheit das Ergebnis überlagerter Fehlerzustände bei Anthropic-Streaming-Protokollen, Timeout-Mechanismen und dem Kontextmanagement. Dieser Artikel basiert auf der offiziellen Fehlerbehebungsdokumentation von Claude Code sowie auf den GitHub-Issues #25979, #24688, #39718, #25286, #25539 und #51659. Wir erklären systematisch die wahren Ursachen für das Hängenbleiben von Claude Code und bieten 7 sofort anwendbare Wiederherstellungsmethoden sowie 5 Präventionsstrategien.
Kernnutzen: Nach dem Lesen dieses Artikels verstehen Sie die Bedeutung hinter jedem Spinner-Verb, warum eine Nachricht manchmal Wunder bewirkt, wann Sie zwingend mit Strg+C neu starten müssen und wie Sie die Rate der Hänger gegen Null senken.
Vollständige Interpretation der Claude Code Statusanzeige
Um Probleme beim „Hängenbleiben“ zu beheben, müssen Sie zuerst die Statuszeile verstehen, die Claude Code im Terminal anzeigt. Die im Screenshot gezeigte Zeile Symbioting… (3m 12s · ↓ 5.7k tokens) sieht mysteriös aus, ist aber eine strukturierte Information, bei der jeder Teil eine klare Bedeutung hat.
| Feld | Beispielwert | Bedeutung |
|---|---|---|
| Spinner-Verb | Symbioting… |
Vermenschlichte Beschreibung der aktuellen Phase, ab 2.1.23 anpassbar |
| Wartezeit | 3m 12s |
Kumulierte Zeit seit Beginn dieser Runde |
| Streaming-Pfeil | ↓ oder ↑ |
↓ bedeutet Empfang von API-Daten, ↑ bedeutet Senden |
| Token-Anzahl | 5.7k tokens |
Anzahl der bereits heruntergeladenen/hochgeladenen Token |
Claude Code enthält 187 Standard-Spinner-Verben; Befuddling, Ruminating, Accomplishing und Symbioting sind nur einige davon. Sie dienen lediglich der lebendigeren Warteerfahrung und haben keine technischen Unterschiede. Ab Version 2.1.23 wurde die Konfigurationsoption spinnerVerbs eingeführt; die Community bietet sogar Pakete mit über 1900 benutzerdefinierten Verben an.
Ob Claude Code wirklich hängt, hängt nicht vom Verb ab, sondern von zwei Dingen: Steigt die Zeit noch? und Bewegt sich die Token-Anzahl noch? Wenn die Zeit nach 3m 12s nach weiteren 30 Sekunden auf 3m 42s springt, die Token-Anzahl aber bei 5.7k stehen bleibt, kann man davon ausgehen, dass die Streaming-Antwort zum Stillstand gekommen ist.
Wenn Sie die Claude API über einen API-Proxy-Dienst wie APIYI (apiyi.com) nutzen, haben die Felder in der Statuszeile dieselbe Bedeutung wie beim Original, und Sie können dieselbe Methode zur Fehlerdiagnose anwenden.
Die 6 Hauptursachen für Hänger in Claude Code
Wenn Sie die Statusanzeigen verstanden haben, können Sie das tatsächliche Verhalten abgleichen, um die Grundursache zu lokalisieren. Die folgenden 6 Gründe sind nach ihrer Häufigkeit sortiert und decken über 90 % der realen Fälle im GitHub Issue Tracker ab.
Ursache 1: Stille Unterbrechung der API-Streaming-Antwort
Dies ist die häufigste und am schwersten zu erkennende Ursache, die dem GitHub Issue #25979 entspricht. Der HTTP-Client von Claude Code verfügt über keinen Read-Timeout-Mechanismus. Sobald die Upstream-API während der Übertragung keine Pakete mehr sendet, verharrt der Prozess im epoll_wait-Kernel-Status und wartet auf neue Daten. In der Benutzeroberfläche dreht sich der Spinner weiter, aber der Token-Zähler steigt nicht an. Häufige Auslöser sind Netzwerk-Jitter bei grenzüberschreitenden Verbindungen, tmux-Multiplexing oder Verbindungsabbrüche bei langen SSH-Sitzungen.
Ursache 2: Zu große Tool-Aufruf-Payload löst Verbindungs-Reset aus
Entspricht Issue #39718. Wenn das Modell Claude Code anweist, ein Tool auszuführen, das eine extrem große Ausgabe erzeugt (z. B. Write für eine Datei mit hunderttausenden Zeilen), wird die zugrunde liegende HTTP-Verbindung vom Betriebssystem aktiv zurückgesetzt (Reset), wenn 5 Minuten lang keine gültigen Daten übertragen wurden. Claude Code fängt diesen Fehler jedoch nicht ab, sodass der Spinner in der UI weiterhin aktiv bleibt. Diese Art von Hänger tritt meist exakt nach etwa 5 Minuten auf.
Ursache 3: Automatisches Komprimierungs-Thrashing
Wenn das Kontextfenster von Claude Code fast voll ist, wird eine automatische Komprimierung (Auto-Compact) ausgelöst. Wenn eine sehr große Datei oder eine Tool-Ausgabe nach der Komprimierung sofort wieder in den Kontext zurückgelesen wird, kommt es zu einer Endlosschleife der Komprimierung. Das System bleibt schließlich stehen und gibt die Meldung Autocompact is thrashing aus. Bevor diese Meldung erscheint, sieht es in der UI so aus, als wäre das Programm eingefroren.
Ursache 4: Kontextauslastung über 80 %
Die offizielle Dokumentation weist ausdrücklich darauf hin, dass sich die Antwortzeiten bei einer Kontextauslastung von über 80 % erheblich verschlechtern. In einigen Szenarien äußert sich dies durch eine lange Zeit ohne Reaktion. Das Merkmal dieses "Pseudo-Hängers" ist, dass der Token-Zähler zwar langsam weiter wächst, die Geschwindigkeit jedoch nur einen Bruchteil des Normalzustands beträgt.
Ursache 5: Fehlerhafte Einstellungen führen zu einem "Scheintod" beim Start
Entspricht den Issues #31049, #29652 usw. Wenn beispielsweise die Konfiguration enableAllProjectMcpServers: true eine große Anzahl lokaler MCP-Server lädt oder additionalDirectories einen ungültigen Pfad wie //C:/ enthält, kann Claude Code beim Start hängen bleiben. Dieser Hänger tritt normalerweise in den ersten Sekunden nach dem Öffnen einer neuen Sitzung auf.
Ursache 6: Hängengebliebene Statuszeile (Antwort fertig, UI nicht aktualisiert)
Entspricht Issue #25539. In einigen Versionen hat Claude das vollständige Ergebnis bereits zurückgegeben, aber der Spinner in der Terminal-UI wurde nicht gelöscht und dreht sich scheinbar weiter. Wenn Sie in diesem Moment die Eingabetaste drücken oder eine neue Nachricht senden, beginnt Claude sofort mit der nächsten Aufgabe – das Programm war nie wirklich abgestürzt, die UI hat lediglich einen falschen Status angezeigt.
Bei der Fehlersuche empfiehlt es sich, zuerst zu prüfen, ob der Token-Zähler noch steigt. Wenn Sie den API-Proxy-Dienst von APIYI (apiyi.com) für Claude-API-Aufrufe nutzen, können Sie zusätzlich in den Plattform-Logs prüfen, ob die Anfrage bereits mit 200 OK beantwortet wurde, um dies mit dem Status der Claude Code UI abzugleichen.
Warum eine einfache Nachricht Claude Code wieder zum Leben erweckt
Viele Nutzer haben ein "mysteriöses" technisches Phänomen beobachtet: Claude Code hängt seit drei Minuten fest, doch sobald man "Bist du noch da?" schreibt oder einfach die Eingabetaste drückt, setzt es die Arbeit sofort fort. Dieses Verhalten lässt sich auf Protokollebene erklären.
Der erste Fall ist ein hängengebliebener Status-Indikator (Grundursache 6). Claude hat die Antwort eigentlich bereits abgeschlossen, aber die Benutzeroberfläche hat den Lade-Spinner nicht entfernt. Wenn Sie in diesem Moment eine neue Nachricht senden, wird diese direkt als nächster Prompt verarbeitet. Es wirkt wie eine "Wiederbelebung", ist aber in Wahrheit nur die Fortsetzung des Prozesses.
Der zweite Fall betrifft Verzögerungen bei der Streaming-Antwort (Grundursache 1). Wenn Claude Code eine neue Eingabe erhält, schließt es aktiv den aktuellen Hängestatus, bereinigt die halbfertigen Anfragen und startet eine neue HTTP-Anfrage. Diese neue Anfrage enthält den vollständigen Sitzungsverlauf, und das Modell setzt die Antwort nahe dem Haltepunkt fort – daher sieht es so aus, als würde es einfach "weiterarbeiten".
Der dritte Fall tritt auf, wenn ein MCP-Server oder ein Tool-Aufruf auf eine Antwort von nachgelagerten Systemen wartet. Die neue Nachricht wird von Claude Code als neue Entscheidung für einen Tool-Aufruf interpretiert, wodurch der hängengebliebene Aufruf indirekt umgangen wird.
Es ist jedoch wichtig zu betonen, dass das Senden einer Nachricht kein Allheilmittel ist. Wenn der Prozess aufgrund eines nicht wiederherstellbaren Wartezustands (z. B. spätere Phasen von Grundursache 2) blockiert ist, landet die Nachricht zwar in der Warteschlange, wird aber nicht verarbeitet. In diesem Fall müssen Sie Ctrl+C drücken oder das Terminal schließen. Bei der Nutzung über den API-Proxy-Dienst von APIYI (apiyi.com) ist die Erfolgsquote bei dieser Methode oft höher, da der Proxy-Dienst zeitlich begrenzte Verbindungen meist schneller freigibt als die offiziellen Endpunkte.
7 Methoden zur Wiederherstellung bei einem Hänger in Claude Code
Unterschiedliche Ursachen erfordern unterschiedliche Lösungsansätze. Die folgende Tabelle listet die 7 effektivsten Methoden nach "Intrusionsgrad" (von leicht bis schwer) auf, um Ihnen die Entscheidung zu erleichtern.
| Methode | Befehl | Ursache | Kontextverlust |
|---|---|---|---|
| Nachricht senden | Text eingeben | Ursache 1 / 6 | Nein |
| Vorgang abbrechen | Ctrl+C |
Ursache 1 / 2 / 3 | Nein |
| Selbstdiagnose | /doctor |
Beliebig | Nein |
| Kontext komprimieren | /compact |
Ursache 3 / 4 | Teilweise (Zusammenfassung) |
| Sitzung leeren | /clear |
Ursache 4 (schwer) | Ja |
| Terminal neu starten | claude --resume |
Ursache 1 / 2 (schwer) | Nein |
| Prozess erzwingen | kill -9 <pid> |
Ursache 1 / 2 (kritisch) | Aktuelle Runde verloren |
Die empfohlene Vorgehensweise lautet: "Erst leicht, dann schwer". Drücken Sie zuerst die Eingabetaste oder senden Sie eine beliebige Nachricht. Wenn das nicht hilft, brechen Sie die aktuelle Runde mit Ctrl+C ab. Wenn das Terminal gar nicht mehr reagiert, schließen Sie es komplett und verwenden Sie claude --resume, um die Sitzung wiederherzustellen.
/doctor ist der von Anthropic empfohlene Diagnosebefehl für den Notfall. Er prüft Installation, Einstellungsdateien, MCP-Server-Listen und die Kontextauslastung. Nach dem Durchlauf erhalten Sie meist konkrete Reparaturvorschläge. Wenn die Ausgabe Context: 87% meldet, ist die Ursache 4 fast sicher; hier hilft /compact sofort.
Für lange Aufgaben empfiehlt es sich, regelmäßig /compact in den Workflow einzubauen, um den Kontext unter 60 % zu halten. Wenn Sie Claude über die APIYI-Plattform (apiyi.com) aufrufen, können Sie zudem separate Kontingente für den Claude Code-Hauptprozess und die MCP-Server beantragen, um Fehlerquellen leichter zu identifizieren.
5 Best Practices zur Vermeidung von Hängern bei Claude Code
Fehlerbehebung ist nur Schadensbegrenzung – ein wirklich stabiler Workflow basiert auf Prävention. Die folgenden 5 Praktiken basieren auf der Analyse der Grundursachen zahlreicher GitHub-Issues und können die Wahrscheinlichkeit von Hängern nahezu auf null reduzieren.
-
Segmentiertes Lesen großer Dateien: Das direkte Lesen von Dateien über 1 MB führt fast zwangsläufig zu Problemen mit dem Kontextfenster. Nutzen Sie stattdessen einen zweistufigen Ansatz: Erst
ls -la, um die Größe zu prüfen, dann das Lesen mitoffset– undlimit-Parametern. Dies vermeidet die Ursache 4. -
Komplexe Aufgaben an Sub-Agents delegieren: Die Sub-Agents von Claude Code verfügen über ein eigenes Kontextfenster. Aufgaben wie das Generieren vieler Dateien oder umfangreiche Code-Refactorings sollten an Sub-Agents ausgelagert werden, um das Haupt-Kontextfenster nicht zu überlasten.
-
Deaktivieren verdächtiger MCP-Server: Jeder zusätzliche MCP-Server erhöht das Risiko von Start-Hängern. Behalten Sie in den Einstellungen nur die MCP-Server, die Sie täglich benötigen, und deaktivieren Sie den Rest. Dies reduziert die Ursache 5 erheblich.
-
Timeouts für das Hauptmodell und Lese-Timeouts festlegen: Eine bewährte Methode in der Community ist es,
STREAM_READ_TIMEOUT_MSauf 120 Sekunden zu setzen und einen externen Watchdog-Prozess zu verwenden, der den JSONL-Datenstrom überwacht. Wenn dieser nicht wächst, wird der Prozess automatisch beendet und neu gestartet. Dies ist äußerst effektiv gegen Ursache 1. -
Stabile API-Verbindungen nutzen: Grenzüberschreitende Aufrufe, Heimnetzwerke oder tmux-Verbindungen erhöhen die Wahrscheinlichkeit von Streaming-Unterbrechungen. Eine einfache Lösung ist die Nutzung einer Aggregator-Plattform wie APIYI (apiyi.com) für den Modellaufruf. Dadurch laufen die TCP-Verbindungen über stabile Proxy-Knoten, was die Häufigkeit von Ursache 1 reduziert.
Teams, die diese 5 Punkte umsetzen, berichten, dass die Anzahl der Hänger pro Woche von 5-10 auf unter 1 sinkt und die durchschnittliche Wiederherstellungszeit von 5-10 Minuten auf wenige Sekunden reduziert wird.
Häufig gestellte Fragen (FAQ)
Q1: Bedeuten unterschiedliche Spinner-Verben, dass Claude unterschiedliche Dinge tut?
Nein. Die 187 Standard-Verben sind lediglich zufällig ausgewählte, vermenschlichte Texte und haben keine direkte Entsprechung zum tatsächlichen Status von Claude. Um den Status zu beurteilen, achten Sie bitte auf den Token-Zähler und die Wartezeit.
Q2: Geht der Kontext nach Ctrl+C verloren?
Nein. Ctrl+C bricht nur den aktuellen, nicht abgeschlossenen Schritt ab; die gesamte Sitzung bleibt erhalten. Wenn Ctrl+C nicht reagiert, können Sie es erneut drücken oder das Terminal schließen und die Sitzung mit claude --resume wiederherstellen.
Q3: Ist es bei der Nutzung von Claude Code in China wahrscheinlicher, dass es zu Hängern kommt?
Netzwerkverbindungen über Grenzen hinweg sind eine der Hauptursachen für Streaming-Unterbrechungen. Es wird empfohlen, Claude-Modelle über Aggregator-Plattformen wie APIYI (apiyi.com) aufzurufen, da stabile Proxy-Knoten die Verbindung zu Anthropic aufrechterhalten, was die Wahrscheinlichkeit von Hängern für Entwickler vor Ort deutlich senkt.
Q4: Was sollte ich tun, wenn ich `Autocompact is thrashing` sehe?
Stoppen Sie die aktuelle Aufgabe sofort und verwenden Sie einen fokussierten Komprimierungsbefehl wie /compact keep only the plan and the diff, um große Mengen an Rohdaten aus dem Kontext zu löschen. Wenn dies fehlschlägt, starten Sie eine neue Sitzung oder stellen Sie das Lesen großer Dateien auf den Sub-Agent-Modus um.
Q5: Kann ich die Spinner-Verben selbst anpassen?
Ja. Fügen Sie in Ihrer ~/.claude/settings.json das Feld spinnerVerbs hinzu. Die Modi können default, append oder replace sein, kombiniert mit einem Array von Strings. Die Community bietet Pakete mit über 88 Themen und 1900+ Verben an, die direkt übernommen werden können.
Zusammenfassung
Das Hängenbleiben von Claude Code ist im Kern ein kombiniertes Problem der drei Subsysteme Streaming-Protokoll, Kontextverwaltung und MCP-Integration in Randfällen. Wenn Sie die 4 Felder der Statusanzeige verstehen, sich die 6 Hauptursachen und 7 Wiederherstellungsmethoden einprägen, verwandeln Sie "unerklärliche Mysterien" in "bekannte Fehler".
Unsere Empfehlung für die Praxis ist, die Wiederherstellungsschritte zur Routine werden zu lassen: Zuerst eine Nachricht senden, dann Strg+C drücken, anschließend /doctor ausführen und schließlich das Terminal mit claude --resume neu starten. In Kombination mit einem stabilen API-Proxy-Dienst und 5 präventiven Maßnahmen – wie das Halten des Kontextfensters unter 80 %, das Auslagern großer Dateien an Subagents und die Nutzung stabiler Verbindungen über APIYI (apiyi.com) – lassen sich die meisten Hänger innerhalb weniger Sekunden selbst beheben.
Autor: APIYI Technik-Team
Kontakt: Erhalten Sie Zugriff auf die gesamte Claude-Modellreihe und stabile API-Proxy-Unterstützung für Claude Code über APIYI (apiyi.com)
Aktualisiert am: 13.05.2026
