Einstellungsdateien und Priorität

​

Einstellungsdateien und wer sie betreffen

​

Vergleichen Sie den Bereich jeder Einstellungsdatei

• ~/.claude/settings.json: jedes Projekt auf Ihrer Maschine, und nichts auf der Ihres Teamkollegen oder in der Cloud-Sitzung
• acme-app/.claude/settings.json: Ihr acme-app/. Es erreicht den Klon Ihres Teamkollegen und die Cloud-Sitzung nur, wenn Sie die Datei in die Versionskontrolle committen; bis dahin ist es eine Datei auf Ihrer Festplatte wie jede andere und niemand sonst hat sie
• acme-app/.claude/settings.local.json: nur Ihr acme-app/. Claude Code fügt es zu Ihren globalen Git-Ausschlüssen hinzu, wenn es die Datei zum ersten Mal schreibt, sodass es aus Ihren Commits herausbleibt; wenn Sie die Datei von Hand erstellen, fügen Sie sie selbst zu .gitignore hinzu
• Verwaltete Einstellungen, ob eine managed-settings.json Datei, eine MDM-Richtlinie oder serververwaltete Einstellungen von der claude.ai-Konsole: jedes Projekt auf jeder Maschine, für die Ihre Organisation es bereitstellt, oder auf die Sie sich mit Ihrem Organisationskonto anmelden. Nur serververwaltete Einstellungen erreichen die Cloud-Sitzung

​

Finden oder erstellen Sie Ihre Einstellungsdateien

• Verwaltet: Ihre Organisation stellt sie bereit. Sie erstellen oder bearbeiten sie nicht.
• Gemeinsames Projekt: Ein Projekt, das bereits Claude Code verwendet, kann eine eingecheckte haben. Wenn nicht, erstellen Sie eine unter .claude/settings.json im Projektordner.
• Benutzer und Projekt lokal: Erstellen Sie sie selbst, oder lassen Sie Claude Code sie erstellen. Es schreibt ~/.claude/settings.json das erste Mal, wenn Sie eine Option im /config Menü ändern, die es in Benutzereinstellungen speichert, wie das Design, und .claude/settings.local.json das erste Mal, wenn Sie eine stehende Genehmigung auf einer Berechtigungsaufforderung geben, wie “Ja, und frag mich nicht mehr” für einen Bash-Befehl. Ein paar /config Optionen, einschließlich Tipps anzeigen, speichern stattdessen in .claude/settings.local.json.

​

Teilen Sie Einstellungen mit Ihrem Team

​

Halten Sie persönliche Einstellungen aus einem Repository heraus

• Claude Code schreibt sie auch. Wenn Claude Sie fragt, einen Bash-Befehl auszuführen und Sie “Ja, und frag mich nicht mehr” wählen, speichert Claude Code diese Berechtigungsgenehmigung hier als allow Regel.
• Sie müssen sie nicht selbst gitignorieren, es sei denn, Sie haben sie von Hand erstellt. Das erste Mal, wenn Claude Code die Datei in einem Git-Repository schreibt, das sie nicht bereits ignoriert, fügt es **/.claude/settings.local.json zu Ihrer globalen Git-Ausschluss-Datei hinzu, sodass die Datei in jedem Repository aus Ihren Commits herausbleibt. Diese Datei ist core.excludesFile, wenn Ihre globale Git-Konfiguration sie auf einen absoluten oder ~-präfixierten Pfad setzt; ansonsten ist es $XDG_CONFIG_HOME/git/ignore, oder ~/.config/git/ignore, wenn XDG_CONFIG_HOME nicht gesetzt ist. Wenn Sie die Datei von Hand erstellt haben und Claude Code noch nicht darin geschrieben hat, fügen Sie sie selbst zu .gitignore hinzu.
• Seine Allow-Regeln warten nicht auf Vertrauen, während die Datei nicht verfolgt bleibt. Weil die Datei Ihnen gehört und nicht dem Repository, wendet Claude Code ihre allow Regeln ohne den Workspace-Vertrauens-Schritt an, den es für die eingecheckte Datei erfordert. Wenn die Datei von Git verfolgt wird, gilt der Vertrauensschritt auch für sie; siehe Wenn Ihre lokale Einstellungsdatei Vertrauen benötigt.

​

Wo Claude Code die lokale Datei in einem Git-Repository behält

• Wenn die Datei stattdessen bei .claude/settings.json bleibt: außerhalb eines Git-Repositorys, wenn der Repository-Root Ihr Home-Verzeichnis ist, unter Windows, oder wenn der Repository-Root oder sein .git oder .claude Eintrag nicht Ihrem Benutzer gehört.
• Pfade in der Datei verankern nicht im Repository-Root: eine Berechtigungsregel, die mit / beginnt oder ein relativer Sandbox-Pfad verankert stattdessen im primären Arbeitsverzeichnis der Sitzung.

