OpenClaw Environment Variables: Sources and Precedence Order

OpenClaw gathers environment variables from several origins, following the principle of never overwriting an already set value.
Workspace .env files are considered less trustworthy: before applying precedence, OpenClaw discards provider credentials and protected runtime controls that originate from workspace .env.

Precedence (highest to lowest)

1. Process environment (the variables the Gateway process inherits from its parent shell or daemon).
2. .env in the current working directory (the default dotenv file; does not overwrite; provider credentials and protected runtime controls are excluded).
3. Global .env at ~/.openclaw/.env (also referred to as $OPENCLAW_STATE_DIR/.env; intended for provider API keys; does not overwrite).
4. Config env block inside ~/.openclaw/openclaw.json (applied only when the key is absent).
5. Optional login-shell import (env.shellEnv.enabled or OPENCLAW_LOAD_SHELL_ENV=1), used only for expected keys that are missing.

On a fresh Ubuntu installation using the default state directory, OpenClaw additionally treats ~/.config/openclaw/gateway.env as a compatibility fallback after the global .env. If both files exist and conflict, OpenClaw retains ~/.openclaw/.env and emits a warning.

When the config file is absent entirely, step 4 is omitted; shell import still runs if it has been enabled.

Supported operator-facing variables

The table below defines the supported environment contract for operators. Any undocumented OPENCLAW_* variables are internal implementation details and may be removed without notice.

Paths and instances

Gateway and authentication

Provider credentials

Core and bundled provider plugins recognize the credential and provider-selection variables listed below. When you need credentials scoped to a single provider rather than a process-wide value, prefer that provider’s own config or SecretRef fields.

AI_GATEWAY_API_KEY, ANTHROPIC_ADMIN_API_KEY, ANTHROPIC_ADMIN_KEY, ANTHROPIC_API_KEY, ANTHROPIC_OAUTH_TOKEN, ARCEEAI_API_KEY, AZURE_OPENAI_API_KEY, AZURE_SPEECH_API_KEY, AZURE_SPEECH_KEY, AZURE_SPEECH_REGION, BASETEN_API_KEY, BRAVE_API_KEY, BYTEPLUS_API_KEY, BYTEPLUS_SEED_SPEECH_API_KEY, CEREBRAS_API_KEY, CHUTES_API_KEY, CHUTES_OAUTH_TOKEN, CLAWROUTER_API_KEY, CLOUDFLARE_AI_GATEWAY_API_KEY, CODEX_API_KEY, COHERE_API_KEY, COMFY_API_KEY, COMFY_CLOUD_API_KEY, COPILOT_GITHUB_TOKEN, DASHSCOPE_API_KEY, DEEPGRAM_API_KEY, DEEPINFRA_API_KEY, DEEPSEEK_API_KEY, ELEVENLABS_API_KEY, EXA_API_KEY, FAL_API_KEY, FAL_KEY, FEATHERLESS_API_KEY, FIRECRAWL_API_KEY, FIREWORKS_API_KEY, GCLOUD_PROJECT, GEMINI_API_KEY, GH_TOKEN, GITHUB_TOKEN, GMI_API_KEY, GOOGLE_API_KEY, GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CLOUD_API_KEY, GOOGLE_CLOUD_LOCATION, GOOGLE_CLOUD_PROJECT, GRADIUM_API_KEY, GROQ_API_KEY, HF_TOKEN, HUGGINGFACE_HUB_TOKEN, INWORLD_API_KEY, KILOCODE_API_KEY, KIMICODE_API_KEY, KIMI_API_KEY, LITELLM_API_KEY, LM_API_TOKEN, LONGCAT_API_KEY, MINIMAX_API_KEY, MINIMAX_CODE_PLAN_KEY, MINIMAX_CODING_API_KEY, MINIMAX_OAUTH_TOKEN, MISTRAL_API_KEY, MODELSTUDIO_API_KEY, MODEL_API_KEY, MOONSHOT_API_KEY, NOVITA_API_KEY, NVIDIA_API_KEY, OLLAMA_API_KEY, OPENAI_ADMIN_KEY, OPENAI_API_KEY, OPENCODE_API_KEY, OPENCODE_ZEN_API_KEY, OPENROUTER_API_KEY, PARALLEL_API_KEY, PERPLEXITY_API_KEY, PIXVERSE_API_KEY, QIANFAN_API_KEY, QWEN_API_KEY, QWEN_TOKEN_PLAN_API_KEY, RUNWAYML_API_SECRET, RUNWAY_API_KEY, SENSEAUDIO_API_KEY, SGLANG_API_KEY, SPEECH_KEY, SPEECH_REGION, STEPFUN_API_KEY, SYNTHETIC_API_KEY, TAVILY_API_KEY, TOGETHER_API_KEY, TOKENHUB_API_KEY, TOKENPLAN_API_KEY, VENICE_API_KEY, VLLM_API_KEY, VOLCANO_ENGINE_API_KEY, VOLCENGINE_TTS_API_KEY, VOLCENGINE_TTS_APPID, VOLCENGINE_TTS_TOKEN, VOYAGE_API_KEY, VYDRA_API_KEY, XAI_API_KEY, XIAOMI_API_KEY, XIAOMI_TOKEN_PLAN_API_KEY, XI_API_KEY, ZAI_API_KEY, and Z_AI_API_KEY.

