Claude Code Hooks auf dem Remote-Mac nicht ausgeführt? Was tun? Fehlerbehebungsleitfaden 2026

Der Hook wird in Ihrer SSH-Sitzung nicht sichtbar ausgeführt, obwohl derselbe Befehl im Terminal funktioniert.

Schnellste Diagnose: Prüfen Sie zuerst Hook-Ereignis und Matcher, danach Skriptpfad und Ausführungsrechte, anschließend PATH und Arbeitsverzeichnis der Remote-Sitzung und zuletzt Exitstatus sowie Hook-Ausgabe. Schalten Sie Berechtigungsschutz nicht aus, um die Ursache zu umgehen.

Urteil: Eine schrittweise Prüfung ist geeignet, wenn Sie Claude Code auf einem Remote-Mac verwenden und die Hook-Kette nachvollziehen können. Sie ist nicht geeignet, um ein ungeprüftes Skript mit erweiterten Rechten „zum Laufen zu bringen“.

Dieser Leitfaden richtet sich an Entwickler, die Claude Code per SSH auf einem Mac nutzen und Hook-Ausführungen eingrenzen möchten.
Auch Teams, die gemeinsame Projekt-Hooks pflegen, können Unterschiede zwischen Benutzerkonfigurationen und Sitzungen prüfen.
Für CI-Verantwortliche ist der Ablauf hilfreich, wenn Formatierung, Build oder Tests eine echte macOS-Toolchain benötigen.

Zuerst den Fehlerzustand statt die Installation prüfen

„Hook funktioniert nicht“ beschreibt mehrere unterschiedliche Zustände. Das Ereignis kann ausbleiben, der Matcher kann nicht passen, der Befehl kann nicht starten oder das Skript kann laufen, ohne dass das erwartete Ergebnis sichtbar wird. Diese Fälle verlangen unterschiedliche Maßnahmen. Eine Neuinstallation oder pauschale Änderung an Dateirechten würde zunächst nur weitere Variablen einführen.

Notieren Sie vor der Änderung drei Dinge: die verwendete Claude-Code-Version, die Art der Sitzung und die konkrete Aktion, mit der Sie den Fehler auslösen. Halten Sie außerdem fest, ob die betreffende Einstellung im Projekt oder benutzerbezogen abgelegt ist. So können Sie nach jeder Korrektur denselben Ablauf wiederholen, statt mehrere Änderungen gleichzeitig zu testen.

Legen Sie für die erste Prüfung ein ungefährliches Signal an, das lediglich eine Zeile in eine temporäre Protokolldatei schreibt. Es soll weder Dateien im Projekt verändern noch Zugangsdaten oder vollständige Umgebungsvariablen ausgeben. Wenn die Zeile erscheint, wissen Sie, dass der Hook-Befehl gestartet wurde; die eigentliche Formatierungs- oder Build-Aktion bleibt bis zur späteren Prüfung außen vor.

Die offizielle Hook-Referenz beschreibt die Ereignisse, Konfiguration und Rückgaben. Verwenden Sie sie als maßgebliche Quelle dafür, welches Ereignis zu Ihrer Aktion passt. Die Hook-Anleitung bietet dazu Beispiele für die Einrichtung. Ob eine konkrete Aktion einen Hook auslöst, sollten Sie dennoch mit Ihrer aktuellen Version und einem reproduzierbaren Test bestätigen.

Ereignis und Matcher an der tatsächlichen Aktion ausrichten

Ein Hook wird an ein dokumentiertes Ereignis gebunden. Wenn Sie ein Ereignis wählen, das bei Ihrer Aktion nicht eintritt, kann das Skript korrekt sein und trotzdem nie starten. Prüfen Sie deshalb zunächst den Ereignisnamen in der Konfiguration und gleichen Sie ihn mit dem Ablauf ab, den Sie tatsächlich testen. Die Übersicht der Hook-Ereignisse ist dafür die Referenz; raten Sie nicht anhand eines ähnlich klingenden Ereignisnamens.

Danach kommt der Matcher. Er grenzt ein, bei welchen passenden Werkzeugen oder Aktionen der Hook ausgeführt werden soll. Ein enger Matcher ist für ein gezieltes Verhalten nützlich, kann aber auch dafür sorgen, dass ein anderer Werkzeugname oder eine andere Aktion nicht erfasst wird. Entfernen Sie ihn für einen kontrollierten Diagnosetest nur dann vorübergehend, wenn die Hook-Dokumentation die Konfiguration ohne diesen Filter zulässt. Stellen Sie die gewünschte Einschränkung anschließend wieder her.

