# Claude Code wiederherstellen: Safe Mode, /cd und Fallback > Claude Code mit Safe Mode, dem Befehl /cd, Fallback-Modellen und der Wiederherstellung der Einstellungen diagnostizieren. Die Reihenfolge der Prüfungen und die ursprünglichen Einschränkungen. Source: https://ailoot.ai/blog/de/claude-code-safe-mode-recovery/ Canonical: https://ailoot.ai/blog/de/claude-code-safe-mode-recovery/ Language: de Publisher: Ailoot (https://ailoot.ai/) Translation: guide-140 Revision: sha256-493382b23fcc3dd0a3a66a704372f56491b70b41743db2b36545e1b2b4a4e141 Praxisnahe Materialien zur Arbeit mit Agents: [Ailoot-Dokumentation](https://ailoot.ai/docs/). ## Welche Wiederherstellungsfunktionen änderten sich in Claude Code im Juni 2026?
Das Wichtigste Am 8. Juni 2026 fügte Anthropic in Claude Code v2.1.169 das Flag `--safe-mode` und den Befehl `/cd` hinzu. Zwei Tage zuvor führte v2.1.166 Fallback-Modelle ein, bis zu 3 in einer Kette. Diese drei Funktionen lösen den häufigsten Schmerzpunkt beim Vibe Coding: „Alles ist ausgefallen, ich weiß nicht, wer schuld ist, und ich möchte keine Stunde mit einer Neuinstallation verlieren.“
Bisher gab es nur einen Ausweg, wenn Claude Code sich merkwürdig verhielt – ein endloser Ladekringel, ein Absturz beim Start, der Agent ignorierte Regeln in `CLAUDE.md`, ein Hook wurde stillschweigend nicht ausgeführt: Abschnitte in `.claude/settings.json` manuell auskommentieren, MCP-Server einzeln deaktivieren oder im schlimmsten Fall `~/.claude` löschen und neu installieren. In einem beschriebenen Fall wurde `~/.claude` gelöscht und die MCP-Server-Konfiguration ging verloren, deren Zusammenstellung anderthalb Stunden gedauert hatte. Später stellte sich heraus, dass eine Zeile in `CLAUDE.md` schuld war und sich der Fehler in 10 Sekunden hätte finden lassen – klar wurde das allerdings erst nach einer vollständigen Wiederherstellung. Im Juni 2026 führte Anthropic drei Mechanismen ein, die dieses Szenario verändern. Kurz zusammengefasst: Was kam wann hinzu? | Version | Datum | Neuerungen | |----|----|----| | **2.1.166** | 6. Juni 2026 | Einstellung `fallbackModel` + Flag `--fallback-model` für interaktive Sitzungen | | **2.1.169** | 8. Juni 2026 | Flag `--safe-mode` und Umgebungsvariable `CLAUDE_CODE_SAFE_MODE`, Befehl `/cd` | | **2.1.176** | 12. Juni 2026 | Fehlerbehebung: `/cd` und Worktree-Wechsel zeigten nicht mehr den alten Git-Branch an | Im Folgenden wird jeder Mechanismus Schritt für Schritt erklärt, ebenso die Reihenfolge, in der Sie sie anwenden sollten, wenn eine Claude-Code-Sitzung aus dem Ruder läuft. ## Was bringt Claude Code am häufigsten zum Absturz?
Das Wichtigste Nach den beschriebenen Erfahrungen geht Claude Code beim Vibe Coding typischerweise aus vier Gründen kaputt: eine überladene `CLAUDE.md` mit widersprüchlichen Regeln, ein Hook mit falschem Exit-Code, ein MCP-Server, der stillschweigend ausfällt, und überlappende Einstellungen auf drei Ebenen von `settings.json`. Es gibt einen Verursacher, die Diagnose dauert Minuten, und die Panik verleitet dazu, sofort zu `rm -rf` zu greifen.
Im beschriebenen Beispiel wurde `CLAUDE.md` zunächst mit 80 Zeilen erstellt – und einen Monat lang funktionierte alles. Im zweiten Monat fiel auf, dass Claude einmal pro Woche jede festgelegte Regel verletzte: `.env` anfassen, `git push --force` ausführen, in `node_modules` herumstöbern. Nicht böswillig – Claude hatte es einfach vergessen. Einmal wurde `.gitignore` gelöscht, und der Grund war zunächst nicht klar. Dieses Szenario wird ausführlicher im [Leitfaden zu `CLAUDE.md`](https://ailoot.ai/blog/de/claude-md-template/) behandelt. Wenn `CLAUDE.md` auf über 400 Zeilen anwächst, verursacht sie zunehmend stillschweigend Probleme: Sie nimmt beim Start einer Sitzung einen beträchtlichen Teil des Kontextfensters ein und verwässert wichtige Anweisungen mit zweitrangigen. Claude liest die Datei formal weiterhin, sodass es von außen so aussieht, als seien „die Regeln zwar da, aber sie funktionieren nicht“ – ein typisches Zeichen für einen überladenen Vertrag. Hooks sind die zweithäufigste Ursache. Bei `Claude Code hooks` gibt es eine Feinheit, die Anthropic nicht hervorhebt. Das heißt: `sys.exit(1)` in einem Python-Hook (oder ein beliebiges Unix-übliches „mit Fehler fehlgeschlagen“) hält Claude nicht auf. Nur Code `2` blockiert. Im beschriebenen Fall galt der Hook als „striktes Verbot“, tatsächlich protokollierte er aber nur eine Beschwerde und ließ die Aktion zu. MCP-Server bilden die dritte Ebene und können ebenfalls auf ihre eigene Art ausfallen. Das Symptom sieht oft gleich aus: MCP-Befehle sind verfügbar, liefern aber `failed` ohne Traceback zurück. Weitere Informationen zur MCP-Konfiguration und zum Hinzufügen von Servern mit `claude mcp add` finden Sie im [separaten Leitfaden](https://ailoot.ai/blog/de/mcp-servers-claude-code/). Die vierte Ursache ist die dreistufige `settings.json`-Hierarchie. Es gibt `~/.claude/settings.json` (Benutzerebene), `.claude/settings.json` im Projektstamm (Projekt), `.claude/settings.local.json` (lokal) und optional verwaltete Einstellungen einer Unternehmensadministration. Sie werden nach Prioritätsregeln zusammengeführt. Wenn jemand auf Projektebene einen MCP-Server hinzufügt, während auf Benutzerebene ein ähnlicher Eintrag mit einer anderen Startkonfiguration vorhanden ist, entsteht ein stiller Konflikt, der aussieht, als sei „Claude Code kaputt“. ## Wie funktioniert `--safe-mode`, und was wird dadurch deaktiviert?
Das Wichtigste `claude --safe-mode` startet Claude Code mit vollständig deaktivierten Anpassungen: `CLAUDE.md`, Plugins, Skills, Hooks, MCP-Server, Benutzerbefehle, Agents, Ausgabestile, Workflows und Tastenkombinationen. Autorisierung, Modellauswahl, integrierte Tools und Berechtigungen bleiben erhalten. Dies ist ein Diagnosewerkzeug: Verschwindet das Problem im Safe Mode, ist eine der hinzugefügten Ebenen schuld.
Anthropics ursprünglicher Wortlaut im Changelog zu v2.1.169 lautet:

Das Flag --safe-mode (und CLAUDE_CODE_SAFE_MODE) hinzugefügt, um Claude Code mit deaktivierten Anpassungen (CLAUDE.md, Plugins, Skills, Hooks, MCP-Server) zu Diagnosezwecken zu starten.

— Anthropic Claude Code Changelog, https://code.claude.com/docs/en/changelog
Anthropic präzisiert es in der Dokumentation zur Modellkonfiguration:

Um zu prüfen, ob Anpassungen die Ursache sind, starten Sie eine Sitzung mit claude --safe-mode. Dadurch werden CLAUDE.md, Skills, MCP-Server und Hooks deaktiviert. Git-Status und Verzeichnisnamen gelten nicht als Anpassungen und bleiben verfügbar.

— Anthropic Docs - Model configuration, https://code.claude.com/docs/en/model-config
Dies ist ein **Diagnosewerkzeug**, keine „saubere Umgebung“. Safe Mode hilft bei der Beantwortung einer Frage: Liegt das Problem am Verhalten von Claude Code direkt nach der Installation oder an den hinzugefügten Anpassungen? Dies ist Teil des Context Engineering – also der Steuerung dessen, was Claude zu einem bestimmten Zeitpunkt sieht und nicht sieht. Wenn im Safe Mode alles funktioniert, ist klar, dass die Ebenen per binärer Suche geprüft werden müssen. Funktioniert es nicht, liegt das Problem an der Installation selbst, der Autorisierung, dem Netzwerk oder der Infrastruktur; dann ist es sinnvoll, `claude doctor` und die Logs zu prüfen. Was Safe Mode deaktiviert (Anthropics offizielle Liste – 5 Hauptebenen): - `CLAUDE.md` auf allen Ebenen (Benutzer / Projekt) - Plugins - Skills - Hooks - MCP-Server Was weiterhin funktioniert: - Autorisierung (Ihre OAuth-Sitzung oder Ihr API-Schlüssel) - Modellauswahl (`--model sonnet`, `--model opus`) - Integrierte Tools (Read, Write, Bash, Grep usw.) - Berechtigungen - Git-Status - Verzeichnisnamen Ein wichtiges Detail: Safe Mode deaktiviert keine verwalteten Richtlinieneinstellungen einer Unternehmensadministration. Wenn Sie in einem Team arbeiten, in dem Bedrock GovCloud oder eine MDM-Konfiguration `availableModels` festlegt, bleiben diese Einschränkungen bestehen – Safe Mode deaktiviert nur Ihre Anpassungen, nicht die Unternehmensrichtlinien. ## Wie lässt sich eine Ebene isolieren und der Verursacher in 60 Sekunden finden?
Das Wichtigste Schritt 1: Führen Sie `claude --safe-mode` im selben Ordner aus, in dem die Probleme aufgetreten sind. Wenn es funktioniert, liegt das Problem an Ihren Anpassungen. Aktivieren Sie sie dann einzeln wieder: `CLAUDE.md` -> Hooks -> MCP -> Skills. Funktioniert es selbst im Safe Mode nicht, liegt das Problem an der Authentifizierung, Version, Netzwerkverbindung oder am Betriebssystem. Führen Sie in diesem Fall `claude doctor` zur automatischen Diagnose aus, ohne `rm -rf` anzurühren.
Ein Diagnoseszenario für den Fall, dass Claude Code „nicht mehr zuhört“. Die Mindestversion für alle folgenden Befehle ist **Claude Code v2.1.169**. Ist Ihre Version älter, aktualisieren Sie zuerst (`npm update -g @anthropic-ai/claude-code` oder Anthropics nativer Installer). 1. Öffnen Sie denselben Ordner, in dem die Probleme aufgetreten sind. 2. Führen Sie `claude --safe-mode` aus. 3. Wenn Claude sauber startet, prüfen Sie Ihre ursprüngliche Anfrage. Hat es funktioniert? Dann ist eine der Ebenen schuld. Weiter mit Schritt 4. 4. Wenn es im Safe Mode weiterhin nicht funktioniert, rühren Sie die Konfigurationen nicht an. Führen Sie zuerst `claude doctor` aus; prüfen Sie Authentifizierung, Version und konkurrierende Installationen. Sobald Safe Mode sauber startet, aktivieren Sie die Ebenen einzeln, beginnend mit dem wahrscheinlichsten Verursacher. Die Reihenfolge basiert auf den beschriebenen Erfahrungen: 1. **`CLAUDE.md`.** Führen Sie `claude` ohne Safe Mode aus, benennen Sie die Datei aber vorübergehend um: `mv CLAUDE.md CLAUDE.md.bak`. Wenn es funktioniert, ist diese Datei die Ursache. Anschließend können Sie eine binäre Suche durchführen: Die Hälfte der Zeilen beibehalten und prüfen. 2. **Hooks.** Öffnen Sie `.claude/settings.json` und setzen Sie den Abschnitt `hooks` vorübergehend auf `[]`. Starten Sie `claude` neu. Funktioniert es? Dann ist einer der Hooks schuld. Aktivieren Sie sie einzeln wieder. 3. **MCP-Server.** Setzen Sie ebenso in `~/.claude.json` oder `.claude/settings.json` den Abschnitt `mcpServers` vorübergehend auf ein leeres Objekt, starten Sie neu und prüfen Sie. 4. **Skills.** Verschieben Sie `.claude/skills/` in einen temporären Ordner. Starten und prüfen. Was „vorübergehend umbenennen“ bedeutet: Dateien werden während der Diagnose nicht gelöscht. Mit `mv` oder `git stash` können Sie alles mit einem Befehl wiederherstellen, falls sich diese Ebene als unschuldig herausstellt. ## Wie wechselt man mit `/cd` den Arbeitsordner, ohne den Kontext zu verlieren?
Das Wichtigste Der Befehl `/cd ` in Claude Code 2.1.169+ wechselt den Arbeitsordner in der aktiven Sitzung, ohne den Prompt-Cache zu verlieren. Das ist nützlich, wenn die Konfiguration des aktuellen Projekts kaputt ist: Sie können in einen sauberen Ordner wechseln, prüfen, ob Claude funktioniert, und zurückkehren. Früher mussten Sie die Sitzung schließen und neu starten.
Aus dem Changelog zu v2.1.169 vom 8. Juni:

Den Befehl /cd hinzugefügt, um die Sitzung in einen neuen Arbeitsordner zu wechseln, ohne den Prompt-Cache mitten in der Sitzung zurückzusetzen.

— Anthropic Claude Code Changelog, https://code.claude.com/docs/en/changelog
Warum das bei der Fehlersuche nützlich ist. Angenommen, Sie befinden sich im Projektordner `~/work/myapp`, und Claude Code verhält sich merkwürdig. Früher ließ sich nur durch Schließen der Sitzung, Wechsel in einen anderen Ordner und Neustart prüfen, ob es „überhaupt funktioniert“. Dabei gingen Kontext, Verlauf und der aufgewärmte Prompt-Cache verloren. Jetzt geht es so: ```bash # In the same session: /cd ~/sandbox/test ``` Claude wechselt in den neuen Ordner und liest dessen `CLAUDE.md` (falls vorhanden) als Nachricht, nicht als Ersatz für den System-Prompt – der Cache bleibt also erhalten. Wenn in `~/sandbox/test` alles funktioniert, liegt das Problem eindeutig in der Konfiguration von `~/work/myapp`. Am 12. Juni wurde in v2.1.176 eine unangenehme Regression behoben – `/cd` zeigte bis zu einem vollständigen Neustart den alten Git-Branch an. Wenn Sie eine ältere Version verwenden, aktualisieren Sie entweder oder ignorieren Sie `git status` einfach in den ersten Nachrichten nach dem Wechsel – der Status wird sich aktualisieren. ## Wie konfiguriert man Fallback-Modelle für einen 529-Fehler?
Das Wichtigste In v2.1.166 fügte Anthropic `fallbackModel` hinzu – eine Kette von bis zu 3 Modellen, die nacheinander ausprobiert werden, wenn das primäre Modell überlastet oder nicht verfügbar ist. Die Kette wird nur durch Überlastung und nicht wiederholbare Serverfehler ausgelöst. Autorisierungs-, Abrechnungs-, Rate-Limit- und Transportfehler lösen die Fallback-Kette nicht aus – für sie gilt die reguläre Wiederholungslogik.
Im beschriebenen Szenario läuft einmal pro Woche eine lange Aufgabe mit Opus in einem Projekt; nach 10 Minuten gibt die API 529 Overloaded zurück und die Sitzung stürzt ab. Früher musste man entweder warten oder manuell mit `--model sonnet` zu Sonnet wechseln und den aufgewärmten Kontext verlieren. In einem großen `business/`-Ordner mit Second-Brain-Struktur kostet das etwa zwanzig Minuten Arbeit. Jetzt gibt es einen geeigneten Mechanismus. Das genaue Zitat aus der offiziellen Dokumentation:

Wenn das primäre Modell überlastet oder nicht verfügbar ist oder einen anderen nicht wiederholbaren Serverfehler zurückgibt, kann Claude Code zu einem Fallback-Modell wechseln, anstatt die Anfrage fehlschlagen zu lassen. Autorisierungs-, Abrechnungs-, Rate-Limit-, Anfragegrößen- und Transportfehler lösen niemals einen Wechsel aus – für sie gilt der reguläre Wiederholungs- und Fehlerbehandlungspfad.

— Anthropic Docs - Model configuration, https://code.claude.com/docs/en/model-config
Und separat dazu, wie die Kette funktioniert:

Konfigurieren Sie ein oder mehrere Fallback-Modelle. Claude Code probiert sie der Reihe nach aus und zeigt beim Wechsel eine Benachrichtigung an. Der Wechsel gilt nur für den aktuellen Turn – bei der nächsten Nachricht wird erneut das primäre Modell verwendet. Nach der Deduplizierung ist die Kette auf drei Modelle begrenzt; weitere Einträge werden ignoriert.

— Anthropic Docs - Model configuration, https://code.claude.com/docs/en/model-config
Es gibt zwei Möglichkeiten zur Konfiguration. Über die CLI: ```bash claude --fallback-model sonnet,haiku ``` Über `~/.claude/settings.json`: ```json { "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"] } ``` Eine gesonderte Feinheit betrifft Rate-Limits. Anthropic leitet einen 429-Fehler bewusst nicht durch die Kette, damit das Anfrage-Limit nicht durch einen Wechsel zum nächsten Modell umgangen werden kann. Fallback funktioniert nur, wenn das primäre Modell überlastet oder nicht verfügbar ist oder einen nicht wiederholbaren Serverfehler zurückgibt (zum Beispiel 529 Overloaded). Für Rate-Limits gelten die reguläre Wiederholungslogik und das Backoff. Noch eine Feinheit: Am 12. Juni wurde in v2.1.174 eine Regression behoben, bei der die Kompaktierung `--fallback-model` nicht berücksichtigt hatte. Wenn eine lange Sitzung während einer Überlastung kompakt wird, wurde vor dieser Korrektur das Fallback-Modell nicht aufgerufen. Wenn Sie mit langen Sitzungen arbeiten (`/compact`, `/loop` über Nacht), aktualisieren Sie auf mindestens v2.1.174. ## Was ist zu beheben, wenn `CLAUDE.md`, ein Hook, MCP oder ein Skill schuld ist?
Das Wichtigste Wenn der Safe Mode die schuldige Ebene identifiziert, unterscheidet sich die Lösung je nach Ebene. Bei `CLAUDE.md` verwenden Sie eine binäre Suche oder wechseln zu einer fertigen Vorlage mit weniger als 200 Zeilen. Bei einem Hook prüfen Sie Exit-Code (2 blockiert, 1 nicht) und Logik. Bei MCP entfernen Sie einen Server und prüfen. Bei einem Skill prüfen Sie die `SKILL.md` auf Widersprüche zu `CLAUDE.md`.
Konkrete Strategien für jede Ebene. ### Wenn `CLAUDE.md` schuld ist Öffnen Sie die Datei und prüfen Sie ihre Größe. Nach den beschriebenen Erfahrungen sollte die aktive `CLAUDE.md` **höchstens 200 Zeilen lang sein**; verschieben Sie den Rest in Router und ergänzende Dokumente neben dem Projekt (die vollständige Second-Brain-Struktur finden Sie im [Leitfaden zum Second Brain](https://ailoot.ai/blog/de/claude-code-second-brain/)). Bei über 400 Zeilen ist sie mit ziemlicher Sicherheit schuld. Schritte: 1. Erstellen Sie eine Sicherung: `cp CLAUDE.md CLAUDE.md.full`. 2. Wechseln Sie zu einer kurzen, funktionierenden Vorlage. Eine fertige Vorlage finden Sie im [Leitfaden „CLAUDE.md konfigurieren“](https://ailoot.ai/blog/de/claude-md-template/). 3. Starten Sie Claude Code neu. Prüfen Sie. 4. Wenn es funktioniert, stellen Sie Regeln in kleinen Blöcken von 10–20 Zeilen wieder her und prüfen Sie nach jedem Block. 5. Finden Sie den Block, der das Verhalten beeinträchtigt. Schreiben Sie ihn als Hook mit dem korrekten Exit-Code um (Exit-Codes für Hooks werden im nächsten Unterabschnitt dieses H2 behandelt). ### Wenn ein Hook schuld ist Die wichtigste Frage ist, ob der Exit-Code korrekt ist. Claude-Code-Hooks verwenden: - **Exit 0** – alles in Ordnung; die Aktion wird ausgeführt. - **Exit 1** – ein Fehler, aber **nicht blockierend**. Claude macht weiter, als wäre nichts passiert. - **Exit 2** – ein **blockierender** Fehler. Nur dieser hält die Aktion tatsächlich auf. Wenn Sie `sys.exit(1)` oder `exit 1` in einem Shell-Hook geschrieben haben, weil Sie dachten, damit zu blockieren, funktioniert dieser Code in Claude Code wie ein Warnprotokoll, ohne die Aktion aufzuhalten. Ändern Sie ihn in `2`. Einzelheiten zu Hooks und ihrer Konfiguration ohne diese Stolperfalle finden Sie im [separaten Leitfaden](https://ailoot.ai/blog/de/claude-code-hooks/). Ein zweiter häufiger Fall ist, dass ein Hook ungültiges JSON auf stdout zurückgibt. Claude Code parst die Hook-Antwort als JSON; enthält sie anderen Inhalt (ein Log, einen Fortschrittsmarker, ein Emoji), gilt der Hook als fehlgeschlagen und die Aktion wird ausgeführt. Regel: **stdout enthält nur JSON; alles andere geht an stderr**. Der dritte Fall ist ein Hook, der etwas aus `~/.claude/` liest, das Safe Mode ausgeblendet hat. Das ist ein normales Szenario. Beheben Sie es nicht durch Änderungen am Hook, sondern prüfen Sie zu Beginn `os.environ.get('CLAUDE_CODE_SAFE_MODE')` und beenden Sie den Hook mit 0. ### Wenn ein MCP-Server schuld ist Symptome: MCP-Befehle sind verfügbar, liefern aber `failed` ohne klaren Traceback zurück. Schritte: 1. Führen Sie `claude mcp list` aus – welche Server sind definiert? 2. Deaktivieren Sie Server einzeln in `~/.claude.json`: Benennen Sie den Schlüssel `claude-server-A` in `_claude-server-A` um (dadurch wird er deaktiviert, aber nicht gelöscht). 3. Starten Sie `claude` neu. Prüfen Sie, welche Aufrufe funktionieren. 4. Wenn Sie den schuldigen Server gefunden haben, prüfen Sie sein Log: `claude mcp logs `. 5. Prüfen Sie bei einem Server eines Drittanbieters (`@modelcontextprotocol/server-postgres` und ähnlichen), ob es eine aktuelle Version gibt. Das MCP-Ökosystem ist noch in Bewegung; Server gehen durch Updates von Claude Code regelmäßig kaputt. Wenn Sie „Abstürze beim Start und nur mit zwei MCPs“ erleben, vergleichen Sie das Verhalten im Safe Mode ohne MCP. ### Wenn ein Skill schuld ist Ein Skill besteht aus `SKILL.md` und Code in `.claude/skills//`. Symptome: Claude ignoriert den Skill, wendet ihn zum falschen Zeitpunkt an oder nutzt ihn, produziert dabei aber unbrauchbare Ergebnisse. Schritte: 1. Öffnen Sie `SKILL.md`. Prüfen Sie die Beschreibung – sie **sollte 1–2 Sätze umfassen und konkret beschreiben, wann der Skill zu verwenden ist**. Steht dort „ein universeller Helfer für alles“, versteht Claude nicht, wann der Skill aufgerufen werden soll. 2. Prüfen Sie auf Widersprüche mit `CLAUDE.md`. Wenn `CLAUDE.md` „immer Tests schreiben“ vorgibt, die Skill-Beschreibung aber „für schnelles Prototyping ohne Tests verwenden“ sagt, liegt ein Konflikt vor. 3. Wenn der Skill externe Befehle verwendet (npm, python, git), prüfen Sie, ob sie im systemweiten PATH verfügbar sind. Ein Skill hat eine eigene minimale Umgebung. ## Wenn Safe Mode nicht hilft: vor der Reparatur diagnostizieren und Zustand sichern
Das Wichtigste Scheitert auch Safe Mode, bleiben Installation, Autorisierung, Netzwerk oder Infrastruktur als Ursachen. Führen Sie `claude doctor` aus und prüfen Sie seine Nachweise. Ein unklarer Bericht rechtfertigt keine Löschung von Einstellungen oder Sitzungen. Sichern und prüfen Sie zuerst den vollständigen Zustand; reparieren Sie dann nur die diagnostisch betroffene Installation.
Das Entfernen von Nutzerzustand ist keine Diagnoseabkürzung. Nutzen Sie die folgenden Prüfungen zur Fehlereingrenzung. Bleiben sie unklar, sichern Sie die Nachweise und untersuchen Sie weiter. Jede Installationsreparatur beginnt mit geprüftem Backup und bewahrt Konto und Zugangsspeicheridentität. Reihenfolge: 1. **`claude doctor`** – automatische Diagnose. Anthropic schreibt in seiner Dokumentation:

Wenn claude --version funktioniert, aber etwas anderes schiefläuft, führen Sie claude doctor aus, um einen automatischen Diagnosebericht zu erstellen.

— Anthropic Docs - Troubleshoot installation, https://code.claude.com/docs/en/troubleshoot-install
2. **Prüfen Sie auf konkurrierende Installationen.** Viele haben gleichzeitig sowohl eine globale npm-Version als auch den nativen Installer installiert:

Mehrere Claude-Code-Installationen können zu Versionsabweichungen oder unerwartetem Verhalten führen.

— Anthropic Docs - Troubleshoot installation, https://code.claude.com/docs/en/troubleshoot-install
3. **Prüfen Sie, ob `ANTHROPIC_API_KEY` Ihre OAuth-Sitzung abfängt.** Dies ist eine häufige Ursache für „nichts funktioniert, der Schlüssel ist abgelaufen“:

Wenn `ANTHROPIC_API_KEY` gesetzt ist und Sie ihn bestätigt haben, verwendet Claude Code diesen Schlüssel statt Ihrer OAuth-Zugangsdaten für das Abonnement.

— Anthropic Docs - Troubleshoot installation, https://code.claude.com/docs/en/troubleshoot-install
Lösung: `unset ANTHROPIC_API_KEY` in der aktuellen Shell-Sitzung ausführen oder die Variable aus `~/.zshrc` / `~/.bashrc` entfernen. 4. **Reparieren Sie nur die diagnostisch betroffene Installation und sichern Sie zuerst alle Nutzerdaten.** Weder ein Safe-Mode-Fehler noch ein unklarer doctor-Bericht begründet das Entfernen von Nutzerdaten. Stoppen Sie für eine konsistente Sicherung alle Claude-Sitzungen und sonstigen Schreiber. Behalten Sie Unix-Konto, HOME, Betriebssystem-Zugangsspeicher und Anthropic-Konto bei. Rotieren Sie keine Schlüssel und erstellen Sie keine Ersatzidentität. Das folgende Beispiel gilt für **Linux mit GNU tar**. Verwenden Sie auf macOS oder Windows ein Sicherungstool, das dort ACLs, erweiterte Attribute, Links und Metadaten bewahrt. Prüfen Sie eine Wiederherstellung, bevor Sie fortfahren; GNU-spezifische Flags funktionieren nicht automatisch dort. Das Archiv enthält Zugangsdaten und Sitzungsprotokolle und muss privat außerhalb von Repositorys bleiben. ```bash # Run as the same user who owns the Claude state, after stopping writers. set -eu umask 077 backup_dir=$(mktemp -d "$HOME/.claude-recovery-XXXXXXXX") set -- if [ -e "$HOME/.claude" ] || [ -L "$HOME/.claude" ]; then set -- "$@" .claude fi if [ -e "$HOME/.claude.json" ] || [ -L "$HOME/.claude.json" ]; then set -- "$@" .claude.json fi [ "$#" -gt 0 ] || exit 1 tar --acls --xattrs --numeric-owner -cpf "$backup_dir/claude-state.tar" -C "$HOME" "$@" tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$HOME" sha256sum "$backup_dir/claude-state.tar" > "$backup_dir/claude-state.sha256" (cd "$backup_dir" && sha256sum -c claude-state.sha256) mkdir "$backup_dir/restore-check" tar --acls --xattrs -xpf "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check" tar --acls --xattrs --compare -f "$backup_dir/claude-state.tar" -C "$backup_dir/restore-check" printf 'Verified recovery directory: %s\n' "$backup_dir" ``` Alle Befehle müssen erfolgreich sein. Gesichert werden der gesamte vorhandene `.claude`-Baum einschließlich ignorierter und nicht erfasster Sitzungen und Pluginzustände sowie `.claude.json`, nicht nur Git-Einstellungen. Ist ein Pfad ein Symlink oder liegen Daten an einem separat konfigurierten Ort, stoppen Sie und nehmen Sie das aufgelöste Ziel in dieselbe geprüfte Sicherung auf. Ein archivierter Link allein sichert dessen Ziel nicht. macOS Keychain und andere externe Zugangsspeicher fehlen im Archiv; behalten Sie diese Identitäten unverändert. Identifiziert die Diagnose ausdrücklich die **alte lokale Installation** als Konflikt, verschieben Sie nur diese in das private Wiederherstellungsverzeichnis, statt Konfiguration und Sitzungen zu löschen: ```bash # Use the verified backup_dir from the previous block. if [ -d "$HOME/.claude/local" ]; then mv "$HOME/.claude/local" "$backup_dir/legacy-local" fi ``` Entfernen Sie eine npm-Installation nur bei diagnostisch bestätigtem Konflikt, wenn die native bleiben soll. Nutzen Sie anschließend den [dokumentierten nativen Installer](https://code.claude.com/docs/en/setup), ohne `.claude` oder `.claude.json` zu löschen: ```bash curl -fsSL https://claude.ai/install.sh | bash claude --version claude doctor ``` Unter Windows bleibt der native Installationsbefehl: ```powershell irm https://claude.ai/install.ps1 | iex ``` **Separat wiederherstellen.** Stoppen Sie erneut Schreiber. Prüfen Sie die Archivprüfsumme, extrahieren Sie wie oben in ein leeres Wiederherstellungsverzeichnis und vergleichen Sie erfolgreich vor Verwendung. Soll die verschobene alte Installation zurück, bestätigen Sie zuerst das Fehlen von `$HOME/.claude/local` und verschieben Sie `$backup_dir/legacy-local` genau dorthin. Stellen Sie eine diagnostisch betroffene Einstellungsdatei erst nach Sicherung eines aktuellen Ersatzes aus der geprüften Extraktion wieder her. Überlagern Sie niemals blind den gesamten Baum. Sitzungen, MCP-Einstellungen und Originalidentität bleiben erhalten. Ein Git-Snapshot allein sichert keine ignorierten Protokolle, Zugangsdaten und Dateimetadaten. ## Was sollten Sie NICHT tun, wenn Claude Code kaputt ist?
Das Wichtigste Sechs Anti-Patterns aus den beschriebenen Supportfällen: Schlüssel vor der Diagnose ändern, sofort einen vollständigen Reset durchführen, wegen eines UI-Fehlers bei einem Hook in Panik geraten, den Exit-Code eines Hooks erhöhen, bevor die Logik korrigiert ist, `CLAUDE.md` ohne Safe-Mode-Sicherung bearbeiten und glauben, „Claude repariert sein MCP selbst“. Jedes davon kostet Stunden, keines ist nötig.
### Ändern Sie die Schlüssel nicht vor der Diagnose „Die Autorisierung funktioniert nicht“ liegt in 90% der Fälle entweder daran, dass `ANTHROPIC_API_KEY` das Abonnement abfängt, an einem UI-Fehler eines Hooks oder an einem ausgefallenen MCP. Eine Schlüsselrotation behebt nichts davon, verursacht aber eine weitere Stunde Ausfallzeit: Sie müssen den alten Schlüssel widerrufen, einen neuen ausstellen, CI damit neu signieren und die Variablen in der Produktion aktualisieren. Führen Sie zuerst `claude --safe-mode` aus. Funktioniert es? Dann liegt das Problem an den Anpassungen; die Schlüssel müssen nicht angefasst werden. ### Führen Sie keinen vollständigen Reset vor dem Safe Mode durch Safe Mode stellt in 1 Sekunde eine isolierte Umgebung bereit. Das Löschen von `.claude` kann Sitzungen, MCP-Konfiguration und anderen nicht erfassten Zustand zerstören. Diagnostizieren Sie zuerst, prüfen Sie ein privates Backup und verschieben Sie nur die tatsächlich betroffene Installations- oder Konfigurationsebene reversibel. ### Geraten Sie wegen eines UI-Fehlers bei einem Hook nicht in Panik Bevor Sie etwas beheben, prüfen Sie, ob der Hook tatsächlich ausgeführt wurde (über ein Log an `stderr` oder eine explizite Ausgabe), statt sich auf die visuelle Anzeige zu verlassen. ### Erhöhen Sie den Exit-Code eines Hooks nicht, bevor die Logik korrigiert ist Wenn Ihr blockierender Hook nicht blockiert, liegt es nahe, `exit 2` zu setzen und die Sache für erledigt zu erklären. Das ist ein funktionierender Patch, verdeckt aber ein weiteres Problem: Wenn die Sperre einen Monat lang nicht funktionierte, wurde alles ausgeführt, was der Hook hätte verhindern sollen. Gehen Sie zuerst das Git-Log durch und finden Sie genau heraus, was durchgerutscht ist. Fügen Sie anschließend die Sperre hinzu. Andernfalls macht eine geschlossene Sperre nicht rückgängig, was zuvor geschehen ist. ### Bearbeiten Sie die produktive `CLAUDE.md` nicht ohne Safe-Mode-Sicherung Im beschriebenen Fall bearbeiten Sie `CLAUDE.md`, Claude verhält sich merkwürdig, Sie führen `git diff` aus und sehen, dass jemand am selben Abend auch einen MCP-Server und einen Hook zum Repo hinzugefügt hat. Sie geben Ihrer Änderung die Schuld, setzen sie zurück, und Claude verhält sich weiterhin merkwürdig. Regel: Führen Sie vor `git revert` `claude --safe-mode` aus. Bleibt das Problem im Safe Mode bestehen, hatte Ihre Änderung nichts damit zu tun; ein Zurücksetzen ist nicht nötig. ### Glauben Sie nicht, dass „Claude sein MCP selbst repariert“ Ein typisches Szenario: Sie bitten Claude, „ein bestimmtes Tool zum MCP-Server hinzuzufügen“. Claude schreibt die funktionierende Konfiguration neu, alles geht kaputt, und anschließend verbringt Claude mehrere Turns damit, den selbst verursachten Schaden zu beheben – dabei verbraucht es das Sitzungskontingent. Wenn MCP kaputt ist, **beschaffen Sie die Konfiguration manuell** und überlassen Sie sie nicht dem Agent. Ein Teil seines Tool-Arsenals läuft ebenfalls über MCP, und ein kaputtes MCP bedeutet einen kaputten Diagnostiker. ## Wohin geht es nach der Wiederherstellung?
Das Wichtigste Sobald Sie Claude Code wiederhergestellt haben, treffen Sie Vorsorgemaßnahmen, damit es nicht erneut kaputtgeht. Mindestens: `disableBypassPermissionsMode: "disable"` in den Benutzereinstellungen, Hooks, die `.env` und `git push --force` blockieren, sowie eine Sandbox für lange autonome Durchläufe. Der Präventionsleitfaden ist das Gegenstück.
Kehren Sie nach der Analyse des Vorfalls nicht sofort zur Arbeit zurück. Treffen Sie zuerst Vorsorgemaßnahmen, damit sich der Vorfall nicht wiederholt. Ein Second Brain (der Ordner `business/` mit der Projektstruktur) und `CLAUDE.md` kosten Stunden; sie manuell wiederherzustellen ist schwierig – das ist ein gewichtiger Grund. Mindestumfang: 1. **`~/.claude/settings.json`** mit `permissions.disableBypassPermissionsMode: "disable"` – ein architektonisches Verbot des Bypass-Modus, sodass ein versehentlich gestartetes `--dangerously-skip-permissions` einfach nicht funktioniert. 2. **Hooks für `Read(./env*)`, `Bash(git push --force)`, `Write(./node_modules/**)`** – Dinge, die auf der Ebene verbindlicher Regeln abgefangen werden müssen, nicht durch bloße Wünsche. 3. **Sandbox-Konfiguration für lange autonome Durchläufe** (`/loop`, `/schedule`). 4. **`/compact` mit eigenen Regeln** dafür, was aus dem Kontext verworfen werden soll, damit Claude sich nicht selbst aufzehrt. Das vollständige vierstufige Schutzkonzept finden Sie im [Leitfaden „Claude Code so konfigurieren, dass es Ihr Projekt nicht über Nacht beschädigt“](https://ailoot.ai/blog/de/claude-code-safe-overnight-setup/). Ein Leitfaden behandelt die Vorsorge vor dem Start von `/loop`; der andere die Wiederherstellung, nachdem `/loop` bereits etwas beschädigt hat. Ein logisches Paar.
### Quellen - [Anthropic Claude Code Changelog](https://code.claude.com/docs/en/changelog) – offizielles Changelog zu v2.1.166 (`fallbackModel`), v2.1.169 (Safe Mode, /cd), v2.1.174 (Kompaktierungsfehler behoben), v2.1.176 (Git-Branch-Fehler bei /cd behoben). - [Anthropic Docs - Model configuration](https://code.claude.com/docs/en/model-config) – Abschnitte „Fallback model chains“, „Check what triggered fallback“, „Setting your model“. - [Anthropic Docs - Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install) – konkurrierende Installationen, `claude doctor`, Abfangen von `ANTHROPIC_API_KEY`.
Praxisnahe Materialien: [Ailoot-Dokumentation](https://ailoot.ai/docs/). Weitere Materialien und Tools: [Ailoot](https://ailoot.ai/). ## Fragen und Antworten ### Bedeutet ein Safe-Mode-Fehler, dass ich ~/.claude löschen sollte? Nein. Installation, Autorisierung, Netzwerk und Infrastruktur bleiben zu untersuchen. Ein unklarer doctor-Bericht belegt keinen Löschbedarf für Einstellungen oder Sitzungen. Reparieren Sie nur die diagnostisch betroffene Ebene. ### Was muss vor einer Installationsreparatur erhalten bleiben? Stoppen Sie Schreiber und sichern Sie den vollständigen Claude-Zustand einschließlich Sitzungen, Plugin-/MCP-Konfiguration, ignorierter Dateien und Metadaten. Prüfen Sie Prüfsumme und Extraktion, bewahren Sie Konto und Zugangsspeicher und stellen Sie nur die betroffene Ebene ohne blindes Überlagern wieder her. ## Ailoot · Das Unternehmen und sein Projektportfolio Ailoot baut auf bewährte Betriebserfahrung, einen großen Kundenstamm, stabilen Service und kontinuierliche KPI-Kontrolle. Das Unternehmen und sein Projektportfolio: Millionen von Kunden; monatliche Umsätze in Milliardenhöhe. Ailoot nutzt diese Betriebserfahrung für den API-Zugang zu KI-Funktionen in Kundenprodukten, Agenten, Anwendungen und Automatisierungen.