Environment variables

OpenClaw pulls environment variables from multiple sources. The rule is never override existing values.

Precedence (highest → lowest)

1. Process environment (what the Gateway process already has from the parent shell/daemon).
2. text

   Copy

   .env
   in the current working directory (dotenv default; does not override).
3. Global
   text

   Copy

   .env
   at
   text

   Copy

   ~/.openclaw/.env
   (aka
   text

   Copy

   $OPENCLAW_STATE_DIR/.env
   ; does not override).
4. Config
   text

   Copy

   env
   block in
   text

   Copy

   ~/.openclaw/openclaw.json
   (applied only if missing).
5. Optional login-shell import (
   text

   Copy

   env.shellEnv.enabled
   or
   text

   Copy

   OPENCLAW_LOAD_SHELL_ENV=1
   ), applied only for missing expected keys.

On Ubuntu fresh installs that use the default state dir, OpenClaw also treats

as a compatibility fallback after the global . If both files exist and disagree, OpenClaw keeps and prints a warning.

If the config file is missing entirely, step 4 is skipped; shell import still runs if enabled.

Config

text

Copy

env

block

Two equivalent ways to set inline env vars (both are non-overriding):

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

Shell env import

runs your login shell and imports only missing expected keys:

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

Env var equivalents:

• text

  Copy

  OPENCLAW_LOAD_SHELL_ENV=1
• text

  Copy

  OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Runtime-injected env vars

OpenClaw also injects context markers into spawned child processes:

• text

  Copy

  OPENCLAW_SHELL=exec
  : set for commands run through the
  text

  Copy

  exec
  tool.
• text

  Copy

  OPENCLAW_SHELL=acp
  : set for ACP runtime backend process spawns (for example
  text

  Copy

  acpx
  ).
• text

  Copy

  OPENCLAW_SHELL=acp-client
  : set for
  text

  Copy

  openclaw acp client
  when it spawns the ACP bridge process.
• text

  Copy

  OPENCLAW_SHELL=tui-local
  : set for local TUI
  text

  Copy

  !
  shell commands.

These are runtime markers (not required user config). They can be used in shell/profile logic to apply context-specific rules.

UI env vars

• text

  Copy

  OPENCLAW_THEME=light
  : force the light TUI palette when your terminal has a light background.
• text

  Copy

  OPENCLAW_THEME=dark
  : force the dark TUI palette.
• text

  Copy

  COLORFGBG
  : if your terminal exports it, OpenClaw uses the background color hint to auto-pick the TUI palette.

Env var substitution in config

You can reference env vars directly in config string values using

syntax:

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

See Configuration: Env var substitution for full details.

Secret refs vs

text

Copy

${ENV}

strings

OpenClaw supports two env-driven patterns:

• text

  Copy

  ${VAR}
  string substitution in config values.
• SecretRef objects (
  text

  Copy

  { source: "env", provider: "default", id: "VAR" }
  ) for fields that support secrets references.

Both resolve from process env at activation time. SecretRef details are documented in Secrets Management.

Path-related env vars

Logging

text

Copy

OPENCLAW_HOME

When set,

replaces the system home directory ( / ) for all internal path resolution. This enables full filesystem isolation for headless service accounts.

Precedence:

> > >

Example (macOS LaunchDaemon):

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

can also be set to a tilde path (e.g. ), which gets expanded using before use.

nvm users: web_fetch TLS failures

If Node.js was installed via nvm (not the system package manager), the built-in

uses nvm's bundled CA store, which may be missing modern root CAs (ISRG Root X1/X2 for Let's Encrypt, DigiCert Global Root G2, etc.). This causes to fail with on most HTTPS sites.

On Linux, OpenClaw automatically detects nvm and applies the fix in the actual startup environment:

• text

  Copy

  openclaw gateway install
  writes
  text

  Copy

  NODE_EXTRA_CA_CERTS
  into the systemd service environment
• the
  text

  Copy

  openclaw
  CLI entrypoint re-execs itself with
  text

  Copy

  NODE_EXTRA_CA_CERTS
  set before Node startup

Manual fix (for older versions or direct

launches):

Export the variable before starting OpenClaw:

bash
Copy
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
openclaw gateway run

Do not rely on writing only to

for this variable; Node reads at process startup.

Legacy environment variables

OpenClaw only reads

environment variables. The legacy and prefixes from earlier releases are silently ignored.

If any are still set on the Gateway process at startup, OpenClaw emits a single Node deprecation warning (

) listing the detected prefixes and the total count. Rename each value by replacing the legacy prefix with (for example → ); the old names take no effect.

Related

• Gateway configuration
• FAQ: env vars and .env loading
• Models overview