Claude Code 2.1.310: Gateway-Fehler und Windows-Hooks

Wenn Claude Code bei Anfragen über ein Gateway Unexpected value(s) mit einem Verweis auf effort-2025-11-24 oder Unexpected role "system" meldet, aktualisiere auf 2.1.310 oder neuer und wiederhole die Anfrage in der betroffenen Unterhaltung. Teams unter Windows sollten außerdem prüfen, ob Tool-Aufrufe tatsächlich blockiert werden, wenn der Interpreter eines Hooks fehlschlägt. Falls bei einem extrem hohen cleanupPeriodDays-Wert eingefügte Bilder fehlen, sichere die verbliebenen Daten, bevor du die Aufbewahrungsfrist änderst.

Stand 2026-10-25 bestätigen die offiziellen Versionshinweise zu 2.1.310 Korrekturen für diese Gateway-, Windows-Hook- und Bereinigungsfehler. Die folgenden Anleitungen behandeln die einzelnen Fehler getrennt.

Prüfe, ob tatsächlich 2.1.310 oder neuer gestartet wird

Prüfe zunächst, welche Programmdatei dein Terminal startet, und aktualisiere anschließend über die Installationsmethode, die du bereits verwendest. Führe in Bash oder unverändert in Windows PowerShell Folgendes aus:

claude --version
claude doctor

claude doctor liefert Diagnosen zu Installation und Einstellungen, ohne Änderungen vorzunehmen. Bewahre die Versionsausgabe auf, damit du sie nach dem Update vergleichen kannst.

Wähle den passenden Befehl aus Anthropics Installations- und Update-Anleitung:

Vorhandene Installation	Shell	Update-Befehl
Nativer Installer	Bash oder PowerShell	`claude update`
Homebrew-Cask für stable	Bash	`brew upgrade claude-code`
Homebrew-Cask für latest	Bash	`brew upgrade claude-code@latest`
WinGet	PowerShell	`winget upgrade Anthropic.ClaudeCode`
npm	Bash oder PowerShell	`npm install -g @anthropic-ai/claude-code@latest`

Native Updates folgen dem konfigurierten Release-Kanal. Bei Homebrew folgt claude-code dem Kanal stable und claude-code@latest dem Kanal latest. Ein Update kann deshalb erfolgreich abgeschlossen werden, obwohl die installierte Version weiterhin älter als erforderlich ist.

Bei einer vorhandenen nativen Installation unterstützt die CLI auch die Installation einer bestimmten Version mit claude install 2.1.310. Wird die Installation über eine Paketverwaltung bereitgestellt, wähle im üblichen Bereitstellungsprozess ein Paket oder einen Kanal, der die benötigte Version liefert.

Führe claude --version erneut aus und starte eine neue Claude-Code-Sitzung. Wird weiterhin die alte Version angezeigt, suche mit which -a claude in Bash oder where.exe claude in PowerShell nach konkurrierenden Installationen. Bei einem integrierten Terminal musst du möglicherweise auch den Editor neu starten, damit er den geänderten PATH übernimmt.

Ordne den Gateway-Fehler dem passenden Wiederholungsversuch zu

Wähle die Korrektur anhand des zurückgegebenen Fehlertexts. Ein allgemeiner 400 sagt noch nicht, welche Funktion das Gateway abgelehnt hat.

Anthropics Leitfaden zur Gateway-Kompatibilität dokumentiert diese Möglichkeiten zur Wiederherstellung der Anfrage:

