Umgebungsvariablen in OpenClaw verwalten

API-Keys und Konfigurationen über verschiedene Umgebungen hinweg zu verwalten, kann schnell unübersichtlich werden. Oft fragt man sich, welche .env-Datei gerade Vorrang hat oder warum ein gesetzter Wert einfach nicht übernommen wird.

OpenClaw löst das mit einer klaren Hierarchie. Die wichtigste Regel dabei: Bestehende Werte werden nie überschrieben. Wenn eine Variable bereits im System gesetzt ist, behält sie diesen Wert.

Voraussetzungen

• Eine installierte OpenClaw-Instanz
• Eine openclaw.json Konfigurationsdatei

Schnellstart

In fünf Minuten hast du deine Umgebung im Griff. Folge diesen Schritten für ein minimales Setup:

1. Variablen in der Config definieren: Öffne deine ~/.openclaw/openclaw.json und füge einen env Block hinzu.
2. Substitution nutzen: Verwende das ${VAR_NAME} Format in deinen Config-Strings, um direkt auf Variablen zuzugreifen.
3. Shell-Import aktivieren: Falls du Variablen aus deiner Shell (wie .zshrc oder .bashrc) brauchst, aktiviere shellEnv.
4. Pfade anpassen: Nutze OPENCLAW_HOME, falls du das Standardverzeichnis verschieben musst.

Hier ist ein Beispiel für die Einbindung in deine openclaw.json:

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

Für die Substitution in der Config sieht das Ganze so aus:

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}

Die Hierarchie (Precedence)

OpenClaw prüft Quellen in dieser Reihenfolge (höchste → niedrigste):

1. Process environment: Variablen, die der Gateway-Prozess bereits vom Shell- oder Daemon-Parent hat.
2. .env im aktuellen Verzeichnis: Der Standard von dotenv (überschreibt nichts).
3. Globale .env: Liegt unter ~/.openclaw/.env (bzw. $OPENCLAW_STATE_DIR/.env).
4. Config env Block: Aus deiner openclaw.json.
5. Shell-Shell-Import: Optionaler Import aus der Login-Shell.

Shell env import

Mit env.shellEnv startet OpenClaw deine Login-Shell und importiert nur fehlende Keys:

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

Alternativ kannst du das über diese Variablen steuern:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Pfad-Variablen

Diese Variablen steuern, wo OpenClaw seine Daten speichert:

Variable	Zweck
OPENCLAW_HOME	Überschreibt das Home-Verzeichnis für interne Pfade (~/.openclaw/, Agent-Verzeichnisse, Sessions). Hilfreich für dedizierte Service-User.
OPENCLAW_STATE_DIR	Überschreibt das State-Verzeichnis (Standard: ~/.openclaw).
OPENCLAW_CONFIG_PATH	Überschreibt den Pfad zur Config-Datei (Standard: ~/.openclaw/openclaw.json).
OPENCLAW_LOAD_SHELL_ENV	Aktiviert den Import der Shell-Umgebung.

Fehlerbehebung

Die Konfiguration im env Block wird ignoriert Falls die openclaw.json komplett fehlt, wird dieser Schritt in der Hierarchie übersprungen. Der Shell-Import läuft trotzdem weiter, sofern er aktiviert ist.

Variablen werden nicht aktualisiert Denk an die goldene Regel: OpenClaw überschreibt niemals existierende Werte. Wenn eine Variable bereits in deinem Process Environment oder einer lokalen .env Datei definiert ist, wird der Wert aus der globalen Config oder dem Shell-Import ignoriert.

Fragen zum Setup? Nutze den AI Setup Assistant.

Nächste Schritte

• Gateway configuration
• FAQ: env vars and .env loading
• Models overview
• Configuration: Env var substitution