Ein­stel­lungen und Ebenen

Claude Code merkt sich vieles, ohne dass man es jedes Mal neu sagt: mit welchem Modell eine Sitzung startet, welche Befehle ohne Rückfrage laufen, welche Dateien tabu sind, wie das Terminal aussieht. All das steht in Einstellungen, also in Schlüsseln im JSON-Format, verteilt auf eine Handvoll Dateien. Die Doku zu den Ein­stel­lungs­da­teien (externe Seite, code.claude.com) stellt die wichtigste Regel an den Anfang: Die Datei, aus der ein Wert kommt, bestimmt, für wen er gilt.

Dieses Kapitel ordnet die Dateien, zeigt, welcher Wert gewinnt, wenn derselbe Schlüssel an mehreren Stellen steht, und wie man nachsieht, was gerade gilt. Dazu kommt, was eine Organisation für alle festlegen kann. Wie man Regeln für Rechte schreibt, steht in Kapitel 16, was in eine CLAUDE.md gehört, in Kapitel 14.

Wo Einstellungen stehen

Claude Code liest vier Dateien. Eine Organisation kann zusätzlich Einstellungen über die Konsole von claude.ai ausliefern.

• Nutzer (~/.claude/settings.json): gilt für einen selbst, in jedem Projekt auf diesem Rechner; gedacht für Thema, Standardmodell, eigene Freigaben.
• Projekt (.claude/settings.json): gilt für alle, die im Projekt arbeiten, sobald die Datei im Repository liegt; gedacht für Rechte, Hooks und Plugins des Teams.
• lokal (.claude/settings.local.json): gilt für einen selbst, nur in diesem Projekt; gedacht für persönliche Abweichungen, Versuche vor dem Teilen.
• verwaltet (managed-settings.json und weitere Wege): gilt für alle, an die die Organisation sie verteilt; gedacht für Sicher­heits­vor­gaben und Compliance.

~/.claude ist der Ordner .claude im eigenen Benut­zer­ver­zeichnis, ein .claude ohne Tilde der Ordner im Projekt. Die Installation legt keine dieser Dateien an. Die Nutzerdatei schreibt Claude Code, sobald man in /config etwa das Thema ändert. Die lokale Datei entsteht bei der ersten dauerhaften Freigabe auf eine Rückfrage.

Eine fünfte Datei, ~/.claude.json, führt Claude Code für sich selbst. Darin stehen die Anmeldung, eigene MCP-Server, Ver­trau­ens­ent­schei­dungen je Projekt und einige Schalter aus /config. Von Hand bearbeiten muss man sie nicht. Rechte, Hooks und Umge­bungs­va­ria­blen haben dort keine Wirkung. Die Doku zur Fehlersuche in der Konfiguration (externe Seite, code.claude.com) führt diese Verwechslung als häufige Ursache, wenn global gesetzte Rechte wirkungslos bleiben.

Welche Einstellung gewinnt

Steht derselbe Schlüssel an mehreren Stellen, gilt der Wert der höchsten Ebene, die ihn setzt. Von oben nach unten:

1. Verwaltet: die Einstellungen der Organisation. Kein Wert aus den eigenen Dateien überschreibt sie.
2. Kommandozeile: JSON, das man beim Start mit --settings übergibt, nur für diese eine Sitzung.
3. Lokal: .claude/settings.local.json im Projekt.
4. Projekt: .claude/settings.json im Projekt.
5. Nutzer: ~/.claude/settings.json.

Unterhalb der Organisation gewinnt also die Datei, die näher am Projekt liegt.

Listen folgen einer eigenen Regel. Steht etwa permissions.allow in mehreren Dateien, führt Claude Code die Einträge zusammen. Jede Datei kann so Einträge ergänzen, ohne die einer anderen zu entfernen. Für eine Organisation heißt das: Ihre Entwickler können eine verwaltete Liste erweitern, aber nichts daraus streichen (Doku zur Einrichtung für Organisationen (externe Seite, code.claude.com)).

Die Doku spielt die Rangfolge an den Tipps durch, die unter dem Spinner wechseln, solange Claude arbeitet. Wer sie in den eigenen Einstellungen mit "spinnerTipsEnabled": false abschaltet, sieht sie in einem Projekt wieder, dessen Team den Schlüssel auf true setzt. Eine Zeile in der lokalen Datei dieses Projekts holt den eigenen Wert zurück, und die Sitzungen der Kollegen bleiben, wie sie sind. Setzt dagegen die Organisation den Schlüssel, bleibt nur die Frage an den Administrator. Umgekehrt gilt für einige Schlüssel, die eine Sitzung einschränken, der strengere Wert auch dann, wenn er von weiter unten kommt. Welche das sind, steht in der Vertiefung. Dort steht auch, wie eine Organisation mit einem eigenen Mod einen ihrer Werte zur Obergrenze macht.

Einstellungen mit dem Team teilen

Seit Version 0.2.67 vom April 2025 lassen sich Rechteregeln eines Projekts in .claude/settings.json ablegen und so mit anderen teilen (Versionsliste (externe Seite, code.claude.com)). Heute gehört in diese Datei alles, was für jeden im Projekt gleich sein soll: Freigaben, Hooks, Plugins und die Umge­bungs­va­ria­blen, die das Projekt braucht. Liegt sie im Repository, bekommt sie jeder, der es klont.

Ein geteilter Wert kann an zwei Stellen hängen bleiben. Freigaberegeln, Marktplätze für Plugins und die meisten Umge­bungs­va­ria­blen aus der Projektdatei wirken erst, wenn jeder Einzelne dem Ordner vertraut hat. Bis dahin kommen weiter Rückfragen. Sperren und erzwungene Rückfragen gelten dagegen sofort, mit oder ohne Vertrauen (Beispieldateien (externe Seite, code.claude.com)). Außerdem wirken manche Schlüssel und Werte aus einer Projektdatei gar nicht, etwa "defaultMode": "auto". Ein fremdes Repository kann eine Sitzung so weder in den Modus auto noch, seit Version 2.1.257, in bypassPermissions schalten; mehr dazu in Vibe-Coding / Agentic Engineering, Kapitel 08.

