Skip to main content

Environment Variables

OpenClaw reads these environment variables at startup. They override corresponding openclaw.json settings. Variables are grouped by function.

tip

Any config value in openclaw.json can also reference environment variables using ${VAR_NAME} syntax. See Configuration Reference.

LLM API Keys​

VariableDescription
ANTHROPIC_API_KEYAnthropic API key for Claude models
OPENAI_API_KEYOpenAI API key for GPT models
CODEX_API_KEYOpenAI fallback key (used if OPENAI_API_KEY is not set)
XAI_API_KEYxAI API key for Grok models
GEMINI_API_KEYGoogle Gemini API key
GOOGLE_API_KEYGoogle API key (alternative to GEMINI_API_KEY)
DEEPSEEK_API_KEYDeepSeek API key
MISTRAL_API_KEYMistral AI API key
GROQ_API_KEYGroq API key
PERPLEXITY_API_KEYPerplexity API key
OPENROUTER_API_KEYOpenRouter meta-provider API key

Gateway​

VariableDefaultDescription
OPENCLAW_PORT18789Gateway WebSocket port
OPENCLAW_HOST127.0.0.1Gateway bind address
OPENCLAW_AUTH_TOKEN—Gateway authentication token
OPENCLAW_LOG_LEVELinfoLog verbosity: debug, info, warn, error
warning

Never set OPENCLAW_HOST to 0.0.0.0 unless the gateway is behind a reverse proxy with authentication. Binding to all interfaces exposes the gateway to the network. See Security Hardening.

Paths​

VariableDefaultDescription
OPENCLAW_HOME~/.openclawBase directory for all OpenClaw data
OPENCLAW_CONFIG_PATH~/.openclaw/openclaw.jsonConfig file path
OPENCLAW_MEMORY_PATH~/.openclaw/memoryMemory directory
OPENCLAW_SKILLS_PATH~/.openclaw/skillsSkills directory
OPENCLAW_WORKSPACE_DIR—Default workspace directory for agents

Brain​

VariableDefaultDescription
OPENCLAW_PROVIDERanthropicLLM provider name
OPENCLAW_MODELclaude-opus-4-6Model identifier
OPENCLAW_TEMPERATURE0.7Response temperature (0.0-1.0)
OPENCLAW_MAX_TOKENS4096Max response tokens

Heartbeat​

VariableDefaultDescription
OPENCLAW_HEARTBEAT_ENABLEDtrueEnable heartbeat loop
OPENCLAW_HEARTBEAT_INTERVAL1800Seconds between heartbeats

Local Models​

VariableDefaultDescription
OPENCLAW_LOCAL_ENDPOINT—Local model API endpoint
OPENCLAW_LOCAL_MODEL—Local model name
OLLAMA_HOSThttp://localhost:11434Ollama server URL
VLLM_API_KEY—vLLM server API key (for auto-discovery)

Channel Credentials​

These variables set credentials for the default account of each channel. In multi-account setups, credentials must be set per-account in openclaw.json — env vars do not propagate to non-default accounts.

VariableChannelDescription
TELEGRAM_BOT_TOKENTelegramBot token from BotFather
DISCORD_BOT_TOKENDiscordBot token from Discord Developer Portal
SLACK_BOT_TOKENSlackBot OAuth token (xoxb-...)
SLACK_APP_TOKENSlackApp-level token for Socket Mode (xapp-...)
GOOGLE_CHAT_SERVICE_ACCOUNTGoogle ChatService account JSON (inline)
GOOGLE_CHAT_SERVICE_ACCOUNT_FILEGoogle ChatPath to service account JSON file
IRC_NICKSERV_PASSWORDIRCNickServ password for authentication
info

WhatsApp and Signal use QR code / device linking authentication rather than API tokens, so they have no credential env vars.

Search & Web Providers​

VariableDescription
PARALLEL_API_KEYParallel web search provider (bundled since v2026.6.5)
BRAVE_API_KEYBrave Search API key
TAVILY_API_KEYTavily search API key
EXA_API_KEYExa search API key
FIRECRAWL_API_KEYFirecrawl web scraping API key