Erkennbares Antwortmuster	Automatischer Fallback	Was du prüfen solltest
`400`, der mit `Unexpected value(s)` beginnt und `effort-2025-11-24` für `anthropic-beta` nennt	Lässt für dieses Modell das effort-Feld und die Beta weg, bis Claude Code beendet wird.	Entferne diesen Wert, falls du ihn manuell zu `ANTHROPIC_BETAS` hinzugefügt hast.
`400` mit `output_config.effort` und `Extra inputs are not permitted` oder dem Hinweis, dass effort nicht unterstützt wird	Verwendet den Fallback ohne effort.	Bestätige, dass tatsächlich das effort-Feld abgelehnt wird.
`400`, beispielsweise `Unexpected role "system"`	Verschiebt Systemtext innerhalb der Unterhaltung in Benutzernachrichten; behält dieses Format bis `/clear` oder zur Kontextkomprimierung bei.	Wiederhole die Anfrage in der betroffenen Unterhaltung.

Der Fallback verändert die Anfrage. Der effort-Parameter steuert, wie das Modell Tokens verwendet. Ein erfolgreicher Wiederholungsversuch ohne diesen Parameter belegt daher nicht, dass deine gewünschte effort-Einstellung berücksichtigt wurde. Auch beim Verschieben von Systemtext in Benutzernachrichten bleibt der Text erhalten, seine Darstellung ändert sich jedoch.

Reproduziere den Fehler in derselben Unterhaltung

Behalte beim Prüfen des Updates dasselbe Gateway, dieselbe Quelle der Zugangsdaten und dasselbe ausgewählte Modell bei. So bleibt der Vergleich aussagekräftig: Wechselst du gleichzeitig Anbieter und Version, lässt sich die Ursache nicht mehr eindeutig zuordnen.

Starte zunächst Claude Code und führe /status aus. Die Anleitung zum Verbinden mit einem Gateway erklärt, wie du dort die aktive Basis-URL und die Quelle der Zugangsdaten bestätigst. Fehlt das gewünschte Gateway, korrigiere zuerst diese Konfiguration, bevor du dessen Beta-Unterstützung untersuchst.

Beende anschließend die Sitzung und öffne die betroffene Unterhaltung mit einem lokalen Diagnoseprotokoll erneut. In Bash:

claude --resume --debug-file ./claude-gateway-debug.log

Wähle die fehlgeschlagene Sitzung in der Auswahlliste und wiederhole die kleinste Anfrage, die das Problem reproduziert. Diese Optionen sind in der CLI-Referenz dokumentiert.

Der unmittelbare Erfolgsnachweis ist eine brauchbare Antwort des Assistenten an der Stelle, an der die vorherige Anfrage fehlgeschlagen ist. Um festzustellen, ob der Kompatibilitäts-Fallback die Anfrage wieder ermöglicht hat, prüfe die verfügbaren Client-Diagnosen und gegebenenfalls die Anfrageprotokolle des Gateways: Auf die Ablehnung sollte ein angepasster Wiederholungsversuch folgen. Eine erfolgreiche erste Eingabe in einer neuen Unterhaltung prüft nicht alle Nachrichtenstrukturen, die später auftreten können.

Für BetterToken nennt die Claude-Code-Konfiguration ANTHROPIC_BASE_URL=https://bettertoken.ai ohne /v1. Behalte diese dokumentierte Adresse bei, während du das Client-Update prüfst.

Wenn der aktualisierte Client weiterhin scheitert

Lass den Body der Fehlerantworten des Upstream-Dienstes unverändert: Wird eine erkennbare Ablehnung durch einen undurchsichtigen Gateway-Fehler ersetzt, erkennt der Client möglicherweise nicht mehr, dass ein Fallback nötig ist. Auch mit CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 bleiben effort und Systemeinträge innerhalb der Unterhaltung erhalten. Die Einstellung ist daher kein universeller Schalter gegen diese Fehler.

Wähle den nächsten Schritt anhand der verbleibenden Hinweise:

