Skip to main content
Claude Code bietet eine Vielzahl von Einstellungen, um sein Verhalten an Ihre Anforderungen anzupassen. Sie können Claude Code konfigurieren, indem Sie den Befehl /config ausführen, wodurch eine Einstellungsoberfläche mit Registerkarten geöffnet wird, auf der Sie Statusinformationen anzeigen und Konfigurationsoptionen ändern können. Ab v2.1.181 können Sie eine einzelne Option ändern, ohne die Oberfläche zu öffnen, indem Sie key=value an /config übergeben, zum Beispiel /config verbose=true.

Konfigurationsbereiche

Claude Code verwendet ein Bereichssystem, um zu bestimmen, wo Konfigurationen gelten und wer sie teilt. Das Verständnis von Bereichen hilft Ihnen zu entscheiden, wie Sie Claude Code für persönliche Nutzung, Teamzusammenarbeit oder Unternehmensbereitstellung konfigurieren.

Verfügbare Bereiche

Wann sollte jeder Bereich verwendet werden

Der Verwaltungsbereich ist für:
  • Sicherheitsrichtlinien, die organisationsweit durchgesetzt werden müssen
  • Compliance-Anforderungen, die nicht überschrieben werden können
  • Standardisierte Konfigurationen, die von IT/DevOps bereitgestellt werden
Der Benutzerbereich ist am besten für:
  • Persönliche Voreinstellungen, die Sie überall haben möchten (Designs, Editor-Einstellungen)
  • Tools und Plugins, die Sie in allen Projekten verwenden
  • API-Schlüssel und Authentifizierung (sicher gespeichert)
Der Projektbereich ist am besten für:
  • Teamübergreifend gemeinsame Einstellungen (Berechtigungen, Hooks, MCP-Server)
  • Plugins, die das gesamte Team haben sollte
  • Standardisierung von Tools über Mitarbeiter hinweg
Der lokale Bereich ist am besten für:
  • Persönliche Überschreibungen für ein bestimmtes Projekt
  • Testen von Konfigurationen vor dem Teilen mit dem Team
  • Maschinenspezifische Einstellungen, die für andere nicht funktionieren

Wie Bereiche interagieren

Wenn die gleiche Einstellung in mehreren Bereichen konfiguriert ist, wendet Claude Code sie in Prioritätsreihenfolge an:
  1. Verwaltet (höchste): kann von nichts überschrieben werden
  2. Befehlszeilenargumente: temporäre Sitzungsüberschreibungen
  3. Lokal: überschreibt Projekt- und Benutzereinstellungen
  4. Projekt: überschreibt Benutzereinstellungen
  5. Benutzer (niedrigste): gilt, wenn nichts anderes die Einstellung angibt
Wenn beispielsweise Ihre Benutzereinstellungen spinnerTipsEnabled auf true setzen und Projekteinstellungen es auf false setzen, gilt der Projektwert. Berechtigungsregeln verhalten sich anders, da sie über Bereiche hinweg zusammengeführt werden, anstatt sich zu überschreiben. Siehe Einstellungspriorität.

Was verwendet Bereiche

Bereiche gelten für viele Claude Code-Funktionen: Unter Windows werden Pfade, die als ~/.claude angezeigt werden, zu %USERPROFILE%\.claude aufgelöst.

Einstellungsdateien

Die Datei settings.json ist der offizielle Mechanismus zur Konfiguration von Claude Code durch hierarchische Einstellungen:
  • Benutzereinstellungen werden in ~/.claude/settings.json definiert und gelten für alle Projekte.
  • Projekteinstellungen werden in Ihrem Projektverzeichnis gespeichert:
    • .claude/settings.json für Einstellungen, die in die Versionskontrolle eingecheckt und mit Ihrem Team geteilt werden
    • .claude/settings.local.json für Einstellungen, die nicht eingecheckt werden, nützlich für persönliche Voreinstellungen und Experimente. Wenn Claude Code .claude/settings.local.json erstellt, konfiguriert es Git so, dass die Datei ignoriert wird. Wenn Sie die Datei selbst erstellen, fügen Sie sie manuell zu Ihrer gitignore hinzu. Da diese Datei Ihnen gehört und nicht dem Repository, werden ihre Berechtigungsregeln allow ohne den Workspace-Trust-Schritt wirksam, den allow-Regeln in .claude/settings.json erfordern. Wenn das Repository die Datei bereitstellt, z. B. durch Committen, gilt Workspace-Trust weiterhin.
  • Verwaltete Einstellungen: Für Organisationen, die zentrale Kontrolle benötigen, unterstützt Claude Code mehrere Bereitstellungsmechanismen für verwaltete Einstellungen. Alle verwenden das gleiche JSON-Format und können nicht durch Benutzer- oder Projekteinstellungen überschrieben werden:
    • Serververwaltete Einstellungen: von Anthropics Servern über die Claude.ai-Administratorkonsole bereitgestellt oder von einem selbstgehosteten Claude-Apps-Gateway. Siehe Serververwaltete Einstellungen.
    • MDM/OS-Richtlinien: über native Geräteverwaltung auf macOS und Windows bereitgestellt:
      • macOS: com.anthropic.claudecode verwaltete Präferenzdomäne. Die Schlüssel der obersten Ebene der plist spiegeln managed-settings.json wider, mit verschachtelten Einstellungen als Wörterbücher und Arrays als plist-Arrays. Bereitstellung über Konfigurationsprofile in Jamf, Iru (Kandji) oder ähnlichen MDM-Tools.
      • Windows: HKLM\SOFTWARE\Policies\ClaudeCode Registrierungsschlüssel mit einem Settings-Wert (REG_SZ oder REG_EXPAND_SZ) mit JSON (bereitgestellt über Gruppenrichtlinie oder Intune)
      • Windows (Benutzerebene): HKCU\SOFTWARE\Policies\ClaudeCode (niedrigste Richtlinienpriorität, wird nur verwendet, wenn keine Admin-Quelle vorhanden ist)
    • Dateibasiert: managed-settings.json und managed-mcp.json in Systemverzeichnissen bereitgestellt:
      • macOS: /Library/Application Support/ClaudeCode/
      • Linux und WSL: /etc/claude-code/
      • Windows: C:\Program Files\ClaudeCode\
      Der veraltete Windows-Pfad C:\ProgramData\ClaudeCode\managed-settings.json wird ab v2.1.75 nicht mehr unterstützt. Administratoren, die Einstellungen an diesem Speicherort bereitgestellt haben, müssen Dateien zu C:\Program Files\ClaudeCode\managed-settings.json migrieren.
      Dateibasierte verwaltete Einstellungen unterstützen auch ein Drop-in-Verzeichnis unter managed-settings.d/ im gleichen Systemverzeichnis neben managed-settings.json. Dies ermöglicht es separaten Teams, unabhängige Richtlinienfragmente bereitzustellen, ohne Änderungen an einer einzelnen Datei zu koordinieren. Nach der systemd-Konvention wird managed-settings.json zuerst als Basis zusammengeführt, dann werden alle *.json-Dateien im Drop-in-Verzeichnis alphabetisch sortiert und oben zusammengeführt. Spätere Dateien überschreiben frühere für Skalarwerte; Arrays werden verkettet und dedupliziert; Objekte werden tiefgreifend zusammengeführt. Versteckte Dateien, die mit . beginnen, werden ignoriert. Verwenden Sie numerische Präfixe, um die Zusammenführungsreihenfolge zu steuern, z. B. 10-telemetry.json und 20-security.json.
    Siehe Verwaltete Einstellungen und Verwaltete MCP-Konfiguration für Details. Dieses Repository enthält Starter-Bereitstellungsvorlagen für Jamf, Iru (Kandji), Intune und Gruppenrichtlinie. Verwenden Sie diese als Ausgangspunkte und passen Sie sie an Ihre Anforderungen an.
    Verwaltete Bereitstellungen können auch Plugin-Marketplace-Ergänzungen mit strictKnownMarketplaces einschränken. Weitere Informationen finden Sie unter Verwaltete Marketplace-Einschränkungen.
  • Andere Konfiguration wird in ~/.claude.json gespeichert. Diese Datei enthält Ihre OAuth-Sitzung, MCP-Server-Konfigurationen für Benutzer- und lokale Bereiche, projektbezogenen Status (zulässige Tools, Vertrauenseinstellungen) und verschiedene Caches. Projektbezogene MCP-Server werden separat in .mcp.json gespeichert.
