Fehlerbehebung

​

Häufige Installationsprobleme

​

Windows-Installationsprobleme: Fehler in WSL

Sie könnten auf die folgenden Probleme in WSL stoßen:

Probleme bei der Betriebssystem-/Plattformerkennung: Wenn Sie während der Installation einen Fehler erhalten, verwendet WSL möglicherweise Windows npm. Versuchen Sie:

• Führen Sie npm config set os linux vor der Installation aus
• Installieren Sie mit npm install -g @anthropic-ai/claude-code --force --no-os-check (Verwenden Sie NICHT sudo)

Node nicht gefunden Fehler: Wenn Sie exec: node: not found beim Ausführen von claude sehen, verwendet Ihre WSL-Umgebung möglicherweise eine Windows-Installation von Node.js. Sie können dies mit which npm und which node bestätigen, die auf Linux-Pfade zeigen sollten, die mit /usr/ beginnen, anstatt mit /mnt/c/. Um dies zu beheben, versuchen Sie Node über den Paketmanager Ihrer Linux-Distribution oder über nvm zu installieren.

nvm-Versionskonflikte: Wenn Sie nvm sowohl in WSL als auch in Windows installiert haben, können Sie Versionskonflikte beim Wechseln von Node-Versionen in WSL erleben. Dies geschieht, weil WSL standardmäßig den Windows-PATH importiert, wodurch Windows nvm/npm Vorrang vor der WSL-Installation erhält.

Sie können dieses Problem identifizieren durch:

• Ausführen von which npm und which node - wenn sie auf Windows-Pfade zeigen (beginnend mit /mnt/c/), werden Windows-Versionen verwendet
• Erleben von defekter Funktionalität nach dem Wechseln von Node-Versionen mit nvm in WSL

Um dieses Problem zu lösen, korrigieren Sie Ihren Linux-PATH, um sicherzustellen, dass die Linux node/npm-Versionen Vorrang haben:

Primäre Lösung: Stellen Sie sicher, dass nvm ordnungsgemäß in Ihrer Shell geladen wird

Die häufigste Ursache ist, dass nvm nicht in nicht-interaktiven Shells geladen wird. Fügen Sie das Folgende zu Ihrer Shell-Konfigurationsdatei hinzu (~/.bashrc, ~/.zshrc, etc.):

# Load nvm if it exists
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Oder führen Sie direkt in Ihrer aktuellen Sitzung aus:

source ~/.nvm/nvm.sh

Alternative: PATH-Reihenfolge anpassen

Wenn nvm ordnungsgemäß geladen ist, aber Windows-Pfade immer noch Vorrang haben, können Sie Ihre Linux-Pfade explizit dem PATH in Ihrer Shell-Konfiguration voranstellen:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

​

Linux- und Mac-Installationsprobleme: Berechtigung oder Befehl nicht gefunden Fehler

Bei der Installation von Claude Code mit npm können PATH-Probleme den Zugriff auf claude verhindern. Sie können auch auf Berechtigungsfehler stoßen, wenn Ihr npm-Global-Präfix nicht benutzerschreibbar ist (z.B. /usr oder /usr/local).

​

Empfohlene Lösung: Native Claude Code-Installation

Claude Code hat eine native Installation, die nicht von npm oder Node.js abhängt.

Verwenden Sie den folgenden Befehl, um den nativen Installer auszuführen.

macOS, Linux, WSL:

# Install stable version (default)
curl -fsSL https://claude.ai/install.sh | bash

# Install latest version
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Install specific version number
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell:

# Install stable version (default)
irm https://claude.ai/install.ps1 | iex

# Install latest version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Install specific version number
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Dieser Befehl installiert den entsprechenden Build von Claude Code für Ihr Betriebssystem und Ihre Architektur und fügt einen Symlink zur Installation bei ~/.local/bin/claude hinzu.

​

Alternative Lösung: Migration zur lokalen Installation

Alternativ, wenn Claude Code läuft, können Sie zu einer lokalen Installation migrieren:

claude migrate-installer

Dies verschiebt Claude Code nach ~/.claude/local/ und richtet einen Alias in Ihrer Shell-Konfiguration ein. Kein sudo ist für zukünftige Updates erforderlich.

Nach der Migration starten Sie Ihre Shell neu und überprüfen dann Ihre Installation:

Auf macOS/Linux/WSL:

which claude  # Should show an alias to ~/.claude/local/claude

Auf Windows:

where claude  # Should show path to claude executable

Installation überprüfen:

claude doctor # Check installation health

​

Berechtigungen und Authentifizierung

​

Wiederholte Berechtigungsaufforderungen