Auch der Geltungsbereich ist relevant: Eine Projektkonfiguration ist nicht automatisch dasselbe wie eine benutzerspezifische Einstellung. Vergleichen Sie den Speicherort der aktiven Konfiguration mit dem Projekt, in dem Sie testen. Die Dokumentation zu Einstellungen beschreibt die verfügbaren Konfigurationsorte und Formate. Prüfen Sie zudem die Konfiguration auf syntaktische Fehler, bevor Sie ein Ereignisverhalten untersuchen.

Für einen Befehl-Hook kann eine Konfiguration in dieser Art aussehen; gleichen Sie die Struktur mit der aktuellen offiziellen Referenz ab, bevor Sie sie in Ihr Projekt übernehmen:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/check.sh"
          }
        ]
      }
    ]
  }
}

Die Namen und Werte in diesem Beispiel sind keine Diagnose für Ihre konkrete Konfiguration. Entscheidend ist, dass Ereignis, Matcher und Befehl gemeinsam zu Ihrer gewünschten Aktion passen. Beginnen Sie mit einem minimalen Hook, der nur einen sichtbaren, harmlosen Eintrag protokolliert. Wenn er ausgelöst wird, ergänzen Sie die eigentliche Prüfung. Bleibt das Signal aus, liegt die Untersuchung weiterhin bei Ereignis, Matcher, Konfigurationsort oder Laden der Konfiguration – nicht bei der Build-Logik.

Skriptstart auf dem Remote-Mac nachvollziehen

Wenn das Signal fehlt, obwohl Ereignis und Matcher plausibel sind, prüfen Sie den Befehl, den Claude Code tatsächlich starten soll. Bei einem relativen Pfad müssen Sie wissen, von welchem Arbeitsverzeichnis aus er ausgewertet wird. Kontrollieren Sie den Pfad direkt auf dem Remote-Mac und führen Sie das Skript dort mit derselben Benutzeridentität aus, die auch die Claude-Code-Sitzung verwendet.

Achten Sie bei einem Skript mit Shebang darauf, dass der angegebene Interpreter auf dem Host verfügbar ist. Ein Skript kann im Editor unauffällig aussehen, aber nicht starten, wenn der Interpreterpfad fehlt oder der Hook-Befehl nicht zur tatsächlichen Skriptdatei führt. Die Beispiele in der offiziellen Hook-Anleitung helfen, den dokumentierten Aufbau eines Befehls-Hooks mit Ihrer Konfiguration abzugleichen.

Prüfen Sie außerdem die Ausführungsrechte, statt sie pauschal zu erweitern. Auf dem Remote-Mac kann ls -l zeigen, welche Rechte für die Datei gesetzt sind. Wenn das Skript ausführbar sein soll, prüfen Sie den gezielten Aufruf von chmod für genau diese Datei und verifizieren Sie anschließend, dass der konfigurierte Pfad weiterhin stimmt. Vergeben Sie keine unnötigen Schreib- oder Ausführungsrechte an das gesamte Projekt.

Ein kleines Diagnose-Skript kann den Interpreter, den Startordner und den aufgelösten Programmstandort sichtbar machen:

#!/bin/sh
printf 'PWD=%s\n' "$PWD"
printf 'PATH=%s\n' "$PATH"
command -v xcodebuild || true
printf 'Hook-Probe erreicht\n' >> /tmp/claude-hook-probe.log
exit 0

Verwenden Sie das Beispiel nur als kontrollierten Test und passen Sie die abgefragten Programme an Ihr Projekt an. Die Ausgabe von PATH kann interne Verzeichnisse offenlegen; veröffentlichen Sie sie nicht ungeprüft in einem Ticket oder Build-Protokoll. Für einen sicheren Austausch genügt oft die Information, ob ein benötigter Befehl gefunden wurde und welcher nicht vertrauliche Pfad dafür verwendet wird.

Beachten Sie: Eine erfolgreiche Ausführung im interaktiven Terminal beweist nicht, dass der Hook denselben Befehl über dieselbe Umgebung und denselben Arbeitsordner erreicht.

SSH-Umgebung gezielt mit der Hook-Umgebung vergleichen

Ein häufiger Diagnosefehler besteht darin, nur die interaktive SSH-Shell zu prüfen. Claude Code wird zwar in einer Remote-Sitzung gestartet, doch für die Fehlersuche zählt, was der konkrete Hook-Prozess sieht. Vergleichen Sie deshalb dessen PATH und Arbeitsverzeichnis mit dem Terminal, ohne alle Variablen blind auszugeben. Die Referenz zu Umgebungsvariablen beschreibt dokumentierte Variablen; sie ersetzt nicht die Prüfung Ihrer tatsächlich gestarteten Sitzung.

