OpenClaw Environment Variables: The Setup Mistakes to Avoid

Q: What environment variables does OpenClaw use?

Core OpenClaw environment variables include OPENCLAW_GATEWAY_TOKEN (gateway auth), OPENCLAW_LLM_PROVIDER and OPENCLAW_API_KEY (model configuration), OPENCLAW_LOG_LEVEL (logging verbosity), OPENCLAW_CONFIG_PATH (custom config file location), and OPENCLAW_DATA_DIR (storage path). Provider-specific keys like ANTHROPIC_API_KEY and OPENAI_API_KEY are also read automatically.

Q: Do environment variables override gateway.yaml settings?

Yes. Environment variables take precedence over gateway.yaml. This is intentional — it allows you to keep secrets out of config files while still version-controlling everything else. If OPENCLAW_GATEWAY_TOKEN is set as an env var, it overrides the token field in gateway.yaml regardless of its value.

Q: How do I set environment variables for a systemd OpenClaw service?

Add an EnvironmentFile directive to your systemd unit pointing to a file like /etc/openclaw/env. List variables as KEY=VALUE pairs in that file, one per line. The file should be owned by root and readable only by the openclaw user (chmod 640). Never put secrets in the unit file itself — it's world-readable.

Q: Can I use a .env file with OpenClaw?

OpenClaw doesn't natively load .env files, but you can source one before starting the process. For Docker Compose, use the env_file directive to load a .env file into the container. For systemd, use EnvironmentFile. Never commit .env files to version control — add them to .gitignore immediately.

Q: What's the difference between OPENCLAW_API_KEY and provider-specific keys?

OPENCLAW_API_KEY is a generic key that OpenClaw passes to whatever LLM provider is configured. Provider-specific keys (ANTHROPIC_API_KEY, OPENAI_API_KEY) are recognized by name automatically. If you're using multiple providers, set the provider-specific keys — OPENCLAW_API_KEY only works reliably for a single configured provider.

Q: How do I rotate an API key without restarting OpenClaw?

OpenClaw reads environment variables at startup and doesn't hot-reload them. To rotate an API key, update the env var in your secrets manager or .env file, then restart the gateway process. For zero-downtime key rotation on production, use a rolling restart: start a new gateway instance with the new key before stopping the old one.

Key Takeaways

Environment variables always override gateway.yaml — use this deliberately to keep secrets out of version-controlled config files
Core vars: OPENCLAW_GATEWAY_TOKEN, OPENCLAW_LLM_PROVIDER, OPENCLAW_API_KEY, OPENCLAW_LOG_LEVEL, OPENCLAW_CONFIG_PATH, OPENCLAW_DATA_DIR
For systemd: use EnvironmentFile pointing to a restricted file — never put secrets directly in the unit file
For Docker: use env_file or --env-file, never -e with secrets inline in shell commands that appear in history
OpenClaw reads env vars at startup only — key rotation requires a process restart; plan for this in production

Three weeks after launch, a team's Anthropic API key gets rotated unexpectedly. They spent four hours figuring out why agents were failing — the key was hardcoded in gateway.yaml, committed to git, and they hadn't thought to check the config file when the error just said "authentication failed." Environment variables would have made this a two-minute fix: update the value, restart the process, done.

Core Environment Variables Reference

These are the variables OpenClaw reads at startup. All are optional — if unset, the value from gateway.yaml is used. If both are set, the environment variable wins.

OPENCLAW_GATEWAY_TOKEN — The master authentication token for the gateway. Authenticates API requests and agent connections. This is the most important secret to keep out of config files.
OPENCLAW_LLM_PROVIDER — The default LLM provider. Values: anthropic, openai, ollama, groq, openrouter. Overrides the provider field in the models block of gateway.yaml.
OPENCLAW_API_KEY — The API key for the configured provider. For multi-provider setups, use provider-specific keys instead.
OPENCLAW_LOG_LEVEL — Logging verbosity. Values: error, warn, info, debug. Default: info. Set to debug for troubleshooting, never in production (very verbose).
OPENCLAW_CONFIG_PATH — Full path to a custom gateway.yaml location. Useful when you can't place the config in the default location or when running multiple instances with different configs on the same host.
OPENCLAW_DATA_DIR — Directory for agent memory, logs, and skill data. Defaults to ~/.openclaw/data. Override this for dedicated storage volumes or when running in Docker.
OPENCLAW_PORT — Gateway listen port. Overrides the port field in gateway.yaml. Default: 8080.
OPENCLAW_HOST — Gateway listen address. Default: 0.0.0.0. Set to 127.0.0.1 when running behind a local reverse proxy and you don't want the gateway exposed on public interfaces.

💡

Verify What's Active

Run openclaw status --json after startup to verify which provider and log level are active. The status output reflects the resolved configuration — env vars applied, yaml applied, defaults applied. If the wrong provider shows up, an env var is likely overriding your yaml.

Provider-Specific API Keys

OpenClaw recognizes standard provider key names automatically. Set these and the gateway uses them for the matching provider, regardless of OPENCLAW_API_KEY:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GROQ_API_KEY=gsk_...
OPENROUTER_API_KEY=sk-or-...
GEMINI_API_KEY=AI...
GROK_API_KEY=xai-...

When you're running multiple providers (e.g., different agents use different models), set each provider's key individually. OPENCLAW_API_KEY is a fallback — if a provider-specific key isn't set, OpenClaw uses OPENCLAW_API_KEY. If both are set, the provider-specific key wins.

This matters more than it sounds. We've seen setups where OPENCLAW_API_KEY was set to an old OpenAI key while ANTHROPIC_API_KEY wasn't set at all — the Anthropic agent was silently using the wrong key type and failing auth on every request.

