Environment variables

OmeniaClaw pulls environment variables from multiple sources. The rule is never override existing values. Workspace .env files are a lower-trust source: OmeniaClaw ignores provider credentials and protected runtime controls from workspace .env before applying precedence.

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; provider credentials and protected runtime controls are ignored).
3. Global .env at ~/.OmeniaClaw/.env (aka $OmeniaClaw_STATE_DIR/.env; recommended for provider API keys; does not override).
4. Config env block in ~/.OmeniaClaw/OmeniaClaw.json (applied only if missing).
5. Optional login-shell import (env.shellEnv.enabled or OmeniaClaw_LOAD_SHELL_ENV=1), applied only for missing expected keys.

On Ubuntu fresh installs that use the default state dir, OmeniaClaw also treats ~/.config/OmeniaClaw/gateway.env as a compatibility fallback after the global .env. If both files exist and disagree, OmeniaClaw keeps ~/.OmeniaClaw/.env and prints a warning.

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

Provider credentials and workspace .env

Do not keep provider API keys only in a workspace .env. OmeniaClaw ignores provider credential environment variables from workspace .env files, including common keys 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, and FIRECRAWL_API_KEY.

Use one of these trusted sources for provider credentials:

• The Gateway process environment, such as a shell, launchd/systemd unit, container secret, or CI secret.
• The global runtime dotenv file at ~/.OmeniaClaw/.env or $OmeniaClaw_STATE_DIR/.env.
• The config env block in ~/.OmeniaClaw/OmeniaClaw.json.
• Optional login-shell import when env.shellEnv.enabled or OmeniaClaw_LOAD_SHELL_ENV=1 is enabled.

If you previously stored provider keys only in a workspace .env, move them to one of the trusted sources above. Workspace .env can still provide ordinary project variables that are not credentials, endpoint redirects, host overrides, or OmeniaClaw_* runtime controls.

See Workspace .env files for the security rationale.

Config env block

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

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

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

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

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.OmeniaClaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

See Secrets Management and the SecretRef credential surface for supported fields.

Shell env import

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

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

Env var equivalents:

• OmeniaClaw_LOAD_SHELL_ENV=1
• OmeniaClaw_SHELL_ENV_TIMEOUT_MS=15000

Exec shell snapshots

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

Runtime-injected env vars

OmeniaClaw also injects context markers into spawned child processes:

• OmeniaClaw_SHELL=exec: set for commands run through the exec tool.
• OmeniaClaw_SHELL=acp: set for ACP runtime backend process spawns (for example acpx).
• OmeniaClaw_SHELL=acp-client: set for OmeniaClaw acp client when it spawns the ACP bridge process.
• OmeniaClaw_SHELL=tui-local: set for local TUI ! shell commands.
• OmeniaClaw_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

• OmeniaClaw_THEME=light: force the light TUI palette when your terminal has a light background.
• OmeniaClaw_THEME=dark: force the dark TUI palette.
• COLORFGBG: if your terminal exports it, OmeniaClaw 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}",      },    },  },}

See Configuration: Env var substitution for full details.

Secret refs vs ${ENV} strings

OmeniaClaw 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

Logging

OmeniaClaw_HOME

When set, OmeniaClaw_HOME replaces the system home directory ($HOME / os.homedir()) for internal OmeniaClaw path defaults. This includes the default state directory, config path, agent directories, credentials, installer onboarding workspace, and the default dev checkout used by OmeniaClaw update --channel dev.

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

Example (macOS LaunchDaemon):

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

OmeniaClaw_HOME can also be set to a tilde path (e.g. ~/svc), which gets expanded using the same OS home fallback chain before use.

Explicit path variables such as OmeniaClaw_STATE_DIR, OmeniaClaw_CONFIG_PATH, and OmeniaClaw_GIT_DIR still take precedence. OS-account tasks such as shell startup file detection, package-manager setup, and host ~ expansion may still use the real system home.

nvm users: web_fetch TLS failures

If Node.js was installed via nvm (not the system package manager), the built-in fetch() 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 web_fetch to fail with "fetch failed" on most HTTPS sites.

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

• OmeniaClaw gateway install writes NODE_EXTRA_CA_CERTS into the systemd service environment
• the OmeniaClaw CLI entrypoint re-execs itself with NODE_EXTRA_CA_CERTS set before Node startup

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

Export the variable before starting OmeniaClaw:

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

Do not rely on writing only to ~/.OmeniaClaw/.env for this variable; Node reads NODE_EXTRA_CA_CERTS at process startup.

Legacy environment variables

OmeniaClaw only reads OmeniaClaw_* environment variables. The legacy CLAWDBOT_* and MOLTBOT_* prefixes from earlier releases are silently ignored.

If any are still set on the Gateway process at startup, OmeniaClaw emits a single Node deprecation warning (OmeniaClaw_LEGACY_ENV_VARS) listing the detected prefixes and the total count. Rename each value by replacing the legacy prefix with OmeniaClaw_ (for example CLAWDBOT_GATEWAY_TOKEN → OmeniaClaw_GATEWAY_TOKEN); the old names take no effect.

Related

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