Advanced Environment Variables and Configuration File Usage

Configuration Priority

OpenClaw configuration sources are applied in the following order (highest to lowest priority):

Command-line arguments
Environment variables
.env file
User configuration file (~/.openclaw/config.json)
Default values

Environment Variable Naming Convention

All OpenClaw environment variables use the OPENCLAW_ prefix:

# Gateway configuration
OPENCLAW_PORT=3000
OPENCLAW_HOST=0.0.0.0
OPENCLAW_BASE_URL=https://gateway.example.com

# Provider configuration
OPENCLAW_OPENAI_API_KEY=sk-your-key
OPENCLAW_OPENAI_BASE_URL=https://api.openai.com/v1
OPENCLAW_ANTHROPIC_API_KEY=sk-ant-your-key

# Channel configuration
OPENCLAW_TELEGRAM_TOKEN=123456:ABC-DEF
OPENCLAW_DISCORD_TOKEN=your-discord-token

# Logging configuration
OPENCLAW_LOG_LEVEL=info
OPENCLAW_LOG_FORMAT=json

The .env File

Create a .env file in your project directory:

# .env
OPENCLAW_PORT=3000
OPENCLAW_LOG_LEVEL=info

# Provider keys
OPENAI_API_KEY=sk-your-key
ANTHROPIC_API_KEY=sk-ant-key

# Channel tokens
TELEGRAM_BOT_TOKEN=123456:ABC-DEF

OpenClaw automatically loads the .env file on startup.

Multi-Environment Configuration

Using Different .env Files

# Development
openclaw start --env-file .env.development

# Staging
openclaw start --env-file .env.staging

# Production
openclaw start --env-file .env.production

Using Different Config Files

OPENCLAW_CONFIG=./config.production.json openclaw start

Configuration Inheritance

Use a base config plus environment-specific overrides:

// config.base.json - base configuration
{
  "gateway": {
    "port": 3000
  },
  "logging": {
    "level": "info"
  }
}

// config.production.json - production overrides
{
  "extends": "./config.base.json",
  "gateway": {
    "host": "0.0.0.0",
    "baseUrl": "https://gateway.example.com"
  },
  "logging": {
    "level": "warn"
  }
}

Conditional Configuration

Apply configuration conditionally based on environment variables:

{
  "providers": {
    "openai": {
      "type": "openai",
      "apiKey": "{{OPENAI_API_KEY}}"
    }
  },
  "models": {
    "main": {
      "provider": "openai",
      "model": "{{OPENCLAW_DEFAULT_MODEL|gpt-4o-mini}}"
    }
  }
}

The {{VAR|default}} syntax supports default values -- the default is used when the environment variable is not set.

Docker Environment Variables

When deploying with Docker, inject configuration via environment variables:

services:
  openclaw:
    image: openclaw/openclaw:latest
    environment:
      - OPENCLAW_PORT=3000
      - OPENCLAW_LOG_LEVEL=info
      - OPENAI_API_KEY=sk-your-key
      - TELEGRAM_BOT_TOKEN=123456:ABC
    env_file:
      - .env.production

Configuration Validation

# Validate current configuration
openclaw configure --validate

# Show configuration sources
openclaw configure --show --sources

Configuration Sources:
  gateway.port: 3000 (env: OPENCLAW_PORT)
  gateway.host: 0.0.0.0 (config: ~/.openclaw/config.json)
  logging.level: debug (cli: --log-level)
  providers.openai.apiKey: sk-*** (secrets)

Hot Reloading

OpenClaw supports configuration hot reloading -- changes take effect without a restart:

# Send a reload signal
openclaw reload

# Or
kill -HUP $(pgrep openclaw)

Supports hot reloading:

Model parameters (temperature, maxTokens, etc.)
System prompts
Log level
Rate limits

Requires restart:

Gateway port and address
Channel additions/removals
Provider additions/removals

Configuration Debugging

# Print the fully resolved configuration (all sources merged)
openclaw configure --dump

# Trace the resolution of a specific config item
openclaw configure --trace gateway.port

Tracing: gateway.port
  Default: 3000
  Config file: not set
  Env (OPENCLAW_PORT): 8080
  CLI args: not set
  → Resolved value: 8080 (from env)

Security Considerations

Do not commit .env files to Git: Ensure .gitignore includes .env*
Use secrets for managing keys: Environment variables are better suited for non-sensitive configuration
Restrict config file permissions: chmod 600 ~/.openclaw/config.json
Avoid debug-level logging in production: It may record sensitive information

Summary

OpenClaw's configuration system supports multiple sources and a flexible priority mechanism. By properly using environment variables, configuration files, and the secrets system, you can safely manage configuration across environments and achieve proper isolation between development, staging, and production.