Files

Sebastian a36735b913 feat(config): add env var substitution in config values

Support ${VAR_NAME} syntax in any config string value, substituted at
config load time. Useful for referencing API keys and secrets from
environment variables without hardcoding them in the config file.

- Only uppercase env vars matched: [A-Z_][A-Z0-9_]*
- Missing/empty env vars throw MissingEnvVarError with path context
- Escape with $${VAR} to output literal ${VAR}
- Works with $include (included files also get substitution)

Closes #1009

2026-01-16 16:32:07 -05:00

2.0 KiB

Raw Blame History

summary, read_when

summary

read_when

Where Clawdbot loads environment variables and the precedence order

You need to know which env vars are loaded, and in what order

You are debugging missing API keys in the Gateway

You are documenting provider auth or deployment environments

Environment variables

Clawdbot 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).
.env in the current working directory (dotenv default; does not override).
Global .env at ~/.clawdbot/.env (aka $CLAWDBOT_STATE_DIR/.env; does not override).
Config env block in ~/.clawdbot/clawdbot.json (applied only if missing).
Optional login-shell import (env.shellEnv.enabled or CLAWDBOT_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):

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

Shell env import

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

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

Env var equivalents:

CLAWDBOT_LOAD_SHELL_ENV=1
CLAWDBOT_SHELL_ENV_TIMEOUT_MS=15000

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.

2.0 KiB Raw Blame History