How OpenClaw Handles Environment Variables

Managing API keys and paths across different environments is often a headache. I have spent too much time debugging why a service isn’t picking up a key or why it is looking in the wrong directory. It is frustrating when a tool overwrites a variable you set manually in your shell. OpenClaw handles this by following a strict “never override” rule, which makes your setup predictable.

What You’ll Need

• OpenClaw installed on your system.
• A configuration file (usually at ~/.openclaw/openclaw.json).
• Environment variables or .env files you want to use.

Quick Start

OpenClaw pulls variables from several places. The most important thing to remember is that it never overrides existing values. If a variable is already set in your shell, OpenClaw won’t touch it.

Here is the order of priority from highest to lowest:

1. Process environment: Variables already in your shell or daemon.
2. Local .env: A file in your current working directory.
3. Global .env: Located at ~/.openclaw/.env.
4. Config env block: Variables defined in your openclaw.json.
5. Shell import: Optional import from your login shell.

Setting Variables in Config

You can define variables directly in your ~/.openclaw/openclaw.json file. I find this useful for keeping keys organized. You can use two different formats:

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

Using Substitution

You don’t have to hardcode everything. You can reference environment variables inside your config strings using the ${VAR_NAME} syntax. This is great for keeping secrets out of your main config file.

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
}

Path Overrides

If you are running OpenClaw as a service user or want to isolate your filesystem, you can use these specific variables:

• OPENCLAW_HOME: Replaces the system home directory for all internal paths.
• OPENCLAW_STATE_DIR: Overrides the default state directory (~/.openclaw).
• OPENCLAW_CONFIG_PATH: Points to a specific config file location.

If you use a macOS LaunchDaemon, your configuration might look like this:

<key>EnvironmentVariables</key>
<dict>
  <key>OPENCLAW_HOME</key>
  <string>/Users/kira</string>
</dict>

Troubleshooting

Config Block is Ignored

If your openclaw.json is missing entirely, OpenClaw skips the config env block step. However, the shell environment import will still run if you have it enabled.

Shell Import Issues

If you enable shell environment imports, OpenClaw only pulls in missing keys. If the process takes too long, you can adjust the timeout in your config:

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

You can also trigger this via environment variables:

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

If you need more help with your specific setup, check out the AI Setup Assistant.

What’s Next

• Gateway configuration
• FAQ: env vars and .env loading
• Models overview