Dieselbe erkennbare Ablehnung wiederholt sich: Prüfe die tatsächlich gestartete Programmdatei, manuell gesetzte Beta-Werte und ob das Gateway den Upstream-Fehler umschreibt.
Die Authentifizierung schlägt fehl: Folge den Zugangsdaten-Anweisungen des Gateways. Die Verbindungsanleitung unterscheidet ANTHROPIC_AUTH_TOKEN für Bearer-Authentifizierung und ANTHROPIC_API_KEY für x-api-key. Verwende das von deinem Anbieter dokumentierte Verfahren.
Der Fehler nennt ein anderes Feld: Untersuche die Kompatibilitätsanforderungen dieses Felds. Ordne nicht jede Schema-Ablehnung dem effort-Fehler zu.
Die Verbindung scheitert, bevor eine API-Antwort eintrifft: Prüfe Endpoint, Proxy, DNS oder die TLS-Verbindung.

Wenn du den Fall an den Support weitergibst, sammle Client-Version, Betriebssystem, ausgewählte Modell-ID, Anfragezeit oder Anfrage-ID, HTTP-Status und den genauen Fehlertext. Teile einen um sensible Angaben bereinigten Diagnoseausschnitt statt Zugangsdaten oder eines vollständigen Gesprächsprotokolls.

Prüfe, ob Windows-Hooks wirklich blockieren

Aktualisiere mindestens auf 2.1.310 und teste anschließend den Fehlerfall jedes Hooks, auf den du dich zur Durchsetzung von Richtlinien verlässt. Die beiden aufeinanderfolgenden Versionen beheben unterschiedliche Fälle:

2.1.309 korrigiert die Verarbeitung von Exit-Codes bei PowerShell-Hooks sowie Fehler bei fehlendem Git, wenn Hooks ausdrücklich PowerShell auswählen.
2.1.310 behebt zusätzlich den Fall, in dem Git Bash fehlt und der Hook-Befehl ausschließlich aus Zeichenfolgen in Anführungszeichen besteht.

Ein Hook-Fehler bedeutet nicht automatisch, dass die Aktion abgelehnt wird. Die Hooks-Referenz bietet onFailure: "block" für Befehls- und HTTP-Hooks, die bei einem Fehler die auslösende Aktion stoppen müssen.

Teste die Regression bei Befehlen in Anführungszeichen

Verwende eine separate Testumgebung mit nativem Windows, die du anschließend verwerfen kannst. Dort darf Git Bash nicht vorhanden sein; die Claude-Code-Verbindung muss funktionieren, und keine unbeteiligten Hooks oder Plugins dürfen das Ergebnis beeinflussen. So prüfst du den Fall ohne Git Bash, ohne Git von deinem Arbeitsrechner zu entfernen.

Erstelle in PowerShell ein neues Testverzeichnis und eine unbedenkliche Datei:

$hookProbe = Join-Path $env:TEMP ("claude-hook-probe-" + [guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path (Join-Path $hookProbe '.claude') -Force | Out-Null
Set-Location $hookProbe
Set-Content -LiteralPath .\probe.txt -Value ([guid]::NewGuid().ToString())
Test-Path 'C:\__claude_hook_probe_missing__\python.exe'
claude --version

Test-Path muss False zurückgeben, und die Version muss mindestens 2.1.310 sein.

Erstelle im Testverzeichnis die Datei .claude/settings.local.json mit folgendem Inhalt:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "\"C:\\__claude_hook_probe_missing__\\python.exe\""
          }
        ]
      }
    ]
  }
}

Die Felder shell, args und onFailure fehlen absichtlich: Diese Phase untersucht den Fallback für den Befehl in Anführungszeichen selbst.

Starte die Sitzung in PowerShell:

claude --tools Read --debug-file .\phase1.log

Bestätige für dieses Testverzeichnis, dass du dem Arbeitsbereich vertraust. Führe anschließend /hooks aus und prüfe, ob der PreToolUse-Hook auf Read zutrifft. Gib folgende Anweisung:

Verwende das Tool Read genau einmal, um probe.txt zu lesen. Falls der Aufruf blockiert wird, melde das und halte an. Verwende keinen anderen Weg.

