Environment Variables: Sources and Precedence Order

OpenClaw gathers environment variables from a variety of locations. The primary guideline is never overwrite existing values. For a systemd service installed by OpenClaw, the global .env can only override service values that OpenClaw itself marked as managed; any service values set by the operator continue to take priority. Workspace .env files are considered a less trusted source: before precedence rules are applied, OpenClaw discards provider credentials and protected runtime controls from workspace .env.

Precedence (highest to lowest)

1. Process environment (the variables already present in the Gateway process, inherited from the parent shell or daemon).
2. .env in the current working directory (the dotenv default; does not override; provider credentials and protected runtime controls are ignored).
3. Global .env located at ~/.openclaw/.env (also known as $OPENCLAW_STATE_DIR/.env; suggested for provider API keys; does not override, except for recorded OpenClaw-managed systemd service values).
4. Config env block within ~/.openclaw/openclaw.json (only applied when the value is absent).
5. Optional login-shell import (env.shellEnv.enabled or OPENCLAW_LOAD_SHELL_ENV=1), applied only for expected keys that are missing.

On fresh Ubuntu installations using the default state directory, OpenClaw also treats ~/.config/openclaw/gateway.env as a compatibility fallback after the global .env. When both files exist but conflict, ~/.openclaw/.env is kept by OpenClaw and a warning is emitted.

If the config file is absent entirely, step 4 is skipped; shell import still executes when enabled.

Supported operator-facing variables

The following variables form the supported environment contract for operators. Undocumented OPENCLAW_* variables are internal implementation details and can be removed without any notice.

Paths and instances

Gateway and authentication

Provider credentials

Core and bundled provider plugins recognize the following credential and provider-selection variables. When scoped credentials are needed rather than a single process-wide value, prefer each provider's 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 you install may add their own credential variables through their manifests. Those variables belong to the plugin that declares them, not to OpenClaw itself.

Logging and diagnostics

Feature and runtime toggles

Provider credentials and workspace .env

Avoid keeping provider API keys solely in a workspace .env. OpenClaw refuses a broad range of provider credential and endpoint-redirect keys from workspace .env files, covering every known provider auth env var (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), as well as any key that ends in _API_HOST, _BASE_URL, _ENDPOINT, or _HOMESERVER, and the complete OPENCLAW_*, CLAWHUB_*, ANTHROPIC_API_KEY_*, and OPENAI_API_KEY_* namespaces.

Instead, get provider credentials from one of these trusted places:

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

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

The security rationale is covered in Workspace .env files.

Config env block

Inline environment variables are set under env.vars (these values do not override others):

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

The config env.vars block accepts only 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 that string.

For provider keys backed by files, 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" },
      },
    },
  },
}

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

Shell env import

env.shellEnv launches 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 (defaults to 15000)

With Bash, the import relies on an interactive login shell (bash -lic) so that PS1 gets initialized before login startup files execute. Bash reads /etc/profile plus the first available user login profile (~/.bash_profile, ~/.bash_login, or ~/.profile); many login profiles also source ~/.bashrc. Keep those files quiet and bounded because their output, long-running work, or failures can impact OpenClaw startup. Other shells use noninteractive login startup (-l -c). This interactive Bash mode applies only to explicit shell env imports; automatic executable PATH discovery during normal Gateway commands stays noninteractive.

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 turn off this path. 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 adds context markers to spawned child processes:

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

These are runtime markers, not required user config. They can be used in shell/profile logic to apply 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 auto-pick the TUI palette.

Env var substitution in config

You can reference env vars directly in config string values using ${VAR_NAME} syntax:

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

A missing or empty variable remains visible as ${VAR_NAME} and emits a warning. Consumers that require the value treat it as unavailable. Use $${VAR_NAME} when the literal ${VAR_NAME} text is intended.

See Configuration: Env var substitution for full details.

Secret refs vs ${ENV} strings

OpenClaw supports two env-driven patterns:

• ${VAR} string substitution in config values.
• SecretRef objects ({ 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. The config env block itself does not resolve SecretRefs or file:... shorthand values.

Path-related env vars

Agent helper tool downloads

Assign OPENCLAW_OFFLINE=1 to stop OpenClaw from fetching its pinned fd and ripgrep helper binaries. Helpers already present under the OpenClaw tools directory and working system binaries are still usable; a helper that is absent remains unavailable rather than prompting a network fetch.

Logging

OPENCLAW_HOME

When this is set, OPENCLAW_HOME swaps in a different home directory (replacing $HOME / os.homedir()) for OpenClaw's internal path defaults. That includes the default state directory, config path, agent directories, credentials, installer onboarding workspace, and the default dev checkout that openclaw update --channel dev relies on.

OPENCLAW_HOME does not give you control over the OS account's native Gateway service. Gateway service-management commands treat a relocated home as isolated state; use the OS account home plus a named profile when you need a separate native service identity.

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>

A tilde path (e.g. ~/svc) is also valid for OPENCLAW_HOME, and it gets expanded through the same OS home fallback chain before use.

Explicit path variables like OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, and OPENCLAW_GIT_DIR still win. OS-account tasks, including shell startup file detection, package-manager setup, and host ~ expansion, may still reference the real system home.

nvm users: web_fetch TLS failures

When Node.js came from nvm rather than the system package manager, the built-in fetch() picks up nvm's bundled CA store, which can lack modern root CAs (ISRG Root X1/X2 for Let's Encrypt, DigiCert Global Root G2, and others). As a result, web_fetch fails with "fetch failed" on most HTTPS sites.

On Linux, OpenClaw spots nvm automatically and applies the fix in the real startup environment:

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

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

Export the variable before launching OpenClaw:

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

Do not depend on ~/.openclaw/.env alone when setting this variable, since Node checks NODE_EXTRA_CA_CERTS during startup.

Legacy environment variables

Environment variables with the OPENCLAW_* prefix are the only ones OpenClaw recognizes. Any variables using the older CLAWDBOT_* or MOLTBOT_* prefixes from previous versions are disregarded without notice.

When the Gateway process starts, if any of those legacy variables remain set, OpenClaw triggers a single Node deprecation warning (OPENCLAW_LEGACY_ENV_VARS) that reports the prefixes it found and how many there are. To fix this, swap each legacy prefix for OPENCLAW_ (for instance, change CLAWDBOT_GATEWAY_TOKEN into OPENCLAW_GATEWAY_TOKEN); the outdated names have no effect.

Related

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