VS Code Remote SSH zum Mac: Fehler 2026 beheben

Prüfen Sie bei VS Code Remote SSH zum Mac zuerst den Befehl aus dem Terminal und teilen Sie den Fehler danach in Netzwerk, Anmeldung, VS Code Server oder Arbeitsbereich ein; wenn der Terminal-Login funktioniert, liegt die Ursache meistens nicht mehr beim SSH-Dienst selbst. Diese Reihenfolge gilt besonders für Verbindungen aus Windows, Linux oder einem lokalen Mac zu einer entfernten macOS-Entwicklungsumgebung.

Für die ersten 10 Minuten: Terminalverbindung mit demselben Host-Alias testen, die Ausgabe von „Remote - SSH“ sichern und den Start des VS Code Server beobachten.
Für diese Woche: Prüfen Sie bei jedem Entwicklungs-Mac, ob Remote Login, Benutzerrechte, HTTPS-Ausgang, Speicherplatz und Wiederanlauf nach einem Neustart dokumentiert sind.

Dieser Beitrag ist für plattformübergreifende Entwickler, DevOps-Ingenieure und Plattformverantwortliche gedacht, die einen Remote Mac als Entwicklungs-, Test- oder Build-Knoten betreiben. Wer nur Dateien per SFTP übertragen kann, aber keinen vollständigen Shell-Zugriff besitzt, verwendet nicht den vorgesehenen Betriebsmodus von Remote - SSH.

Der typische Fall lautet: Im Terminal funktioniert ssh, aber VS Code bleibt bei „Verbindung wird hergestellt“ oder „VS Code Server wird initialisiert“ stehen. Das ist kein Widerspruch. Die Erweiterung verbindet sich zunächst per SSH, installiert oder startet anschließend den VS Code Server auf dem entfernten Rechner und baut danach den Kommunikationskanal für Editor, Terminal und Erweiterungen auf. Die einzelnen Schritte sind voneinander abhängig. (Dokumentation zu Visual Studio Code Remote - SSH)

Speichern Sie vor jeder Änderung mindestens diese drei Ergebnisse:

• den vollständigen, aber um Hostnamen, Benutzer und Pfade bereinigten Terminal-Login;
• die Ausgabe aus Ansicht → Ausgabe → Remote - SSH;
• den Status des entfernten Terminals, des geöffneten Ordners und des eigentlichen Projektbefehls.

Wichtig: Private Schlüssel, Passwörter, Tokens, vollständige Hostadressen und interne Pfade gehören weder in einen Fehlerbericht noch in ein öffentliches Repository. Für eine spätere Analyse genügt eine redigierte Fehlermeldung mit Zeitstempel und Fehlerklasse.

Beginnen Sie nicht mit einer Neuinstallation der Erweiterung. Prüfen Sie zuerst, ob der entfernte Mac aus demselben lokalen System erreichbar ist, das VS Code verwendet.

1. Namensauflösung und Portpfad testen

Verwenden Sie den Hostnamen aus der SSH-Konfiguration und vergleichen Sie ihn mit der Adresse, die der Dienstbetreiber oder die interne Plattform vorgibt. Je nach lokalem Betriebssystem stehen dafür die dort verfügbaren Netzwerkdiagnosebefehle zur Verfügung. Entscheidend ist nicht, welcher einzelne Befehl verwendet wird, sondern ob drei Zustände sauber auseinandergehalten werden:

1. Der Hostname wird nicht aufgelöst.
2. Der Netzwerkpfad oder der SSH-Port ist nicht erreichbar.
3. Der SSH-Dienst antwortet, lehnt aber die Anmeldung ab.

Ein Timeout spricht typischerweise für einen unterbrochenen Netzwerkpfad, eine Firewall oder eine nicht erreichbare externe Schnittstelle. „Connection refused“ bedeutet dagegen, dass ein Ziel antwortet, dort aber kein passender Dienst Verbindungen annimmt oder die Verbindung aktiv zurückweist. Eine Hostschlüsselwarnung ist eine andere Kategorie: Sie betrifft die Identität des Gegenübers und sollte nicht durch blindes Löschen der bekannten Schlüssel umgangen werden.

2. SSH mit demselben Alias ausführen

Der wichtigste Vergleich lautet:

ssh mein-mac

