Zum Hauptinhalt springen

settings.json: Das Konfigurationssystem

Fortgeschritten

In settings.json liegt die Konfiguration von Claude Code — Berechtigungen, Hooks, Umgebungsvariablen, Modell-Standards und mehr. Der Schlüssel liegt im Verständnis der Ebenen.

What you'll learn
  • Der fünfstufige Vorrang-Stack und welche Datei gewinnt, wenn zwei davon denselben Schlüssel setzen
  • Warum Umgebungsvariablen keine Ebene sind und was das für ANTHROPIC_MODEL bedeutet
  • In welche Datei eine Einstellung gehört: eingecheckte Team-Konvention, persönliche Überschreibung oder Ein-Sitzungs-Experiment
  • Die vier Abschnitte, die du tatsächlich bearbeiten wirst, und wo jeder ausführlich dokumentiert ist
  • Wie du bearbeitest, ohne die Datei zu zerstören, und was nie in eine eingecheckte Einstellungsdatei gehört

Die Ebenen (höchster Vorrang zuerst)​

Wenn derselbe Schlüssel an mehr als einer Stelle gesetzt ist, verwendet Claude Code den Wert der höchsten Ebene, die ihn setzt:

Guided walkthrough1 of 5
  1. managed-settings.json, eine MDM-Richtlinie oder serverseitig verwaltete Einstellungen aus der claude.ai-Konsole. Nichts, was du setzt, überschreibt sie (bis auf ein paar sicherheitsrelevante Ausnahmen).
Umgebungsvariablen sind keine Ebene

Sie stehen außerhalb dieses Stacks und werden pro Schlüssel aufgelöst. ANTHROPIC_MODEL gilt zum Beispiel über dem Schlüssel model aus jeder Datei, während ANTHROPIC_DEFAULT_MODEL nur greift, wenn keine Datei model setzt.

Die geteilte Datei einchecken, die lokale ignorieren

Lege Team-Konventionen in .claude/settings.json ab (eingecheckt). Lege persönliche Anpassungen und maschinenspezifische Pfade in .claude/settings.local.json ab (von Git ignoriert). So bleibt das Team konsistent, ohne dass du anderen deine Vorlieben aufzwingst.

Was du üblicherweise setzt​

  • permissions — Allow-/Ask-/Deny-Regeln. Siehe Berechtigungen.
  • hooks — Befehle, die bei Lebenszyklus-Ereignissen laufen. Siehe Hooks.
  • env — Umgebungsvariablen für die Sitzung.
  • Modell-/Verhaltens-Standards — z. B. das bevorzugte Modell.

Sicher bearbeiten​

  • Halte die Datei gültiges JSON (ein abschließendes Komma macht sie kaputt).
  • Bevorzuge enge Berechtigungsregeln gegenüber breiten.
  • Lege nie Secrets in eine eingecheckte Datei — verwende env-Verweise oder einen Secrets-Manager.

Eine Einstellung für eine Sitzung ausprobieren, ohne sie in eine Datei zu schreiben

claude --settings '{"permissions":{"allow":["Bash(git log *)"]}}'

Startdateien zum Kopieren findest du unter Hooks- & settings.json-Rezepte. Wenn eine Datei fehlerhaft ist oder ein Schlüssel nicht tut, was du erwartest, gibt claude doctor Validierungsfehler der Einstellungsdatei aus, ohne eine Sitzung zu starten — dazu und zu --safe-mode siehe die CLI-Seite.

Teste dich selbst​

Check yourself

0/3
  1. Die eingecheckte .claude/settings.json deines Repos setzt ein Modell, und deine ~/.claude/settings.json setzt ein anderes. Welches gilt?
  2. Wohin gehört ein maschinenspezifischer absoluter Pfad?
  3. Welche Aussage über Umgebungsvariablen stimmt?
Key takeaways
  • Fünf Ebenen, eine Regel: Die höchste Ebene, die einen Schlüssel setzt, gewinnt. Verwaltet ist absolut; Benutzereinstellungen sind die schwächsten.
  • Eingecheckte Datei für Team-Konventionen, lokale Datei für persönliche und maschinenspezifische Werte, --settings für ein Wegwerf-Experiment.
  • Umgebungsvariablen sind keine Ebene. Prüfe die Regel jeder Variable, statt eine Position im Stack anzunehmen.
  • Secrets gehören nie in eine eingecheckte Einstellungsdatei.
  • Wenn eine Einstellung ignoriert scheint, führe claude doctor aus und achte auf Validierungsfehler, bevor du irgendetwas anderes änderst.

Weiter​