Claude Code settings.json und Umgebungsvariablen: Base-URL, Auth-Token und Modell

Claude Code bezieht seine Konfiguration aus JSON-Einstellungsdateien und Umgebungsvariablen. Wenn Sie es über ein Gateway statt über die API von Anthropic ausführen möchten, benötigen Sie zwei Variablen, ANTHROPIC_BASE_URL und ein Token, sowie üblicherweise ein Modell. Die Variablen sind einfach. Verwirrend ist, wo sie eingetragen werden, denn dieselbe Variable kann in Ihrem Shell-Profil, in mehreren settings.json-Dateien und in den Einstellungen von VS Code stehen.

Dieser Leitfaden beginnt mit einer funktionierenden Konfiguration und erklärt anschließend, wo sich die Dateien befinden, welcher Wert Vorrang hat und welche Fehler wahrscheinlich auftreten. Er wurde anhand der Dokumentation von Anthropic überprüft und am 20. Oktober 2026 mit AIHubMix unter Claude Code 2.1.304 getestet. Die Beispiele verwenden AIHubMix als Gateway; jeder Anthropic-kompatible Endpunkt wird auf die gleiche Weise eingerichtet.

Kurzfassung

• Ihre persönliche Einstellungsdatei ist ~/.claude/settings.json oder unter Windows %USERPROFILE%\.claude\settings.json.
• Tragen Sie für ein Gateway ANTHROPIC_BASE_URL (ohne /v1) und ANTHROPIC_AUTH_TOKEN im env-Block dieser Datei ein.
• Ein Wert im env-Block einer Einstellungsdatei überschreibt dieselbe Variable, wenn sie in Ihrer Shell exportiert wurde.
• Sobald ein Token festgelegt ist, werden Anfragen nicht mehr über Ihr Claude-Abonnement, sondern über das Gateway abgerechnet.
• Die VS-Code-Erweiterung benötigt dieselben Variablen in ihrer eigenen Einstellung claudeCode.environmentVariables.

Eine funktionierende AIHubMix-Konfiguration

1. Erstellen Sie einen Schlüssel in der AIHubMix-Konsole.
2. Fügen Sie Folgendes in ~/.claude/settings.json ein. Erstellen Sie die Datei, falls sie noch nicht vorhanden ist.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-aihubmix-key"
  },
  "model": "claude-sonnet-5-5"
}

3. Führen Sie einen kurzen Test durch:

claude -p "1+1, output only the answer"

4. Starten Sie claude in einem Projekt. In der Kopfzeile unter dem Logo sollte etwa Sonnet 5.5 · API Usage Billing stehen. Mit /status wird Ihr Gateway in der Zeile Anthropic base URL angezeigt.

Zwei Details sind wichtig. Die Base-URL ist die Stammadresse: Claude Code hängt selbst /v1/messages an, daher führt eine URL mit dem Ende /v1 dazu, dass alle Anfragen fehlschlagen. Außerdem verwendet AIHubMix die Modell-IDs von Anthropic, etwa claude-sonnet-5-5. Daher funktionieren die Kurzformen sonnet, opus und haiku ohne zusätzliche Einrichtung.

Die Zeile $schema ist optional. Sie ermöglicht es VS Code, Cursor und anderen Editoren, beim Tippen Fehler in der Datei zu markieren.

Sie können dieselben beiden Variablen stattdessen in Ihrer Shell exportieren. Eine Einstellungsdatei ist jedoch der bessere Ort: Jede Terminal- und IDE-Erweiterung sowie Hintergrundagenten lesen sie aus.

Speicherorte der Einstellungsdateien

Legen Sie niemals ein Token in der Projektdatei .claude/settings.json ab, da diese in Git eingecheckt wird. Verwenden Sie Ihre Benutzerd Datei oder .claude/settings.local.json.

Einstellungsdateien müssen gültiges JSON enthalten. Ein Kommentar mit // oder ein nachgestelltes Komma führt dazu, dass Claude Code die gesamte Datei ignoriert, einschließlich des Tokens. Statt Ihres Gateways wird dann der Anmeldebildschirm angezeigt.

