Skip to main content

Environment variables

WednesdayAI 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. .env in the current working directory (dotenv default; does not override).
  3. Global .env at ~/.openclaw/.env (aka $OPENCLAW_STATE_DIR/.env; does not override).
  4. Config env block in ~/.openclaw/openclaw.json (applied only if missing).
  5. Optional login-shell import (env.shellEnv.enabled or OPENCLAW_LOAD_SHELL_ENV=1), applied only for missing expected keys.
If the config file is missing entirely, step 4 is skipped; shell import still runs if enabled.

Config env block

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

Shell env import

env.shellEnv runs your login shell and imports only missing expected keys:
Env var equivalents:
  • OPENCLAW_LOAD_SHELL_ENV=1
  • OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Runtime-injected env vars

WednesdayAI also injects context markers into spawned child processes:
  • OPENCLAW_SHELL=exec: set for commands run through the exec tool.
  • OPENCLAW_SHELL=acp: set for ACP runtime backend process spawns (for example acpx).
  • OPENCLAW_SHELL=acp-client: set for wednesdayai acp client when it spawns the ACP bridge process.
  • OPENCLAW_SHELL=tui-local: set for local TUI ! shell commands.
These are runtime markers (not required user config). They can be used in shell/profile logic to apply context-specific rules.

Env var substitution in config

You can reference env vars directly in config string values using ${VAR_NAME} syntax:
See Configuration: Env var substitution for full details.

Secret refs vs ${ENV} strings

WednesdayAI 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.

Logging

Media understanding provider keys

Audio transcription, image description and video understanding providers ship as extensions that are disabled by default. Enabling one is not enough on its own; it also needs a credential. Each provider reads its own variable: A provider whose key resolves nowhere is skipped during auto-detection rather than attempted, so a missing key looks like the provider was never tried. Third-party provider extensions declare their own variables the same way. Full resolution order and troubleshooting: Media understanding.

Plugin and skill catalogs

OPENCLAW_CATALOG_REMOTE=0 disables all remote catalog fetching, plugins and skills alike; each feed then falls back to its bundled offline snapshot. Catalog feeds cache in memory for the TTL and fail open on any fetch error.

OPENCLAW_HOME

When set, OPENCLAW_HOME replaces the system home directory ($HOME / os.homedir()) for all internal path resolution. This enables full filesystem isolation for headless service accounts. Precedence: OPENCLAW_HOME > $HOME > USERPROFILE > os.homedir() Example (macOS LaunchDaemon):
OPENCLAW_HOME can also be set to a tilde path (e.g. ~/svc), which gets expanded using $HOME before use.