Configure OpenClaw Environment Variables: Quick Setup Guide

Ever spent way too much time debugging why an API key isn’t working, only to realize your environment variables didn’t load? It is a common headache when you switch between local shells and background services.

Let’s look at how OpenClaw handles your environment variables so you can get your setup working correctly.

How does OpenClaw load environment variables?

OpenClaw pulls variables from your parent process, like your shell or systemd. It also checks your local .env file and the global fallback at ~/.openclaw/.env. Finally, it looks at any inline variables you have defined in your configuration. These files will not overwrite variables that already exist in your environment.

You can define inline variables in your config like this:

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

“I started the Gateway via the service and my env vars disappeared.” What now?

If you run the Gateway as a service using launchd or systemd, it often won’t inherit your shell environment. You can fix this with these two options:

1. Put your missing keys in ~/.openclaw/.env so the service can find them even without your shell.

2. Enable the shell import feature:

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

This runs your login shell to import missing keys. It will never override existing ones. You can also use the environment variables OPENCLAW_LOAD_SHELL_ENV=1 and OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000.

I set COPILOT_GITHUB_TOKEN, but models status shows “Shell env: off.” Why?

The openclaw models status command tells you if the shell env import feature is active. Seeing “Shell env: off” just means OpenClaw isn’t automatically loading your login shell. It does not mean your variables are missing.

If your Gateway runs as a service, it won’t see your shell variables. You can fix this by following these steps:

1. Move your token to ~/.openclaw/.env.
2. Set env.shellEnv.enabled: true in your config.
3. Add the token directly to your config env block.
4. Restart your gateway to apply the changes.

Use these commands to restart and check your status:

openclaw gateway restart
openclaw models status

OpenClaw reads Copilot tokens from COPILOT_GITHUB_TOKEN, GH_TOKEN, or GITHUB_TOKEN.

---

Need more help with your configuration? Check out the AI Setup Assistant.

Next Steps

• Configuration Reference
• Gateway Setup Guide