Persönliches gehört in .claude/settings.local.json. Claude Code schreibt selbst hinein: Wer bei einer Rückfrage „Yes, and don’t ask again“ wählt, legt dort eine Freigaberegel ab. Beim ersten Schreiben nimmt Claude Code die Datei in die globale Ignorierliste von Git auf, damit sie in keinem Commit landet.

Eine Einstellung ändern

Im Terminal öffnet /config ein Menü. Es zeigt eine kurze Liste persönlicher Optionen wie Thema, Eingabemodus und ausführliche Ausgabe, und nur einen Teil der Schlüssel. Die meisten Änderungen landen in ~/.claude/settings.json. Seit Version 2.1.181 vom 17.06.2026 setzt /config schlüssel=wert einen Wert direkt aus der Eingabe, etwa /config verbose=true (Versionsliste (externe Seite, code.claude.com)). Das Chatfenster von VS Code und die Desktop-App öffnen /config nicht. Dort ändert man die Datei oder die Einstellungen der App.

Wer eine Datei von Hand bearbeitet, schreibt reines JSON. Ein Kommentar mit // oder ein Komma hinter dem letzten Eintrag gilt als Fehler, und Claude Code meldet die Datei beim nächsten Start. Eine Zeile mit dem Schlüssel $schema am Anfang gibt im Editor Vorschläge und eine Prüfung beim Tippen.

"$schema": "https://json.schemastore.org/claude-code-settings.json"

Seit Version 1.0.90 vom 25.08.2025 wirkt eine geänderte Datei ohne Neustart. Claude Code beobachtet seine Ein­stel­lungs­da­teien und lädt sie neu, sobald sie sich ändern, auch Rechte und Hooks. Einige Schlüssel liest es aber nur beim Start einer Sitzung, darunter Modell und Effort. Für die gibt es /model und /effort, siehe Kapitel 06.

Für eine einzige Sitzung übergibt man einen Wert beim Start, etwa claude --settings '{"model": "claude-opus-5-5"}'. Die Dateien bleiben dabei unverändert.

Prüfen, was gilt

/status zeigt in der Zeile „Setting sources“, welche Dateien die Sitzung geladen hat. Wirken verwaltete Einstellungen, steht in Klammern, auf welchem Weg sie kamen. Welche Datei welchen Schlüssel geliefert hat, zeigt die Zeile allerdings nicht. Abgelehnte Einträge listet claude doctor in der Shell. Es liest nur und startet dafür keine Sitzung. Was die Prüfung /doctor in einer Sitzung zusätzlich kann, steht in Kapitel 02.

Hängt ein Fehler womöglich an der eigenen Konfiguration, hilft seit Version 2.1.169 vom 08.06.2026 ein Start mit claude --safe-mode. Er schaltet CLAUDE.md, Plugins, Skills, Hooks und MCP-Server für diese Sitzung ab. Hooks und Richtlinien aus verwalteten Einstellungen gelten auch dann weiter. Verwaltete Plugins, Skills und MCP-Server und die CLAUDE.md der Organisation schaltet er dagegen mit ab.

Umgebungsvariablen als zweiter Weg

Vieles lässt sich auch über Umge­bungs­va­ria­blen steuern, vom Modell bis zu Zeitgrenzen. Sie stehen entweder in der Shell oder im Block env einer Einstellungsdatei. In der Shell gelten sie für diese Sitzung des Terminals, in der Datei bei jedem Start (Doku zu Umge­bungs­va­ria­blen (externe Seite, code.claude.com)).

Eine Ebene im Stapel sind Umge­bungs­va­ria­blen nicht. Gibt es für dieselbe Sache eine Variable und einen Schlüssel, regelt jedes Paar selbst, wer vorgeht. ANTHROPIC_MODEL aus der Shell gilt vor dem Schlüssel model aus jeder Datei, ANTHROPIC_DEFAULT_MODEL nur, solange keine Datei ein Modell setzt. Der Block env selbst ist ein gewöhnlicher Schlüssel und folgt der Rangfolge der Dateien.

Verwaltete Einstellungen einer Organisation

Verwaltete Einstellungen verteilt eine Organisation auf die Rechner aller Entwickler (Doku zu verwalteten Einstellungen (externe Seite, code.claude.com)). Sie stehen über allen anderen Ebenen. Meist kommen sie auf einem von drei Wegen auf den Rechner:

• Serververwaltet: Ein Owner der Organisation legt sie in der Konsole von claude.ai an. Claude Code holt sie beim Start und danach stündlich. Das gibt es in den Tarifen Claude for Teams und Claude for Enterprise (Doku zu serververwalteten Einstellungen (externe Seite, code.claude.com)).
• MDM oder Betriebssystem: als Kon­fi­gu­ra­ti­ons­profil unter macOS oder als Wert in der Registry von Windows, verteilt mit Werkzeugen wie Jamf, Intune oder Group Policy.
• Datei: managed-settings.json in einem Systemordner, unter macOS in /Library/Application Support/ClaudeCode/, unter Linux und WSL in /etc/claude-code/, unter Windows in C:\Program Files\ClaudeCode\.

Auf jedem dieser Wege kommen dieselben Schlüssel an wie in einer eigenen Einstellungsdatei. Dazu kommen Schlüssel, die nur dort wirken: dass allein die Rechteregeln der Organisation gelten, allein ihre Hooks laufen oder allein ihre MCP-Server erlaubt sind, an welche Organisation die Anmeldung gebunden ist und welche Fassungen von Claude Code überhaupt starten. Seit Version 2.1.285 vom 29.09.2026 begrenzt allowedProviders, über welche Anbieter ein Rechner Claude erreichen darf, etwa nur die API von Anthropic oder nur Amazon Bedrock. Ob eine Vorgabe angekommen ist, zeigt /status in der Zeile „Setting sources“.

Eine Grenze nennt die Doku ausdrücklich. Serververwaltete Einstellungen setzt das Programm auf dem Rechner durch. Eine Sicherheitsgrenze sind sie damit nicht. Auf einem Rechner ohne Geräteverwaltung braucht niemand Admi­nis­tra­tor­rechte, um sie zu umgehen. Mehr Schutz geben Datei und MDM auf verwalteten Geräten, weil das Betriebssystem die Datei vor Änderungen schützen kann. Und jede dieser Vorgaben bindet allein Claude Code. Wer die API über ein anderes Werkzeug anspricht, steht nicht darunter.

