Umgebungsvariablen

OpenClaw bezieht Umgebungsvariablen aus mehreren Quellen. Die Regel lautet: Vorhandene Werte werden nie ueberschrieben.

Rangfolge (hoechste zu niedrigste)

Prozessumgebung (was der Gateway-Prozess bereits von der uebergeordneten Shell/dem Daemon hat).
.env im aktuellen Arbeitsverzeichnis (dotenv-Standard; ueberschreibt nicht).
Globale .env unter ~/.openclaw/.env (alias $OPENCLAW_STATE_DIR/.env; ueberschreibt nicht).
env-Block in der Konfiguration in ~/.openclaw/openclaw.json (nur angewendet wenn fehlend).
Optionaler Login-Shell-Import (env.shellEnv.enabled oder OPENCLAW_LOAD_SHELL_ENV=1), nur fuer fehlende erwartete Schluessel angewendet.

Wenn die Konfigurationsdatei komplett fehlt, wird Schritt 4 uebersprungen; der Shell-Import laeuft dennoch, wenn aktiviert.

`env`-Block in der Konfiguration

Zwei aequivalente Wege, Umgebungsvariablen inline zu setzen (beide sind nicht-ueberschreibend):

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

Shell-Env-Import

env.shellEnv fuehrt deine Login-Shell aus und importiert nur fehlende erwartete Schluessel:

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

Aequivalente Umgebungsvariablen:

OPENCLAW_LOAD_SHELL_ENV=1
OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Zur Laufzeit injizierte Umgebungsvariablen

OpenClaw injiziert auch Kontextmarkierungen in gestartete Kindprozesse:

OPENCLAW_SHELL=exec: gesetzt fuer Befehle, die ueber das exec-Tool ausgefuehrt werden.
OPENCLAW_SHELL=acp: gesetzt fuer ACP-Runtime-Backend-Prozessstarts (zum Beispiel acpx).
OPENCLAW_SHELL=acp-client: gesetzt fuer openclaw acp client beim Starten des ACP-Bridge-Prozesses.
OPENCLAW_SHELL=tui-local: gesetzt fuer lokale TUI !-Shell-Befehle.

Dies sind Laufzeitmarkierungen (keine erforderliche Benutzerkonfiguration). Sie koennen in Shell-/Profillogik verwendet werden, um kontextspezifische Regeln anzuwenden.

UI-Umgebungsvariablen

OPENCLAW_THEME=light: die helle TUI-Palette erzwingen, wenn dein Terminal einen hellen Hintergrund hat.
OPENCLAW_THEME=dark: die dunkle TUI-Palette erzwingen.
COLORFGBG: wenn dein Terminal es exportiert, verwendet OpenClaw den Hintergrundfarb-Hinweis zur automatischen Palettenwahl.

Umgebungsvariablen-Substitution in der Konfiguration

Du kannst Umgebungsvariablen direkt in Konfigurationszeichenfolgen mit der ${VAR_NAME}-Syntax referenzieren:

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

Siehe Konfiguration: Umgebungsvariablen-Substitution fuer vollstaendige Details.

SecretRef vs `${ENV}`-Zeichenfolgen

OpenClaw unterstuetzt zwei umgebungsvariablenbasierte Muster:

${VAR}-Zeichenfolgensubstitution in Konfigurationswerten.
SecretRef-Objekte ({ source: "env", provider: "default", id: "VAR" }) fuer Felder, die Geheimnis-Referenzen unterstuetzen.

Beide werden zur Aktivierungszeit aus der Prozessumgebung aufgeloest. SecretRef-Details sind in Geheimnis-Verwaltung dokumentiert.

Pfadbezogene Umgebungsvariablen

Variable	Zweck
`OPENCLAW_HOME`	Das Home-Verzeichnis fuer alle interne Pfadaufloesung ueberschreiben (`~/.openclaw/`, Agent-Verzeichnisse, Sitzungen, Zugangsdaten). Nuetzlich wenn OpenClaw als dedizierter Dienstbenutzer laeuft.
`OPENCLAW_STATE_DIR`	Das Statusverzeichnis ueberschreiben (Standard `~/.openclaw`).
`OPENCLAW_CONFIG_PATH`	Den Konfigurationsdateipfad ueberschreiben (Standard `~/.openclaw/openclaw.json`).

Logging

Variable	Zweck
`OPENCLAW_LOG_LEVEL`	Log-Level fuer Datei und Konsole ueberschreiben (z.B. `debug`, `trace`). Hat Vorrang vor `logging.level` und `logging.consoleLevel` in der Konfiguration. Ungueltige Werte werden mit einer Warnung ignoriert.

`OPENCLAW_HOME`

Wenn gesetzt, ersetzt OPENCLAW_HOME das System-Home-Verzeichnis ($HOME / os.homedir()) fuer alle interne Pfadaufloesung. Dies ermoeglicht vollstaendige Dateisystem-Isolation fuer Headless-Dienstkonten.

Rangfolge: OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir()

Beispiel (macOS LaunchDaemon):

<key>EnvironmentVariables</key>
<dict>
  <key>OPENCLAW_HOME</key>
  <string>/Users/kira</string>
</dict>

OPENCLAW_HOME kann auch auf einen Tilde-Pfad gesetzt werden (z.B. ~/svc), der vor der Verwendung mit $HOME expandiert wird.