Environment Variables Guide

Overview

Environment variables control your agent's behavior, API keys, and configuration. All values are encrypted at rest.

Required Variables

At minimum, you need:

AI Provider Key: One of OPENAI_API_KEY, ANTHROPIC_API_KEY, or OPENROUTER_API_KEY
Messaging Platform: One of TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, etc.

AI Provider Variables

OpenAI

OPENAI_API_KEY=sk-... AI_MODEL=gpt-4  # Optional, defaults to gpt-3.5-turbo

Anthropic

ANTHROPIC_API_KEY=sk-ant-... AI_MODEL=claude-4.5-sonnet  # Optional

OpenRouter

OPENROUTER_API_KEY=sk-or-... AI_MODEL=anthropic/claude-4.5-sonnet OPENROUTER_APP_NAME=MyBot  # Optional

Messaging Platform Variables

TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

Discord

DISCORD_BOT_TOKEN=your-discord-token

WHATSAPP_PHONE_NUMBER_ID=your-phone-id WHATSAPP_ACCESS_TOKEN=your-access-token WHATSAPP_VERIFY_TOKEN=your-verify-token

Optional Configuration Variables

AI Behavior

SYSTEM_PROMPT=You are a helpful assistant... MAX_TOKENS=1000  # Maximum response length TEMPERATURE=0.7  # Randomness (0.0-2.0) TOP_P=1.0  # Nucleus sampling FREQUENCY_PENALTY=0.0  # Reduce repetition (-2.0 to 2.0) PRESENCE_PENALTY=0.0  # Encourage new topics (-2.0 to 2.0)

Conversation Settings

CONVERSATION_HISTORY_LIMIT=10  # Messages to remember ENABLE_MEMORY=true  # Remember past conversations CONTEXT_WINDOW=4096  # Token limit for context

Response Behavior

TYPING_INDICATOR=true  # Show "typing..." on Telegram/Discord STREAM_RESPONSES=false  # Send response as it's generated ENABLE_MARKDOWN=true  # Format responses with markdown

Advanced Variables

Rate Limiting

MAX_REQUESTS_PER_MINUTE=60  # Rate limit per user REQUEST_TIMEOUT=30  # Seconds before timeout

Logging

LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR VERBOSE_LOGGING=false  # Extra detailed logs

Security

ALLOWED_USER_IDS=123,456,789  # Whitelist user IDs BLOCKED_USER_IDS=111,222  # Blacklist user IDs REQUIRE_APPROVAL=false  # Admin approval for new users

Variable Naming Rules

Use UPPERCASE for variable names
Separate words with underscores: MY_VARIABLE
No spaces in names or values (unless value needs spaces)
Case-sensitive
No special characters in names (except underscore)

Setting Variables

Go to instance Configuration tab
Click "Add Variable"
Enter name (e.g., OPENAI_API_KEY)
Enter value
Click "Save"
Restart instance for changes to take effect

See updating environment variables guide.

Security Best Practices

Never hardcode: Use environment variables, not code
Never commit: Don't add to version control
Use different keys: Separate dev/prod environments
Rotate regularly: Change API keys periodically
Minimum privileges: Only set variables you need
Monitor access: Check logs for unauthorized use

Common Mistakes

Typos in Variable Names

Wrong: OPENAI_KEY
Correct: OPENAI_API_KEY

Extra Spaces

Wrong: sk-123456 (leading/trailing spaces)
Correct: sk-123456

Not Restarting

Changes don't take effect until instance is restarted!

Incorrect Data Types

Boolean: Use true or false (lowercase)
Numbers: Just the number, no quotes: 1000
Strings: Can include spaces if needed

Viewing Current Variables

In the Configuration tab, you can see:

Variable names (visible)
Variable values (hidden for security)

Note: Values are encrypted and never displayed after saving.

Debugging Variable Issues

Check instance logs for startup errors
Verify variable names are exactly correct
Ensure you restarted after changes
Test API keys independently
Check for typos in values

OpenClaw-Specific Variables

OpenClaw may support additional variables. Check the OpenClaw documentation for the latest list.