Ermitteln Sie im interaktiven Terminal mit command -v den Pfad jedes benötigten Programms, etwa eines Projektwerkzeugs oder eines macOS-Buildbefehls. Lassen Sie dasselbe gezielt im Hook ausführen. Wenn das Terminal einen Pfad findet, der Hook aber nicht, prüfen Sie, ob der benötigte Verzeichnispfad in dessen PATH enthalten ist. Ergänzen Sie nur die erforderlichen Einträge und prüfen Sie erneut, statt eine umfangreiche persönliche Shell-Konfiguration ungeprüft in Automatisierungen zu übernehmen.

Untersuchen Sie auch den Arbeitsordner. Ein Aufruf wie ./scripts/check.sh setzt voraus, dass der Prozess an einem Ort startet, von dem aus dieser relative Pfad gültig ist. Protokollieren Sie für den Test PWD und lösen Sie den Skriptpfad auf. Wenn der Startordner nicht stabil feststeht, verwenden Sie einen eindeutig bestimmten Pfad oder ändern Sie das Skript so, dass es den Projektordner kontrolliert ermittelt. Übernehmen Sie keine angenommene Verzeichnisstruktur in die Konfiguration, ohne sie auf dem Host zu verifizieren.

Für macOS-Werkzeuge ist außerdem zu prüfen, ob die benötigte Entwicklungsumgebung auf dem Remote-Mac vorhanden und für den Sitzungsbenutzer erreichbar ist. Ein lokales Terminal auf einem anderen Rechner kann diesen Nachweis nicht liefern. Bei einer gemeinsam verwendeten Remote-Mac-Entwicklungsumgebung sollten Sie daher festhalten, welche Werkzeuge das Projekt benötigt und wie das Team ihre Pfade prüft. Vermeiden Sie in Hook-Logs die Ausgabe von Zugangstokens, privaten Schlüsseln oder vollständigen Umgebungsvariablen.

Exitstatus und Rückgaben auseinanderhalten

Startet der Hook, aber die erwartete Formatierung oder Prüfung bleibt aus, untersuchen Sie Standardausgabe, Standardfehler und Exitstatus des Skripts. Ein Skript kann etwa vor der eigentlichen Arbeit wegen eines fehlenden Werkzeugs abbrechen oder einen Fehler melden, den die Sitzung nicht als sichtbaren Dialogtext anzeigt. Die Hook-Referenz beschreibt, wie Claude Code Hook-Eingaben und -Rückgaben verarbeitet. Prüfen Sie dort das Verhalten für genau das Ereignis und den Hook-Typ, den Sie verwenden.

Führen Sie den Befehl zunächst manuell im Projektordner aus und notieren Sie, ob er erwartungsgemäß endet. Wiederholen Sie anschließend denselben Test über Claude Code. Vergleichen Sie die Ausgaben und den Status, ohne gleichzeitig weitere Einstellungen zu ändern. Bei einem Shell-Skript kann ein temporäres printf unmittelbar vor dem Ende helfen festzustellen, ob es den letzten Abschnitt erreicht. Entfernen Sie solche Diagnoseschritte nach der Untersuchung, damit sie keine dauerhafte Ausgabe oder Seiteneffekte erzeugen.

Für Debugging bietet die offizielle Dokumentation eine eigene Anleitung zur Konfigurationsdiagnose. Verwenden Sie die dort dokumentierten Diagnosemöglichkeiten, um zu unterscheiden, ob Claude Code die Einstellung lädt und ob der Hook ausgeführt wird. Interpretieren Sie die Ausgabe passend zum Ereignis: Nicht jede Hook-Antwort wird als normale Unterhaltung angezeigt, und eine sichtbare Protokollzeile allein beweist nicht, dass ein nachgelagerter Build erfolgreich war.

Wenn die Rückgabe das Verhalten beeinflussen soll, richten Sie sie exakt nach dem dokumentierten Format aus. Verwechseln Sie nicht die Ausgabe eines beliebigen Shell-Befehls mit einer strukturierten Hook-Antwort. Prüfen Sie ebenfalls, ob die Rückmeldung tatsächlich vom Hook stammt oder erst durch das aufgerufene Skript erzeugt wird. Das trennt Fehler in der eigenen Prüf- oder Build-Logik von einem Missverständnis darüber, wie Claude Code das Hook-Ergebnis verarbeitet.

Entscheidung nach Befund: Konfiguration, Host oder Skript

Die folgende Gegenüberstellung hilft Ihnen, die nächste Änderung auf die beobachtete Fehlerklasse zu beschränken:

Ändern Sie pro Test nur einen dieser Bereiche. So können Sie ein Ergebnis einer konkreten Korrektur zuordnen und vermeiden, dass ein neu gesetzter Matcher, ein veränderter Pfad und zusätzliche Rechte gleichzeitig eine andere Fehlerursache verdecken.

Mit einem realen Arbeitsablauf und sicheren Rechten abschließen