Claude Code erstellt automatisch zeitgestempelte Sicherungen von Konfigurationsdateien und behält die fünf neuesten Sicherungen bei, um Datenverlust zu verhindern.
Beispiel settings.json
Die Zeile $schema im obigen Beispiel verweist auf das offizielle JSON-Schema für Claude Code-Einstellungen. Das Hinzufügen zu Ihrer settings.json ermöglicht Autovervollständigung und Inline-Validierung in VS Code, Cursor und jedem anderen Editor, der JSON-Schema-Validierung unterstützt. Das veröffentlichte Schema wird regelmäßig aktualisiert und enthält möglicherweise keine Einstellungen, die in den neuesten CLI-Versionen hinzugefügt wurden. Eine Validierungswarnung zu einem kürzlich dokumentierten Feld bedeutet daher nicht unbedingt, dass Ihre Konfiguration ungültig ist.

Wenn Änderungen wirksam werden

Claude Code überwacht Ihre Einstellungsdateien und lädt sie neu, wenn sie sich ändern, sodass Änderungen an den meisten Schlüsseln ohne Neustart auf die laufende Sitzung angewendet werden. Dies umfasst permissions, hooks und Anmeldedaten-Helper wie apiKeyHelper. Das Neuladen umfasst Benutzer-, Projekt-, lokale und verwaltete Einstellungen, und der ConfigChange Hook wird für jede erkannte Änderung ausgelöst. Einige wenige Schlüssel werden einmal beim Sitzungsstart gelesen und gelten stattdessen beim nächsten Neustart:
  • model: Verwenden Sie /model, um während der Sitzung zu wechseln
  • outputStyle: Teil der Systemaufforderung, die beim /clear oder Neustart neu erstellt wird

Ungültige Einträge in verwalteten Einstellungen

Verwaltete Einstellungen werden tolerant analysiert. Wenn eine verwaltete Konfiguration einen Eintrag enthält, der die Schema-Validierung nicht besteht, entfernt Claude Code diesen Eintrag, zeichnet eine Warnung auf und erzwingt jede verbleibende gültige Richtlinie. Ein einzelner Tippfehler kann nicht die restliche Organisationsrichtlinie deaktivieren. Führen Sie /doctor aus, um entfernte Einträge mit ihrer Quelldatei und ihrem Feld aufzulisten. Dieses Verhalten ist konsistent über alle drei Bereitstellungsmechanismen: Serververwaltete Einstellungen, plist- und Registry-Richtlinien, die über MDM bereitgestellt werden, und managed-settings.json-Dateien. Erfordert Claude Code v2.1.169 oder später. Sicherheitsdurchsetzungsfelder werden pro Feld behandelt, anstatt vollständig entfernt zu werden, wenn sie vorhanden, aber ungültig sind: requiredMinimumVersion und requiredMaximumVersion schlagen offen fehl: Ein ungültiger Wert wird entfernt, anstatt erzwungen zu werden, sodass ein schlechter Richtlinien-Push Claude Code nicht am Starten hindern kann. Validierungsfehler werden an drei Stellen angezeigt:
  • Interaktive Sitzungen zeigen beim Start einen Dialog mit den ungültigen Einträgen an.
  • Headless-Läufe mit -p drucken eine Zusammenfassung zu stderr.
  • claude doctor listet jeden ungültigen Eintrag mit seiner Quelle und seinem Feld auf.