Verwechseln Sie diese Dateien nicht mit ~/.claude.json, einer einzelnen Datei in Ihrem Home-Ordner. Darin speichert Claude Code seinen eigenen Status, etwa Ihre Anmeldung und MCP-Server. Sie müssen diese Datei nur selten bearbeiten.

Welcher Wert Vorrang hat

Wenn mehrere Dateien denselben Wert festlegen, gilt die von Anthropic definierte Rangfolge der Einstellungen (höchster Vorrang zuerst):

1. Von Ihrer Organisation verwaltete Einstellungen
2. --settings in der Befehlszeile, nur für diese Sitzung
3. .claude/settings.local.json
4. .claude/settings.json
5. ~/.claude/settings.json

Für Umgebungsvariablen gilt noch eine weitere Regel: Eine Variable im env-Block einer Einstellungsdatei überschreibt dieselbe Variable aus Ihrer Shell. Daher hat ein export ANTHROPIC_BASE_URL=... in ~/.zshrc keine Wirkung, wenn sie auch in einer Einstellungsdatei festgelegt ist. Tools zum Wechseln des Anbieters schreiben meist in ~/.claude/settings.json, weshalb deren Werte Vorrang vor denen Ihrer Shell haben.

In Claude Code zeigt /status in der Zeile Setting sources die geladenen Dateien an.

ANTHROPIC_AUTH_TOKEN oder ANTHROPIC_API_KEY

Verwenden Sie die Variable, die Ihr Gateway ausliest. AIHubMix akzeptiert beide. In der Anleitung von AIHubMix für Claude Code wird ANTHROPIC_AUTH_TOKEN verwendet; das ist auch die einfachere Wahl. Lassen Sie nicht beide Variablen gesetzt. Claude Code sendet dann beide Header, und AIHubMix prüft zuerst x-api-key: In unserem Test führte ein korrektes Token in settings.json trotzdem zu einem 401-Fehler, weil ein alter ANTHROPIC_API_KEY in der Shell exportiert war. Der env-Block überschreibt nur die Variablen, die er selbst festlegt. Entfernen Sie daher beim Wechsel den alten Schlüssel aus Ihrem Shell-Profil.

Was ist mit Ihrem Claude-Abonnement? Laut dem Gateway-Leitfaden von Anthropic werden Anfragen mit einem festgelegten Token oder API-Key anstelle Ihrer Anmeldung bei claude.ai gesendet. Das Gateway rechnet pro Token ab. Ihre Anmeldung bleibt gespeichert und wird wieder verwendet, sobald Sie die Variable entfernen. Wenn Sie nur ANTHROPIC_BASE_URL, aber kein Token festlegen, wird weiterhin Ihr Abonnement genutzt.

Das Modell auswählen

Auf der Seite zur Modellkonfiguration von Anthropic ist die folgende Reihenfolge angegeben (höchster Vorrang zuerst):

1. /model <name> während einer Sitzung
2. claude --model <name> beim Start
3. Die Variable ANTHROPIC_MODEL
4. Der Schlüssel model in einer Einstellungsdatei

/model speichert Ihre Auswahl als neuen Standard. Wenn jedoch ANTHROPIC_MODEL festgelegt ist, wird jede neue Sitzung erneut mit diesem Modell gestartet. Wenn Sie häufig zwischen Modellen wechseln, legen Sie den Schlüssel model fest und lassen Sie ANTHROPIC_MODEL weg. Wenn nirgendwo ein Modell festgelegt ist, verwendet Claude Code Opus 5.5.

ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL und ANTHROPIC_DEFAULT_HAIKU_MODEL ändern, welches Modell die jeweilige Kurzform aufruft. Sie benötigen diese Variablen nur, wenn eine Kurzform auf ein anderes Modell verweisen soll, zum Beispiel, wenn sonnet weiterhin eine ältere Version verwenden soll.