Third party plugins that have been installed can introduce extra credential variables through their plugin manifests. These variables belong to the plugin that declares them and are not part of the core OpenClaw environment.

Logging and diagnostics

Feature and runtime toggles

Provider credentials and workspace .env

Provider API keys should not be stored solely in a workspace .env. OpenClaw blocks a wide range of provider credential and endpoint redirect keys from workspace .env files. This includes every known provider authentication environment variable (such as 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), any key that ends with _API_HOST, _BASE_URL, _ENDPOINT, or _HOMESERVER, and the complete OPENCLAW_*, CLAWHUB_*, ANTHROPIC_API_KEY_*, and OPENAI_API_KEY_* namespaces.

Instead, rely on one of these trusted sources for provider credentials:

• The Gateway process environment, for example a shell, launchd or systemd unit, container secret, or CI secret.
• The global runtime dotenv file located at ~/.openclaw/.env or $OPENCLAW_STATE_DIR/.env.
• The env configuration block inside ~/.openclaw/openclaw.json.
• An optional login shell import when env.shellEnv.enabled or OPENCLAW_LOAD_SHELL_ENV=1 is enabled.

If you previously kept provider keys or endpoint routing values only inside a workspace .env, relocate them into one of the trusted sources listed above. A workspace .env can still hold ordinary project variables that are not credentials, endpoint redirects, host overrides, or OPENCLAW_* runtime controls.

For the security reasoning, refer to Workspace .env files.

Config env block

Two equivalent approaches exist for setting inline environment variables, neither of which overrides existing values:

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

The config env block only accepts literal string values. It does not expand file:... values; for instance, XAI_API_KEY: "file:secrets/xai-api-key.txt" is handed to providers exactly as written.

For provider keys backed by a file, use a SecretRef on the credential field that supports it:

{
  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" },
      },
    },
  },
}

Check Secrets Management and the SecretRef credential surface for the list of supported fields.

Shell env import

env.shellEnv runs your login shell and imports only missing expected keys:

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

Environment variable equivalents:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000 (default 15000)

Exec shell snapshots

On non-Windows Gateway hosts, bash and zsh exec commands use a startup snapshot by default. Set OPENCLAW_EXEC_SHELL_SNAPSHOT=0 in the Gateway process environment to disable this behavior. Values false, no, and off also turn it off. Per-call exec.env values cannot enable or disable snapshots or redirect the snapshot cache.

Runtime-injected env vars