Validieren Sie Richtlinienänderungen, indem Sie claude doctor auf einem Test-Computer ausführen, bevor Sie sie unternehmensweite bereitstellen. Diese Toleranz gilt nur für verwaltete Einstellungen. Benutzer-, Projekt- und lokale Einstellungsdateien bleiben streng: Eine Datei, die die Validierung nicht besteht, wird als Ganzes abgelehnt und gemeldet.

Verfügbare Einstellungen

settings.json unterstützt eine Reihe von Optionen:

Globale Konfigurationseinstellungen

Diese Einstellungen werden in ~/.claude.json statt in settings.json gespeichert. Das Hinzufügen zu settings.json löst einen Schema-Validierungsfehler aus.
Versionen vor v2.1.119 speichern auch eine Reihe von /config Voreinstellungsschlüsseln hier statt in settings.json, einschließlich theme, verbose, editorMode, autoCompactEnabled und preferredNotifChannel.

Worktree-Einstellungen

Konfigurieren Sie, wie --worktree Git-Worktrees erstellt und verwaltet. Um gitignorierte Dateien wie .env in neue Worktrees zu kopieren, verwenden Sie stattdessen eine .worktreeinclude-Datei in Ihrem Projektstamm.

Berechtigungseinstellungen

Berechtigungsregelsyntax

Berechtigungsregeln folgen dem Format Tool oder Tool(specifier). Regeln werden in der Reihenfolge ausgewertet: zuerst Deny-Regeln, dann Ask, dann Allow. Die erste übereinstimmende Regel bestimmt das Ergebnis, unabhängig von der Regelspezifität. Siehe Berechtigungsregelbewertungsreihenfolge für Details. Schnelle Beispiele: Für die vollständige Referenz der Regelsyntax, einschließlich Platzhalterverhalten, werkzeugspezifischer Muster für Read, Edit, WebFetch, MCP und Agent-Regeln sowie Sicherheitsbeschränkungen von Bash-Mustern, siehe Berechtigungsregelsyntax.

Sandbox-Einstellungen

Konfigurieren Sie erweitertes Sandbox-Verhalten. Sandboxing isoliert Bash-Befehle von Ihrem Dateisystem und Netzwerk. Siehe Sandboxing für Details.

Sandbox-Pfadpräfixe

Pfade in filesystem.allowWrite, filesystem.denyWrite, filesystem.denyRead, filesystem.allowRead und credentials.files unterstützen diese Präfixe: Das ältere //path-Präfix für absolute Pfade funktioniert weiterhin. Wenn Sie zuvor ein einzelnes Schrägstrich /path erwartet haben, um projektrelativ aufgelöst zu werden, wechseln Sie zu ./path. Diese Syntax unterscheidet sich von Read- und Edit-Berechtigungsregeln, die //path für absolut und /path für projektrelativ verwenden. Sandbox-Dateisystempfade verwenden Standard-Konventionen: /tmp/build ist ein absoluter Pfad. Konfigurationsbeispiel:
Dateisystem- und Netzwerkbeschränkungen können auf zwei Arten konfiguriert werden, die zusammengeführt werden:
  • sandbox.filesystem-Einstellungen (oben gezeigt): Steuern Sie Pfade an der OS-Level-Sandbox-Grenze. Diese Einschränkungen gelten für alle Subprozess-Befehle (z. B. kubectl, terraform, npm), nicht nur für Claudes Datei-Tools.
  • Berechtigungsregeln: Verwenden Sie Edit Allow/Deny-Regeln, um den Zugriff auf Claudes Datei-Tool zu steuern, Read Deny-Regeln, um Lesevorgänge zu blockieren, und WebFetch Allow/Deny-Regeln, um Netzwerk-Domänen zu steuern. Pfade aus diesen Regeln werden auch in die Sandbox-Konfiguration zusammengeführt.

Zuschreibungseinstellungen

Claude Code fügt Git-Commits und Pull Requests Zuschreibungen hinzu. Diese werden separat konfiguriert:
  • Commits verwenden Git-Trailer (wie Co-Authored-By) standardmäßig, die angepasst oder deaktiviert werden können
  • Pull-Request-Beschreibungen sind Klartext
Standard-Commit-Zuschreibung:
Der Modellname im Trailer spiegelt das aktive Modell für die Sitzung wider. Standard-Pull-Request-Zuschreibung:
Beispiel:
Die Einstellung attribution hat Vorrang vor der veralteten Einstellung includeCoAuthoredBy. Um alle Zuschreibungen auszublenden, setzen Sie commit und pr auf leere Zeichenketten und sessionUrl auf false.

Dateivorschlag-Einstellungen

Konfigurieren Sie einen benutzerdefinierten Befehl für @ Dateipath-Autovervollständigung. Der integrierte Dateivorschlag verwendet schnelle Dateisystem-Durchquerung, aber große Monorepos können von projektspezifischer Indizierung wie einem vorgefertigten Dateiindex oder benutzerdefinierten Tools profitieren.
Der Befehl wird mit den gleichen Umgebungsvariablen wie Hooks ausgeführt, einschließlich CLAUDE_PROJECT_DIR. Er empfängt JSON über stdin mit einem query-Feld:
Geben Sie zeilengetrennte Dateipfade zu stdout aus (derzeit auf 15 begrenzt):
Beispiel:
Die Einstellung footerLinksRegexes rendert zusätzliche anklickbare Badges in der Fußzeile unter dem Eingabefeld. Verwenden Sie sie, um IDs, die von Projekt-CLIs gedruckt werden, wie Review-Tools und Issue-Tracker, in Sitzungslinks umzuwandeln. Jeder Eintrag’s pattern Regex wird gegen die Ausgabe der Runde abgeglichen: Tool-Ergebnisse, einschließlich Dateiinhalte und abgerufene Seiten, und Claudes eigene Antworten. {name} Platzhalter in url und label werden aus benannten Erfassungsgruppen im Pattern gefüllt. Das folgende Beispiel rendert ein Badge, wenn eine Issue-Taste wie PROJ-1234 in der Ausgabe der Runde erscheint. Die (?<key>...) benannte Gruppe erfasst den Schlüssel, und {key} ersetzt ihn in der URL und dem Label:
~/.claude/settings.json
Mit dieser Konfiguration wird, wenn PROJ-1234 in einem Tool-Ergebnis oder in Claudes Antwort erscheint, ein PROJ-1234 Chip in der Fußzeile angezeigt, der auf https://issues.example.com/browse/PROJ-1234 verlinkt. Die folgenden Einschränkungen gelten für jeden Eintrag: Wenn eine Runde abgeschlossen ist, gleicht Claude Code jeden Eintrag’s pattern Regex gegen die Ausgabe der Runde im Haupt-Thread ab, daher blockiert ein langsamer Regex die UI, bis er fertig ist. Verschachtelte Quantoren wie (a+)+$ können gegen bestimmte Eingaben exponentiell lange dauern und die Sitzung einfrieren, daher halten Sie jeden pattern linear und vermeiden Sie Verschachtelung von + oder *. Footer-Badges werden neben einer benutzerdefinierten Statuszeile gerendert, wenn eine konfiguriert ist; keiner ersetzt den anderen. Verwenden Sie eine Statuszeile für eine skriptgesteuerte Zeile, die ihren eigenen Inhalt aus Sitzungsdaten berechnet, und Footer-Badges, um IDs aus dem Gespräch in Links umzuwandeln, ohne ein Skript.