​

Überprüfen Sie, was Ihre Organisation erzwingt

• Serververwaltete Einstellungen, die Claude Code von der claude.ai Admin-Konsole oder einem selbstgehosteten Claude-Apps-Gateway abruft
• MDM- oder OS-Richtlinien und managed-settings.json Dateien in einem Systemverzeichnis
• Ein Embedding-Host wie Claude Desktop, über die SDK managedSettings Option; siehe Kontrollieren Sie die Richtlinie von einem Embedding-Host

​

Ändern Sie eine Einstellung

​

Verwenden Sie das /config Menü

• Die meisten Optionen: ~/.claude/settings.json
• Ein paar Optionen, wie Tipps anzeigen: .claude/settings.local.json
• Die globalen Konfigurationsoptionen: ~/.claude.json

​

Bearbeiten Sie eine Einstellungsdatei

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

​

Ändern Sie eine Einstellung für eine Sitzung

• --settings: übergeben Sie einen Schlüssel als JSON, inline oder als Pfad zu einer Datei. Claude Code wendet ihn über Ihre Benutzer-, Projekt- und lokalen Dateien und unter verwalteten Einstellungen an. Es kann jeden Schlüssel setzen, den Ihre Benutzereinstellungsdatei kann; es kann keine Managed oder Global config Schlüssel setzen.
• Ein Flag für diesen Schlüssel: einige Schlüssel haben ihr eigenes Flag, wie --model für model und --effort für effortLevel und modelSettings.
• Eine Umgebungsvariable: exportieren Sie die gepaarte Variable des Schlüssels, bevor Sie claude ausführen, wie ANTHROPIC_MODEL für model.

claude --settings '{"model": "claude-opus-4-8"}'

​

Wenn Änderungen wirksam werden

• model: verwenden Sie /model, um mid-Sitzung zu wechseln. Jedes Modell hat seinen eigenen Prompt-Cache, sodass die erste Anfrage nach einem Wechsel das ganze Gespräch ungecacht erneut liest; siehe Wechsel von Modellen
• effortLevel und modelSettings: verwenden Sie /effort, um Anstrengung mid-Sitzung zu ändern

​

Bestätigen Sie, was geladen wurde

​

Beheben Sie eine fehlerhafte Einstellungsdatei

• Einstellungsfehler: eine Benutzer-, Projekt- oder lokale Datei hat ungültiges JSON oder einen Wert, den das Schema ablehnt. Am Anfang einer interaktiven Sitzung zeigt Claude Code einen Dialog, der Ihnen erlaubt, die Datei mit Claudes Hilfe zu beheben, zu beenden oder ohne die fehlerhaften Einstellungen fortzufahren.
• Einstellungswarnung: nur einzelne Einträge schlagen fehl, wie eine fehlerhafte Berechtigungsregel oder ein unbekannter Hook-Ereignisname. Claude Code überspringt diese Werte und behält den Rest der Datei wirksam.
• Verwaltete Einstellungen: Claude Code erzwingt weiterhin den Rest der Datei. Ungültige Einträge in verwalteten Einstellungen sagt, was es ablegt und welche Schlüssel auf einen strengeren Wert zurückfallen, bis Sie sie beheben. Für ein verwaltetes Einstellungsdokument, das nicht gültiges JSON ist, siehe Verwaltetes Einstellungsdokument konnte nicht analysiert werden.
• Konfigurationsfehler: ~/.claude.json kann nicht analysiert werden. Claude Code kopiert die fehlerhafte Datei zu ~/.claude/backups/.claude.json.corrupted.<timestamp> und fragt, ob Sie beenden und sie von Hand beheben oder auf die Standardkonfiguration zurücksetzen möchten; ein -p Lauf druckt den Fehler und beendet. Um Ihren vorherigen Status wiederherzustellen, kopieren Sie eine der fünf neuesten .claude.json.backup.<timestamp> Dateien in ~/.claude/backups/ zurück, die Claude Code vor dem Schreiben der Datei speichert.

​

Einstellungspriorität