Welche Ebene wofür passt

• Eigene Vorlieben für alle Projekte: die Nutzerdatei, am bequemsten über /config.
• Was im Team für alle gleich sein soll: die Projektdatei, im Repository committet.
• Eine persönliche Abweichung in einem Projekt: die lokale Datei.
• Ein Versuch für eine Sitzung: --settings beim Start.
• Was niemand ändern darf: verwaltete Einstellungen, auf verwalteten Geräten besser per MDM oder Datei als allein über die Konsole. Wer auch Cloud-Sitzungen nutzt, braucht zusätzlich die Konsole.

Eine Cloud-Sitzung in einer Umgebung von Anthropic läuft auf einem frischen Klon. Sie liest von all dem höchstens die Projektdatei aus dem Repository, dazu die serververwalteten Einstellungen.

Die Vertiefung zeigt, welche Schlüssel eine Projektdatei nicht setzen kann, wo die Rangfolge Ausnahmen kennt, was hilft, wenn ein Wert nicht greift, und wie eine Organisation ihre Vorgaben ausrollt.

Der Überblick hat die fünf Ebenen und ihre Rangfolge sortiert. Im Alltag haken Einstellungen an anderen Stellen:

• an einer Datei, die woanders liegt als gedacht,
• an einem Schlüssel, den eine Projektdatei gar nicht setzen darf,
• an einer Liste, die anders zusammengeführt wird als die übrigen Werte,
• an einer Vorgabe der Organisation, die den Rechner noch nicht erreicht hat.

Jeder Schlüssel hat in der Referenz aller Einstellungen (externe Seite, code.claude.com) einen eigenen Eintrag mit Typ, Vorgabe und einer Zeile „Scope“. Die Zeile sagt, in welchen Dateien er wirkt. „Any file“ heißt in allen vier, „Managed“ nur in verwalteten Einstellungen, „Global config“ nur in ~/.claude.json. Dazwischen gibt es Stufen wie „User or managed“. Wer wissen will, wohin ein Schlüssel gehört, liest zuerst diese Zeile.

Wo die Dateien liegen

Unter Windows steht ~/.claude für %USERPROFILE%\.claude. Wer die Dateien im Benut­zer­ver­zeichnis woanders haben will, setzt CLAUDE_CONFIG_DIR. Dann liegen dort auch der Verlauf der Sitzungen und die Plugins (Doku zu den Ein­stel­lungs­da­teien (externe Seite, code.claude.com)). Wie man damit zwei Konten auf einem Rechner trennt, steht in Kapitel 02.

Die geteilte Projektdatei liest Claude Code aus dem Arbeits­ver­zeichnis, in dem die Sitzung beginnt. Wer eine Datei an der Wurzel des Repositorys nutzen will, startet also dort. Wechselt die Sitzung mit /cd in ein anderes Verzeichnis, liest Claude Code seit Version 2.1.246 die Projektdateien von dort. Für die lokale Datei gilt in einem Git-Repository etwas anderes: Claude Code liest und schreibt sie an der Wurzel des Repositorys, in einem Worktree an der Wurzel des Haupt­ver­zeich­nisses. Eine Freigabe gilt damit im ganzen Repository und in allen Worktrees. Das gilt seit Version 2.1.211 vom 15.07.2026 (Versionsliste (externe Seite, code.claude.com)). Vorher lag die Datei im Startverzeichnis. Neben .claude/settings.json bleibt sie außerhalb eines Repositorys, unter Windows, wenn die Wurzel des Repositorys das eigene Benut­zer­ver­zeichnis ist, und wenn die Wurzel einem anderen Nutzer gehört.

Die lokale Datei hat noch eine Eigenheit. Solange Git sie nicht verfolgt, wirken ihre Freigaberegeln ohne den Schritt, in dem man dem Ordner vertraut. Der Grund: Die Datei gehört einem selbst. Liegt sie doch im Repository, braucht auch sie das Vertrauen.

~/.claude.json sichert Claude Code, bevor es die Datei neu schreibt. Die fünf jüngsten Fassungen liegen in ~/.claude/backups/. Lässt sich die Datei nicht lesen, fragt Claude Code beim Start, ob man sie von Hand reparieren oder auf die Grundeinstellung zurücksetzen will.

Was eine Projektdatei nicht setzen kann

Eine Projektdatei kommt mit dem Repository, also auch mit einem fremden. Deshalb wirken manche Schlüssel aus .claude/settings.json gar nicht. In der Referenz steht bei ihnen in der Zeile „Scope“ etwa „User“, „User or managed“ oder „Managed“. Einige Beispiele, die im Alltag auffallen:

• Startmodus ohne Rückfragen: "defaultMode": "auto" und "bypassPermissions" wirken aus Projekt- und lokaler Datei nicht. Für bypassPermissions gilt das seit Version 2.1.257 vom 01.09.2026, vorher wirkte es aus jeder Datei.
• Remote Control beim Start: Seit Version 2.1.222 vom 04.08.2026 kann eine Datei im Repository es nicht mehr einschalten, nur noch ausschalten.
• Bestimmte Umge­bungs­va­ria­blen: Projekt- und lokale Datei können etwa CLAUDE_CONFIG_DIR und die Variablen für den Export von Telemetrie nicht setzen (Doku zu Umge­bungs­va­ria­blen (externe Seite, code.claude.com)).

Andere Schlüssel wirken, aber erst, wenn jemand dem Ordner vertraut hat: Freigaberegeln, zusätzliche Verzeichnisse, Marktplätze für Plugins und die meisten Umge­bungs­va­ria­blen. Sperren und erzwungene Rückfragen wirken sofort. Für ein Team heißt das: Was jeder als Freigabe bekommen soll, braucht beim ersten Öffnen ein Ja von jedem Einzelnen. In welcher Reihenfolge Claude Code die Regeln prüft, erklärt Kapitel 16.

Wo die Rangfolge Ausnahmen kennt

Bei den meisten Schlüsseln gilt der Wert der höchsten Ebene. Drei Gruppen weichen davon ab.