Hook-Konfiguration

Diese Einstellungen steuern, welche Hooks ausgeführt werden dürfen und worauf HTTP-Hooks zugreifen können. Die Einstellung allowManagedHooksOnly kann nur in verwalteten Einstellungen konfiguriert werden. Die URL- und Umgebungsvariablen-Allowlists können auf jeder Einstellungsebene gesetzt werden und werden über Quellen zusammengeführt. Verhalten, wenn allowManagedHooksOnly true ist:
  • Verwaltete Hooks und SDK-Hooks werden geladen
  • Hooks von Plugins, die in verwalteten Einstellungen enabledPlugins erzwungen aktiviert sind, werden geladen. Dies ermöglicht es Administratoren, überprüfte Hooks über einen Organisations-Marketplace zu verteilen, während alles andere blockiert wird. Vertrauen wird durch vollständige plugin@marketplace ID gewährt, daher bleibt ein Plugin mit dem gleichen Namen aus einem anderen Marketplace blockiert
  • Benutzer-Hooks, Projekt-Hooks und alle anderen Plugin-Hooks werden blockiert
HTTP-Hook-URLs einschränken: Begrenzen Sie, auf welche URLs HTTP-Hooks abzielen können. Unterstützt * als Platzhalter zum Abgleichen. Wenn das Array definiert ist, werden HTTP-Hooks, die auf nicht übereinstimmende URLs abzielen, stillschweigend blockiert. Der Hostname-Abgleich ist case-insensitiv und ignoriert einen nachfolgenden FQDN-Punkt, was DNS-Semantik entspricht.
HTTP-Hook-Umgebungsvariablen einschränken: Begrenzen Sie, welche Umgebungsvariablennamen HTTP-Hooks in Header-Werte interpolieren können. Die effektive allowedEnvVars jedes Hooks ist der Schnittpunkt seiner eigenen Liste und dieser Einstellung.

Berechnen Sie verwaltete Einstellungen mit einem Policy Helper

Die Einstellung policyHelper verweist auf eine ausführbare Datei, die verwaltete Einstellungen beim Start dynamisch berechnet, sodass Administratoren Richtlinien von Geräteposition, Identität oder einem Remote-Service ableiten können, anstatt eine statische Datei zu verwenden. Konfigurieren Sie sie von MDM oder einer System-managed-settings.json-Datei. Claude Code ignoriert policyHelper, wenn es in einem anderen Bereich erscheint, einschließlich Benutzereinstellungen, Projekteinstellungen, der HKCU-Registry-Struktur und Serververwalteten Einstellungen. Die Einstellung akzeptiert diese Schlüssel: Der Helper schreibt eine JSON-Umschlag zu stdout. Setzen Sie die Einstellungen unter einen managedSettings-Schlüssel, anstatt auf der obersten Ebene, da ein bloßes Einstellungsobjekt mit managedSettings undefined analysiert wird und nichts anwendet:
Wenn der Helper managedSettings ausgibt, ersetzt dieses Objekt die dateibasierten verwalteten Einstellungen für die Ausführung. Wenn der Helper beim Start mit einem Fehler beendet wird, druckt Claude Code den Fehler und weigert sich zu starten, daher sollte ein Helper, der Ausfallsicherheit benötigt, aus seinem eigenen Cache bedienen und mit 0 beenden.

Einstellungspriorität

