> ## 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.

# Env vars and .env loading

## Env vars and .env loading

> **How does OpenClaw load environment variables?**
>
> OpenClaw reads env vars from the parent process (shell, launchd/systemd, CI, etc.) and additionally loads:
>
> * `.env` from the current working directory.
> * a global fallback `.env` from `~/.openclaw/.env` (`$OPENCLAW_STATE_DIR/.env`).
>
> Normally, neither `.env` file overrides existing env vars. For an OpenClaw-installed systemd service, the global `.env` may replace only service values that OpenClaw recorded as managed; operator-owned service values still take precedence. Provider credential and endpoint-routing keys are an exception for workspace `.env`: keys such as `GEMINI_API_KEY`, `XAI_API_KEY`, `MISTRAL_API_KEY`, or any key ending in `_ENDPOINT` (and other bundled-provider auth or endpoint env vars) are ignored from workspace `.env` and should live in the process environment, `~/.openclaw/.env`, or config `env.vars`.
>
> Inline env vars in config apply only if missing from the process env:
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   env: {
>     vars: {
>       OPENROUTER_API_KEY: "sk-or-...",
>       GROQ_API_KEY: "gsk-...",
>     },
>   },
> }
> ```
>
> See [/environment](https://docs2.openclaw.ai/help/environment.md) for full precedence and sources.

> **I started the Gateway via the service and my env vars disappeared. What now?**
>
> Two fixes:
>
> 1. Put the missing keys in `~/.openclaw/.env` so they load even when the service does not inherit your shell env.
> 2. Enable shell import (opt-in convenience):
>    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
>    {
>      env: {
>        shellEnv: {
>          enabled: true,
>          timeoutMs: 15000,
>        },
>      },
>    }
>    ```
>    This runs your login shell and imports only missing expected keys (never overrides). Env var equivalents: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`.

> **I set COPILOT\_GITHUB\_TOKEN, but models status shows "Shell env: off." Why?**
>
> `openclaw models status` reports whether **shell env import** is enabled. "Shell env: off" does **not** mean your env vars are missing - it just means OpenClaw will not load your login shell automatically.
>
> If the Gateway runs as a service (launchd/systemd), it will not inherit your shell environment. Fix by putting the token in `~/.openclaw/.env`, enabling `env.shellEnv.enabled: true`, or adding it to config `env` (applies only if missing), then restarting the gateway and rechecking:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw models status
> ```
>
> Copilot activates only with an explicit `models.providers.github-copilot` entry, a saved Copilot auth profile, or `COPILOT_GITHUB_TOKEN`. Generic `GH_TOKEN` and `GITHUB_TOKEN` variables do not enable or authenticate Copilot. Run `openclaw models auth login --provider github-copilot` to sign in.
>
> See [/concepts/model-providers](https://docs2.openclaw.ai/concepts/model-providers.md) and [/environment](https://docs2.openclaw.ai/help/environment.md).