Umgebungsvariablen

OpenClaw lädt Umgebungsvariablen aus mehreren Quellen. Dabei gilt die Regel: Vorhandene Werte niemals überschreiben. .env-Dateien im Workspace sind eine weniger vertrauenswürdige Quelle: OpenClaw ignoriert Provider-Anmeldedaten und geschützte Laufzeitsteuerungen aus der .env-Datei des Workspace, bevor die Rangfolge angewendet wird.

Rangfolge (höchste bis niedrigste Priorität)

1. Prozessumgebung (die Umgebung, die der Gateway-Prozess bereits von der übergeordneten Shell bzw. dem Daemon übernommen hat).
2. .env im aktuellen Arbeitsverzeichnis (dotenv-Standard; überschreibt nichts; Provider-Anmeldedaten und geschützte Laufzeitsteuerungen werden ignoriert).
3. Globale .env unter ~/.openclaw/.env (auch $OPENCLAW_STATE_DIR/.env; für Provider-API-Schlüssel empfohlen; überschreibt nichts).
4. Konfigurationsblock env in ~/.openclaw/openclaw.json (wird nur bei fehlenden Werten angewendet).
5. Optionaler Import aus der Anmelde-Shell (env.shellEnv.enabled oder OPENCLAW_LOAD_SHELL_ENV=1), der nur für fehlende erwartete Schlüssel angewendet wird.

Bei neuen Ubuntu-Installationen, die das standardmäßige Zustandsverzeichnis verwenden, behandelt OpenClaw außerdem ~/.config/openclaw/gateway.env nach der globalen .env als Kompatibilitätsrückfall. Wenn beide Dateien vorhanden sind und voneinander abweichen, behält OpenClaw die Werte aus ~/.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, sofern er aktiviert ist.

Provider-Anmeldedaten und Workspace-.env

Bewahren Sie Provider-API-Schlüssel nicht ausschließlich in einer Workspace-.env auf. OpenClaw blockiert eine umfangreiche Menge von Schlüsseln für Provider-Anmeldedaten und Endpunktumleitungen aus Workspace-.env-Dateien. Dazu gehören alle bekannten Umgebungsvariablen für die Provider-Authentifizierung (beispielsweise GEMINI_API_KEY, GOOGLE_API_KEY, XAI_API_KEY, MISTRAL_API_KEY, GROQ_API_KEY, DEEPSEEK_API_KEY, PERPLEXITY_API_KEY, BRAVE_API_KEY, TAVILY_API_KEY, EXA_API_KEY, FIRECRAWL_API_KEY), alle Schlüssel mit der Endung _API_HOST, _BASE_URL oder _HOMESERVER sowie die vollständigen Namensräume OPENCLAW_*, CLAWHUB_*, ANTHROPIC_API_KEY_* und OPENAI_API_KEY_*.

Verwenden Sie für Provider-Anmeldedaten stattdessen eine der folgenden vertrauenswürdigen Quellen:

• Die Prozessumgebung des Gateway, beispielsweise eine Shell, eine launchd-/systemd-Unit, ein Container-Secret oder ein CI-Secret.
• Die globale dotenv-Laufzeitdatei unter ~/.openclaw/.env oder $OPENCLAW_STATE_DIR/.env.
• Den Konfigurationsblock env in ~/.openclaw/openclaw.json.
• Den optionalen Import aus der Anmelde-Shell, wenn env.shellEnv.enabled oder OPENCLAW_LOAD_SHELL_ENV=1 aktiviert ist.

Wenn Sie Provider-Schlüssel bisher ausschließlich in einer Workspace-.env gespeichert haben, verschieben Sie sie in eine der oben genannten vertrauenswürdigen Quellen. Eine Workspace-.env kann weiterhin gewöhnliche Projektvariablen bereitstellen, sofern es sich nicht um Anmeldedaten, Endpunktumleitungen, Host-Überschreibungen oder OPENCLAW_*-Laufzeitsteuerungen handelt.

Die Sicherheitsbegründung finden Sie unter Workspace-.env-Dateien.

Konfigurationsblock env

Es gibt zwei gleichwertige Möglichkeiten, Umgebungsvariablen direkt festzulegen (beide überschreiben keine vorhandenen Werte):

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

Der Konfigurationsblock env akzeptiert ausschließlich literale Zeichenfolgenwerte. Er löst file:...-Werte nicht auf; beispielsweise wird XAI_API_KEY: "file:secrets/xai-api-key.txt" genau als diese Zeichenfolge an Provider übergeben.

Verwenden Sie für dateibasierte Provider-Schlüssel eine SecretRef im Anmeldedatenfeld, das diese unterstützt:

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

Unterstützte Felder finden Sie unter Secret-Verwaltung und auf der SecretRef-Anmeldedatenoberfläche.

Import der Shell-Umgebung

env.shellEnv führt Ihre Anmelde-Shell aus und importiert ausschließlich fehlende erwartete Schlüssel:

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

Entsprechende Umgebungsvariablen:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000 (Standardwert: 15000)

Snapshots der Ausführungs-Shell