Wenn Sie sich dabei wiederfinden, dieselben Befehle wiederholt zu genehmigen, können Sie bestimmte Tools erlauben, ohne Genehmigung zu laufen, indem Sie den /permissions-Befehl verwenden. Siehe Berechtigungsdokumentation.

​

Authentifizierungsprobleme

Wenn Sie Authentifizierungsprobleme haben:

1. Führen Sie /logout aus, um sich vollständig abzumelden
2. Schließen Sie Claude Code
3. Starten Sie mit claude neu und schließen Sie den Authentifizierungsprozess erneut ab

Wenn Probleme bestehen bleiben, versuchen Sie:

rm -rf ~/.config/claude-code/auth.json
claude

Dies entfernt Ihre gespeicherten Authentifizierungsinformationen und erzwingt eine saubere Anmeldung.

​

Leistung und Stabilität

​

Hohe CPU- oder Speichernutzung

Claude Code ist darauf ausgelegt, mit den meisten Entwicklungsumgebungen zu arbeiten, kann aber erhebliche Ressourcen verbrauchen, wenn große Codebasen verarbeitet werden. Wenn Sie Leistungsprobleme haben:

1. Verwenden Sie /compact regelmäßig, um die Kontextgröße zu reduzieren
2. Schließen und starten Sie Claude Code zwischen größeren Aufgaben neu
3. Erwägen Sie, große Build-Verzeichnisse zu Ihrer .gitignore-Datei hinzuzufügen

​

Befehl hängt oder friert ein

Wenn Claude Code nicht reagiert:

1. Drücken Sie Ctrl+C, um zu versuchen, die aktuelle Operation abzubrechen
2. Wenn es nicht reagiert, müssen Sie möglicherweise das Terminal schließen und neu starten

​

Such- und Entdeckungsprobleme

Wenn das Such-Tool, @file-Erwähnungen, benutzerdefinierte Agenten und benutzerdefinierte Slash-Befehle nicht funktionieren, installieren Sie das System-ripgrep:

# macOS (Homebrew)  
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep

Setzen Sie dann USE_BUILTIN_RIPGREP=0 in Ihrer Umgebung.

​

Langsame oder unvollständige Suchergebnisse auf WSL

Festplatten-Leseleistungsstrafen beim Arbeiten über Dateisysteme auf WSL können zu weniger als erwarteten Übereinstimmungen führen (aber nicht zu einem vollständigen Mangel an Suchfunktionalität), wenn Claude Code auf WSL verwendet wird.

Lösungen:

1. Spezifischere Suchen einreichen: Reduzieren Sie die Anzahl der durchsuchten Dateien, indem Sie Verzeichnisse oder Dateitypen angeben: “Suche nach JWT-Validierungslogik im auth-service-Paket” oder “Finde Verwendung von md5-Hash in JS-Dateien”.

2. Projekt zum Linux-Dateisystem verschieben: Wenn möglich, stellen Sie sicher, dass sich Ihr Projekt auf dem Linux-Dateisystem (/home/) befindet und nicht auf dem Windows-Dateisystem (/mnt/c/).

3. Natives Windows verwenden: Erwägen Sie, Claude Code nativ auf Windows anstatt über WSL auszuführen, für bessere Dateisystemleistung.

​

IDE-Integrationsprobleme

​

JetBrains IDE nicht auf WSL2 erkannt

Wenn Sie Claude Code auf WSL2 mit JetBrains IDEs verwenden und “No available IDEs detected”-Fehler erhalten, liegt dies wahrscheinlich an der Netzwerkkonfiguration von WSL2 oder daran, dass die Windows-Firewall die Verbindung blockiert.

​

WSL2-Netzwerkmodi

WSL2 verwendet standardmäßig NAT-Netzwerk, was die IDE-Erkennung verhindern kann. Sie haben zwei Optionen:

Option 1: Windows-Firewall konfigurieren (empfohlen)

1. Finden Sie Ihre WSL2-IP-Adresse:

   wsl hostname -I
   # Example output: 172.21.123.456
   

2. Öffnen Sie PowerShell als Administrator und erstellen Sie eine Firewall-Regel:

   New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
   

   (Passen Sie den IP-Bereich basierend auf Ihrem WSL2-Subnetz aus Schritt 1 an)

3. Starten Sie sowohl Ihre IDE als auch Claude Code neu

Option 2: Zu gespiegeltem Netzwerk wechseln

Fügen Sie zu .wslconfig in Ihrem Windows-Benutzerverzeichnis hinzu:

[wsl2]
networkingMode=mirrored

Starten Sie dann WSL mit wsl --shutdown von PowerShell neu.

Für zusätzliche JetBrains-Konfigurationstipps siehe unseren IDE-Integrationsleitfaden.