Listen. Listen werden zusammengeführt. Vier Schlüssel für Modelle haben eigene Regeln, darunter diese zwei. fallbackModel ist eine Kette, in der die Reihenfolge zählt. Claude Code nimmt sie deshalb ganz aus der höchsten Datei, die sie setzt. Ein verwaltetes availableModels gilt unverändert, eigene Einträge aus Nutzer-, Projekt- oder lokaler Datei fallen weg. Das gilt nicht, wenn eine App, die Claude Code einbettet, eine eigene Liste mitbringt. Was die Kette bei einem Ausfall tut, steht in Kapitel 06.

Startwerte der Organisation. Ein verwaltetes model ist ein Startwert. --model und ANTHROPIC_MODEL wählen weiterhin das Modell einer Sitzung (Doku zu verwalteten Einstellungen (externe Seite, code.claude.com)). Wer die Wahl wirklich einschränken will, braucht availableModels oder deniedModels. Ein Startwert ist auch das Fenster, ab dem Claude Code verdichtet: Ein verwaltetes autoCompactWindow gibt es vor, --autocompact setzt einen anderen für die Sitzung.

Strengere Werte von unten. Für einige Schlüssel, die eine Sitzung einschränken, gilt ein strengerer Wert auch aus einer Ebene, die verwaltete Einstellungen sonst nicht überschreiben kann. Einige davon:

• disableClaudeAiConnectors: true aus jeder Ebene, auch gegen ein verwaltetes false
• permissions.blockReadsOutsideWorkingDirectories: true aus jeder Ebene, seit 2.1.257
• maxEffortLevel: die niedrigste Obergrenze aus allen Ebenen, seit 2.1.267
• remoteControlAtStartup: false aus Projekt- oder lokaler Datei

Bei maxEffortLevel kann niemand die Obergrenze anheben, auch die Organisation nicht, wenn ein Entwickler für sich eine niedrigere setzt.

Eine Obergrenze für einen anderen Schlüssel kann eine Organisation seit Version 2.1.304 vom 19.10.2026 selbst bauen, mit einem eigenen Mod. Ein Mod der Organisation kann das Lesen der Einstellungen abfangen, das Ereignis settings.read. Er bekommt dabei jede Ebene einzeln zu sehen und darf das zusammengeführte Ergebnis umschreiben (Versionsliste (externe Seite, code.claude.com)). So macht die Organisation einen ihrer Werte zur Obergrenze, unter der jeder Entwickler einen eigenen wählen kann. Die Versionsliste nennt ausdrücklich cleanupPeriodDays, also wie viele Tage Claude Code die Verläufe der Sitzungen aufbewahrt, bevor es sie löscht. Auch die Löschung im Hintergrund richtet sich dann nach dem umgeschriebenen Wert. Wie ein Mod der Organisation vor die Mods der Nutzer kommt, steht in Kapitel 18.

Wenn ein Wert nicht greift

Die Doku nennt vier Ursachen, wenn ein gesetzter Wert keine Wirkung zeigt: Eine höhere Ebene setzt ihn, ein Schlüssel für Sicherheit hält seinen strengeren Wert, die Datei darf den Wert nicht setzen, oder die Datei ist kaputt. Der erste Blick gilt /status, der zweite claude doctor.

Eine kaputte Datei meldet Claude Code beim Start einer Sitzung im Terminal auf zwei Stufen:

• Settings Error: Die Datei ist kein gültiges JSON, oder ein Wert passt nicht zum Schema. Ein Dialog bietet an, die Datei mit Claudes Hilfe zu reparieren, das Programm zu beenden oder ohne die kaputten Einstellungen weiterzumachen.
• Settings Warning: Nur einzelne Einträge sind fehlerhaft, etwa eine falsch geschriebene Rechteregel. Claude Code überspringt sie und behält den Rest der Datei.

Ein Lauf mit claude -p zeigt keinen Dialog. Solange sich jede verwaltete Vorgabe lesen lässt, überspringt er die kaputte Datei oder die kaputten Werte und arbeitet mit dem Rest weiter. Wer ein Skript laufen lässt, das eine Einstellung zu ignorieren scheint, fragt danach claude doctor. Wie Claude Code ohne Terminal läuft, zeigt Kapitel 29.

Ein dritter Fall sieht aus wie ein Fehler im Programm. Man wählt mit /model ein Modell, und die nächste Sitzung startet wieder auf dem alten. Manchmal erzeugt ein anderes Werkzeug ~/.claude/settings.json oder verlinkt sie auf eine schreibgeschützte Kopie. Dann gilt die Wahl nur für die laufende Sitzung.

Hilft das alles nicht, empfiehlt die Doku zur Fehlersuche in der Konfiguration (externe Seite, code.claude.com) zwei Stufen. Zuerst kommt claude --safe-mode, das die eigenen Anpassungen abschaltet. Bleibt der Fehler, folgt ein Start ganz ohne eigene Konfiguration:

1. in einem leeren Ordner,
2. mit CLAUDE_CONFIG_DIR auf einem frischen Verzeichnis,
3. mit --setting-sources user, das Projektdateien wie .claude/settings.json, CLAUDE.md und .mcp.json weglässt (Kommandozeilen-Referenz (externe Seite, code.claude.com)).

Dass der frische Ordner greift, erkennt man daran, dass Claude Code die Einrichtung beim ersten Start wieder durchläuft. Verwaltete Einstellungen gelten auch hier. Verschwindet der Fehler, liegt die Ursache in der eigenen Nutzer- oder Pro­jekt­kon­fi­gu­ra­tion, und man kopiert die alten Dateien einzeln zurück, bis er wiederkommt.

Umgebungsvariablen im Einzelnen

Ein Block env in einer Einstellungsdatei schreibt seine Werte in die Umgebung des Prozesses. Steht dieselbe Variable auch in der Shell, gilt in den meisten Sitzungen der Wert aus der Datei (Doku zu Umge­bungs­va­ria­blen (externe Seite, code.claude.com)). Drei Eigenheiten fallen dabei auf:

• Keine Shell dazwischen. Claude Code übernimmt die Werte so, wie sie dastehen. ~ und $HOME werden nicht ersetzt, ein Pfad gehört also ausgeschrieben hinein.
• Setzen geht, Löschen nicht. Eine Variable, die ein fremdes Shell-Profil exportiert, lässt sich in der Datei nicht entfernen. Eine leere Zeichenkette wirkt bei der Wahl des Anbieters wie ungesetzt, etwa "CLAUDE_CODE_USE_VERTEX": "".
• Entfernen wirkt erst beim nächsten Start. Neue und geänderte Werte übernimmt eine laufende Sitzung beim Speichern, ein gelöschter Eintrag bleibt bis zum Neustart gesetzt. Eine Funktion, die ihre Variablen nur beim Start liest, etwa die Überwachung über OpenTelemetry, behält ihre Startwerte bis zum Neustart.

