# Env vars and .env loading

> How OpenClaw loads environment variables and why service starts lose them

- 网址：https://funcoding.ai/agents/openclaw/help/faq/env-vars/
- 来源：OpenClaw 官方文档原文（英文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/help/faq/env-vars

---
## Env vars and .env loading

<details>
<summary>How does OpenClaw load environment variables?</summary>

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
{
  env: {
    vars: {
      OPENROUTER_API_KEY: "sk-or-...",
      GROQ_API_KEY: "gsk-...",
    },
  },
}
```

See [/environment](https://funcoding.ai/agents/openclaw/help/environment/) for full precedence and sources.

</details>

<details>
<summary>I started the Gateway via the service and my env vars disappeared. What now?</summary>

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
   {
     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`.

</details>

<details>
<summary>I set COPILOT_GITHUB_TOKEN, but models status shows "Shell env: off." Why?</summary>

`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
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://funcoding.ai/agents/openclaw/concepts/model-providers/) and [/environment](https://funcoding.ai/agents/openclaw/help/environment/).

</details>