Erwartetes Ergebnis: Der Read-Aufruf wird blockiert, und im Fehler oder in den Diagnosen erscheint PowerShell started no program. PowerShell wertet einen Pfad in Anführungszeichen normalerweise als Zeichenfolge aus. Microsofts Dokumentation zum Aufrufoperator erklärt, warum für die Ausführung dieses Pfads eine andere Syntax erforderlich ist.

Liefert Read tatsächlich ein erfolgreiches Ergebnis, ist diese Prüfung fehlgeschlagen. Versucht Claude gar nicht erst, Read aufzurufen, ist das Ergebnis nicht aussagekräftig. Prüfe das Tool-Ergebnis und das Protokoll, statt die Beschreibung des Modells als Beleg zu akzeptieren.

Falls /hooks die Konfiguration nicht aufführt, folge den Prüfschritten zum Laden von Hooks. Einstellungen werden normalerweise automatisch neu geladen. Hat die Dateiüberwachung eine Änderung übersehen, erzwingt ein Neustart das erneute Laden. Eine verwaltete Richtlinie, die ausschließlich verwaltete Hooks zulässt, bedeutet ebenfalls, dass dieser Test auf Projektebene nicht ausgeführt wurde.

Teste einen tatsächlich fehlenden Interpreter

Lege ausdrücklich fest, wie Fehler behandelt werden sollen, und prüfe damit, was passiert, wenn der Interpreter nicht starten kann. Beende die Testsitzung und ersetze nur das innere Hook-Objekt durch:

{
  "type": "command",
  "command": "C:\\__claude_hook_probe_missing__\\python.exe",
  "args": [],
  "onFailure": "block"
}

Hier wählt args den direkten Aufruf der Programmdatei. Die fehlende Programmdatei verursacht jetzt einen echten Startfehler; es wird nicht lediglich ein Ausdruck mit einer Zeichenfolge in Anführungszeichen ausgewertet.

Starte die Sitzung in PowerShell erneut und wiederhole dieselbe Read-Anweisung:

claude --tools Read --debug-file .\phase2.log

Erwartetes Ergebnis: Read wird blockiert, weil der Interpreter nicht gestartet werden konnte. Das prüft die ausdrücklich konfigurierte Fehlerbehandlung unabhängig davon, ob Git Bash verfügbar ist. Es ist eine andere Prüfung als die Regression beim Befehl in Anführungszeichen.

Entferne nach der Auswertung die Testkonfiguration. Stelle bei echten Richtlinien-Hooks den funktionsfähigen Interpreter wieder her und behalte eine ausdrückliche Blockierregel bei, wenn eine fehlgeschlagene Prüfung die Aktion stoppen muss.

Diese Tests prüfen PreToolUse. Ein PermissionRequest-Hook benötigt eine separate Prüfung mit einer Aktion, die tatsächlich die Berechtigungsabfrage erreicht. Seine reguläre Ablehnung verwendet hookSpecificOutput.decision.behavior mit dem Wert "deny". Der Exit-Code 2 allein führt bei diesem Ereignis nicht zur Ablehnung. Ein tatsächlicher Fehler mit onFailure: "block" lehnt die Anfrage ab.

Lege die Aufbewahrungsfrist gezielt fest

Verwende den dokumentierten Standard von 30 Tagen, sofern dein Team keine andere konkrete Aufbewahrungsanforderung hat. Archiviere benötigte Verläufe, bevor du eine bestehende Frist verkürzt.

Die Bereinigungskorrektur betrifft das Löschen neuerer Dateien bei extrem hohen Werten für cleanupPeriodDays. Sie macht die Einstellung weder zu einem Archivierungssystem noch stellt sie bereits entfernte Dateien wieder her.

Sichere verbliebene Daten, bevor du die Frist änderst

Beende aktive Sitzungen und kopiere weiterhin benötigte Daten an einen Speicherort außerhalb der von Claude Code verwalteten Verzeichnisse. Sichere die relevanten Daten aus ~/.claude beziehungsweise %USERPROFILE%\.claude unter Windows sowie noch vorhandene Bildanhänge.