Override Precedence

When the same setting exists in multiple places, OpenClaw resolves it in this order (highest to lowest priority):

Environment variable (e.g., OPENCLAW_LOG_LEVEL=debug)
gateway.yaml setting (e.g., log.level: info)
Default value baked into the binary

This is intentional. The design philosophy: version-control your non-secret configuration in gateway.yaml, inject secrets via environment variables, rely on defaults only for non-critical settings. This gives you a reproducible config in git without secrets ever touching your repository.

⚠️

Accidental Overrides

If you tested with a debug env var and forgot to unset it, it will override your gateway.yaml in production. Always audit active env vars before deploying. Run env | grep OPENCLAW on the server to see exactly which vars are set in the current process environment.

Systemd and Docker Configuration

Systemd EnvironmentFile

The correct approach for systemd-managed OpenClaw deployments:

# /etc/systemd/system/openclaw.service
[Service]
User=openclaw
EnvironmentFile=/etc/openclaw/env
ExecStart=/usr/local/bin/openclaw start

# /etc/openclaw/env  (owned by root, chmod 640, group: openclaw)
OPENCLAW_GATEWAY_TOKEN=your-secret-token
ANTHROPIC_API_KEY=sk-ant-your-key
OPENCLAW_LOG_LEVEL=info
OPENCLAW_DATA_DIR=/var/lib/openclaw

The EnvironmentFile is loaded as part of the service environment. The file itself should be owned by root, readable only by the openclaw service user. Never put secrets directly in the [Service] block with Environment= — those are visible in systemctl show output.

Docker and Docker Compose

# docker-compose.yml
services:
  openclaw:
    image: openclaw/openclaw:latest
    env_file: .env.production
    volumes:
      - openclaw-data:/var/lib/openclaw

# .env.production (never committed to git)
OPENCLAW_GATEWAY_TOKEN=your-secret-token
ANTHROPIC_API_KEY=sk-ant-your-key
OPENCLAW_DATA_DIR=/var/lib/openclaw

Add .env.production to .gitignore immediately. Use a separate .env.example with placeholder values committed to the repo as documentation.

Secrets Management in Production

For serious production deployments, don't store secrets in .env files on disk at all. Use a secrets manager:

AWS Secrets Manager — Fetch at deploy time via the startup script: export ANTHROPIC_API_KEY=$(aws secretsmanager get-secret-value ...)
HashiCorp Vault — Use the Vault agent sidecar to inject secrets into the environment before OpenClaw starts
Kubernetes Secrets — Mount as environment variables via envFrom.secretRef in your pod spec

The pattern: secrets live in the manager, OpenClaw reads them from environment variables injected at runtime. Nothing sensitive touches disk or version control.

Common Mistakes

Setting OPENCLAW_API_KEY when using Anthropic instead of ANTHROPIC_API_KEY. It often works — until you add a second provider and the generic key gets sent to the wrong provider. Use the provider-specific variable from day one.

Putting API keys in inline Docker run commands: docker run -e ANTHROPIC_API_KEY=sk-ant-... openclaw. This appears in shell history, Docker inspect output, and process listings. Use --env-file instead, pointing to a file with restricted permissions.

Not restarting after changing env vars. OpenClaw reads environment variables at startup and caches them. Changing a var in your EnvironmentFile or .env file has no effect until you restart the process. This trips up builders who update a key and then wonder why the old key is still being used.

Frequently Asked Questions

What environment variables does OpenClaw use?

Core variables: OPENCLAW_GATEWAY_TOKEN, OPENCLAW_LLM_PROVIDER, OPENCLAW_API_KEY, OPENCLAW_LOG_LEVEL, OPENCLAW_CONFIG_PATH, OPENCLAW_DATA_DIR, OPENCLAW_PORT, OPENCLAW_HOST. Provider-specific keys like ANTHROPIC_API_KEY and OPENAI_API_KEY are also recognized automatically and take precedence over the generic OPENCLAW_API_KEY.

Do environment variables override gateway.yaml settings?

Yes, env vars always win over gateway.yaml. This is deliberate — keep secrets in env vars, non-secret config in gateway.yaml, rely on defaults for everything else. Run openclaw status --json to verify the resolved configuration after startup.

How do I set environment variables for a systemd OpenClaw service?

Use EnvironmentFile=/etc/openclaw/env in your systemd unit. The file lists KEY=VALUE pairs, one per line. Own it by root, restrict read access to the openclaw user (chmod 640). Never use the inline Environment= directive for secrets — it's visible in systemctl output.

Can I use a .env file with OpenClaw?

OpenClaw doesn't auto-load .env files, but Docker Compose's env_file directive and shell source .env both work. Never commit .env files to version control — add them to .gitignore immediately and provide a .env.example with placeholder values instead.

What's the difference between OPENCLAW_API_KEY and provider-specific keys?

OPENCLAW_API_KEY is a fallback used when no provider-specific key is set. Provider-specific keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.) take precedence and are the correct choice for multi-provider setups. Use provider-specific keys from the start to avoid silent misrouting of API calls.

How do I rotate an API key without restarting OpenClaw?

You can't — OpenClaw reads env vars at startup only. To rotate a key, update it in your secrets source, then restart the gateway. For zero-downtime rotation in production, start a new instance with the new key before stopping the old one. Rolling restarts in Kubernetes handle this automatically.

M. Kim

AI Product Specialist

M. Kim specializes in secure configuration and deployment patterns for OpenClaw production environments. Has audited environment variable management across cloud, on-premises, and hybrid deployments, with a focus on secrets hygiene and zero-downtime configuration changes.