Updating Environment Variables

Overview

Environment variables control your agent's behavior, API keys, and configuration. You can update them at any time through the instance configuration page.

How to Update Environment Variables

1. Navigate to your instance details page
2. Click the "Configuration" tab
3. In the "Environment Variables" section, find the variable to update
4. Click the "Edit" button next to the variable
5. Enter the new value
6. Click "Save Changes"
7. Important: Restart your instance for changes to take effect

Adding New Variables

1. Go to the Configuration tab
2. Scroll to the "Environment Variables" section
3. Click "Add Variable"
4. Enter the variable name (e.g., NEW_VARIABLE)
5. Enter the value
6. Click "Save"
7. Restart the instance

Deleting Variables

1. Find the variable in the Configuration tab
2. Click the "Delete" button
3. Confirm the deletion
4. Restart the instance

Note: Deleted variables are permanently removed from encrypted storage.

Common Variables to Update

API Keys

• OPENAI_API_KEY - When rotating OpenAI keys
• ANTHROPIC_API_KEY - When rotating Anthropic keys
• OPENROUTER_API_KEY - When switching to OpenRouter

Bot Tokens

• TELEGRAM_BOT_TOKEN - When regenerating Telegram token
• DISCORD_BOT_TOKEN - When regenerating Discord token

Configuration

• AI_MODEL - Switch between models (e.g., gpt-4, claude-4.5-sonnet)
• SYSTEM_PROMPT - Update agent personality/instructions
• MAX_TOKENS - Adjust response length limits
• TEMPERATURE - Control randomness (0.0-2.0)

Why Restart is Required

Environment variables are loaded when the instance starts. Changes don't take effect until the instance restarts because:

• Variables are read once at startup
• OpenClaw caches configuration in memory
• API connections are established with original values
• Restart ensures clean initialization with new values

Best Practices

Before Updating

• Document current values: Keep a backup of working configuration
• Plan downtime: Restart causes brief interruption (30-60 seconds)
• Test new values: Verify API keys work before updating
• Update during low traffic: Minimize impact on users

During Update

• Double-check values: Verify no typos or extra spaces
• Update related variables together: E.g., change both AI_MODEL and API key if switching providers
• Save before restarting: Ensure changes are committed

After Update

• Check logs: Verify successful restart with new values
• Test functionality: Send a test message to your bot
• Monitor for errors: Watch logs for authentication issues

Security Considerations

Variable Values Are Hidden

For security, environment variable values are never displayed after being saved. You can see variable names but not values.

Encryption

All environment variables are encrypted at rest using AES-256-GCM encryption. Only your running instance can decrypt them.

Key Rotation

Regularly rotate API keys for security:

1. Create new API key in provider dashboard
2. Update environment variable in AgentClaw
3. Restart instance
4. Verify new key works
5. Revoke old key in provider dashboard

Bulk Updates

To update multiple variables at once:

1. Update all variables in the Configuration tab
2. Click "Save Changes" (saves all at once)
3. Restart instance once for all changes

This is more efficient than restarting after each individual change.

Common Update Scenarios

Switching AI Providers

1. Add new provider's API key (e.g., ANTHROPIC_API_KEY)
2. Update AI_MODEL to new model name
3. Save and restart
4. Optional: Remove old API key if not needed

Changing Bot Personality

1. Update SYSTEM_PROMPT with new instructions
2. Optionally adjust TEMPERATURE for creativity
3. Save and restart
4. Test with sample messages

Reducing Costs

1. Switch AI_MODEL to cheaper model (e.g., gpt-3.5-turbo)
2. Reduce MAX_TOKENS to limit response length
3. Save and restart
4. Monitor quality and adjust as needed

Troubleshooting

Changes Not Taking Effect

• Verify you clicked "Save Changes"
• Ensure you restarted the instance
• Check logs for errors during startup
• Wait for instance to fully start before testing

Instance Won't Start After Update

• Check logs for specific error messages
• Verify new API key is correct
• Ensure no typos in variable names or values
• Try reverting to previous working values
• See instance won't start guide

Lost Previous Value

Since values are hidden after saving, if you lose a working value:

• Cannot retrieve from AgentClaw (security measure)
• Must get new value from original source (e.g., OpenAI dashboard)
• Update with new value and restart

Variable Naming Conventions

• Use UPPERCASE for variable names
• Separate words with underscores: MY_VARIABLE
• Be descriptive: OPENAI_API_KEY not KEY1
• Follow OpenClaw conventions for compatibility

Next Steps

• Learn about adding API keys securely
• Read the complete environment variables guide
• Understand restarting instances
• See how to read logs after updates