Laut der aktuellen Dokumentation zu Anwendungsdaten liegen neu eingefügte Bilder in sitzungsspezifischen images/-Verzeichnissen unter dem temporären Stammverzeichnis von Claude Code, das über CLAUDE_CODE_TMPDIR gesteuert wird. Eine Sicherung ausschließlich von ~/.claude belegt daher nicht, dass auch die aktuellen Bildkopien gesichert wurden.

Ergänze nach der Sicherung die entsprechende Einstellungsdatei um diesen Eintrag:

{
  "cleanupPeriodDays": 30
}

Für deinen persönlichen Standard ist das ~/.claude/settings.json beziehungsweise %USERPROFILE%\.claude\settings.json unter Windows. Behalte die anderen Schlüssel der Datei bei.

Laut Dokumentationsstand vom 2026-10-25 ist der Mindestwert 1; 0 besteht die Validierung nicht. Mit einer kürzeren Frist können ältere Daten bei der Bereinigung gelöscht werden. Sichere sie deshalb zuerst.

Führe claude doctor aus, um die Gültigkeit der Einstellungen zu prüfen. Wird der gewünschte Wert nicht angewendet, prüfe die Rangfolge der Einstellungen: Verwaltete Einstellungen sowie höher priorisierte Sitzungs- oder Projekteinstellungen können deine persönliche Datei übersteuern. /status zeigt die geladenen Quellen, nicht den endgültig wirksamen Wert jedes einzelnen Schlüssels.

Stelle fehlende Anhänge separat wieder her

Stelle ein fehlendes Bild aus seiner Originaldatei oder einer vorhandenen Dateisystemsicherung wieder her und füge die wiederhergestellte Kopie erneut der Unterhaltung hinzu. Prüfe, ob sich die Datei lokal öffnen lässt und Claude den Anhang wieder verwenden kann.

Eine geänderte Aufbewahrungsfrist kann gelöschte Bytes nicht rekonstruieren. Gehe auch nicht davon aus, dass /rewind einen Anhang zurückholt: Checkpoint-Snapshots laufen ebenfalls ab, und eine Wiederherstellung kann scheitern, wenn die erforderlichen Snapshots fehlen.

Falls dein Team bereits Telemetrie exportiert, untersuche ein abgeschlossenes claude_code.retention_sweep-Ereignis. Die Monitoring-Referenz dokumentiert result: "complete" und period_days als Zeichenfolge. Der Wert "30" bestätigt, dass genau dieser Bereinigungslauf eine Frist von 30 Tagen verwendet hat.

Ein kurzer Neustart reicht nicht als Beleg dafür, dass die Bereinigung ausgeführt wurde. Sie läuft im Hintergrund höchstens einmal pro Sitzung. Gab es in den vorherigen 24 Stunden einen Bereinigungslauf, verzögert sich der Lauf der nächsten Sitzung um mindestens 10 Minuten. Behandle die Lesbarkeit der Anhänge und den Nachweis einer abgeschlossenen Bereinigung als getrennte Beobachtungen.

Die Verfügbarkeit von Monitor ist eine separate Änderung

Version 2.1.310 macht das Monitor-Tool und Plugin-Monitore auch auf Bedrock, Vertex und Foundry verfügbar, einschließlich Konfigurationen mit deaktivierter Telemetrie oder deaktiviertem, nicht notwendigem Netzwerkverkehr. Die Versionshinweise nennen außerdem das Blockieren langer Wartephasen im Vordergrund in diesen Umgebungen.

Falls Monitor in einer solchen Bereitstellung fehlte, prüfe die laufende Version, bevor du die Telemetrierichtlinie änderst. Diese erweiterte Verfügbarkeit sagt nichts darüber aus, ob ein bestimmtes Gateway effort-Einstellungen oder Systemeinträge innerhalb der Unterhaltung akzeptiert.