Claude Code: Umgebungsvariablen

Umgebungsvariablen sind ein wichtiger Weg, das Verhalten von Claude Code zu steuern und ermöglichen die flexible Anpassung verschiedener Einstellungen, ohne Konfigurationsdateien zu bearbeiten. Dieses Kapitel beschreibt detailliert alle von Claude Code unterstützten Umgebungsvariablen, ihre Zwecke, Konfigurationsmethoden und häufige Anwendungsszenarien.


Überblick über Umgebungsvariablen

Claude Code verwendet Umgebungsvariablen, um das Verhalten zu steuern. Diese Variablen können auf folgende Weise festgelegt werden:

  • Direkt in der Shellexport
  • In~/.claude/settings.jsonvonenvIm Feld konfigurieren
  • Auf Projektebene.claude/settings.jsonKonfigurieren in
  • Über die Einstellungsoberfläche des IDE-Plugins konfigurieren

Priorität der Umgebungsvariablen von höchster bis niedrigster: Befehlszeile > settings.json auf Projektebene > settings.json auf Benutzerebene > Shell-Umgebungsvariablen. In settings.json konfigurierte Variablen werden automatisch an den Claude-Prozess übergeben.


Authentifizierungsbezogene Variablen

Variablenname Beschreibung Wert
ANTHROPIC_API_KEY Claude-API-Schlüssel (von claude.ai bezogen) API-Schlüssel-Zeichenfolge
ANTHROPIC_BASE_URL Zieladresse für API-Anfragen (verwendet für Proxy oder benutzerdefinierte Endpunkte) URL-Adresse
ANTHROPIC_AUTH_TOKEN Authentifizierungstoken (verwendet für Szenarien wie VS Code-Plugin) Token-Zeichenfolge

Konfigurationsbeispiele

Beispiel

# In der Shell festlegen
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"

Beispiel

// In settings.json konfigurieren
{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxxxx",
    "ANTHROPIC_BASE_URL": "https://custom-proxy.com/v1"
  }
}

Variablen zur Modellkonfiguration

Variablenname Beschreibung Wert
ANTHROPIC_MODEL Standardmäßig verwendetes Modell claude-opus-4-5、claude-sonnet-4-5、claude-haiku-3-5warten
ANTHROPIC_SMALL_FAST_MODEL Im Schnellantwortmodus verwendetes Modell (für einfache Aufgaben) Modellname
CLAUDE_CODE_SUBAGENT_MODEL Legt einheitlich das von allen Subagenten verwendete Modell fest Modellname
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS Experimentelle Funktionen deaktivieren, wenn das Anthropic Messages-Format mit Bedrock oder Vertex verwendet wird 1

Verwendungsszenarien

Subagenten erben standardmäßig das Modell der Hauptkonversation. Mithilfe vonCLAUDE_CODE_SUBAGENT_MODELkönnen Sie sie einheitlich konfigurieren, indem Sie einfache Aufgaben Haiku und komplexe Analysen Sonnet zuweisen, um Kosten zu optimieren:

Beispiel

# Hauptkonversation verwendet Opus für komplexes Schlussfolgern, Subagenten verwenden einheitlich Sonnet
export ANTHROPIC_MODEL="claude-opus-4-5"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5"

Werkzeug- und Befehlsvariablen

Variablenname Beschreibung Wert
CLAUDE_CODE_DISABLE_SLASH_COMMANDS Alle Slash-Befehle deaktivieren 1
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS Die integrierten Git-bezogenen System-Prompts deaktivieren (Priorität höher als die in settings.jsonincludeGitInstructions) 1
CLAUDE_CODE_USE_POWERSHELL_TOOL PowerShell-Tools unter Windows aktivieren (erfordertdefaultShell: "powershell"einstellung) 1
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL Automatische IDE-Erweiterungsinstallation überspringen (AlternativeautoInstallIdeExtensioneinstellung) 1
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS Hintergrundaufgaben-Funktionalität deaktivieren 1

Berechtigungs- und Sicherheitsvariablen

Variablenname Beschreibung Wert
CLAUDE_CODE_PERMISSION_MODE Standard-Berechtigungsmodus festlegen (siehe Subagenten-Abschnitt für Details) default、acceptEdits、dontAsk、bypassPermissions、plan
CLAUDE_CODE_ALLOWED_TOOLS Whitelist der Werkzeuge, die Claude verwenden darf (kommagetrennt) Werkzeugliste
CLAUDE_CODE_DISALLOWED_TOOLS Sperrliste von Tools, die Claude nicht verwenden darf Werkzeugliste

