{
  "title": "Environment variables",
  "content": "OpenClaw pulls environment variables from multiple sources. The rule is **never override existing values**.\n\n## Precedence (highest → lowest)\n\n1. **Process environment** (what the Gateway process already has from the parent shell/daemon).\n2. **`.env` in the current working directory** (dotenv default; does not override).\n3. **Global `.env`** at `~/.openclaw/.env` (aka `$OPENCLAW_STATE_DIR/.env`; does not override).\n4. **Config `env` block** in `~/.openclaw/openclaw.json` (applied only if missing).\n5. **Optional login-shell import** (`env.shellEnv.enabled` or `OPENCLAW_LOAD_SHELL_ENV=1`), applied only for missing expected keys.\n\nIf the config file is missing entirely, step 4 is skipped; shell import still runs if enabled.\n\n## Config `env` block\n\nTwo equivalent ways to set inline env vars (both are non-overriding):\n\n`env.shellEnv` runs your login shell and imports only **missing** expected keys:\n\n* `OPENCLAW_LOAD_SHELL_ENV=1`\n* `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`\n\n## Env var substitution in config\n\nYou can reference env vars directly in config string values using `${VAR_NAME}` syntax:\n\nSee [Configuration: Env var substitution](/gateway/configuration#env-var-substitution-in-config) for full details.\n\n* [Gateway configuration](/gateway/configuration)\n* [FAQ: env vars and .env loading](/help/faq#env-vars-and-env-loading)\n* [Models overview](/concepts/models)",
  "code_samples": [
    {
      "code": "## Shell env import\n\n`env.shellEnv` runs your login shell and imports only **missing** expected keys:",
      "language": "unknown"
    },
    {
      "code": "Env var equivalents:\n\n* `OPENCLAW_LOAD_SHELL_ENV=1`\n* `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`\n\n## Env var substitution in config\n\nYou can reference env vars directly in config string values using `${VAR_NAME}` syntax:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Precedence (highest → lowest)",
      "id": "precedence-(highest-→-lowest)"
    },
    {
      "level": "h2",
      "text": "Config `env` block",
      "id": "config-`env`-block"
    },
    {
      "level": "h2",
      "text": "Shell env import",
      "id": "shell-env-import"
    },
    {
      "level": "h2",
      "text": "Env var substitution in config",
      "id": "env-var-substitution-in-config"
    },
    {
      "level": "h2",
      "text": "Related",
      "id": "related"
    }
  ],
  "url": "llms-txt#environment-variables",
  "links": []
}