Einstellungen werden in Prioritätsreihenfolge angewendet. Von höchster zu niedrigster:
  1. Verwaltete Einstellungen (Serververwaltete, MDM/OS-Richtlinien oder Verwaltete Einstellungen)
    • Richtlinien, die von IT über Server-Bereitstellung, MDM-Konfigurationsprofile, Registry-Richtlinien oder verwaltete Einstellungsdateien bereitgestellt werden
    • Können nicht durch andere Ebenen überschrieben werden, einschließlich Befehlszeilenargumenten
    • Innerhalb der verwalteten Ebene ist die Priorität: policyHelper Ausgabe, die bei Konfiguration die einzige verwaltete Quelle ist > Remote (claude.ai Serververwaltete oder Claude-Apps-Gateway-bereitgestellt) > MDM/OS-Richtlinien > dateibasierte (managed-settings.d/*.json + managed-settings.json) > HKCU-Registry (nur Windows). Nur eine verwaltete Quelle wird verwendet; Quellen werden nicht zusammengeführt, mit einer Ausnahme: die Sandbox-Sperr-Schlüssel sandbox.network.allowManagedDomainsOnly und sandbox.filesystem.allowManagedReadPathsOnly, mit ihren zugehörigen Allowlists, allowAllClaudeAiMcps und die Sandbox-Binär-Pfade sandbox.bwrapPath und sandbox.socatPath werden berücksichtigt, wenn eine Admin-kontrollierte verwaltete Quelle sie setzt; die benutzerbare HKCU-Ebene ist ausgeschlossen. Innerhalb der dateibasierten Ebene werden Drop-in-Dateien und die Basisdatei zusammengeführt.
    • Eingebettete Hosts wie Claude Desktop können Richtlinien über die SDK managedSettings Option bereitstellen. Standardmäßig wird dies ignoriert, wenn eine Admin-bereitgestellte verwaltete Quelle vorhanden ist: Serververwaltete Einstellungen, eine MDM- oder OS-Richtlinie oder eine verwaltete Einstellungsdatei. Der benutzerbare HKCU-Registry-Fallback zählt nicht als Admin-bereitgestellte Quelle. Administratoren können sich anmelden, indem sie parentSettingsBehavior auf "merge" setzen. Die Werte des Embedders werden gefiltert, sodass sie verwaltete Richtlinien verschärfen, aber nicht lockern können.
  2. Befehlszeilenargumente
    • Temporäre Überschreibungen für eine bestimmte Sitzung. JSON, das über --settings <file-or-json> übergeben wird, wird mit dateibasierten Einstellungen unter Verwendung der gleichen Regeln wie die anderen Ebenen zusammengeführt: Ein hier gesetzter Schlüssel überschreibt den gleichen Schlüssel in lokalen, Projekt- oder Benutzereinstellungen, und das Weglassen eines Schlüssels lässt den Wert der niedrigeren Ebene bestehen
  3. Lokale Projekteinstellungen (.claude/settings.local.json)
    • Persönliche projektspezifische Einstellungen
  4. Gemeinsame Projekteinstellungen (.claude/settings.json)
    • Teamübergreifend gemeinsame Projekteinstellungen in der Versionskontrolle
  5. Benutzereinstellungen (~/.claude/settings.json)
    • Persönliche globale Einstellungen
Diese Hierarchie stellt sicher, dass Organisationsrichtlinien immer durchgesetzt werden, während Teams und Einzelpersonen ihre Erfahrung weiterhin anpassen können. Die gleiche Priorität gilt, ob Sie Claude Code von der CLI, der VS Code-Erweiterung oder einer JetBrains IDE ausführen. Wenn beispielsweise Ihre Benutzereinstellungen permissions.defaultMode auf acceptEdits setzen und die gemeinsamen Einstellungen eines Projekts es auf default setzen, gilt der Projektwert. Das folgende Beispiel zeigt, wie Array-wertige Einstellungen wie Berechtigungsregeln stattdessen kombiniert werden.
Array-Einstellungen werden über Bereiche zusammengeführt. Wenn die gleiche Array-wertige Einstellung (wie sandbox.filesystem.allowWrite oder permissions.allow) in mehreren Bereichen erscheint, werden die Arrays verkettet und dedupliziert, nicht ersetzt. Dies bedeutet, dass Bereiche mit niedrigerer Priorität Einträge hinzufügen können, ohne diejenigen mit höherer Priorität zu überschreiben, und umgekehrt. Wenn beispielsweise verwaltete Einstellungen allowWrite auf ["/opt/company-tools"] setzen und ein Benutzer ["~/.kube"] hinzufügt, sind beide Pfade in der endgültigen Konfiguration enthalten.Zwei Array-Einstellungen werden nicht auf diese Weise zusammengeführt:
  • fallbackModel ist eine geordnete Kette, bei der Position Bedeutung hat: Die Datei mit der höchsten Priorität, die sie definiert, liefert den gesamten Wert.
  • availableModels: Wenn die höchste Priorität verwaltete Quelle sie definiert, wird diese Liste wie sie ist angewendet und Benutzer-, Projekt- und lokale Einträge können sie nicht erweitern. Über nicht verwaltete Bereiche werden die Arrays wie üblich zusammengeführt. Siehe Zusammenführungsverhalten.

Aktive Einstellungen überprüfen

Führen Sie /status aus und überprüfen Sie die Zeile Setting sources auf der Registerkarte Status. Sie listet jede Einstellungsebene auf, die Claude Code für diese Sitzung geladen hat:
  • Wenn eine Ebene wie User settings oder Project local settings angezeigt wird, wird diese Datei gelesen.
  • Wenn eine Ebene fehlt, wurde diese Datei nicht gefunden oder enthält keine Schlüssel.
Wenn verwaltete Einstellungen wirksam sind, zeigt der Eintrag den Bereitstellungskanal in Klammern an, z. B. Enterprise managed settings (remote), (plist), (HKLM), (HKCU) oder (file). Der remote Kanal deckt sowohl claude.ai Serververwaltete Einstellungen als auch Claude-Apps-Gateway-bereitgestellte Richtlinien ab. Die Zeile bestätigt, welche Dateien gelesen werden, nicht welche Ebene jeden einzelnen Schlüssel bereitgestellt hat. Die Registerkarte Config im gleichen Dialog bearbeitet integrierte Umschalter wie Thema und ausführliche Ausgabe, nicht Ihre settings.json-Inhalte. Wenn eine Einstellungsdatei Fehler enthält, wie ungültiges JSON oder einen Wert, der die Validierung nicht besteht, zeigt Claude Code beim Start einen Setup-Probleme-Hinweis an und /status listet die betroffenen Dateien auf. Führen Sie /doctor aus, um die Details für jeden Fehler zu sehen.

Wichtige Punkte zum Konfigurationssystem

  • Speicherdateien (CLAUDE.md): Enthalten Anweisungen und Kontext, die Claude beim Start lädt
  • Einstellungsdateien (JSON): Konfigurieren Sie Berechtigungen, Umgebungsvariablen und Werkzeugverhalten
  • Skills: Benutzerdefinierte Aufforderungen, die mit /skill-name aufgerufen oder von Claude automatisch geladen werden können
  • MCP-Server: Erweitern Sie Claude Code mit zusätzlichen Tools und Integrationen
  • Priorität: Höherrangige Konfigurationen (Verwaltet) überschreiben niedrigere (Benutzer/Projekt)
  • Vererbung: Einstellungen werden zusammengeführt; Skalarwerte aus höherer Priorität überschreiben, und Arrays werden verkettet, mit zwei Ausnahmen, die in der Array-Merge-Notiz beschrieben sind

Systemaufforderung

Claudes interne Systemaufforderung wird nicht veröffentlicht. Um benutzerdefinierte Anweisungen hinzuzufügen, verwenden Sie CLAUDE.md-Dateien oder das Flag --append-system-prompt.

Ausschließen sensibler Dateien

Um zu verhindern, dass Claude Code auf Dateien mit sensiblen Informationen wie API-Schlüsseln, Geheimnissen und Umgebungsdateien zugreift, verwenden Sie die Einstellung permissions.deny in Ihrer .claude/settings.json-Datei:
Dies ersetzt die veraltete Konfiguration ignorePatterns. Dateien, die diesen Mustern entsprechen, werden von der Dateiermittlung und Suchergebnissen ausgeschlossen, und Lesevorgänge auf diesen Dateien werden verweigert.

Subagent-Konfiguration

Claude Code unterstützt benutzerdefinierte KI-Subagents, die auf Benutzer- und Projektebene konfiguriert werden können. Diese Subagents werden als Markdown-Dateien mit YAML-Frontmatter gespeichert:
  • Benutzer-Subagents: ~/.claude/agents/, verfügbar über alle Ihre Projekte
  • Projekt-Subagents: .claude/agents/, spezifisch für Ihr Projekt und teilbar mit Ihrem Team
Subagent-Dateien definieren spezialisierte KI-Assistenten mit benutzerdefinierten Aufforderungen und Werkzeugberechtigungen. Erfahren Sie mehr über das Erstellen und Verwenden von Subagents in der Subagents-Dokumentation.

Plugin-Konfiguration

Claude Code unterstützt ein Plugin-System, mit dem Sie die Funktionalität mit Skills, Agents, Hooks und MCP-Servern erweitern können. Plugins werden über Marketplaces verteilt und können auf Benutzer- und Repository-Ebene konfiguriert werden.

Plugin-Einstellungen

Plugin-bezogene Einstellungen in settings.json:

enabledPlugins

Steuert, welche Plugins aktiviert sind. Format: "plugin-name@marketplace-name": true/false. Ein Plugin ohne Eintrag in einem beliebigen Bereich fällt auf seinen defaultEnabled Wert zurück. Bereiche:
  • Benutzereinstellungen (~/.claude/settings.json): Persönliche Plugin-Voreinstellungen
  • Projekteinstellungen (.claude/settings.json): Projektspezifische Plugins, die mit dem Team geteilt werden
  • Lokale Einstellungen (.claude/settings.local.json): Pro-Maschinen-Überschreibungen, gitignored wenn Claude Code es erstellt
  • Verwaltete Einstellungen (managed-settings.json): Organisationsweite Richtlinien-Überschreibungen, die die Installation auf allen Ebenen blockieren und das Plugin aus dem Marketplace ausblenden
Projekteinstellungen haben Vorrang vor Benutzereinstellungen, daher führt das Setzen eines Plugins auf false in ~/.claude/settings.json nicht dazu, dass ein Plugin deaktiviert wird, das die .claude/settings.json des Projekts aktiviert. Um sich von einem projektaktivierten Plugin auf Ihrem Computer abzumelden, setzen Sie es stattdessen auf false in .claude/settings.local.json.Plugins, die durch verwaltete Einstellungen erzwungen aktiviert sind, können auf diese Weise nicht deaktiviert werden, da verwaltete Einstellungen lokale Einstellungen überschreiben.Das Aktivieren eines Plugins aus einer externen Quelle wie einem GitHub-Repository oder npm-Paket in der .claude/settings.json eines Projekts installiert es nicht für andere Personen. Ab Claude Code v2.1.195 fragt jeder Pfad, der Plugins lädt, jeden Benutzer auf, das Plugin zu installieren und zu vertrauen, bevor es ausgeführt wird.
Beispiel:

pluginConfigs

Speichert die nicht-sensiblen Optionswerte, die die userConfig Eingabeaufforderung eines Plugins sammelt, indiziert nach Plugin-ID. Claude Code schreibt diesen Schlüssel in Benutzereinstellungen, wenn Sie das Konfigurationsdialogfeld des Plugins ausfüllen, sodass Sie ihn nicht manuell bearbeiten müssen. Sensible Optionen werden stattdessen im macOS Keychain gespeichert oder in ~/.claude/.credentials.json auf Plattformen ohne unterstützten Keychain. Dieses Beispiel speichert eine Option für ein Plugin, das vom acme-tools Marketplace installiert wurde:
pluginConfigs wird nur aus Benutzereinstellungen, dem --settings Flag und verwalteten Einstellungen gelesen. Einträge in der .claude/settings.json oder .claude/settings.local.json eines Projekts werden ignoriert, da diese Werte in Plugin-Hook-, MCP- und LSP-Konfigurationen ersetzt werden, und ein geklontes Repository darf sie nicht bereitstellen. Vor v2.1.207 wurden auch Projekt- und lokale Einstellungen gelesen.

extraKnownMarketplaces

Definiert zusätzliche Marketplaces, die für das Repository verfügbar gemacht werden sollten. Normalerweise in Repository-Ebenen-Einstellungen verwendet, um sicherzustellen, dass Teamkollegen Zugriff auf erforderliche Plugin-Quellen haben. Wenn ein Repository extraKnownMarketplaces enthält:
  1. Teamkollegen werden aufgefordert, den Marketplace zu installieren, wenn sie dem Ordner vertrauen
  2. Teamkollegen werden dann aufgefordert, Plugins aus diesem Marketplace zu installieren
  3. Benutzer können unerwünschte Marketplaces oder Plugins überspringen (in Benutzereinstellungen gespeichert)
  4. Die Installation respektiert Vertrauensgrenzen und erfordert explizite Zustimmung
Beispiel:
Marketplace-Quellentypen:
  • github: GitHub-Repository (verwendet repo)
  • git: Beliebige Git-URL (verwendet url)
  • directory: Lokaler Dateisystem-Pfad (verwendet path, nur für Entwicklung)
  • hostPattern: Regex-Muster zum Abgleichen von Marketplace-Hosts (verwendet hostPattern)
  • settings: Inline-Marketplace, der direkt in settings.json deklariert wird, ohne ein separates gehostetes Repository (verwendet name und plugins)
Der git Quellentyp funktioniert mit jedem Git-Hosting-Service, einschließlich selbstgehosteter GitLab und Bitbucket. Claude Code klont das Repository mit der gleichen Authentifizierung, die git clone auf dieser Maschine verwenden würde: konfigurierte Credential Helper oder SSH-Schlüssel. Ein Provider-Token wie GITHUB_TOKEN wird nur durch einen Credential Helper wirksam, der ihn liest. Siehe Private Repositories für Setup-Details. Für github und git Quellen setzen Sie "skipLfs": true innerhalb des source Objekts (neben repo oder url), um Git LFS-Downloads zu überspringen, wenn Claude Code das Marketplace-Repository klont oder aktualisiert. LFS-Zeigerdateien bleiben als Zeiger erhalten, anstatt ihren Inhalt herunterzuladen. Verwenden Sie dies, wenn das Repository große LFS-Objekte enthält, die nicht mit Plugin-Inhalten zusammenhängen. Erfordert Claude Code v2.1.153 oder später. Jeder Marketplace-Eintrag akzeptiert auch einen optionalen autoUpdate Boolean. Setzen Sie "autoUpdate": true neben source, um Claude Code zu veranlassen, diesen Marketplace zu aktualisieren und seine installierten Plugins im Hintergrund nach dem Start zu aktualisieren. Wenn nicht angegeben, verwenden offizielle Anthropic-Marketplaces standardmäßig true und alle anderen Marketplaces standardmäßig false. Siehe Automatische Aktualisierungen konfigurieren. Verwenden Sie source: 'settings', um einen kleinen Satz von Plugins inline zu deklarieren, ohne ein gehostetes Marketplace-Repository einzurichten. Plugins, die hier aufgelistet sind, müssen externe Quellen wie GitHub oder npm referenzieren. Sie müssen weiterhin jedes Plugin separat in enabledPlugins aktivieren.

strictKnownMarketplaces

Nur verwaltete Einstellungen: Steuert, welche Plugin-Marketplaces Benutzer hinzufügen und Plugins installieren dürfen. Diese Einstellung kann nur in verwalteten Einstellungen konfiguriert werden und bietet Administratoren strikte Kontrolle über Marketplace-Quellen. Verwaltete Einstellungsdatei-Speicherorte:
  • macOS: /Library/Application Support/ClaudeCode/managed-settings.json
  • Linux und WSL: /etc/claude-code/managed-settings.json
  • Windows: C:\Program Files\ClaudeCode\managed-settings.json
Wichtige Merkmale:
  • Nur in verwalteten Einstellungen verfügbar (managed-settings.json)
  • Kann nicht durch Benutzer- oder Projekteinstellungen überschrieben werden (höchste Priorität)
  • Durchgesetzt VOR Netzwerk-/Dateisystem-Operationen, sodass blockierte Quellen nie ausgeführt werden
  • Verwendet exakte Übereinstimmung für Quellspezifikationen (einschließlich ref, path für Git-Quellen), außer hostPattern und pathPattern, die Regex-Abgleich verwenden
Allowlist-Verhalten:
  • undefined (Standard): Keine Einschränkungen, sodass Benutzer jeden Marketplace hinzufügen können
  • Leeres Array []: Vollständiger Lockdown, sodass Benutzer keine neuen Marketplaces hinzufügen können
  • Liste von Quellen: Benutzer können nur Marketplaces hinzufügen, die genau übereinstimmen
Alle unterstützten Quellentypen: Die Allowlist unterstützt mehrere Marketplace-Quellentypen. Die meisten Quellen verwenden exakte Übereinstimmung, während hostPattern und pathPattern Regex-Abgleich gegen den Marketplace-Host und den Dateisystem-Pfad verwenden.
  1. GitHub-Repositories:
Felder: repo (erforderlich), ref (optional: Branch oder Tag), path (optional: Unterverzeichnis)
  1. Git-Repositories:
Felder: url (erforderlich), ref (optional: Branch oder Tag), path (optional: Unterverzeichnis)
  1. URL-basierte Marketplaces:
Felder: url (erforderlich), headers (optional: HTTP-Header für authentifizierten Zugriff)
URL-basierte Marketplaces laden nur die marketplace.json-Datei herunter. Sie laden keine Plugin-Dateien vom Server herunter. Plugins in URL-basierten Marketplaces müssen externe Quellen (GitHub, npm oder Git-URLs) verwenden, anstatt relative Pfade. Für Plugins mit relativen Pfaden verwenden Sie stattdessen einen Git-basierten Marketplace. Siehe Troubleshooting für Details.
  1. NPM-Pakete:
Felder: package (erforderlich, unterstützt scoped Pakete)
  1. Dateipfade:
Felder: path (erforderlich: absoluter Pfad zur marketplace.json-Datei)
  1. Verzeichnispfade:
Felder: path (erforderlich: absoluter Pfad zum Verzeichnis mit .claude-plugin/marketplace.json)
  1. Host-Muster-Abgleich:
Felder: hostPattern (erforderlich: Regex-Muster zum Abgleich gegen den Marketplace-Host) Verwenden Sie Host-Muster-Abgleich, wenn Sie alle Marketplaces von einem bestimmten Host erlauben möchten, ohne jedes Repository einzeln aufzuzählen. Dies ist nützlich für Organisationen mit internen GitHub Enterprise oder GitLab-Servern, auf denen Entwickler ihre eigenen Marketplaces erstellen. Host-Extraktion nach Quellentyp:
  • github: passt immer gegen github.com
  • git: extrahiert Hostname aus der URL (unterstützt sowohl HTTPS als auch SSH-Formate)
  • url: extrahiert Hostname aus der URL
  • npm, file, directory: nicht unterstützt für Host-Muster-Abgleich
  1. Pfad-Muster-Abgleich:
Felder: pathPattern (erforderlich: Regex-Muster, das gegen das path-Feld von file und directory-Quellen abgeglichen wird) Verwenden Sie Pfad-Muster-Abgleich, um dateisystem-basierte Marketplaces neben hostPattern-Einschränkungen für Netzwerk-Quellen zu erlauben. Setzen Sie ".*" auf alle lokalen Pfade, oder ein engeres Muster, um auf bestimmte Verzeichnisse zu beschränken. Konfigurationsbeispiele: Beispiel: Nur bestimmte Marketplaces erlauben:
Beispiel: Alle Marketplace-Ergänzungen deaktivieren:
Beispiel: Alle Marketplaces von einem internen Git-Server erlauben:
Anforderungen für exakte Übereinstimmung: Marketplace-Quellen müssen genau übereinstimmen, damit eine Benutzer-Ergänzung erlaubt wird. Für Git-basierte Quellen (github und git) umfasst dies alle optionalen Felder:
  • Das repo oder url muss genau übereinstimmen
  • Das ref-Feld muss genau übereinstimmen (oder beide sind undefined)
  • Das path-Feld muss genau übereinstimmen (oder beide sind undefined)
Beispiele von Quellen, die nicht übereinstimmen:
Vergleich mit extraKnownMarketplaces: Formatunterschied: strictKnownMarketplaces verwendet direkte Quellobjekte:
extraKnownMarketplaces erfordert benannte Marketplaces:
Beide zusammen verwenden: strictKnownMarketplaces ist ein Richtlinien-Gate: Es steuert, was Benutzer hinzufügen dürfen, registriert aber keine Marketplaces. Um einen Marketplace sowohl einzuschränken als auch für alle Benutzer vorzuregistrieren, setzen Sie beide in managed-settings.json:
Mit nur strictKnownMarketplaces gesetzt, können Benutzer den erlaubten Marketplace weiterhin manuell über /plugin marketplace add hinzufügen, aber er ist nicht automatisch verfügbar. Wichtige Hinweise:
  • Einschränkungen werden VOR Netzwerkanfragen oder Dateisystem-Operationen überprüft
  • Wenn blockiert, sehen Benutzer klare Fehlermeldungen, die angeben, dass die Quelle durch verwaltete Richtlinie blockiert ist
  • Die Einschränkung wird beim Hinzufügen und beim Installieren, Aktualisieren, Aktualisieren und automatischen Aktualisieren von Plugins durchgesetzt. Ein Marketplace, der vor dem Festlegen der Richtlinie hinzugefügt wurde, kann nicht mehr zum Installieren oder Aktualisieren von Plugins verwendet werden, sobald seine Quelle nicht mehr mit der Allowlist übereinstimmt
  • Verwaltete Einstellungen haben die höchste Priorität und können nicht überschrieben werden
Siehe Verwaltete Marketplace-Einschränkungen für Dokumentation für Benutzer.

strictPluginOnlyCustomization

Nur verwaltete Einstellungen: blockiert Skills, Agents, Hooks und MCP-Server aus Benutzer- und Projektquellen, sodass sie nur aus Plugins oder verwalteten Einstellungen stammen können. Kombinieren Sie es mit strictKnownMarketplaces, um die vollständige Anpassungs-Lieferkette zu steuern: Die Marketplace-Allowlist steuert, welche Plugins Benutzer installieren können, und diese Einstellung blockiert alles, das nicht aus einem Plugin oder aus verwalteten Einstellungen stammt. Der Wert ist entweder true, um alle vier Oberflächen zu sperren, oder ein Array, das die zu sperrenden Oberflächen benennt:
Für jede gesperrte Oberfläche überspringt Claude Code Benutzer- und Projektquellen und lädt nur Plugin-bereitgestellte und verwaltete Quellen: Oberflächennamen, die eine Claude Code-Version nicht erkennt, werden ignoriert, anstatt die Einstellungsdatei fehlschlagen zu lassen, sodass Sie neue Oberflächennamen hinzufügen können, bevor alle Clients aktualisiert wurden.

Verwalten von Plugins

Verwenden Sie den Befehl /plugin, um Plugins interaktiv zu verwalten:
  • Durchsuchen Sie verfügbare Plugins aus Marketplaces
  • Installieren/Deinstallieren Sie Plugins
  • Aktivieren/Deaktivieren Sie Plugins
  • Zeigen Sie Plugin-Details an (bereitgestellte Skills, Agents, Hooks)
  • Fügen Sie Marketplaces hinzu/entfernen Sie sie
Erfahren Sie mehr über das Plugin-System in der Plugins-Dokumentation.

Umgebungsvariablen

Umgebungsvariablen ermöglichen es Ihnen, das Verhalten von Claude Code zu steuern, ohne Einstellungsdateien zu bearbeiten. Jede Variable kann auch in settings.json unter dem Schlüssel env konfiguriert werden, um sie auf jede Sitzung anzuwenden oder für Ihr Team bereitzustellen. Siehe die Umgebungsvariablen-Referenz für die vollständige Liste.

Tools, die Claude zur Verfügung stehen

Claude Code hat Zugriff auf eine Reihe von Tools zum Lesen, Bearbeiten, Suchen, Ausführen von Befehlen und Orchestrieren von Subagents. Tool-Namen sind die genauen Zeichenketten, die Sie in Berechtigungsregeln und Hook-Matchern verwenden. Siehe die Tools-Referenz für die vollständige Liste und Details zum Bash-Tool-Verhalten.

Siehe auch