Zwischen den Dateien folgt env der Rangfolge. Ein verwalteter Eintrag überschreibt also dieselbe Variable aus Nutzer- oder Projektdatei. Welche Variable gegen welchen Schlüssel gewinnt, steht je Variable in der Referenz. Für ANTHROPIC_MODEL liest Claude Code zuerst die Variable und nimmt model nur, wenn sie fehlt.

Die Antwortsprache

Seit Version 2.1.0 vom 07.01.2026 legt der Schlüssel language fest, in welcher Sprache Claude antwortet (Versionsliste (externe Seite, code.claude.com)). Eine feste Liste gibt es dafür nicht. Claude Code reicht den Wert wörtlich als Anweisung an Claude weiter, immer in dieser Sprache zu antworten (Referenz (externe Seite, code.claude.com)). Geprüft wird der Wert nicht. Ein Tippfehler im Sprachnamen erreicht Claude also so, wie er dasteht, und erzeugt keine Fehlermeldung. Derselbe Wert stellt die Sprache für das Diktieren ein, dort mit einer festen Liste, und die Sprache der automatisch erzeugten Titel von Sitzungen. Wer "language": "german" in die Nutzerdatei schreibt, bekommt also auch deutsche Titel in der Liste der Sitzungen.

Verwaltete Einstellungen ausrollen

Vier Wege bringen verwaltete Einstellungen auf einen Rechner. Auf allen kommen dieselben Schlüssel an. Sie unterscheiden sich darin, wo die Vorgabe liegt und wann Claude Code sie liest (Doku zu verwalteten Einstellungen (externe Seite, code.claude.com)):

• serververwaltet: liegt in der Konsole von claude.ai oder einem selbst betriebenen Gateway; gelesen beim Start und danach stündlich.
• MDM oder Betriebssystem: liegt im Profil unter macOS (com.anthropic.claudecode) oder in der Registry unter
  HKLM\SOFTWARE\Policies\ClaudeCode;
  gelesen beim Start und alle 30 Minuten.
• Datei: liegt als managed-settings.json im Systemordner; gelesen beim Start und bei jeder Änderung der Datei.
• Registry des Nutzers (Windows): liegt unter
  HKCU\SOFTWARE\Policies\ClaudeCode;
  gelesen beim Start und alle 30 Minuten, nur ohne Vorgabe darüber.

Den letzten Weg kann jeder Nutzer ohne erhöhte Rechte beschreiben. Die Doku zur Einrichtung für Organisationen (externe Seite, code.claude.com) nennt ihn deshalb eine bequeme Vorgabe, mit der sich nichts durchsetzen lässt.

Eine Vorgabe aus mehreren Dateien. Seit Version 2.1.83 vom 25.03.2026 liest Claude Code neben managed-settings.json einen Ordner managed-settings.d/. Getrennte Teams können so eigene Teile einer Vorgabe ausrollen, die Claude Code alphabetisch zusammenführt (Versionsliste (externe Seite, code.claude.com)). Zahlen vor dem Namen legen die Reihenfolge fest, etwa 10-telemetry.json und 20-security.json. Bei einem einzelnen Wert gewinnt die spätere Datei. Listen werden vereinigt, doppelte Einträge fallen weg.

Mehrere Wege auf einem Rechner. Kommen Vorgaben auf mehreren Wegen an, nimmt Claude Code in der Grundeinstellung nur einen davon und lässt die anderen liegen. Die Rangfolge lautet: serververwaltet, dann MDM, dann Datei, dann die Registry des Nutzers. Gewählt wird der höchste Weg, der überhaupt einen Schlüssel liefert, und eine Warnung zu den übrigen gibt es nicht. Einige Schlüssel liest Claude Code trotzdem aus allen Wegen außer der Registry des Nutzers, darunter Sperren für die Sandbox und für MCP-Server. Wer alle Wege zusammenführen will, setzt "managedSourcesBehavior": "merge" im höchsten Weg. Das geht laut Doku ab Version 2.1.242, und die Registry des Nutzers bleibt auch dann außen vor. Die Doku rät zum Zusammenführen nur, wenn jeder Weg darunter in der Hand eines Administrators liegt, denn Listen wie Freigaberegeln und Hooks wandern dann mit hinein.

Eine Vorgabe aus einem Programm. Eine Organisation kann ein Programm ausrollen, das die Vorgabe beim Start berechnet. Grundlage kann etwa der Zustand des Geräts sein oder ein Dienst im Netz. Der Schlüssel dafür heißt policyHelper. Claude Code liest ihn nur aus dem Profil unter macOS, aus der Registry unter HKLM und aus der verwalteten Datei (Referenz der Einstellungen (externe Seite, code.claude.com)). Liefert das Programm ein Objekt managedSettings, ist das die einzige Vorgabe der Sitzung, auch für die Schlüssel, die Claude Code sonst aus allen Wegen liest.

Kommt beim Start eine serververwaltete Vorgabe an, läuft das Programm gar nicht. Scheitert es beim Start, verweigert Claude Code den Start, im Dialog wie mit -p. Dasselbe gilt für einen Fehler im Schema, den Claude Code nicht reparieren kann. Mit refreshIntervalMs läuft das Programm im Hintergrund erneut. Scheitert ein solcher Lauf, bleibt die letzte Vorgabe in Kraft, und /status nennt den Fehler.

Vorgaben einer einbettenden App. Claude Code läuft auch in anderen Anwendungen, etwa in Claude Desktop, in einer Erweiterung für die IDE oder in einer App mit dem Agent SDK. Eine solche App kann beim Start eigene verwaltete Einstellungen mitgeben. Die Doku zu verwalteten Einstellungen (externe Seite, code.claude.com) nennt sie parent settings. Kommt daneben eine Vorgabe über Konsole, MDM oder Datei an, verwirft Claude Code sie in der Grundeinstellung. Mit "parentSettingsBehavior": "merge" im höchsten Weg nimmt Claude Code von der App die Werte dazu, die Claude weiter einschränken.

