Einstellungsdateien und Priorität

​

Einstellungsdateien und wer sie betreffen

​

Vergleichen Sie den Geltungsbereich jeder Einstellungsdatei

• ~/.claude/settings.json: jedes Projekt auf Ihrem Computer, und nichts auf dem Computer 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 beim ersten Mal, wenn es die Datei schreibt, zu Ihren globalen Git-Ausschlüssen hinzu, damit 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 servergesteuerte Einstellungen aus der claude.ai-Konsole: jedes Projekt auf jedem Computer, auf dem Ihre Organisation sie bereitstellt, oder auf dem Sie sich mit Ihrem Organisationskonto anmelden. Nur servergesteuerte Einstellungen erreichen die Cloud-Sitzung

​

Suchen 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 committed haben. Wenn nicht, erstellen Sie sie 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 dauerhafte Genehmigung bei einer Berechtigungsabfrage geben, wie „Ja, und frag mich nicht mehr“ für einen Bash-Befehl. Einige /config-Optionen, einschließlich Tipps anzeigen, werden stattdessen in .claude/settings.local.json gespeichert.

​

Teilen Sie Einstellungen mit Ihrem Team

​

Halten Sie persönliche Einstellungen aus einem Repository heraus

• Claude Code schreibt sie auch. Wenn Claude die Berechtigung zum Ausführen eines Bash-Befehls anfordert 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, damit 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; andernfalls 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.
• Ihre allow-Regeln warten nicht auf Vertrauen, während die Datei nicht verfolgt bleibt. Da 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 committete 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 hä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

• Servergesteuerte Einstellungen, die Claude Code aus der claude.ai-Admin-Konsole oder einem selbstgehosteten Claude-Apps-Gateway abruft
• MDM- oder Betriebssystem-Richtlinien und managed-settings.json-Dateien in einem Systemverzeichnis
• Ein Embedding-Host wie Claude Desktop, über die SDK-Option managedSettings; siehe Steuern 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-5-5"}'

​

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 in Ihren eigenen Einstellungsdateien oder --settings überschreibt einen verwalteten Schlüssel, und ein Flag wie --model wählt nur aus den Modellen, die Ihre Organisation erlaubt. Ein verwaltetes model ist ein Standardwert für den Start, keine Sperre; die Sperren sind availableModels und deniedModels. 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. Befehlszeile: JSON, das Sie mit --settings <file-or-json> übergeben, wenn Sie claude starten, nur für diese Sitzung; siehe Ändern Sie eine Einstellung für eine Sitzung. Ein Schlüssel, den Sie dort setzen, überschreibt den gleichen Schlüssel in Ihren Projekt- und Benutzereinstellungsdateien, und ein Schlüssel, den Sie weglassen, behält seinen Wert aus diesen Dateien. Andere Flags wie --model legen eine einzelne Sache für die Sitzung fest und sind nicht Teil dieses Stapels; der Eintrag eines Schlüssels in der Einstellungsreferenz gibt an, welche Flags ihn überschreiben.
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. Eine Telemetrie-Exportvariable in einem env Block wirkt sich auch nicht von Projekt- oder lokalen Einstellungen aus, außer ein paar Off-Werte. Variablen, die Claude Code in env ignoriert listet die Variablen und diese Werte auf.
• 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, User, Managed oder Global config in der Spalte Scope des Einstellungsindex. Diese Schlüssel wirken sich nie von der gemeinsamen Datei aus, außer ein paar, die eine Repository-Datei immer noch ausschalten kann. Jeder dieser Einträge sagt so auf seiner Scope-Zeile. Global config Schlüssel gelten nur von ~/.claude.json. Innerhalb des env Schlüssels gelten die Telemetrie-Exportvariablen auch nie von der gemeinsamen Datei, außer ein paar Off-Werte; siehe Variablen, die Claude Code in env ignoriert.
• 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 Berechtigungsabfragen 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” in einer Berechtigungsabfrage gewählt, werden aber für das gleiche Tool immer noch nachgefragt. 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

• Cloud-Threads in einem Projekt: In einem Cloud-Thread in einem Projekt gelten keine Berechtigungsregeln, Hooks oder env aus der .claude/settings.json eines Repositorys, unabhängig davon, wie viele Repositorys das Projekt hat. Was Threads aus Ihren Repositorys übernehmen listet auf, was Sie stattdessen verwenden können.
• Gemeinsame Projekt-Einstellungen (.claude/settings.json): werden in einer Sitzung mit einem Repository außerhalb der Threads eines Projekts gelesen, da die Datei Teil des Klons ist und die Sitzung darin startet. Committen Sie eine Einstellung dort, um sie in diesen Sitzungen anzuwenden.
• Gemeinsame Projekt-Einstellungen mit mehreren Repositorys: In einer von Anthropic gehosteten Umgebung startet eine Sitzung mit mehreren Repositorys über den Klonen und liest aus jeder .claude/settings.json des Repositorys nur die Schlüssel enabledPlugins und extraKnownMarketplaces, nicht Berechtigungsregeln, Hooks, env oder andere Schlüssel. Die Marketplaces und Plugins, die diese beiden Schlüssel deklarieren, werden immer noch nicht in einer Cloud-Sitzung geladen. Für eine selbstgehostete Umgebung siehe welche Repository-Einstellungen gelten.
• 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: eine managed-settings.json Datei oder MDM-Profil auf Ihrem Gerät erreicht eine Cloud-Sitzung nicht. Die serververwalteten Einstellungen Ihrer Organisation erreichen sie; Oberflächenabdeckung listet auf, welche Cloud-Sitzungen sie erhalten. 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 Browser unter claude.ai/code ö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. In einer Sitzung mit einem Repository außerhalb der Threads eines Projekts können Sie stattdessen den Schlüssel in die .claude/settings.json dieses Repositorys committen.

​

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