AIHubMix bietet unter derselben Adresse auch Modelle anderer Anbieter an. Anthropic unterstützt Claude Code jedoch nicht mit Modellen, die nicht von Claude stammen, daher funktionieren manche Funktionen damit möglicherweise nicht.

Wann Änderungen wirksam werden

Claude Code überwacht seine Einstellungsdateien. Die meisten gespeicherten Änderungen, auch im env-Block, werden in der laufenden Sitzung übernommen. Der Schlüssel model, entfernte Variablen und Shell-Exporte erfordern einen Neustart. Starten Sie Claude Code im Zweifelsfall neu.

Die VS-Code-Erweiterung

Die Erweiterung liest dieselben Einstellungsdateien, prüft jedoch vor dem Start mithilfe ihrer eigenen Einstellung claudeCode.environmentVariables, ob Sie angemeldet sind. Deshalb kann VS Code Sie zur Anmeldung auffordern, während die CLI funktioniert. Öffnen Sie über die Befehlspalette Preferences: Open User Settings (JSON) und fügen Sie Folgendes hinzu:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://aihubmix.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-your-aihubmix-key" }
  ]
}

Führen Sie anschließend Developer: Reload Window aus. Weitere Optionen finden Sie in der VS-Code-Dokumentation von Anthropic. Die Claude-Desktop-App ist davon getrennt: Sie liest weder settings.json noch diese Variablen aus.

Weitere nützliche Variablen

Alle diese Variablen können in den env-Block. Die vollständige Liste finden Sie in Anthropic’s Referenz zu Umgebungsvariablen.

Häufige Fehler und ihre Bedeutung

Not logged in · Please run /login oder der Anmeldebildschirm beim ersten Start
Claude Code hat kein Token gefunden. Prüfen Sie drei Dinge: einen JSON-Fehler, durch den die Datei ignoriert wurde, ein fehlendes ANTHROPIC_AUTH_TOKEN oder ein Token, das nur in einer Projektdatei steht. Die Anmeldung erfolgt, bevor die Projekteinstellungen geladen werden. Verschieben Sie das Token daher nach ~/.claude/settings.json.

Invalid or malformed JSON
Die in der Meldung genannte Datei enthält einen Kommentar, ein nachgestelltes Komma oder einen anderen Syntaxfehler. Keine ihrer Einstellungen wurde angewendet.

There's an issue with the selected model (...)
Entweder ist die Modell-ID falsch oder die Base-URL endet mit /v1, sodass die Anfrage an /v1/v1/messages gesendet wurde. Wenn die Modell-ID korrekt aussieht, prüfen Sie zuerst die URL.

API Error: 400 mit This model ID is incorrect
AIHubMix kennt kein Modell mit dieser ID; die Meldung wiederholt die empfangene ID. Meist ist sie falsch geschrieben. Kopieren Sie die ID erneut aus der AIHubMix-Modellliste.

Failed to authenticate. API Error: 401 invalid key: ...
AIHubMix akzeptiert den Schlüssel nicht. Die Meldung endet mit den letzten sechs Zeichen des empfangenen Schlüssels. Vergleichen Sie diese mit dem Ende Ihres Tokens. PI_KEY bedeutet, dass statt eines echten Schlüssels der Platzhalter AIHUBMIX_API_KEY eingefügt wurde. Bei anderen Endungen wurde meist ein alter ANTHROPIC_API_KEY aus Ihrer Shell gesendet. Wenn stattdessen this key is not enabled angezeigt wird, prüfen Sie in der AIHubMix-Konsole, ob der Schlüssel aktiviert ist und über Guthaben verfügt.

auth may not work as expected
Sowohl eine Token-Variable als auch eine gespeicherte Anmeldung bei claude.ai sind aktiv. Führen Sie /logout aus, um das Gateway weiterzuverwenden, oder entfernen Sie die Variable, um zu Ihrem Abonnement zurückzukehren.