Wenn VS Code den Alias mein-mac verwendet, muss auch der Terminaltest diesen Alias verwenden. Ein Test mit einer direkt eingegebenen IP-Adresse kann erfolgreich sein, obwohl VS Code wegen eines anderen HostName, User oder IdentityFile auf ein falsches Ziel zeigt.

3. Remote Login auf macOS prüfen

Auf dem Mac liegt die Einstellung unter Systemeinstellungen → Allgemein → Freigaben → Remote Login. Dort muss Remote Login aktiviert sein. Apple erlaubt außerdem, den Zugriff auf alle Benutzer oder nur auf ausdrücklich ausgewählte Benutzer zu beschränken. Nach einem Neustart oder einer Änderung der Benutzerverwaltung kann genau diese Liste die Ursache sein. (Apple-Anleitung zu Remote Login auf dem Mac)

Die offizielle Apple-Anleitung zeigt außerdem den konkreten SSH-Befehl, der für den Mac verwendet werden kann. Dieser Befehl ist für die erste Gegenprobe wertvoller als eine manuell zusammengesetzte Verbindung. Wenn Remote Login deaktiviert, der Benutzer nicht zugelassen oder der falsche Account verwendet wird, kann VS Code den VS Code Server nicht erreichen, unabhängig davon, welche Erweiterung lokal installiert ist.

Wenn der Terminaltest ebenfalls scheitert, wechseln Sie nicht sofort zu VS Code-spezifischen Einstellungen. Korrigieren Sie zuerst die SSH-Schicht.

Öffnen Sie in VS Code über die Befehlspalette Remote-SSH: Open Configuration File… genau die Konfigurationsdatei, die die Erweiterung verwendet. Der Eintrag sollte nur die für diesen Host erforderlichen Werte enthalten, zum Beispiel:

Host mein-mac
    HostName mac.example.invalid
    User entwickler
    IdentityFile ~/.ssh/mac_entwicklung

Die Adresse im Beispiel ist absichtlich nicht real. Ersetzen Sie sie nicht durch eine echte Adresse in Dokumentation, Tickets oder Screenshots.

Nutzen Sie danach für die Gegenprobe denselben Alias:

ssh mein-mac

Wenn erforderlich, können Sie die effektiven Optionen des Alias mit dem auf Ihrem System verfügbaren OpenSSH-Hilfetext beziehungsweise der lokalen Manpage prüfen. So erkennen Sie, ob ein globaler Eintrag, ein späterer Host-Block oder ein Sprungserver die erwartete Einstellung überschreibt.

Bei einem Schlüsselproblem sind drei Fehlerbilder besonders aussagekräftig:

• Der Schlüssel wird nicht gefunden: Der Pfad in IdentityFile ist falsch oder die Datei ist nicht vorhanden.
• Der Schlüssel wird angeboten, aber abgelehnt: Benutzerkonto, öffentlicher Schlüssel oder Serverautorisierung passen nicht zusammen.
• Der Schlüssel wird wegen lokaler Rechte abgelehnt: Die lokale SSH-Implementierung verweigert zu offene Dateirechte.

Eine Passwortanmeldung kann funktionieren, während VS Code scheinbar hängen bleibt, weil ein Eingabedialog nicht sichtbar ist. Aktivieren Sie für die Diagnose die Einstellung remote.SSH.showLoginTerminal. Die offizielle Fehlerbehebungsseite nennt diese Einstellung ausdrücklich für Fälle, in denen VS Code auf eine Eingabe wartet. (Offizielle Fehlerbehebung für Remote - SSH)

Ein erfolgreicher SSH-Login ist nur der Übergang zur nächsten Schicht. Remote - SSH installiert den VS Code Server auf dem entfernten Betriebssystem; eine lokale VS-Code-Installation auf dem Mac ist dafür nicht erforderlich. Der Server stellt die Backend-Funktionen für Dateien, Terminal, Debugging und Remote-Erweiterungen bereit. (Arbeitsweise von Remote - SSH)

4. Die Remote-SSH-Ausgabe als Hauptbeleg verwenden

Öffnen Sie Ansicht → Ausgabe, wählen Sie Remote - SSH und suchen Sie nach dem ersten konkreten Fehler, nicht nur nach der letzten Meldung „Verbindung fehlgeschlagen“. Für die Zuordnung helfen diese Muster:

• Downloadfehler: Der Server kann von den erforderlichen Endpunkten nicht geladen werden.
• Übertragungsfehler: Der Download funktioniert lokal, aber die Übertragung auf den Mac scheitert.
• Entpackfehler: Das Archiv ist unvollständig, der Zielpfad ist nicht beschreibbar oder der Speicherplatz reicht nicht.
• Startfehler: Der Server wurde abgelegt, startet aber nicht oder beendet sich sofort.
• Tunnel- oder Weiterleitungsfehler: SSH funktioniert, aber der Kommunikationskanal zum Server darf nicht aufgebaut werden.

Für die Installation sind ausgehende HTTPS-Verbindungen relevant. Die VS-Code-Dokumentation nennt unter anderem update.code.visualstudio.com und vscode.download.prss.microsoft.com; für Erweiterungen werden zusätzlich Marketplace- und CDN-Endpunkte benötigt. Der Standardpfad versucht den Download zunächst auf dem Remote-System und kann auf einen lokalen Download mit anschließender Übertragung zurückfallen. (Hinweise zu Download und Installation des VS Code Server)

5. Speicherplatz, Rechte und Shell-Ausgabe kontrollieren

Führen Sie die Diagnosebefehle im normalen SSH-Terminal auf dem Mac aus. Prüfen Sie:

pwd
echo "$SHELL"
echo "$PATH"
df -h

Damit lässt sich feststellen, ob das Home-Verzeichnis beschreibbar ist, ob eine ungewöhnliche Shell Initialisierungstext ausgibt und ob der verfügbare Speicherplatz für Download, Entpacken und Erweiterungen ausreicht. Ein Shell-Profil, das bei jeder nicht-interaktiven Sitzung Begrüßungstext, Passwortabfragen oder farbige Statusmeldungen ausgibt, kann das Erkennungsskript von Remote - SSH stören.

Die Dokumentation nennt für Remote-SSH-Hosts mindestens 1 GB Arbeitsspeicher und empfiehlt mindestens 2 GB sowie zwei CPU-Kerne. Diese Werte sind keine Leistungszusage für ein konkretes Projekt, sondern Mindest- beziehungsweise Empfehlungshinweise für den Remote-Development-Betrieb. Bei einem ausgelasteten Build-Knoten können zusätzlich Compiler, Simulatoren, Indizes und Erweiterungen die tatsächliche Reserve deutlich verringern. (Systemanforderungen für Remote-SSH-Verbindungen)

Nicht vorschnell löschen: Der Befehl „Remote-SSH: Kill VS Code Server on Host…“ kann eine beschädigte Serverinstallation beheben, entfernt aber den Serverbestand des ausgewählten Hosts. Verwenden Sie ihn erst, wenn das Protokoll einen Serverstart-, Versions- oder Restdateifehler stützt, und verbinden Sie sich anschließend kontrolliert neu. (Offizielle Anleitung zur gezielten Serverbereinigung)

Prüfen Sie auch, ob die SSH-Weiterleitung auf dem Server erlaubt ist. Die offizielle Fehlerbehebung nennt open failed: administratively prohibited: open failed als Hinweis auf blockierte TCP-Weiterleitung. In diesem Fall muss die SSH-Serverkonfiguration von der zuständigen Administration geprüft werden; eine lokale Änderung an VS Code kann diese Richtlinie nicht ersetzen. (Fehlerbehebung bei blockierter SSH-Weiterleitung)

Wenn die Statusanzeige grün ist, ist die Arbeit noch nicht vollständig validiert. Ein Remote Mac kann verbunden sein, während Terminal, Git, Debugging oder eine native Erweiterung trotzdem fehlschlagen.

Lokale und entfernte Erweiterungen unterscheiden

VS Code führt Erweiterungen entweder auf der lokalen Benutzeroberfläche oder auf dem SSH-Host aus. Eine Erweiterung kann deshalb lokal installiert und sichtbar sein, während ihre Arbeitsbereichskomponente auf dem Mac fehlt. In der Erweiterungsansicht muss die Installation ausdrücklich für den verbundenen SSH-Host erscheinen. (Remote-Erweiterungen in der offiziellen VS-Code-Dokumentation)