Auf Gateway-Hosts, die nicht Windows verwenden, nutzen exec-Befehle von bash und zsh standardmäßig einen Start-Snapshot. Legen Sie OPENCLAW_EXEC_SHELL_SNAPSHOT=0 in der Prozessumgebung des Gateway fest, um diesen Pfad zu deaktivieren. Auch die Werte false, no und off deaktivieren ihn. Aufrufspezifische exec.env-Werte können Snapshots weder umschalten noch den Snapshot-Cache umleiten.

Zur Laufzeit eingefügte Umgebungsvariablen

OpenClaw fügt außerdem Kontextmarkierungen in gestartete Kindprozesse ein:

• OPENCLAW_SHELL=exec: wird für Befehle festgelegt, die über das Werkzeug exec ausgeführt werden.
• OPENCLAW_SHELL=acp-client: wird für openclaw acp client festgelegt, wenn der ACP-Brückenprozess gestartet wird.
• OPENCLAW_SHELL=tui-local: wird für lokale TUI-Shell-Befehle mit ! festgelegt.
• OPENCLAW_CLI=1: wird für Kindprozesse festgelegt, die vom CLI-Einstiegspunkt gestartet werden.

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

Umgebungsvariablen der Benutzeroberfläche

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

Ersetzung von Umgebungsvariablen in der Konfiguration

Sie können mit der Syntax ${VAR_NAME} direkt auf Umgebungsvariablen in Zeichenfolgenwerten der Konfiguration verweisen:

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

Ausführliche Informationen finden Sie unter Konfiguration: Ersetzung von Umgebungsvariablen.

Secret-Referenzen im Vergleich zu ${ENV}-Zeichenfolgen

OpenClaw unterstützt zwei auf Umgebungsvariablen basierende Muster:

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

Beide werden bei der Aktivierung anhand der Prozessumgebung aufgelöst. Einzelheiten zu SecretRef sind unter Secret-Verwaltung dokumentiert. Der Konfigurationsblock env selbst löst weder SecretRefs noch file:...-Kurzschreibweisen auf.

Pfadbezogene Umgebungsvariablen

Protokollierung

OPENCLAW_HOME

Wenn OPENCLAW_HOME festgelegt ist, ersetzt es das Home-Verzeichnis des Systems ($HOME / os.homedir()) für interne OpenClaw-Standardpfade. Dies umfasst das standardmäßige Zustandsverzeichnis, den Konfigurationspfad, Agentenverzeichnisse, Anmeldedaten, den Einrichtungs-Workspace des Installers und den standardmäßigen Entwicklungs-Checkout, den openclaw update --channel dev verwendet.

Rangfolge: OPENCLAW_HOME > $HOME > USERPROFILE > Termux-PREFIX-Home-Rückfall unter Android > os.homedir()

Beispiel (macOS-LaunchDaemon):

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

OPENCLAW_HOME kann auch auf einen Pfad mit Tilde gesetzt werden (z. B. ~/svc). Dieser wird vor der Verwendung über dieselbe Rückfallkette für das Betriebssystem-Home-Verzeichnis expandiert.

Explizite Pfadvariablen wie OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH und OPENCLAW_GIT_DIR haben weiterhin Vorrang. Aufgaben des Betriebssystemkontos wie die Erkennung von Shell-Startdateien, die Einrichtung des Paketmanagers und die Expansion von ~ auf dem Host können weiterhin das tatsächliche System-Home-Verzeichnis verwenden.

nvm-Benutzer: TLS-Fehler bei web_fetch

Wenn Node.js über nvm und nicht über den Systempaketmanager installiert wurde, verwendet das integrierte fetch() den mit nvm gebündelten CA-Speicher, in dem möglicherweise moderne Stammzertifizierungsstellen fehlen (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 Umgebung des systemd-Dienstes.
• Der CLI-Einstiegspunkt openclaw führt sich vor dem Start von Node erneut mit gesetztem NODE_EXTRA_CA_CERTS aus.

Manuelle Korrektur (für ältere Versionen oder direkte Aufrufe mit node ...):

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 ausschließlich in ~/.openclaw/.env zu schreiben; Node liest NODE_EXTRA_CA_CERTS beim Prozessstart.

Veraltete Umgebungsvariablen

OpenClaw liest ausschließlich OPENCLAW_*-Umgebungsvariablen. Die veralteten Präfixe CLAWDBOT_* und MOLTBOT_* aus früheren Versionen werden stillschweigend ignoriert.

Wenn beim Start des Gateway-Prozesses noch solche Variablen festgelegt sind, gibt OpenClaw eine einzelne Node-Veraltungswarnung (OPENCLAW_LEGACY_ENV_VARS) aus, in der die erkannten Präfixe und deren Gesamtanzahl aufgeführt werden. Benennen Sie jeden Wert um, indem Sie das veraltete Präfix durch OPENCLAW_ ersetzen (beispielsweise CLAWDBOT_GATEWAY_TOKEN durch OPENCLAW_GATEWAY_TOKEN); die alten Namen haben keine Wirkung.

Verwandte Themen

• Gateway-Konfiguration
• Häufig gestellte Fragen: Umgebungsvariablen und Laden von .env-Dateien
• Modellübersicht