Berechtigungsmodi erklärt

  • default: Normale Berechtigungsabfrage, vor jedem Vorgang nachfragen
  • acceptEdits: Dateiänderungen automatisch ohne Bestätigung akzeptieren
  • dontAsk: Nicht autorisierte Vorgänge automatisch ablehnen, ohne die Ausführung zu unterbrechen
  • bypassPermissions: Alle Berechtigungsprüfungen überspringen (nur für vollständig vertrauenswürdige Umgebungen)
  • plan: Schreibgeschützter Planungsmodus, keine Schreibvorgänge

Beispiel

# Schreibgeschützten Modus in CI-Umgebung verwenden
export CLAUDE_CODE_PERMISSION_MODE="plan"
export CLAUDE_CODE_ALLOWED_TOOLS="Read,Grep,Glob,Bash(gh *)"

Logging- und Debugging-Variablen

Variablenname Beschreibung Wert
CLAUDE_CODE_DEBUG Debug-Ausgabe aktivieren 1
CLAUDE_CODE_ENABLE_TELEMETRY Telemetrie-Datenerfassung aktivieren 1
OTEL_METRICS_EXPORTER OpenTelemetry-Metriken-Exporter otlpwarten

Sitzungs- und Verlaufsvariablen

Variablenname Beschreibung Wert
CLAUDE_CODE_DISABLE_HISTORY Speichern des Gesprächsverlaufs deaktivieren 1
CLAUDE_CODE_SESSION_TIMEOUT Sitzungs-Timeout (Sekunden) Number
CLAUDE_CODE_MAX_SESSIONS Maximale Anzahl gespeicherter Sitzungen Number

MCP-bezogene Variablen

Wenn Claude Code MCP-Tools ausführt, werden die folgenden Umgebungsvariablen festgelegt:

Variablenname Beschreibung Wert
CLAUDE_CODE_MCP_SERVER_NAME MCP-Servername String
CLAUDE_CODE_MCP_TOOL_NAME Name des aufgerufenen MCP-Tools String
CLAUDE_CODE_MCP_TOOL_ARGS An das MCP-Tool übergebene Parameter JSON-String

Workflow-bezogene Variablen

Variablenname Beschreibung Wert
CLAUDE_CODE_WORKTREE_CLEANUP_PERIOD_DAYS Auto-Cleanup-Zyklus für verwaiste Worktrees Tage
CLAUDE_CODE_DISABLE_WORKTREE_AUTO_CLEANUP Worktree-Auto-Cleanup deaktivieren 1

GitHub Actions-spezifische Variablen

Variablenname Beschreibung Wert
ANTHROPIC_VERTEX_PROJECT_ID Vertex-AI-Projekt-ID (wird vom Authentifizierungsschritt festgelegt, wenn Vertex verwendet wird) GCP-Projekt-ID
CLOUD_ML_REGION Vertex-AI-Region Regionscode (z. B.,us-east5)

Konfigurationsmethode für settings.json

Alle Umgebungsvariablen können konfiguriert werden insettings.json, was deklarativer und portabler ist:

Beispiel

{
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-4-5",
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-3-5",
    "CLAUDE_CODE_PERMISSION_MODE": "plan",
    "CLAUDE_CODE_ALLOWED_TOOLS": "Read,Grep,Glob,Bash",
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  }
}

VS Code-Plugin-Konfiguration

Wenn Sie das Claude Code-Plugin in VS Code verwenden, können Sie konfigurierenenvironmentVariablesEinstellungen:

Beispiel

{
  "claudeCode.environmentVariables": [
    {
      "name": "ANTHROPIC_BASE_URL",
      "value": "https://custom-proxy.com/api"
    },
    {
      "name": "ANTHROPIC_AUTH_TOKEN",
      "value: "your-token-here"
    },
    {
      "name": "ANTHROPIC_MODEL",
      "value": "claude-sonnet-4-5"
    }
  ]
}

Häufige Anwendungsszenarien

Szenario 1: Verwenden eines Proxys oder benutzerdefinierten API-Endpunkts