Eine Lücke nennt die Doku dabei selbst: Ohne die Sperren allowManaged*Only gelten Freigaberegeln und Listen für die Sandbox aus der App weiter. Liefert ein policyHelper eine Vorgabe, nimmt Claude Code nie Werte der App auf.

Nachsehen auf dem Rechner. In /status nennt die Zeile „Setting sources“ bei verwalteten Einstellungen Enterprise managed settings und in Klammern den Weg, den Claude Code gewählt hat:

• (remote): serververwaltet, aus claude.ai oder einem Gateway,
• (plist) oder (HKLM): MDM oder Betriebssystem,
• (file), (drop-ins) oder (file + drop-ins): die Datei, der Ordner oder beide,
• eine Liste mit , merged am Ende, etwa (remote + file, merged): zusammengeführte Wege,
• (HKCU): die Registry des Nutzers,
• (parent process): einschränkende Vorgaben einer einbettenden App,
• (helper): ein policyHelper aus Profil oder Datei.

Eine zweite Zeile „Skipped sources“ listet die vorhandenen Wege, die ein höherer verdrängt. So trennt man eine Vorgabe, die nie ankam, von einer, die ein höherer Weg verdrängt. Die Doku nennt dafür Version 2.1.242 als Mindestfassung. Die Versionsliste (externe Seite, code.claude.com) führt keine Fassung 2.1.242 und nennt die Zeile unter 2.1.243 vom 25.08.2026. Fehlt die Zeile „Setting sources“ ganz, hat Claude Code keine Vorgabe gefunden. Dann lohnt der Blick, ob die Datei am Pfad für das Betriebssystem liegt und überhaupt einen Schlüssel der Vorgabe enthält.

Kaputte Vorgaben. Lässt sich eine verwaltete Datei, ein Profil oder ein Wert unter HKLM nicht als JSON-Objekt lesen, startet Claude Code gar nicht und nennt die Quelle. Ein kaputter Wert in der Registry des Nutzers hält den Start dagegen nie auf. Bei Schlüsseln mit einem einzigen strengen Wert, etwa allowManagedPermissionRulesOnly, gilt ein unlesbarer Eintrag als dieser strenge Wert, bis jemand ihn repariert.

Die Doku zur Einrichtung ordnet, was sich festlegen lässt, in Gruppen, darunter diese:

• Rechteregeln, und ob allein die der Organisation gelten,
• der Modus, in dem Sitzungen starten, und die Sandbox,
• MCP-Server, Marktplätze für Plugins und Hooks,
• Anmeldung, Anbieter, Modelle und eine Obergrenze für den Effort,
• der Bereich der Fassungen, die überhaupt starten.

Gelten allein die Rechteregeln der Organisation (allowManagedPermissionRulesOnly), verwirft Claude Code auch Freigaben, die eine App wie Claude Desktop beim Start mitgibt. In Cowork verlieren so die verbundenen Ordner ihre Freigabe zum Schreiben, bis die Vorgabe selbst Regeln für diese Ordner enthält (Doku zu verwalteten Einstellungen (externe Seite, code.claude.com)). Seit Version 2.1.305 vom 20.10.2026 gilt das auch für die allowed-tools von Plugins, die Claude Desktop über einen Pfad einbindet.

Zulassungs- und Sperrlisten für MCP-Server gibt es in verwalteten Einstellungen seit Version 2.0.22 vom 17.10.2025. Wie sie wirken, beschreibt Kapitel 19.

Serververwaltete Einstellungen im Betrieb

Den Weg über claude.ai pflegen nur der Primary Owner und die Owner der Organisation, unter Organization settings, Claude Code, Managed settings (Doku zu serververwalteten Einstellungen (externe Seite, code.claude.com)). Die Vorgabe gilt für alle Mitglieder gleich, Gruppen kennt dieser Weg noch nicht. Wer verschiedene Gruppen braucht, verteilt verschiedene Dateien oder Profile.

Einige Einstellungen der Vorgabe wendet Claude Code in einer interaktiven Sitzung erst nach einer Rückfrage an. Das betrifft Hooks, Skripte wie apiKeyHelper und statusLine, einige Einstellungen der Sandbox und Umge­bungs­va­ria­blen für Proxy oder Adresse der API. Der Nutzer sieht einen Dialog, der erklärt, was eingerichtet wird. Lehnt er ab, beendet sich Claude Code.

Gibt es noch keine gespeicherte Vorgabe und meldet sich jemand beim Start an, etwa beim ersten Start oder nach /logout, wartet Claude Code bis zu fünf Sekunden auf den Abruf. Bei jedem anderen Start ohne gespeicherte Vorgabe und nach Ablauf der fünf Sekunden öffnet sich die Sitzung sofort. Die Vorgaben greifen dann nach einer kurzen Lücke. Danach arbeitet Claude Code mit einer Kopie im Cache, die auch einen Ausfall des Netzes übersteht. Wer keinen Start ohne frische Vorgabe zulassen will, setzt forceRemoteSettingsRefresh: true. Scheitert dann der Abruf, beendet sich Claude Code. Die Adresse api.anthropic.com muss dann erreichbar sein, sonst startet Claude Code gar nicht.

Die Vorgabe erreicht nur Sitzungen, die direkt mit der API von Anthropic sprechen und mit einem passenden Zugang angemeldet sind, etwa dem Konto der Organisation. Drei Fälle fallen heraus:

• Ein Schlüssel aus der Claude Console. Er gehört zu einer eigenen Organisation der Console, getrennt von der Organisation in claude.ai. Ein CI-Job mit so einem Schlüssel bekommt die Vorgabe nicht.
• Ein anderer Anbieter. Wer in der Shell eine Variable wie CLAUDE_CODE_USE_BEDROCK oder eine eigene ANTHROPIC_BASE_URL setzt, überspringt den Abruf. Für Amazon Bedrock, Google Cloud und Microsoft Foundry übernimmt ein selbst betriebenes Gateway die Rolle der Konsole.
• Cowork in der Desktop-App. Dort holt Claude Code die Vorgabe aus der Konsole nie, auch nicht mit einem Konto aus Team oder Enterprise.