​

Meldung von Windows-IDE-Integrationsproblemen (sowohl nativ als auch WSL)

Wenn Sie IDE-Integrationsprobleme auf Windows haben, erstellen Sie bitte ein Issue mit den folgenden Informationen: ob Sie nativ (git bash) oder WSL1/WSL2 sind, WSL-Netzwerkmodus (NAT oder gespiegelt), IDE-Name/Version, Claude Code-Erweiterungs-/Plugin-Version und Shell-Typ (bash/zsh/etc)

​

ESC-Taste funktioniert nicht in JetBrains (IntelliJ, PyCharm, etc.) Terminals

Wenn Sie Claude Code in JetBrains-Terminals verwenden und die ESC-Taste den Agenten nicht wie erwartet unterbricht, liegt dies wahrscheinlich an einem Tastenkombinationskonflikt mit JetBrains’ Standard-Shortcuts.

Um dieses Problem zu beheben:

1. Gehen Sie zu Einstellungen → Tools → Terminal
2. Entweder:
   • Deaktivieren Sie “Move focus to the editor with Escape”, oder
   • Klicken Sie auf “Configure terminal keybindings” und löschen Sie die “Switch focus to Editor”-Verknüpfung
3. Wenden Sie die Änderungen an

Dies ermöglicht es der ESC-Taste, Claude Code-Operationen ordnungsgemäß zu unterbrechen.

​

Markdown-Formatierungsprobleme

Claude Code generiert manchmal Markdown-Dateien mit fehlenden Sprach-Tags auf Code-Zäunen, was die Syntaxhervorhebung und Lesbarkeit in GitHub, Editoren und Dokumentationstools beeinträchtigen kann.

​

Fehlende Sprach-Tags in Codeblöcken

Wenn Sie Codeblöcke wie diese in generiertem Markdown bemerken:

```
function example() {
  return "hello";
}
```

Anstatt ordnungsgemäß getaggte Blöcke wie:

```javascript
function example() {
  return "hello";
}
```

Lösungen:

1. Claude bitten, Sprach-Tags hinzuzufügen: Fordern Sie einfach an “Bitte fügen Sie geeignete Sprach-Tags zu allen Codeblöcken in dieser Markdown-Datei hinzu.”

2. Nachbearbeitungs-Hooks verwenden: Richten Sie automatische Formatierungs-Hooks ein, um fehlende Sprach-Tags zu erkennen und hinzuzufügen. Siehe das Markdown-Formatierungs-Hook-Beispiel für Implementierungsdetails.

3. Manuelle Überprüfung: Nach der Generierung von Markdown-Dateien überprüfen Sie diese auf ordnungsgemäße Codeblock-Formatierung und fordern Sie Korrekturen an, falls erforderlich.

​

Inkonsistente Abstände und Formatierung

Wenn generiertes Markdown übermäßige Leerzeilen oder inkonsistente Abstände hat:

Lösungen:

1. Formatierungskorrekturen anfordern: Bitten Sie Claude, “Abstands- und Formatierungsprobleme in dieser Markdown-Datei zu beheben.”

2. Formatierungstools verwenden: Richten Sie Hooks ein, um Markdown-Formatierer wie prettier oder benutzerdefinierte Formatierungsskripte auf generierten Markdown-Dateien auszuführen.

3. Formatierungsvorlieben angeben: Schließen Sie Formatierungsanforderungen in Ihre Prompts oder Projekt-Speicher-Dateien ein.

​

Best Practices für Markdown-Generierung

Um Formatierungsprobleme zu minimieren:

• Seien Sie explizit in Anfragen: Bitten Sie um “ordnungsgemäß formatiertes Markdown mit sprach-getaggten Codeblöcken”
• Verwenden Sie Projektkonventionen: Dokumentieren Sie Ihren bevorzugten Markdown-Stil in CLAUDE.md
• Richten Sie Validierungs-Hooks ein: Verwenden Sie Nachbearbeitungs-Hooks, um häufige Formatierungsprobleme automatisch zu überprüfen und zu beheben

​

Weitere Hilfe erhalten

Wenn Sie Probleme haben, die hier nicht behandelt werden:

1. Verwenden Sie den /bug-Befehl innerhalb von Claude Code, um Probleme direkt an Anthropic zu melden
2. Überprüfen Sie das GitHub-Repository auf bekannte Probleme
3. Führen Sie /doctor aus, um die Gesundheit Ihrer Claude Code-Installation zu überprüfen
4. Fragen Sie Claude direkt nach seinen Fähigkeiten und Funktionen - Claude hat eingebauten Zugriff auf seine Dokumentation