Umgebungsvariablen

OpenClaw bezieht Umgebungsvariablen aus mehreren Quellen. Die Regel lautet: vorhandene Werte niemals überschreiben.

Priorität (höchste → niedrigste)

1. Prozessumgebung (was der Gateway-Prozess bereits von der übergeordneten Shell bzw. dem übergeordneten Daemon hat).
2. .env im aktuellen Arbeitsverzeichnis (dotenv-Standard; überschreibt nicht).
3. Globale .env unter ~/.openclaw/.env (auch $OPENCLAW_STATE_DIR/.env; überschreibt nicht).
4. Konfigurationsblock env in ~/.openclaw/openclaw.json (wird nur angewendet, wenn der Wert fehlt).
5. Optionaler Login-Shell-Import (env.shellEnv.enabled oder OPENCLAW_LOAD_SHELL_ENV=1), wird nur für fehlende erwartete Schlüssel angewendet.

Bei Ubuntu-Neuinstallationen, die das standardmäßige State-Verzeichnis verwenden, behandelt OpenClaw außerdem ~/.config/openclaw/gateway.env als Kompatibilitäts-Fallback nach der globalen .env. Wenn beide Dateien vorhanden sind und sich widersprechen, behält OpenClaw ~/.openclaw/.env bei und gibt eine Warnung aus.

Wenn die Konfigurationsdatei vollständig fehlt, wird Schritt 4 übersprungen; der Shell-Import wird weiterhin ausgeführt, wenn er aktiviert ist.

Konfigurationsblock env

Zwei gleichwertige Möglichkeiten, Inline-Umgebungsvariablen festzulegen (beide überschreiben nicht):

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

Shell-Umgebungsimport

env.shellEnv führt Ihre Login-Shell aus und importiert nur fehlende erwartete Schlüssel:

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

Entsprechungen als Umgebungsvariablen:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Zur Laufzeit injizierte Umgebungsvariablen

OpenClaw injiziert außerdem Kontextmarker in gestartete Child-Prozesse:

• OPENCLAW_SHELL=exec: wird für Befehle gesetzt, die über das exec-Tool ausgeführt werden.
• OPENCLAW_SHELL=acp: wird für Starts von ACP-Laufzeit-Backend-Prozessen gesetzt (zum Beispiel acpx).
• OPENCLAW_SHELL=acp-client: wird für openclaw acp client gesetzt, wenn der ACP-Bridge-Prozess gestartet wird.
• OPENCLAW_SHELL=tui-local: wird für lokale TUI-!-Shell-Befehle gesetzt.

Dies sind Laufzeitmarker (keine erforderliche Benutzerkonfiguration). Sie können in Shell-/Profil-Logik verwendet werden, um kontextspezifische Regeln anzuwenden.

UI-Umgebungsvariablen

• OPENCLAW_THEME=light: erzwingt die helle TUI-Palette, wenn Ihr Terminal einen hellen Hintergrund hat.
• OPENCLAW_THEME=dark: erzwingt die dunkle TUI-Palette.
• COLORFGBG: wenn Ihr Terminal dies exportiert, verwendet OpenClaw den Hinweis zur Hintergrundfarbe, um die TUI-Palette automatisch auszuwählen.

Umgebungsvariablensubstitution in der Konfiguration

Sie können Umgebungsvariablen direkt in String-Werten der Konfiguration mit der Syntax ${VAR_NAME} referenzieren:

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

Vollständige Details finden Sie unter Konfiguration: Umgebungsvariablensubstitution.

Secret refs im Vergleich zu ${ENV}-Strings

OpenClaw unterstützt zwei umgebungsbasierte Muster:

• ${VAR}-String-Substitution in Konfigurationswerten.
• SecretRef-Objekte ({ source: "env", provider: "default", id: "VAR" }) für Felder, die Secret-Referenzen unterstützen.

Beide werden zum Aktivierungszeitpunkt aus der Prozessumgebung aufgelöst. Details zu SecretRef sind unter Secrets-Verwaltung dokumentiert.

Pfadbezogene Umgebungsvariablen

Logging

OPENCLAW_HOME

Wenn gesetzt, ersetzt OPENCLAW_HOME das System-Home-Verzeichnis ($HOME / os.homedir()) für die gesamte interne Pfadauflösung. Dies ermöglicht vollständige Dateisystemisolation für headless Service-Konten.

Priorität: OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir()

Beispiel (macOS LaunchDaemon):

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

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

nvm-Benutzer: web_fetch-TLS-Fehler

Wenn Node.js über nvm installiert wurde (nicht über den Systempaketmanager), verwendet das integrierte fetch() den von nvm gebündelten CA-Speicher, in dem moderne Root-CAs fehlen können (ISRG Root X1/X2 für Let's Encrypt, DigiCert Global Root G2 usw.). Dadurch schlägt web_fetch auf den meisten HTTPS-Websites mit "fetch failed" fehl.

Unter Linux erkennt OpenClaw nvm automatisch und wendet die Korrektur in der tatsächlichen Startumgebung an:

• openclaw gateway install schreibt NODE_EXTRA_CA_CERTS in die systemd-Service-Umgebung
• der openclaw-CLI-Einstiegspunkt führt sich selbst mit gesetztem NODE_EXTRA_CA_CERTS erneut aus, bevor Node startet

Manuelle Korrektur (für ältere Versionen oder direkte node ...-Starts):

Exportieren Sie die Variable, bevor Sie OpenClaw starten:

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crtopenclaw gateway run

Verlassen Sie sich für diese Variable nicht darauf, sie nur in ~/.openclaw/.env zu schreiben; Node liest NODE_EXTRA_CA_CERTS beim Prozessstart.

Legacy-Umgebungsvariablen

OpenClaw liest nur OPENCLAW_*-Umgebungsvariablen. Die Legacy-Präfixe CLAWDBOT_* und MOLTBOT_* aus früheren Releases werden stillschweigend ignoriert.

Wenn beim Start noch welche im Gateway-Prozess gesetzt sind, gibt OpenClaw eine einzelne Node-Deprecation-Warnung (OPENCLAW_LEGACY_ENV_VARS) aus, die die erkannten Präfixe und die Gesamtzahl auflistet. Benennen Sie jeden Wert um, indem Sie das Legacy-Präfix durch OPENCLAW_ ersetzen (zum Beispiel CLAWDBOT_GATEWAY_TOKEN → OPENCLAW_GATEWAY_TOKEN); die alten Namen haben keine Wirkung.

Verwandte Themen

• Gateway-Konfiguration
• FAQ: Umgebungsvariablen und .env-Laden
• Modellübersicht