Ob der Abruf geklappt hat, meldet seit Version 2.1.248 vom 27.08.2026 claude doctor in einer eigenen Zeile, samt Grund, wenn er übersprungen wurde.

Für den CI-Job nennt die Doku zwei Auswege. Der erste ist ein Token aus claude setup-token, das für die Organisation freigegeben ist und in CLAUDE_CODE_OAUTH_TOKEN steht. Der zweite ist eine verwaltete Datei auf dem Rechner, der den Job ausführt. Läuft der Job mit --bare, bleibt nur die Datei, denn dieser Modus liest das Token nicht.

Was in einer Cloud-Sitzung gilt

Eine Cloud-Sitzung startet auf einem frischen Klon des Repositorys. Mit einem einzigen Repository außerhalb eines Projects liest sie dessen .claude/settings.json. Mit mehreren beginnt sie in einer Umgebung von Anthropic oberhalb der Klone und übernimmt aus jedem Repository nur die Angaben zu Plugins und Marktplätzen. Die Plugins und Marktplätze darin lädt eine Cloud-Sitzung trotzdem nicht. Die Threads eines Projects in der Cloud (Kapitel 22) übernehmen aus .claude/settings.json keine Rechteregeln, keine Hooks und kein env. Das gilt auch für ein Project mit einem einzigen Repository. Nutzerdatei und lokale Datei bleiben auf dem eigenen Rechner. Von den verwalteten Einstellungen kommen nur die serververwalteten an. Eine selbst betriebene Umgebung liest zusätzlich die verwaltete Datei in ihrem Runner-Image. /config öffnet im Browser die Einstellungen von claude.ai und ändert keinen Wert der Sitzung. Wer für Cloud-Sitzungen etwas einstellen will, setzt eine Umgebungsvariable in der Umgebung der Cloud-Sitzung. Bei einer Sitzung mit einem einzigen Repository außerhalb eines Projects geht auch ein Commit in dessen Projektdatei. Wo diese Sitzungen laufen, steht in Kapitel 01.

Die Ebenen von Claude Code sind in kleinen Schritten gewachsen, die verwalteten Einstellungen am stärksten. Dieser Teil zeichnet nach, wie es dazu kam, und zeigt, wo eine Vorgabe der Organisation aufhört. Dazu kommen die Grenze zwischen Einstellung und Anweisung und ein Blick auf Codex.

Wie die Ebenen entstanden

Versionen mit Datum stammen aus der Versionsliste (externe Seite, code.claude.com). Für 0.2.67 gilt das Datum der Veröffentlichung bei npm, weil die Versionsliste die Fassungen jener Wochen nur gesammelt datiert. Die Archivfassung der Doku vom Mai 2025 (externe Seite, docs.anthropic.com) und die Ankündigung für Team und Enterprise (externe Seite, anthropic.com) füllen zwei Lücken.

Zwei Linien laufen durch die Tabelle. Die erste betrifft den Weg zur Einstellung. Im Mai 2025 nannte die Doku zu den Einstellungen (externe Seite, docs.anthropic.com) zwei Wege: den Befehl claude config in der Shell und /config in der Sitzung. Wenige Wochen später kündigte Version 1.0.7 die Befehle zugunsten der Datei ab, und 2.0.0 nahm sie heraus. Mit /config schlüssel=wert kam im Juni 2026 wieder ein Befehl dazu, der jeden Schlüssel setzt, diesmal in der Sitzung und im Lauf mit -p.

Die zweite Linie betrifft die Organisation. Die Rangfolge selbst stand im Mai 2025 schon fest. Die Archivfassung der Doku (externe Seite, docs.anthropic.com) ordnet von unten nach oben: Nutzerdatei, Projektdatei, lokale Datei, Kommandozeile und ganz oben die Richtlinien des Unternehmens. Seither ist vor allem die oberste Ebene gewachsen.

Von der Richtliniendatei zu vier Wegen

Die Doku vom Mai 2025 (externe Seite, docs.anthropic.com) beschreibt die Vorgaben einer Organisation knapp. Für den Einsatz in Unternehmen gebe es Richtlinien, die vor Nutzer- und Pro­jekt­ein­stel­lungen gelten. Administratoren könnten sie als policies.json unter /Library/Application Support/ClaudeCode/ auf macOS ablegen, unter Linux und unter Windows über WSL in /etc/claude-code/. Die Ordner sind geblieben, die Datei heißt heute managed-settings.json.

Im August 2025 machte Anthropic die zentrale Verteilung zum Teil der Tarife für Organisationen. Die Ankündigung für Team und Enterprise nennt Rechte für Werkzeuge, Grenzen für den Dateizugriff und die Konfiguration von MCP-Servern als Beispiele. Dieselbe Ankündigung brachte Claude Code über Premium-Plätze in diese Tarife. Version 2.0.68 vom Dezember 2025 meldet dann Unterstützung für verwaltete Einstellungen von Enterprise, die das Account-Team von Anthropic freischaltet. Welcher Weg damit gemeint ist, sagt der Eintrag nicht. Die Datei auf dem Rechner gab es zu diesem Zeitpunkt schon seit Monaten.

Ab Februar 2026 kamen die Wege der Geräteverwaltung dazu: Profile unter macOS und Werte in der Registry von Windows. Unter Windows wechselte die Datei zwischen Dezember 2025 und März 2026 den Ort, von C:\ProgramData\ClaudeCode\ nach C:\Program Files\ClaudeCode\. Version 2.0.58 vom 03.12.2025 bevorzugte den neuen Ort, 2.1.2 vom 09.01.2026 kündigte den alten ab, und 2.1.75 vom 13.03.2026 nahm ihn heraus.

Mit vier Wegen kam die Frage, welcher gilt. Die Antwort heißt heute first-wins in der Grundeinstellung und merge als Wahl. Laut Versionsliste nennt /status seit Version 2.1.243 vom August 2026 in der Zeile „Skipped sources“ auch die übergangenen Wege.

Der Schlüssel dafür heißt managedSourcesBehavior und gilt laut Doku ab Version 2.1.242. Das Wertepaar stand schon Monate vorher in der Versionsliste, für die Vorgaben einer App, die Claude Code einbettet. Version 2.1.133 vom 07.05.2026 brachte parentSettingsBehavior mit genau diesen beiden Werten.

Was verwaltete Einstellungen nicht verhindern