Claude Code doesn't recognize the model ...
Das ist eine Warnung, kein Fehler: Die Anfrage wird trotzdem gesendet, aber Claude Code geht von einem Kontextfenster mit 200K Token aus. Wenn es sich bei der ID um ein neueres Claude-Modell handelt, behebt claude update das Problem.

Es scheint mit einem ungültigen Schlüssel zu hängen
Claude Code versucht fehlgeschlagene Anfragen bis zu 10-mal erneut. In einem Test mit einem Schlüssel, der immer abgelehnt wurde, wiederholte claude -p die Anfrage etwa drei Minuten lang. Verringern Sie CLAUDE_CODE_MAX_RETRIES, damit der Fehler früher angezeigt wird.

Wenn Sie in Claude Code einen Schlüssel für Claude und in Ihren anderen Tools Schlüssel für OpenAI, Google und weitere Anbieter verwenden möchten, stellt AIHubMix die Anthropic API unter https://aihubmix.com bereit. Die obige Einstellungsdatei enthält alles, was Claude Code benötigt.

FAQ

Wo befindet sich die settings.json von Claude Code?
Ihre persönliche Datei ist ~/.claude/settings.json oder unter Windows %USERPROFILE%.claude\settings.json. Ein Projekt kann auch eine .claude/settings.json enthalten, die über Git geteilt wird, sowie eine .claude/settings.local.json, die nur für Sie bestimmt ist. Claude Code erstellt diese Dateien nicht bei der Installation.

Überschreibt settings.json Umgebungsvariablen?
Ja. Ein Wert im env-Block einer Einstellungsdatei überschreibt dieselbe Variable, die in Ihrer Shell exportiert wurde. Variablen, die die Datei nicht festlegt, etwa ein altes ANTHROPIC_API_KEY, stammen weiterhin aus der Shell.

Sollte ich ANTHROPIC_AUTH_TOKEN oder ANTHROPIC_API_KEY verwenden?
Verwenden Sie die Variable, die Ihr Gateway ausliest. ANTHROPIC_AUTH_TOKEN sendet ein Bearer-Token und erfordert keine Genehmigung. Für AIHubMix ist ANTHROPIC_AUTH_TOKEN die dokumentierte Option. Legen Sie nicht beide fest: AIHubMix liest zuerst x-api-key aus, sodass ein veralteter ANTHROPIC_API_KEY einen 401-Fehler verursacht.

Sollte ANTHROPIC_BASE_URL mit /v1 enden?
Nein. Claude Code fügt /v1/messages selbst hinzu. Verwenden Sie für AIHubMix https://aihubmix.com.

Muss ich Claude Code nach dem Bearbeiten von settings.json neu starten?
Die meisten Änderungen, einschließlich Änderungen an env, werden beim Speichern übernommen. Der Modellschlüssel und Shell-Exporte erfordern einen Neustart. Ein Neustart ist die sichere Wahl.

Warum fordert VS Code mich zur Anmeldung auf, obwohl die CLI funktioniert?
Bevor die Erweiterung startet, prüft sie anhand ihrer Einstellung claudeCode.environmentVariables, ob eine Anmeldung vorliegt. Werte in ~/.claude/settings.json werden bei dieser Prüfung nicht berücksichtigt. Fügen Sie dort die Basis-URL und das Token hinzu und laden Sie das Fenster neu.

Wird durch das Festlegen von ANTHROPIC_BASE_URL mein Claude-Abonnement verwendet?
Nur wenn kein Token festgelegt ist. Wenn ANTHROPIC_AUTH_TOKEN oder ANTHROPIC_API_KEY festgelegt ist, verwenden Anfragen diesen Schlüssel und das Gateway rechnet pro Token ab.

Quellen

• Einstellungsdateien und Priorität, Anthropic
• Umgebungsvariablen, Anthropic
• Claude Code mit einem LLM-Gateway verbinden, Anthropic
• Modellkonfiguration, Anthropic
• Integrationsleitfaden für Claude Code, AIHubMix