Environment variables
WednesdayAI pulls environment variables from multiple sources. The rule is never override existing values.Precedence (highest → lowest)
- Process environment (what the Gateway process already has from the parent shell/daemon).
.envin the current working directory (dotenv default; does not override).- Global
.envat~/.openclaw/.env(aka$OPENCLAW_STATE_DIR/.env; does not override). - Config
envblock in~/.openclaw/openclaw.json(applied only if missing). - Optional login-shell import (
env.shellEnv.enabledorOPENCLAW_LOAD_SHELL_ENV=1), applied only for missing expected keys.
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:
OPENCLAW_LOAD_SHELL_ENV=1OPENCLAW_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 theexectool.OPENCLAW_SHELL=acp: set for ACP runtime backend process spawns (for exampleacpx).OPENCLAW_SHELL=acp-client: set forwednesdayai acp clientwhen it spawns the ACP bridge process.OPENCLAW_SHELL=tui-local: set for local TUI!shell commands.
Env var substitution in config
You can reference env vars directly in config string values using${VAR_NAME} syntax:
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.
Path-related env vars
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.