Why Secrets Management Matters
OpenClaw needs API keys for multiple external services. Writing these directly in config files is a security risk -- config files can be accidentally committed to Git, logged, or read by unauthorized users. The Secrets system provides secure key storage.
How Secrets Work
OpenClaw encrypts secrets locally, decrypting them at runtime and injecting them into the configuration. Config files use the {{SECRET_NAME}} syntax to reference secrets, which are automatically replaced with actual values when the Gateway starts.
Storage location: ~/.openclaw/secrets.enc
This file is encrypted with a master key stored in the system keychain (macOS Keychain / Linux Secret Service / Windows Credential Manager).
Basic Operations
# Add secrets
openclaw secrets set OPENAI_API_KEY "sk-your-key-here"
openclaw secrets set TELEGRAM_BOT_TOKEN "123456:ABC-DEF"
# List secrets (values not shown)
openclaw secrets list
# View a secret value
openclaw secrets get OPENAI_API_KEY
# Delete a secret
openclaw secrets delete OLD_API_KEY
# Update (set overwrites the old value)
openclaw secrets set OPENAI_API_KEY "sk-new-key-here"
Referencing in Configuration
{
"providers": {
"openai": { "apiKey": "{{OPENAI_API_KEY}}" },
"anthropic": { "apiKey": "{{ANTHROPIC_API_KEY}}" }
},
"channels": {
"telegram": { "token": "{{TELEGRAM_BOT_TOKEN}}" }
}
}
Import from Environment Variables and .env Files
openclaw secrets import-env OPENAI_API_KEY
openclaw secrets import-env --pattern "OPENCLAW_*"
openclaw secrets import-file .env
Key Rotation
# 1. Generate a new key at the provider
# 2. Update in OpenClaw
openclaw secrets set OPENAI_API_KEY "sk-new-rotated-key"
# 3. Restart the Gateway
openclaw restart
# 4. Revoke the old key at the provider
Backup and Restore
openclaw secrets export --output secrets-backup.enc
openclaw secrets import --input secrets-backup.enc
Multi-Environment Management
OPENCLAW_ENV=development openclaw secrets set OPENAI_API_KEY "sk-dev-key"
OPENCLAW_ENV=production openclaw secrets set OPENAI_API_KEY "sk-prod-key"
Security Best Practices
- Don't log secrets: OpenClaw masks secret values in logs by default
- Restrict file permissions:
chmod 700 ~/.openclaw && chmod 600 ~/.openclaw/secrets.enc - Rotate regularly: Recommend rotating API keys every 90 days
- Least privilege: Only grant necessary permissions to API keys
- Don't commit to Git: Add
.openclaw/to.gitignore
Summary
Secrets management is fundamental to OpenClaw's secure operation. Using the secrets system instead of plaintext storage effectively prevents key leakage. Making a habit of managing all sensitive information through openclaw secrets is the first step to protecting your AI assistant.