Das ist bei Apple-Silicon-Systemen besonders relevant, wenn eine Erweiterung native Module oder vorcompilierte Binärdateien verwendet. Die offizielle Dokumentation weist darauf hin, dass native Erweiterungskomponenten auf ARM-Systemen nicht automatisch funktionieren müssen. Prüfen Sie deshalb die Kompatibilität der konkreten Erweiterung und nicht nur die Tatsache, dass macOS als Plattform unterstützt wird. (Hinweise zu nativen Erweiterungen auf Remote-Hosts)

PATH und Shell-Verhalten vergleichen

Ein Terminalfenster kann funktionieren, während ein Task oder Debugger einen Befehl nicht findet. Der Grund ist häufig ein anderer Startmodus der Shell. Vergleichen Sie im VS-Code-Terminal und in einer normalen SSH-Sitzung:

echo "$PATH"
command -v git
command -v node
command -v python3

Wenn command -v im Terminal einen Pfad liefert, ein VS-Code-Task aber „Befehl nicht gefunden“ meldet, prüfen Sie Shell-Profile, Remote-Einstellungen und Workspace-Konfiguration. Ändern Sie nicht pauschal globale Pfade, bevor klar ist, welche Sitzung den falschen Wert setzt.

Proxy und Arbeitsbereich testen

Lokale Proxy-Einstellungen werden nicht automatisch für den entfernten Host wiederverwendet. Muss der VS Code Server oder eine Erweiterung aus dem Internet laden, benötigt der Mac eine passende eigene Proxy- oder HTTPS-Konfiguration.

Die abschließende Abnahme sollte deshalb aus vier Tests bestehen:

• Repository oder Projektordner auf dem Remote Mac öffnen;
• neues Terminal im verbundenen Arbeitsbereich starten;
• einen harmlosen Projektbefehl wie Versionsabfrage oder Testlauf ausführen;
• Debugging oder den vorgesehenen Build einmal tatsächlich starten.

Ein grünes Verbindungssymbol allein ist kein ausreichender Nachweis für eine funktionierende Entwicklungsumgebung.

Nach einem Neustart des entfernten Macs sollte die Prüfung in dieser Reihenfolge erfolgen:

1. Hostname und Netzwerkpfad aus dem lokalen System testen.
2. Mit demselben SSH-Alias eine Shell öffnen.
3. Remote Login und die zugelassenen Benutzer auf macOS kontrollieren.
4. VS Code öffnen und den Kanal „Remote - SSH“ beobachten.
5. Erst danach Server, Erweiterungen und Arbeitsbereich testen.

Wenn Schritt 2 scheitert, ist die Ursache nicht der VS Code Server. Wenn Schritt 2 gelingt, aber Schritt 4 beim Serverstart stoppt, untersuchen Sie Download, Speicherplatz, Rechte, Shell und Serverreste. Wenn Schritt 4 gelingt, aber der Projektbefehl scheitert, gehört der Fehler in die Arbeitsbereichs- oder Erweiterungsschicht.

Die passende nächste Aktion auswählen

• Wenn der Terminal-Login nicht funktioniert: Netzwerk, Remote Login, Benutzer und Schlüssel korrigieren; VS Code zunächst nicht verändern.
• Wenn der Terminal-Login funktioniert, aber kein Remote-SSH-Log entsteht: lokale VS-Code-Erweiterung, Befehlspalette und Konfigurationsdatei prüfen.
• Wenn das Log einen Serverdownload meldet: HTTPS-Zugriff, Proxy, Speicherplatz und lokale Download-Option untersuchen.
• Wenn das Log einen Serverstart- oder Versionsrest meldet: Protokoll sichern und anschließend gezielt „Remote-SSH: Kill VS Code Server on Host…“ verwenden.
• Wenn die Verbindung grün ist, aber Aufgaben scheitern: entfernte Erweiterungen, Shell-PATH, Repositoryrechte und native Abhängigkeiten prüfen.
• Wenn der Fehler nur nach Neustarts wiederkehrt: Stabilität des Mac-Knotens, Startreihenfolge, Benutzerfreigabe und automatische Wiederherstellung dokumentieren.

Für die tägliche Arbeit hilft eine kurze Abnahme vor der Übergabe eines Entwicklungs-Macs:

• [ ] SSH mit dem vorgesehenen Alias funktioniert.
• [ ] Remote Login ist aktiviert und der richtige Benutzer zugelassen.
• [ ] Der Remote-SSH-Log enthält keinen unbehandelten Serverstartfehler.
• [ ] Der VS Code Server kann aktualisiert oder erneut installiert werden.
• [ ] Ein Remote-Terminal startet ohne unerwartete Eingabeaufforderung.
• [ ] Das Repository lässt sich öffnen und der Projektbefehl läuft.
• [ ] Die erforderlichen Erweiterungen sind auf dem Remote Mac installiert.
• [ ] Ein Neustart wurde getestet und die Verbindung lässt sich wiederherstellen.
• [ ] Protokolle sind bereinigt, bevor sie an Dritte weitergegeben werden.

Warum kann das Terminal verbinden, während VS Code dauerhaft wartet?

Der Terminaltest bestätigt nur den SSH-Kanal. Danach muss Remote - SSH den VS Code Server laden, auf dem Mac starten und über einen Tunnel erreichbar machen. Prüfen Sie daher zuerst den Remote-SSH-Log auf einen unsichtbaren Login-Dialog, einen blockierten Download oder einen fehlenden Serverstart.

Wie lässt sich ein Installationsstillstand des VS Code Server eingrenzen?

Sichern Sie die Ausgabe, prüfen Sie HTTPS-Ausgang, Speicherplatz und Schreibrechte und vergleichen Sie die Shell-Umgebung. Erst wenn das Log einen beschädigten Serverbestand oder einen abgebrochenen Start zeigt, ist die offizielle Serverbereinigung angemessen. Ein pauschales Löschen kann die eigentliche Ursache verdecken.

Was bedeutet ein dauerhaft angezeigter Verbindungsstatus?

Der Status beschreibt nur, dass ein Teil der Verbindung noch nicht abgeschlossen ist. Er unterscheidet nicht zwischen Authentifizierung, Serverinstallation, TCP-Weiterleitung und Remote-Erweiterung. Die konkrete Fehlerklasse steht meistens im Kanal „Remote - SSH“ oder im Login-Terminal.

Was ist nach einem Neustart des Remote Mac zu kontrollieren?

Beginnen Sie mit einem normalen SSH-Login. Danach prüfen Sie Remote Login, Benutzerfreigabe und Serverstart. Wenn die Shell erreichbar ist, aber VS Code nicht initialisiert, liegt die Untersuchung beim VS Code Server oder beim Tunnel und nicht bei der grundlegenden Netzwerkverbindung.

Wenn ein vorhandener Mac im Büro oder ein selbst betriebener Mac mini nur gelegentlich erreichbar ist, entstehen in der Praxis drei Nachteile: Der Rechner kann nach einem Neustart auf eine manuelle Anmeldung warten, Netzwerk- oder Firewalländerungen sind oft nicht sauber dokumentiert, und die Fehlersuche hängt von physischem Zugriff oder einer zweiten Person vor Ort ab. Für CI/CD, reproduzierbare Tests oder zeitkritische Entwicklungsaufgaben ist nicht nur die Rechenleistung, sondern die wiederholbare Erreichbarkeit entscheidend.

Eine Übersicht der verfügbaren Betriebsmodelle und Zugriffswege finden Sie in der JEXCLOUD-Übersicht für Remote-Mac-Umgebungen. Wenn der aktuelle Knoten dauerhaft online sein muss, vollständigen SSH-Zugriff benötigt oder nach jeder Störung ohne lokalen Zugriff wiederhergestellt werden soll, kann ein gemieteter Remote Mac von JEXCLOUD die passendere Betriebsform sein.

Prüfen Sie zunächst die in diesem Beitrag genannten Abnahmepunkte und vergleichen Sie dann die verfügbaren Remote-Mac-Angebote von JEXCLOUD mit dem Kauf und der Eigenverwaltung eines Mac mini. Für Projekte mit begrenzter Laufzeit oder eine zusätzliche Testumgebung ist diese Entscheidung meist leichter zu rechtfertigen als die Anschaffung und dauerhafte Wartung eines weiteren physischen Rechners.

• SSH-Tunnel und die Erreichbarkeit eines entfernten Mac systematisch prüfen
• Einen entfernten Mac-Knoten mit Launchd dauerhaft und zuverlässig betreiben
• Fehler bei Cloud-Mac-Diensten analysieren und Launchd-Prozesse korrekt neu starten