Environment Variables Reference

Core Settings

LLM Provider Settings

Memory Settings

Server Settings

Development and Debug Variables

Example .env File

# .env — copy to .env.local and fill in your values
# NEVER commit .env.local to version control

OPENAI_API_KEY=sk-...
OPENCLAW_LLM_MODEL=gpt-4o-mini
OPENCLAW_LOG_LEVEL=INFO
OPENCLAW_SERVER_PORT=8080
OPENCLAW_API_KEY=your-secure-api-key-here
OPENCLAW_MAX_CONCURRENT_TASKS=5

Use a .env file during development (loaded by python-dotenv if installed) and real environment variables in production. Never commit a .env file containing real credentials to version control — add .env.local and .env to your .gitignore.

Security Considerations for Environment Variables

Environment variables are a common and convenient way to pass secrets to applications, but they have security implications you should understand. In containerized environments (Docker, Kubernetes), environment variables are visible to all processes in the container and can be read from /proc/[pid]/environ by any process running as the same user. In Kubernetes, secrets passed as environment variables are stored in etcd and are accessible to anyone with read access to the pod spec.

For OpenClaw specifically: never pass API keys via environment variables on a shared system where other untrusted processes run. In production, prefer Kubernetes Secrets (with encryption at rest enabled) or a secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager) over plain environment variables. OpenClaw supports the openclaw.secrets plugin interface for fetching secrets from external managers at startup, keeping them out of the environment entirely.

Audit your environment variables regularly — remove any that are no longer used, rotate keys on a schedule, and ensure that environment variable values don't appear in application logs (OpenClaw's structured logging sanitizes known secret fields, but check that no custom tool implementations log their environment variables).

When to Use Environment Variables vs. Config File

The general principle: secrets go in environment variables, non-secret configuration goes in the config file. API keys, database passwords, and private tokens should never appear in a config file that might be committed to version control — use environment variables for everything sensitive. On the other hand, agent name, system prompt, max_steps, and tool configuration are not secrets and are fine in the config file where they're readable, documentable, and version-controlled.

In development, a .env file loaded via python-dotenv is a convenient way to manage environment variables locally without polluting your shell. In CI/CD pipelines, use the platform's secret store (GitHub Actions secrets, GitLab CI variables, CircleCI contexts) instead of storing secrets in .env files. In production Kubernetes deployments, use Kubernetes Secrets mounted as environment variables or a cloud secrets manager for the most secure approach.

Twelve-Factor App Compliance

OpenClaw's environment variable configuration is designed to be fully compliant with the Twelve-Factor App methodology, which specifies that configuration (anything that varies between deployments) is stored in the environment, not in the code. The combination of an environment variable for every configuration key, no default values that are deployment-specific, and the ability to override all settings via environment makes OpenClaw straightforward to deploy in twelve-factor environments like Heroku, Fly.io, Render, and containerized cloud platforms. Follow twelve-factor practices — all deployment-specific configuration in environment variables, code and generic configuration in version control — for the most maintainable and portable deployments.

Variable Priority and Override Order

Configuration values are resolved in this priority order (highest to lowest): command-line flags override environment variables, which override the YAML config file, which override compiled defaults. This ordering means you can set a default in the config file and override it for a specific deployment via an environment variable without modifying the file — a clean separation of defaults from environment-specific overrides that makes deployment management predictable. Use openclaw config show at any time to see the current effective configuration after all overrides are applied, making it easy to verify that an override was applied correctly.

Keeping Secrets Out of Environment Variables

For production deployments, prefer injecting API keys via a secrets manager (AWS Secrets Manager, HashiCorp Vault, Kubernetes Secrets) rather than raw environment variables visible in ps aux or container inspect output. When direct env injection is unavoidable, restrict process visibility using the operating system's access controls — run the agent under a dedicated service account and lock down process listing to that account. Always rotate API keys regularly and revoke old ones promptly. Document which keys are in use and which services they belong to in your internal runbook — undocumented credentials become security liabilities during incident response when you need to identify and rotate them quickly.