OpenClaw also injects context markers into spawned child processes:

• OPENCLAW_SHELL=exec: set for commands executed through the exec tool.
• OPENCLAW_SHELL=acp-client: set for openclaw acp client when it launches the ACP bridge process.
• OPENCLAW_SHELL=tui-local: set for local TUI ! shell commands.
• OPENCLAW_CLI=1: set for child processes started by the CLI entry point.

These are runtime markers, not required user configuration. They can be used in shell or profile logic to enforce context-specific rules.

UI env vars

• OPENCLAW_THEME=light: force the light TUI palette when your terminal has a light background.
• OPENCLAW_THEME=dark: force the dark TUI palette.
• COLORFGBG: if your terminal exports it, OpenClaw uses the background color hint to automatically select the TUI palette.

Env var substitution in config

You can reference environment variables directly in config string values with ${VAR_NAME} syntax:

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

See Configuration: Env var substitution for complete details.

Secret refs vs ${ENV} strings

OpenClaw supports two environment-driven patterns:

• ${VAR} string substitution in config values.
• SecretRef objects ({ source: "env", provider: "default", id: "VAR" }) for fields that support secret references.

Both resolve from the process environment at activation time. SecretRef details are documented in Secrets Management. The config env block itself does not resolve SecretRefs or file:... shorthand values.

Path-related env vars

Agent helper tool downloads

Setting OPENCLAW_OFFLINE=1 stops OpenClaw from fetching its pinned fd and ripgrep helper binaries. Helpers already present in the OpenClaw tools directory and working system binaries continue to function, but any missing helper will stay absent instead of initiating a network download.

Logging

OPENCLAW_HOME

When enabled, OPENCLAW_HOME substitutes the system home directory ($HOME / os.homedir()) for OpenClaw's internal default paths. This covers the default state directory, config path, agent directories, credentials, installer onboarding workspace, and the default dev checkout used by openclaw update --channel dev.

Precedence: OPENCLAW_HOME > $HOME > USERPROFILE > Termux PREFIX home fallback on Android > os.homedir()

Example (macOS LaunchDaemon):

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

OPENCLAW_HOME can also accept a tilde path (for instance, ~/svc), which is expanded using the same OS home fallback chain before being used.

Explicit path variables like OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, and OPENCLAW_GIT_DIR still take priority. OS account operations such as shell startup file detection, package manager setup, and host ~ expansion may still reference the actual system home.

nvm users: web_fetch TLS failures

If Node.js was installed through nvm rather than the system package manager, the built-in fetch() uses nvm's bundled CA store, which might lack modern root CAs (ISRG Root X1/X2 for Let's Encrypt, DigiCert Global Root G2, and others). This causes web_fetch to fail with "fetch failed" on most HTTPS sites.

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

• openclaw gateway install writes NODE_EXTRA_CA_CERTS into the systemd service environment
• the openclaw CLI entrypoint re-executes itself with NODE_EXTRA_CA_CERTS set before Node starts

Manual fix (for older versions or direct node ... launches):

Export the variable before starting OpenClaw:

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

Do not rely on setting only ~/.openclaw/.env for this variable; Node reads NODE_EXTRA_CA_CERTS at process startup.

Legacy environment variables

OpenClaw only processes OPENCLAW_* environment variables. The legacy CLAWDBOT_* and MOLTBOT_* prefixes from earlier releases are silently disregarded.

If any legacy prefixes are still set on the Gateway process at startup, OpenClaw emits a single Node deprecation warning (OPENCLAW_LEGACY_ENV_VARS) listing the detected prefixes and their total count. Rename each value by replacing the legacy prefix with OPENCLAW_ (for example, change CLAWDBOT_GATEWAY_TOKEN to OPENCLAW_GATEWAY_TOKEN); the old names have no effect.

Related

• Configuring the gateway
• FAQ: environment variables and .env file loading
• Models reference