1. Verwaltete Einstellungen: Einstellungen, die Ihre Organisation bereitstellt, durch eine managed-settings.json Datei, eine MDM-Richtlinie oder serververwaltete Einstellungen von der claude.ai-Konsole. Nichts, das Sie setzen, überschreibt sie: ein Schlüssel, den Sie mit --settings übergeben, überschreibt nicht den gleichen verwalteten Schlüssel, und ein Flag wie --model wählt nur aus den Modellen, die Ihre Organisation erlaubt. Ein verwaltetes model setzt das Modell, mit dem jede Sitzung startet, und Sie können immer noch mit /model wechseln; die Sperre ist availableModels, die /model, --model und den model Schlüssel in Ihren eigenen Dateien einschränkt. Wenn Ihre Organisation mehr als eine verwaltete Quelle bereitstellt, sagen die Regeln für Priorität innerhalb der verwalteten Ebene, was Claude Code aus jeder liest.
2. Befehlszeilenargumente: Flags, die Sie übergeben, wenn Sie claude von einem Terminal aus starten, für eine Sitzung; siehe Ändern Sie eine Einstellung für eine Sitzung. Claude Code führt JSON, das Sie mit --settings <file-or-json> übergeben, mit Ihren Einstellungsdateien nach den gleichen Regeln wie die anderen Ebenen zusammen: es nimmt einen Schlüssel, den Sie hier setzen, über den gleichen Schlüssel in lokalen, Projekt- oder Benutzereinstellungen, und behält den Wert der niedrigeren Ebene für einen Schlüssel, den Sie weglassen.
3. Projekt-lokale Einstellungen (.claude/settings.local.json): Ihre persönlichen Einstellungen für dieses Projekt.
4. Gemeinsame Projekt-Einstellungen (.claude/settings.json): Einstellungen, die Ihr Team in die Versionskontrolle eincheckt.
5. Benutzer-Einstellungen (~/.claude/settings.json): Ihre persönlichen Einstellungen für jedes Projekt.

​

Listen werden zusammengeführt statt überschrieben

• fallbackModel ist eine geordnete Kette, wo Position Bedeutung hat, sodass Claude Code den ganzen Wert aus der höchsten Prioritätsdatei nimmt, die ihn definiert.
• modelPicker hält eine geordnete Liste von Zeilen plus ein Replace-Flag, sodass Claude Code Zeilen aus zwei Quellen nie zusammenführt. Es nimmt den ganzen Wert aus dem höchsten von verwalteten Einstellungen, --settings und Benutzereinstellungen, die ihn definieren, und ignoriert den Schlüssel in Projekt- und lokalen Einstellungen. Erfordert Claude Code v2.1.242 oder später.
• availableModels: wenn die verwalteten Einstellungen, die Claude Code anwendet, ihn definieren, wendet Claude Code diese Liste wie sie ist an und ignoriert Einträge, die Sie in Benutzer-, Projekt- oder lokalen Einstellungen hinzufügen, es sei denn, eine App, die Claude Code einbettet, liefert ihre eigene Modell-Liste; siehe Ausnahmen zur Priorität der verwalteten Einstellungen. Über verwaltete Quellen wird die Liste auch nie zusammengeführt; wie Claude Code verwaltete Quellen kombiniert sagt, welche Quelle’s Liste angewendet wird. Über nicht verwaltete Bereiche führt Claude Code die Arrays wie üblich zusammen.
• modelSettings: Claude Code löst es ein Modell auf einmal auf, zusammen mit effortLevel. Der modelSettings Eintrag sagt, welche Datei’s Wert auf ein Modell angewendet wird.

​

Beispiele für Priorität

​

Team-Einstellungen überschreiben persönliche Einstellungen

​

Organisations-Einstellungen überschreiben alles

​

Die Befehlszeile überschreibt Ihre Dateien für eine Sitzung

​

Ein Flag oder eine Umgebungsvariable setzt das gleiche

​

Beheben Sie eine Einstellung, die nicht angewendet wird

​

Ein Wert, den Sie setzen, wird ignoriert

• Eine höhere Ebene setzt ihn. Eine andere Einstellungsdatei, ein --settings Flag oder eine verwaltete Quelle setzt den Schlüssel über Ihrem; der Stapel sagt welche. Ein Flag oder eine Umgebungsvariable kann auch den Schlüssel auf eigene Faust überschreiben, entschieden Schlüssel für Schlüssel; der Eintrag des Schlüssels auf der Einstellungsreferenz sagt, welche Claude Code verwendet, und der env Eintrag behandelt einen verwalteten env Wert versus einen Shell-Export.
• Ein Sicherheitsschlüssel behält seinen strengen Wert. Für ein paar Schlüssel ehrt Claude Code den restriktiven Wert aus jeder Datei, sodass ein Projekt true für disableClaudeAiConnectors bleibt an; siehe Ausnahmen zur Priorität der verwalteten Einstellungen.
• Die Datei kann diesen Wert nicht setzen. permissions.defaultMode Werte auto und bypassPermissions wirken sich nicht von Projekt- oder lokalen Einstellungen aus; setzen Sie sie stattdessen in Benutzer- oder verwaltete Einstellungen, oder übergeben Sie --permission-mode für eine Sitzung. Vor v2.1.257 wirkte sich bypassPermissions von jeder Datei aus.
• Die Datei ist fehlerhaft. Ungültiges JSON oder ein abgelehnter Wert lässt Claude Code die Datei oder den Eintrag überspringen; siehe Beheben Sie eine fehlerhafte Einstellungsdatei.

