> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables

## Environment variables

OpenClaw reads env vars from the parent process plus:

* `.env` from the current working directory (if present)
* `~/.openclaw/.env` (global fallback)

Neither file overrides existing env vars. You can also set inline env vars in config:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  env: {
    vars: {
      OPENROUTER_API_KEY: "sk-or-...",
      GROQ_API_KEY: "gsk-...",
    },
  },
}
```

> **Shell env import (optional)**
>
> If enabled and expected keys aren't set, OpenClaw runs your login shell and imports only the missing keys:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   env: {
>     shellEnv: { enabled: true, timeoutMs: 15000 },
>   },
> }
> ```
>
> Env var equivalent: `OPENCLAW_LOAD_SHELL_ENV=1`. Default `timeoutMs`: `15000`.

> **Env var substitution in config values**
>
> Reference env vars in any config string value with `${VAR_NAME}`:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
>   models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
> }
> ```
>
> Rules:
>
> * Only uppercase names matched: `[A-Z_][A-Z0-9_]*`
> * Missing/empty vars stay visibly unresolved, emit a warning, and are unavailable to consumers that require the value
> * Escape with `$${VAR}` to produce a literal `${VAR}` value
> * Works inside `$include` files
> * Inline substitution: `"${BASE}/v1"` → `"https://api.example.com/v1"`

> **Secret refs (env, file, exec, store)**
>
> For fields that support SecretRef objects, you can use:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   models: {
>     providers: {
>       openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
>     },
>   },
>   skills: {
>     entries: {
>       "image-lab": {
>         apiKey: {
>           source: "file",
>           provider: "filemain",
>           id: "/skills/entries/image-lab/apiKey",
>         },
>       },
>     },
>   },
>   channels: {
>     googlechat: {
>       serviceAccount: {
>         source: "exec",
>         provider: "vault",
>         id: "channels/googlechat/serviceAccount",
>       },
>     },
>   },
> }
> ```
>
> The `env` ref above uses the built-in `default` provider and needs no `secrets.providers.default` entry unless `secrets.defaults.env` selects another alias. The same rule applies to `store` refs and `secrets.defaults.store`. See [Secrets Management](https://docs2.openclaw.ai/gateway/secrets.md#secretref-contract) for provider precedence and the required `file`/`exec` provider configuration.
> Supported credential paths are listed in [SecretRef Credential Surface](https://docs2.openclaw.ai/reference/secretref-credential-surface.md).

See [Environment](https://docs2.openclaw.ai/help/environment.md) for full precedence and sources.