Claude Code installieren: Native vs. npm, PATH-Setup und erster Start

Für die native Installation (Native Install) von Claude Code ist die Node.js-Laufzeitumgebung überhaupt nicht erforderlich. Der npm-Installer setzt derzeit Node.js 22+ voraus, die installierte Binärdatei selbst läuft jedoch völlig unabhängig von der Node-Runtime. Die offizielle Dokumentation von Anthropic empfiehlt ausdrücklich die native Installation (weitere Details finden Sie im Installationsleitfaden). Um mit dem Coding-Agenten im Terminal zu arbeiten, müssen Entwickler eine Installationsmethode wählen, den passenden Befehl in einer unterstützten Shell ausführen und sicherstellen, dass die ausführbare Datei vom Betriebssystem korrekt erkannt wird. Wenn Fehler beim Befehlsaufruf auftreten, hängt die Ursachenanalyse davon ab, präzise zwischen einer nativen Standalone-Distribution und einer Installation über einen Paketmanager zu unterscheiden.

Native vs. npm: Architekturgrenzen und die Rolle von Node.js

Die offizielle Dokumentation von Anthropic empfiehlt Native Install (Installationsleitfaden). Bei dieser Variante wird die Node.js-Laufzeitumgebung nicht benötigt: Der Installer lädt eine vorkompilierte Standalone-Binärdatei herunter, die während der Ausführung zu keinem Zeitpunkt auf Node zugreift.

Die Installation über das globale npm-Paket bleibt eine verfügbare Alternative. Derzeit erfordert der npm-Installer Node.js 22 oder höher. Wird die Installation mit einer älteren Node.js-Version ausgeführt, gibt npm die Warnung EBADENGINE aus; der Vorgang wird in der Regel dennoch erfolgreich abgeschlossen: Das Paket lädt eine plattformspezifische, vorkompilierte Binärdatei herunter und verlinkt diese. Zur Laufzeit wird die installierte Claude Code-Binärdatei ebenfalls nicht innerhalb von Node.js ausgeführt.

Daher ist die Behauptung, für die Ausführung von Claude Code sei grundsätzlich Node.js zwingend erforderlich, technisch unzutreffend. Die Überprüfung der Node.js-Version ist nur dann notwendig, wenn Sie die Installation gezielt über npm durchführen.

Installationsbefehle für unterstützte Systeme

Verwenden Sie für eine ordnungsgemäße Einrichtung die offiziellen Skripte passend zu Ihrem Betriebssystem und Ihrer Shell-Umgebung.

macOS, Linux und WSL (Bash / Zsh)

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

Windows-Eingabeaufforderung (CMD)

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Alternative Installation über npm

npm install -g @anthropic-ai/claude-code

Wichtig: Führen Sie diesen Befehl niemals mit sudo npm install -g aus. Das Installieren von Paketen mit Superuser-Rechten führt zu Rechtekonflikten im Home-Verzeichnis und birgt Sicherheitsrisiken.

Unter nativem Windows ist Git for Windows mittlerweile optional. Ist Git for Windows vorhanden, kann der Agent Bash-Befehle über Git Bash ausführen; ist das Werkzeug nicht installiert, greift Claude Code auf das integrierte PowerShell-Tooling zurück.

Überprüfung der Installation

Überprüfen Sie nach Abschluss des Installationsskripts, ob die Binärdatei im System verfügbar ist:

claude --version

Eine korrekte Versionsausgabe bestätigt, dass die Binärdatei heruntergeladen, entpackt und in der Umgebung registriert wurde. Beachten Sie: Die erfolgreiche Anzeige der Versionsnummer bestätigt lediglich die Funktionsfähigkeit der Binärdatei selbst; sie bedeutet nicht, dass der Client bereits autorisiert ist oder Anfragen an das Modell stellen kann.

Führen Sie für eine umfassende Prüfung der Umgebung den Diagnosebefehl aus:

claude doctor

Der Befehl claude doctor führt ein lokales Audit der Umgebung durch: Er überprüft Konfigurationsdateien, Dateisystemberechtigungen und Systemabhängigkeiten, um potenzielle Konfigurationsprobleme aufzudecken, ohne eine interaktive Coding-Session zu starten.

Diagnose: Was tun beim Fehler command not found

Meldet das Terminal, dass der Befehl claude nicht gefunden wurde (oder gibt Windows die Meldung aus, dass der Befehl weder als interner noch als externer Befehl erkannt wird), führen Sie schrittweise folgende Diagnose durch:

[Ошибка вызова: claude не найден]
         │
         ▼
[Шаг 1: Открыть новый сеанс терминала]
         │
    Помогло? ──Да──> Завершено
         │ Нет
         ▼
