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.

​

Vorrang der Einstellungen

1. Verwaltete Einstellungen: Einstellungen, die Ihre Organisation bereitstellt, über eine managed-settings.json-Datei, eine MDM-Richtlinie oder servergesteuerte Einstellungen aus der claude.ai-Konsole. Nichts in Ihren eigenen Einstellungsdateien oder in --settings überschreibt einen verwalteten Schlüssel, und ein Flag wie --model wählt nur aus den Modellen, die Ihre Organisation zulässt. Ein verwaltetes model ist ein Startwert, keine Sperre; die Sperren sind availableModels und deniedModels. Wenn Ihre Organisation mehr als eine verwaltete Quelle bereitstellt, legen die Regeln für den Vorrang innerhalb der verwalteten Ebene fest, was Claude Code aus jeder Quelle liest.
2. Befehlszeile: JSON, das Sie beim Starten von claude mit --settings <file-or-json> übergeben, nur für diese Sitzung; siehe Eine Einstellung für eine Sitzung ändern. Ein Schlüssel, den Sie dort setzen, überschreibt denselben 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 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. Lokale Projekteinstellungen (.claude/settings.local.json): Ihre persönlichen Einstellungen für dieses Projekt.
4. Gemeinsame Projekteinstellungen (.claude/settings.json): Einstellungen, die Ihr Team in die Versionskontrolle eincheckt.
5. Benutzereinstellungen (~/.claude/settings.json): Ihre persönlichen Einstellungen für jedes Projekt.

​

Listen werden zusammengeführt statt überschrieben

• fallbackModel ist eine geordnete Kette, in der die Position Bedeutung trägt, daher übernimmt Claude Code den gesamten Wert aus der Datei mit dem höchsten Vorrang, die ihn definiert.
• modelPicker enthält eine geordnete Liste von Zeilen plus ein Ersetzungs-Flag, daher führt Claude Code nie Zeilen aus zwei Quellen zusammen. Es übernimmt den gesamten Wert aus der höchsten der Quellen verwaltete Einstellungen, --settings und Benutzereinstellungen, die ihn definiert, und ignoriert den Schlüssel in Projekt- und lokalen Einstellungen. Erfordert Claude Code v2.1.242 oder höher.
• availableModels: Wenn die von Claude Code angewendeten verwalteten Einstellungen ihn definieren, wendet Claude Code diese Liste unverändert 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 Modellliste; siehe Ausnahmen vom Vorrang verwalteter Einstellungen. Auch über verwaltete Quellen hinweg wird die Liste nie zusammengeführt; wie Claude Code verwaltete Quellen kombiniert gibt an, welche Liste welcher Quelle gilt. Über nicht verwaltete Geltungsbereiche hinweg führt Claude Code die Arrays wie üblich zusammen.
• modelSettings: Claude Code löst diesen Schlüssel Modell für Modell auf, zusammen mit effortLevel. Der Eintrag zu modelSettings gibt an, welcher Wert aus welcher Datei für ein Modell gilt.

​

Beispiele zum Vorrang

​

Team-Einstellungen überschreiben persönliche Einstellungen

​

Organisationseinstellungen überschreiben alles

​

Die Befehlszeile überschreibt Ihre Dateien für eine Sitzung

​

Ein Flag oder eine Umgebungsvariable setzt dasselbe

​

Fehlerbehebung bei einer Einstellung, die nicht greift

​

Ein von Ihnen gesetzter Wert wird ignoriert

• Eine höhere Ebene setzt ihn. Eine andere Einstellungsdatei, ein --settings-Flag oder eine verwaltete Quelle setzt den Schlüssel oberhalb Ihres Werts; der Stapel zeigt, welche. Ein Flag oder eine Umgebungsvariable kann den Schlüssel auch eigenständig überschreiben, was Schlüssel für Schlüssel entschieden wird; der Eintrag des Schlüssels in der Einstellungsreferenz gibt an, welchen Wert Claude Code verwendet, und der env-Eintrag behandelt einen verwalteten env-Wert im Vergleich zu einem Shell-Export.
• Ein Sicherheitsschlüssel behält seinen strengen Wert. Bei einigen Schlüsseln berücksichtigt Claude Code den restriktiven Wert aus jeder Datei, sodass ein true im Projekt für disableClaudeAiConnectors aktiv bleibt; siehe Ausnahmen vom Vorrang verwalteter Einstellungen.
• Die Datei kann diesen Wert nicht setzen. Die Werte auto und bypassPermissions für permissions.defaultMode werden aus Projekt- oder lokalen Einstellungen nicht wirksam; setzen Sie sie stattdessen in Benutzer- oder verwalteten Einstellungen, oder übergeben Sie --permission-mode für eine Sitzung. Vor v2.1.257 wurde bypassPermissions aus jeder Datei wirksam. Eine Telemetrie-Exportvariable in einem env-Block wird aus Projekt- oder lokalen Einstellungen ebenfalls nicht wirksam, abgesehen von einigen Aus-Werten. 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 führt dazu, dass Claude Code die Datei oder den Eintrag überspringt; siehe Eine fehlerhafte Einstellungsdatei reparieren.

​

Eine in Claude Code vorgenommene Änderung geht in neuen Sitzungen verloren

​

Eine verwaltete Änderung ist nicht bei Ihnen angekommen

​

Ein eingecheckter Schlüssel erreicht Ihre Teammitglieder nicht

• Claude Code ignoriert den Schlüssel in einer Repository-Datei. Suchen Sie in der Spalte „Scope“ des Einstellungsindex nach User, local, or managed, User or managed, User, Managed oder Global config. Diese Schlüssel gelten nie aus der gemeinsamen Datei, abgesehen von einigen, die eine Repository-Datei weiterhin ausschalten kann. Jeder dieser Einträge gibt dies in seiner Scope-Zeile an. Global config-Schlüssel gelten nur aus ~/.claude.json. Innerhalb des Schlüssels env gelten auch die Telemetrie-Exportvariablen nie aus der gemeinsamen Datei, abgesehen von einigen Aus-Werten; 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 erst, nachdem jedes Teammitglied dem Ordner vertraut. Bis dahin sehen sie weiterhin Berechtigungsabfragen und erhalten keine Plugins aus einem Marketplace, den die Datei deklariert. deny- und ask-Regeln gelten sofort.

​

Berechtigungsregeln werden anders kombiniert als erwartet

• Sie haben bei einer Berechtigungsabfrage „Yes, and don’t ask again“ gewählt, werden aber für dasselbe Tool weiterhin gefragt. Diese Auswahl hat eine allow-Regel in Ihrer lokalen Datei gespeichert, und eine allow-Regel dort hat keinen Vorrang vor einer ask-Regel aus einer Projekt- oder verwalteten Datei; wie Berechtigungsregeln kombiniert werden erklärt die Reihenfolge. In der VS Code-Erweiterung können Sie in der Genehmigungskarte die Zieldatei auswä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 weiterhin neben Ihren eigenen. Das ist erwartet: Claude Code führt permissions.allow über Geltungsbereiche hinweg zusammen, es sei denn, Ihre Organisation setzt allowManagedPermissionRulesOnly.

​

Ausnahmen vom Vorrang verwalteter 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: öffnet im Browser unter claude.ai/code Ihre claude.ai-Einstellungsseite Code bzw. Claude Code, 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