Beispiel

# Zugriff auf die Claude-API über einen unternehmensinternen API-Endpunkt
export ANTHROPIC_BASE_URL="https://proxy.company.com/anthropic/v1"
export ANTHROPIC_API_KEY="your-api-key"

Szenario 2: Kostenkonfiguration optimieren

Beispiel

# Hauptkonversation verwendet Sonnet, Subagenten verwenden einheitlich Haiku
export ANTHROPIC_MODEL="claude-sonnet-4-5"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-haiku-3-5"

Szenario 3: Sicherheitskonfiguration für CI/CD-Umgebung

Beispiel

# Schreibgeschützten Modus in CI-Umgebung verwenden
export CLAUDE_CODE_PERMISSION_MODE="plan"
export CLAUDE_CODE_DISABLE_HISTORY="1"
export CLAUDE_CODE_ALLOWED_TOOLS="Read,Grep,Glob,Bash(gh *)"

Szenario 4: Windows PowerShell-Umgebung

Beispiel

# PowerShell unter Windows aktivieren
$env:CLAUDE_CODE_USE_POWERSHELL_TOOL = "1"
# defaultShell in settings.json setzen

Priorität und Überschreibung

Priorität der Umgebungsvariablen (von hoch nach niedrig):

  1. BefehlszeileexportEinstellungen
  2. Projektebene.claude/settings.json
  3. Benutzerebene~/.claude/settings.json
  4. Standardwerte von Claude Code

Insettings.jsonIn konfigurierte Variablen überschreiben Shell-Umgebungsvariablen mit demselben Namen. Das liegt daran, dass settings.json explizit gelesen wird, wenn der Claude Code-Prozess startet, wodurch ihr eine höhere Priorität eingeräumt wird.


Aktuelle Konfiguration anzeigen

Verwenden Sie/configMit dem Befehl kann die aktuelle vollständige Konfiguration angezeigt werden:

/config

Dies zeigt alle derzeit wirksamen Einstellungen an, einschließlich Umgebungsvariablen und Konfigurationen in settings.json.


Best Practices

1. Umgang mit sensiblen Informationen

  • Sensible Informationen wie API-Schlüssel sollten nicht in settings.json hartcodiert werden
  • Verwenden Sie Umgebungsvariablen oder Shell-Konfigurationsdateien (~/.bashrc、~/.zshrc)
  • Stellen Sie sicher, dass Dateien mit sensiblen Informationen nicht in der Git-Versionskontrolle sind

2. Nach Umgebung konfigurieren

  • Lokale Entwicklung: einen permissiveren Berechtigungsmodus verwenden
  • CI/CD: Nur-Lese-Modus verwendenplan
  • Produktions-Debugging: aktivierenCLAUDE_CODE_DEBUG

3. Zentralisierte Verwaltung

  • Gemeinsame Konfiguration gehört in~/.claude/settings.json
  • Projektspezifische Konfiguration gehört in die des Projektverzeichnisses.claude/settings.json
  • Sensible Konfiguration wird über Shell-Umgebungsvariablen oder CI-Secrets bereitgestellt

FAQ

F: Was hat Vorrang, Umgebungsvariablen oder settings.json?

In settings.json konfigurierte Variablen haben höhere Priorität und überschreiben Shell-Umgebungsvariablen mit demselben Namen.

F: Wie bringe ich Claude Code dazu, einen anderen API-Endpunkt zu verwenden?

SetANTHROPIC_BASE_URLdie Umgebungsvariable, um auf Ihren Proxy oder benutzerdefinierten Endpunkt zu verweisen.

F: Wie steuern Subagenten, welches Modell sie verwenden?

Sie könnenCLAUDE_CODE_SUBAGENT_MODELdas Modell für alle Subagenten einheitlich festlegen oder es individuell im Frontmatter jedes Subagenten angeben.

F: Wie aktiviere ich PowerShell unter Windows?

Umgebungsvariable setzenCLAUDE_CODE_USE_POWERSHELL_TOOL=1, und legen Sie sie auch in settings.json festdefaultShell: "powershell"。

F: Wie deaktiviere ich alle Slash-Befehle?

SetCLAUDE_CODE_DISABLE_SLASH_COMMANDS=1die Umgebungsvariable.

Andere Erweiterungen