[Шаг 2: Проверить физическое наличие бинарного файла на диске]
         │
    Файл найден? ──Нет──> Ошибка загрузки/прав; повторить установку
         │ Да
         ▼
[Шаг 3: Проверить тип установки и PATH]
         │
 ┌───────┴────────────────────────┐
 ▼                                ▼
[Native Install]                [npm Install]
Проверить PATH:                 Проверить PATH через npm prefix -g:
- Unix: ~/.local/bin            - Unix: <prefix>/bin
- Win: %USERPROFILE%\.local\bin - Win: <prefix>
(Не переустанавливать только из-за PATH)

Der obige Entscheidungsbaum bildet den schrittweisen Diagnoseablauf ab:

• Ausgangsfehler: [Ошибка вызова: claude не найден] bedeutet [Aufruffehler: claude wurde nicht gefunden].
• Schritt 1: [Шаг 1: Открыть новый сеанс терминала] fordert dazu auf, eine neue Terminal-Sitzung zu öffnen. Hat dies geholfen (Помогло? ──Да──> Завершено / Geholfen? ──Ja──> Abgeschlossen), ist das Problem gelöst. Wenn nicht (Нет / Nein), fahren Sie mit Schritt 2 fort.
• Schritt 2: [Шаг 2: Проверить физическое наличие бинарного файла на диске] prüft, ob die Binärdatei tatsächlich auf der Festplatte existiert. Fehlt die Datei (Файл найден? ──Нет──> Ошибка загрузки/прав; повторить установку / Datei gefunden? ──Nein──> Download-/Rechtefehler; Installation wiederholen), führen Sie das Installationsskript erneut aus. Wenn sie vorhanden ist (Да / Ja), gehen Sie weiter zu Schritt 3.
• Schritt 3: [Шаг 3: Проверить тип установки и PATH] unterscheidet nach der gewählten Installationsmethode und prüft die PATH-Umgebungsvariablen:
  • Für Native Install PATH prüfen (Проверить PATH:): ~/.local/bin unter Unix oder %USERPROFILE%\.local\bin unter Windows.
  • Für npm Install PATH über npm prefix -g ermitteln (Проверить PATH через npm prefix -g:): <prefix>/bin unter Unix oder <prefix> unter Windows.
  • Der abschließende Hinweis (Не переустанавливать только из-за PATH) warnt ausdrücklich: (Nicht allein wegen eines PATH-Problems neu installieren).

1. Öffnen Sie ein neues Terminal-Fenster

Installationsskripte nehmen Änderungen an den Shell-Konfigurationsdateien (.bashrc, .zshrc) oder an den Windows-Benutzerumgebungsvariablen vor. Bereits geöffnete Terminal-Fenster übernehmen diese Modifikationen nicht zur Laufzeit. Schließen Sie Ihre aktuelle Sitzung vollständig und öffnen Sie ein frisches Fenster.

2. Physischen Pfad zur Datei überprüfen

Bei einer nativen Installation (Native Install) wird die ausführbare Datei standardmäßig in folgenden Standardverzeichnissen abgelegt (sofern keine benutzerdefinierten Überschreibungen vorliegen):

• unter macOS, Linux und WSL: ~/.local/bin/claude (versionsspezifische Dateien liegen in ~/.local/share/claude);
• unter Windows: %USERPROFILE%\.local\bin\claude.exe.

Diese Pfade sind Standardvorgaben und keine unveränderlichen Speicherorte, falls benutzerdefinierte Pfade konfiguriert wurden. Befindet sich die Datei nicht im Verzeichnis, wurde der Installationsprozess möglicherweise durch Netzwerkabbrüche oder fehlende Schreibrechte vorzeitig abgebrochen.

3. Shell-Diagnosebefehle ausführen

Nutzen Sie bordeigene Werkzeuge, um festzustellen, ob und wie die Shell die ausführbare Datei auflöst:

• in Zsh / Bash: führen Sie command -v claude oder type -a claude aus;
• in PowerShell: rufen Sie Get-Command claude sowie das Dienstprogramm where.exe claude auf;
• in CMD: nutzen Sie den Befehl where claude.

4. PATH-Variablen für Native und npm sauber trennen

Ein häufiger Diagnosefehler besteht darin, bei Fehlschlägen einer nativen Installation die Node.js-Pfade anpassen zu wollen.