Der Überblick nennt die Grundregel: Vorgaben setzt das Programm auf dem Rechner durch. Die Doku zu verwalteten Einstellungen zählt auf, was daraus folgt. Wer auf dem Rechner Administrator ist, kann die verwaltete Quelle selbst bearbeiten (Doku zu verwalteten Einstellungen (externe Seite, code.claude.com)). Deshalb können MDM-Werkzeuge Profil und Datei in festen Abständen neu verteilen.

Für den Weg über claude.ai nennt die Doku zu serververwalteten Einstellungen (externe Seite, code.claude.com) weitere Fälle:

• Veränderter Cache. Eine bearbeitete Kopie im Cache gilt beim Start, bis der nächste Abruf die Vorgabe wiederherstellt. Schlüssel, die erst beim nächsten Start wirken, etwa model, bleiben bis zum Neustart verändert.
• Verändertes Programm. Wer ein verändertes Claude Code ausführen kann, umgeht jede Prüfung im Programm.
• Alte Fassung. Fassungen aus der Zeit vor den serververwalteten Einstellungen holen sie gar nicht ab.
• Andere Organisation oder anderer Anbieter. Eine Anmeldung bei einer anderen Organisation, ein Schlüssel aus der Console oder ein Anbieter wie Amazon Bedrock führen an der Vorgabe vorbei.

Gegen den Wechsel des Anbieters gibt es seit Version 2.1.285 allowedProviders. Eine Sitzung über einen Anbieter, der nicht auf der Liste steht, weist Claude Code beim Start, bei der Anmeldung und bei der nächsten Anfrage ab (Referenz (externe Seite, code.claude.com)). Damit das auch ohne Abruf vom Server greift, gehört die Liste in eine Datei oder ein Profil auf dem Rechner. Anmeldungen über claude.ai bindet forceLoginOrgUUID aus einer verwalteten Quelle an die eigene Organisation. Gegen eine geänderte Datei auf dem Rechner gibt es den Hook ConfigChange. Er meldet seit Version 2.1.49 Änderungen an Ein­stel­lungs­da­teien während der Sitzung, auch an managed-settings.json. Vorgaben, die vom Server oder über MDM eintreffen, meldet er nicht. Blockieren kann er nur Änderungen außerhalb der verwalteten Einstellungen. Wer Änderungen an der Vorgabe in der Konsole nachvollziehen will, bekommt Ereignisse dazu über die Compliance API oder einen Export des Audit-Logs. Den Zugang vergibt das Account-Team von Anthropic.

Wie Hooks gebaut werden, steht in Kapitel 18. Was die Sandbox für Bash leistet, erklärt Kapitel 16.

Einstellung, Anweisung, Regel

Was Claude Code tut, steuern drei Arten von Angaben, und sie werden leicht verwechselt. Die Doku zur Fehlersuche in der Konfiguration (externe Seite, code.claude.com) zieht die Grenze so: Eine CLAUDE.md erklärt Claude, wie das Projekt funktioniert, damit es gute Entscheidungen trifft. Rechte und Hooks setzen Grenzen, gleich wie Claude entscheidet. Einstellungen sind der Ort, an dem die zweite Sorte steht, dazu alles, was das Programm selbst betrifft: Modell, Darstellung, Updates.

An einer Stelle verschwimmt die Grenze. Der Schlüssel language steht in den Einstellungen und wirkt wie eine Anweisung, denn Claude Code reicht den Wert als Satz an Claude weiter. Umgekehrt kann eine Organisation über den Schlüssel claudeMd eine CLAUDE.md für alle verteilen. Den Systemprompt selbst veröffentlicht Anthropic nicht. Dauerhafte Anweisungen gehören in eine CLAUDE.md oder an die Option --append-system-prompt. Was in eine CLAUDE.md gehört und wie Claude Code sich Dinge über Sitzungen hinweg merkt, steht in Kapitel 14.

Was Codex anders löst

Codex von OpenAI kennt dieselbe Aufgabe und teilt sie anders auf. Die Doku zur verwalteten Konfiguration (externe Seite, learn.chatgpt.com) trennt Vorgaben, die Nutzer nicht überschreiben können, von Startwerten, die sie ändern dürfen. Die Vorgaben folgen dem Format einer eigenen Datei requirements.toml, die Startwerte dem der gewöhnlichen config.toml. Widerspricht ein eigener Wert einer Vorgabe, nimmt Codex einen passenden Wert und sagt es dem Nutzer.

Bei Claude Code stehen Sperren und Startwerte im selben Dokument. Ob ein Schlüssel sperrt oder nur vorgibt, steht je Schlüssel in der Doku: Ein verwaltetes model ist ein Startwert, availableModels eine Sperre. Die Trennung in zwei Dateien macht diesen Unterschied schon am Dateinamen sichtbar, und darin ist Codex klarer.

Auch bei der Verteilung gehen beide eigene Wege. Codex schichtet die Vorgaben aus vier Quellen übereinander, vom niedrigsten Rang aufwärts: Systemdatei, Vorgabe aus der Cloud, die ältere managed_config.toml und ein MDM-Profil unter macOS. Eine höhere Schicht überschreibt einfache Werte und Listen der tieferen. Eine Vorgabe aus der Cloud weist man Nutzern oder Gruppen zu. Claude Code nimmt in der Grundeinstellung nur einen Weg und führt die übrigen erst mit merge zusammen. Teile einer Vorgabe liest es aus managed-settings.d/.

Was offen ist

Die Konsole von claude.ai kennt noch keine Gruppen, eine Vorgabe gilt dort für alle. Ein selbst betriebenes Gateway verteilt Vorgaben dagegen je Gruppe des Iden­ti­täts­an­bie­ters.

Für das Zusammenführen aller Wege und für die Zeile „Skipped sources“ nennt die Doku Version 2.1.242 als Mindestfassung. Die Versionsliste springt von 2.1.241 auf 2.1.243 und führt die Zeile unter 2.1.243. Das Zusammenführen nennt sie bei keiner Fassung als neu.

Das veröffentlichte Schema für Ein­stel­lungs­da­teien hinkt neuen Versionen hinterher. Eine Warnung im Editor zu einem frisch dokumentierten Schlüssel heißt deshalb nicht, dass die Datei falsch ist.