Omgevingsvariabelen

OpenClaw haalt omgevingsvariabelen uit meerdere bronnen. De regel is: bestaande waarden worden nooit overschreven.

Prioriteit (hoogste naar laagste)

Procesomgeving (wat het Gateway-proces al heeft van de bovenliggende shell/daemon).
.env in de huidige werkdirectory (dotenv-standaard; overschrijft niet).
Globale .env in ~/.openclaw/.env (alias $OPENCLAW_STATE_DIR/.env; overschrijft niet).
env-blok in de configuratie in ~/.openclaw/openclaw.json (alleen toegepast als ontbrekend).
Optionele login-shell-import (env.shellEnv.enabled of OPENCLAW_LOAD_SHELL_ENV=1), alleen toegepast voor ontbrekende verwachte sleutels.

Als het configuratiebestand volledig ontbreekt, wordt stap 4 overgeslagen; shell-import draait nog steeds als het is ingeschakeld.

`env`-blok in de configuratie

Twee equivalente manieren om inline omgevingsvariabelen in te stellen (beide overschrijven niet):

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

Shell env-import

env.shellEnv voert je login-shell uit en importeert alleen ontbrekende verwachte sleutels:

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

Equivalente omgevingsvariabelen:

OPENCLAW_LOAD_SHELL_ENV=1
OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Runtime-geinjecteerde omgevingsvariabelen

OpenClaw injecteert ook contextmarkeringen in gestarte kindprocessen:

OPENCLAW_SHELL=exec: ingesteld voor commando’s uitgevoerd via de exec-tool.
OPENCLAW_SHELL=acp: ingesteld voor ACP runtime backend-processtarts (bijvoorbeeld acpx).
OPENCLAW_SHELL=acp-client: ingesteld voor openclaw acp client bij het starten van het ACP bridge-proces.
OPENCLAW_SHELL=tui-local: ingesteld voor lokale TUI !-shellcommando’s.

Dit zijn runtime-markeringen (geen vereiste gebruikersconfiguratie). Ze kunnen worden gebruikt in shell-/profiellogica om contextspecifieke regels toe te passen.

UI-omgevingsvariabelen

OPENCLAW_THEME=light: forceer het lichte TUI-palet wanneer je terminal een lichte achtergrond heeft.
OPENCLAW_THEME=dark: forceer het donkere TUI-palet.
COLORFGBG: als je terminal dit exporteert, gebruikt OpenClaw de achtergrondkleurhint om automatisch het TUI-palet te kiezen.

Omgevingsvariabelen-substitutie in configuratie

Je kunt omgevingsvariabelen direct refereren in configuratie-stringwaarden met de ${VAR_NAME}-syntaxis:

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

Zie Configuratie: Omgevingsvariabelen-substitutie voor volledige details.

SecretRef vs `${ENV}`-strings

OpenClaw ondersteunt twee env-gebaseerde patronen:

${VAR}-stringsubstitutie in configuratiewaarden.
SecretRef-objecten ({ source: "env", provider: "default", id: "VAR" }) voor velden die secretreferenties ondersteunen.

Beide worden opgelost vanuit de procesomgeving op het moment van activering. SecretRef-details zijn gedocumenteerd in Secrets Management.

Padgerelateerde omgevingsvariabelen

Variabele	Doel
`OPENCLAW_HOME`	De homedirectory overschrijven die wordt gebruikt voor alle interne padresolutie (`~/.openclaw/`, agentdirectory’s, sessies, credentials). Handig wanneer OpenClaw als een dedicated servicegebruiker draait.
`OPENCLAW_STATE_DIR`	De statusdirectory overschrijven (standaard `~/.openclaw`).
`OPENCLAW_CONFIG_PATH`	Het configuratiebestandspad overschrijven (standaard `~/.openclaw/openclaw.json`).

Logging

Variabele	Doel
`OPENCLAW_LOG_LEVEL`	Logniveau overschrijven voor zowel bestand als console (bijv. `debug`, `trace`). Heeft voorrang op `logging.level` en `logging.consoleLevel` in de configuratie. Ongeldige waarden worden genegeerd met een waarschuwing.

`OPENCLAW_HOME`

Wanneer ingesteld, vervangt OPENCLAW_HOME de systeemhomedirectory ($HOME / os.homedir()) voor alle interne padresolutie. Dit maakt volledige bestandssysteem-isolatie mogelijk voor headless serviceaccounts.

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

Voorbeeld (macOS LaunchDaemon):

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

OPENCLAW_HOME kan ook worden ingesteld op een tildepad (bijv. ~/svc), dat wordt geexpandeerd met $HOME voor gebruik.