• Wenn Sie die Installation via Native Install durchgeführt haben, spielen Node.js-Verzeichnisse oder npm prefix -g überhaupt keine Rolle. Zu prüfen und in die PATH-Variable aufzunehmen ist das Verzeichnis ~/.local/bin (unter Unix-Systemen) bzw. %USERPROFILE%\.local\bin (unter Windows).
• Bei einer Installation via npm install -g wird das Verzeichnis für globale Binärdateien über den Befehl npm prefix -g ermittelt:
  • auf Unix-ähnlichen Systemen (macOS, Linux, WSL) liegt die Binärdatei in <prefix>/bin;
  • unter Windows befindet sich die Binärdatei direkt im Stammverzeichnis von <prefix>. Befehle wie npm bin -g und npm root -g verweisen nicht auf den korrekten Pfad für ausführbare Dateien.

Ist die Binärdatei auf der Festplatte vorhanden, der Befehl wird jedoch nicht gefunden, prüfen Sie zuerst die PATH-Variable und wie die Shell die ausführbare Datei auflöst. Scheitert auch der direkte Aufruf über den absoluten Pfad, untersuchen Sie den exakten Fehlertext und ziehen Sie den offiziellen Leitfaden zur Fehlerbehebung heran: Dateiberechtigungen, Binärkompatibilität mit der Plattform oder eine unvollständige Installation könnten die Ursache sein. Führen Sie niemals blind eine Neuinstallation durch, nur weil die Meldung command not found ausgegeben wurde.

Erster Start und sicheres Kennenlernen

Wechseln Sie nach erfolgreicher Verifizierung des Befehls in das Verzeichnis eines kleineren Testprojekts und starten Sie die Sitzung:

cd /path/to/test-project
claude

Beim ersten Start führt das Interface durch das standardmäßige Authentifizierungsverfahren im Browser. Innerhalb einer aktiven Sitzung können Sie mit dem Befehl /status das aktuelle Arbeitsverzeichnis, die Account-ID und das verwendete Modell einsehen.

Führen Sie zum ersten Kennenlernen eine Übung mit folgendem Test-Prompt aus:

Объясни назначение основных файлов в проекте. Не изменяй файлы, не устанавливай зависимости и не выполняй команды в терминале.

(Übersetzung des Test-Prompts: „Erkläre den Zweck der wichtigsten Dateien im Projekt. Verändere keine Dateien, installiere keine Abhängigkeiten und führe keine Befehle im Terminal aus.“)

Die konkrete erwartete Antwort: Der Agent listet die Hauptdateien auf und erläutert deren Zweck, ohne Code-Diffs zu erzeugen oder Änderungen am Dateisystem vorzunehmen. Führen Sie nach Abschluss der Aufgabe in einem weiteren Terminal den Befehl git diff aus, um sicherzustellen, dass die Codebasis vollkommen unverändert geblieben ist.

Wichtig zu verstehen: Eine Textanweisung im Prompt ist lediglich eine sprachliche Orientierung für das Modell, jedoch kein erzwungener Ausführungsmodus (enforced mode) und keine Sandbox auf Betriebssystemebene. Wenn für ein Repository automatische Dateiänderungen verbindlich unterbunden werden sollen, verwenden Sie den Planungsmodus:

claude --permission-mode plan

Im plan-Modus liest der Agent standardmäßig Dateien und führt ausschließlich lesende Shell-Befehle aus, ohne den Quellcode zu bearbeiten. Dieser Modus stellt jedoch keine isolierte OS-Sandbox dar: Ist die automatisierte Ausführung aktiv, können vom Klassifikator genehmigte Befehle weiterhin ausgeführt werden (eine starre Systemisolation darf nicht unterstellt werden; Stand der Dokumentation vom 15.09.2026).

Eine detaillierte Übersicht aller Richtlinien zur Aktionsbestätigung finden Sie im Leitfaden zu Berechtigungen. Um die Arbeit mit dem Agenten zu beenden, drücken Sie die Tastenkombination Ctrl+D.

Unabhängigen API-Provider anbinden

Die Installation des CLI-Clients und die anschließende Konfiguration des Modellanbieters sind zwei voneinander unabhängige Schritte. Wenn Sie anstelle des standardmäßigen Account-Logins ein Anthropic-kompatibles Drittanbieter-Gateway nutzen möchten, richten Sie die Verbindungsparameter separat ein, nachdem die lokale Funktionsfähigkeit des CLI bestätigt wurde.

Der unabhängige API-Provider BetterToken stellt Entwicklern hierfür einen persönlichen API-Key bereit, während Modellaufrufe, Token-Verbrauch und Abrechnung im Dashboard übersichtlich überwacht werden. Eine Schritt-für-Schritt-Anleitung zum Exportieren der erforderlichen Umgebungsvariablen und zur Angabe der API-Basisadresse finden Sie in der BetterToken-Dokumentation zu Claude Code. Das Herunterladen, Aktualisieren und lokale Ausführen der eigentlichen Binärdatei erfolgt weiterhin über die regulären CLI-Mechanismen gemäß den Schritten dieser Anleitung.