​

Eine Änderung, die Sie in Claude Code gemacht haben, geht in neuen Sitzungen verloren

​

Eine verwaltete Änderung hat Sie nicht erreicht

​

Ein eingecheckter Schlüssel erreicht Teamkollegen nicht

• Claude Code ignoriert den Schlüssel in einer Repository-Datei. Suchen Sie nach User, local, or managed, User or managed, Managed oder Global config in der Spalte Scope des Einstellungsindex; diese Schlüssel wirken sich nie von der gemeinsamen Datei aus, außer autoContinueAtUsageLimit, das eine Repository-Datei immer noch ausschalten kann: während die Datei den Schlüssel setzt und kein Benutzer, --settings oder verwalteter Wert, liest Claude Code die Einstellung als aus. Global config Schlüssel gelten nur von ~/.claude.json.
• Der Schlüssel wartet auf Vertrauen. permissions.allow Regeln, permissions.additionalDirectories, extraKnownMarketplaces und die meisten env Werte gelten nur, nachdem jeder Teamkollege den Ordner vertraut. Bis dahin sehen sie immer noch Aufforderungen und bekommen keine Plugins von einem Marketplace, den die Datei erklärt. deny und ask Regeln gelten sofort.

​

Berechtigungsregeln kombinieren sich anders als Sie erwartet

• Sie haben “Ja, und frag mich nicht mehr” auf einer Berechtigungsaufforderung gewählt, aber bekommen immer noch eine Aufforderung für das gleiche Tool. Diese Wahl speicherte eine allow Regel in Ihrer lokalen Datei, und eine allow Regel dort übertrifft nicht eine ask Regel aus einer Projekt- oder verwalteten Datei; wie Berechtigungsregeln kombinieren erklärt die Reihenfolge. In der VS Code-Erweiterung lässt die Genehmigungskarte Sie die Zieldatei wählen, einschließlich der gemeinsamen Datei des Projekts, was die Regel für alle ändert; in der CLI schreibt Claude Code nur in Ihre lokale Datei.
• Die Allow-Regeln Ihrer Organisation gelten immer noch neben Ihren. Das ist erwartet: Claude Code führt permissions.allow über Bereiche zusammen, es sei denn, Ihre Organisation setzt allowManagedPermissionRulesOnly.

​

Ausnahmen zur Priorität der verwalteten Einstellungen

​

Einstellungen in Cloud-Sitzungen

• Gemeinsame Projekt-Einstellungen (.claude/settings.json): gelesen, weil die Datei Teil des Klons ist. Committen Sie eine Einstellung dort, um sie in Cloud-Sitzungen anzuwenden.
• Benutzer- und Projekt-lokale Einstellungen (~/.claude/settings.json und .claude/settings.local.json): nicht gelesen. Beide bleiben auf Ihrer Maschine, und die lokale Datei ist nicht im Klon.
• Verwaltete Einstellungen: nur serververwaltete Einstellungen erreichen eine Cloud-Sitzung; eine managed-settings.json Datei oder MDM-Profil auf Ihrem Gerät nicht. Eine selbstgehostete Umgebung liest auch die verwaltete Einstellungsdatei in ihrem Runner-Image. Wie Claude Code verwaltete Quellen kombiniert sagt, wann diese Datei angewendet wird.
• /config: im Web öffnet die Claude Code-Sektion Ihrer claude.ai-Einstellungen statt einen Wert zu ändern. Um eine Einstellung für eine Cloud-Sitzung zu ändern, setzen Sie eine Umgebungsvariable auf der Umgebung oder committen Sie den Schlüssel zu der .claude/settings.json des Repositorys.

​

Was kommt als nächstes

• Alle Einstellungen: jeder Schlüssel, mit wo Sie ihn setzen und einem Beispiel
• Beispiel-Einstellungsdateien: eine persönliche Datei, eine Team-Datei und eine verwaltete Datei einer Organisation
• Berechtigungen konfigurieren: allow, ask und deny Regeln, und was Claude Code ohne Nachfrage ausführt
• Umgebungsvariablen: die Variablen, die Claude Code liest und der env Block
• Debuggen Sie Ihre Konfiguration: wenn eine Einstellung nicht angewendet wird
• Claude-Verzeichnis-Referenz: jede Datei, die Claude Code liest, einschließlich Subagents, MCP-Server, Plugins und CLAUDE.md