Files

Peter Steinberger cfdd5a8c2e docs: consolidate faq under help

2026-01-24 09:49:38 +00:00

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.

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

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

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

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

Env var equivalents:

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

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