Browser Automation​

VariableDefaultDescription
OPENCLAW_BROWSER_CDP_PORT—Chrome DevTools Protocol port override
OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS—Disable GPU rendering flags
OPENCLAW_BROWSER_DISABLE_EXTENSIONS—Disable browser extensions
OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT2Max browser renderer processes

Voice & TTS​

VariableDescription
OPENCLAW_MLX_TTS_BINPath to macOS MLX TTS helper binary
ELEVENLABS_API_KEYElevenLabs voice API key
XI_API_KEYElevenLabs API key (alternative name)
ELEVENLABS_VOICE_IDDefault ElevenLabs voice ID
SAG_VOICE_IDSAG voice provider voice ID

Lobster (Workflow Engine)​

VariableDescription
LOBSTER_LLM_PROVIDERLLM provider override: openclaw, pi, http
LOBSTER_LLM_ADAPTER_URLGeneric HTTP LLM endpoint
LOBSTER_PI_LLM_ADAPTER_URLPi LLM adapter endpoint
LOBSTER_LLM_PRICING_JSONPath to custom token pricing file
OPENCLAW_URLGateway URL for openclaw.invoke shim (default: ws://localhost:18789)
OPENCLAW_TOKENGateway auth token for openclaw.invoke shim

See Lobster Workflows Guide for full Lobster documentation.

MCP Servers​

MCP server environment variables are set per-server in openclaw.json, not as global env vars:

~/.openclaw/openclaw.json
{
  "mcp": {
    "servers": {
      "github": {
        "command": "npx @anthropic/mcp-github",
        "env": {
          "GITHUB_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
}

Common MCP-related env vars:

VariableDescription
GITHUB_TOKENGitHub personal access token (used by MCP GitHub server)
GITHUB_PERSONAL_ACCESS_TOKENAlternative GitHub token name

Testing & CI​

VariableDescription
OPENCLAW_E2E_NPM_INSTALL_TIMEOUTTimeout for npm installs in E2E tests
OPENCLAW_TESTBOXDelegate execution to a remote Testbox instance

Legacy Variables​

These variables are from the Clawdbot/Moltbot era and may still work but are deprecated:

VariableReplacementNotes
CLAWDBOT_*OPENCLAW_*All CLAWDBOT_ prefixed vars map to OPENCLAW_ equivalents

Workspace .env Security​

Workspace .env files are blocked from overriding security-sensitive variables. This is a fail-closed design — new OPENCLAW_* variables in future releases are automatically blocked.

Blocked categories:

  • All OPENCLAW_* variables
  • Provider credential keys: GEMINI_API_KEY, GOOGLE_API_KEY, XAI_API_KEY, MISTRAL_API_KEY, GROQ_API_KEY, DEEPSEEK_API_KEY, PERPLEXITY_API_KEY, BRAVE_API_KEY, TAVILY_API_KEY, EXA_API_KEY, FIRECRAWL_API_KEY
  • Channel endpoint settings for Matrix, Mattermost, IRC, Synology Chat

This prevents malicious workspaces from hijacking credentials or redirecting API calls. See Security Hardening for details.

Docker Compose Example​

docker-compose.yml
services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENCLAW_HOST=0.0.0.0          # Only safe within Docker network
      - OPENCLAW_LOG_LEVEL=debug
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - DISCORD_BOT_TOKEN=${DISCORD_BOT_TOKEN}
      - PARALLEL_API_KEY=${PARALLEL_API_KEY}
    ports:
      - "127.0.0.1:18789:18789"        # Bind to localhost on host
    volumes:
      - openclaw-data:/root/.openclaw
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
      interval: 30s
      timeout: 5s
      retries: 3

Precedence Order​

When the same setting is configured in multiple places, this order applies (highest wins):

  1. CLI flags (--port 18790)
  2. Environment variables (OPENCLAW_PORT=18790)
  3. openclaw.json ("gateway": { "port": 18790 })
  4. Built-in defaults (18789)

See Also​