Sobald der harmlose Test funktioniert, prüfen Sie den Hook in der Reihenfolge, in der er später eingesetzt wird. Beginnen Sie mit einer rein lesenden Kontrolle oder einer Prüfung, die keine Projektdateien verändert. Testen Sie danach einen tatsächlichen Formatierungs-, Test- oder Build-Aufruf. Vergewissern Sie sich jeweils, dass erwartete Ausgaben entstehen und ein Fehlschlag erkennbar bleibt.

Danach prüfen Sie, ob der Hook nur die benötigte Aktion ausführen kann. Eine Formatierungsprüfung sollte nicht nebenbei Dateien außerhalb des Projekts verändern; ein Build-Skript sollte keine Zugangsdaten protokollieren. Die Claude-Code-Sicherheitsdokumentation und die Dokumentation zu Berechtigungen erläutern die Sicherheits- und Berechtigungsgrenzen. Verwenden Sie diese Grenzen als Teil der Fehlerbehebung, nicht als Hindernis, das Sie durch pauschales Freigeben beseitigen.

Bewahren Sie für gemeinsam verwendete Konfigurationen eine kurze Diagnosebeschreibung auf: betroffenes Ereignis, erwarteter Matcher, benötigter Befehl und geprüfter Remote-Pfad. Entfernen Sie temporäre Protokollierung und stellen Sie diagnostische Änderungen zurück, die nicht zum endgültigen Verhalten gehören. So kann das Team den Hook später auf einem weiteren Mac nachvollziehen, ohne sensible Informationen oder lokale Shell-Annahmen in die Projektkonfiguration zu übernehmen.

Häufige Fragen

Warum wird mein Claude Code Hook nicht ausgelöst?

Prüfen Sie zuerst, ob Ihre Aktion das konfigurierte Ereignis tatsächlich erreicht. Danach gleichen Sie den Matcher mit dem betroffenen Werkzeug ab und bestätigen, dass die Einstellung für das richtige Projekt oder Benutzerprofil gilt. Ein ungefährlicher Protokolleintrag im Hook ist der schnellste Nachweis, ob die Konfiguration geladen und das Ereignis erreicht wurde. Ändern Sie nicht gleichzeitig mehrere Bedingungen.

Was tun, wenn ein Befehl nach der SSH-Verbindung fehlt?

Lassen Sie PATH und PWD direkt im Hook gezielt ausgeben und prüfen Sie den benötigten Befehl dort mit command -v. Vergleichen Sie das Ergebnis mit dem interaktiven Terminal. Ergänzen Sie dann nur den erforderlichen Pfad oder korrigieren Sie den Arbeitsordner. Geben Sie keine vollständige Umgebung aus: Sie kann vertrauliche Werte enthalten, die in Protokollen oder geteilten Fehlerberichten nichts zu suchen haben.

Wie kontrolliere ich Skriptpfad, Rechte und Arbeitsordner?

Prüfen Sie den tatsächlich konfigurierten Pfad auf dem Remote-Mac, die Interpreterangabe in der Shebang-Zeile und die Rechte der konkreten Datei. Lassen Sie für die Diagnose PWD und den erreichten Skriptabschnitt protokollieren. Relative Pfade sind nur dann verlässlich, wenn der Startordner bekannt ist. Vermeiden Sie pauschale Rechteänderungen am gesamten Projekt.

Wo finde ich die Ursache, wenn der Hook-Befehl fehlschlägt?

Nutzen Sie die dokumentierte Debug-Diagnose und erfassen Sie zusätzlich Standardausgabe, Standardfehler und Exitstatus des Skripts. Vergleichen Sie die Rückgabe mit der Beschreibung des verwendeten Hook-Ereignisses: Hook-Ausgaben werden nicht zwangsläufig wie normaler Unterhaltungstext angezeigt. Teilen Sie Debug-Protokolle erst, nachdem Sie sie auf Zugangsdaten und andere vertrauliche Umgebungswerte geprüft haben.

Prüfen Sie die hier beschriebene Kette zunächst auf Ihrem vorhandenen Host; damit lässt sich feststellen, ob die Ursache in der Konfiguration, im Skript oder in der Remote-Sitzung liegt. Wenn Ihr Projekt dauerhaft auf eine erreichbare macOS-Toolchain angewiesen ist, vergleichen Sie die Optionen in unserer Übersicht zu Mac-Umgebungen. Ein Remote-Mac kann den Zugriff auf eine reale macOS-Ausführungsumgebung ermöglichen, ersetzt aber weder die Pflege sicherer Hook-Konfigurationen noch ist er für jeden Dauerbetrieb die passende Wahl. Wenn Sie den Einsatz für Ihren konkreten Build prüfen möchten, können Sie OakVM kontaktieren; beurteilen Sie dabei auch, ob ein eigener Mac oder eine andere vorhandene Umgebung Ihre Anforderungen bereits erfüllt.

Häufig gestellte Fragen