API Key Security Best Practices

Environment Variables (Recommended)

The simplest and safest default for API key storage is environment variables. OpenClaw reads all standard provider key env vars automatically:

# Set for current session
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENCLAW_API_KEY="oc-..."

# Or add to ~/.bashrc / ~/.zshrc for persistence
echo 'export OPENAI_API_KEY="sk-proj-..."' >> ~/.bashrc

Reference them in config files without exposing the value:

# config.yaml — safe to commit to Git
provider: openai
openai:
  api_key: "${OPENAI_API_KEY}"     # reads from environment
  model: gpt-4o

Using .env Files

For local development, use a .env file with the dotenv pattern:

# .env (NEVER commit this to Git!)
OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-...

# Add .env to .gitignore
echo ".env" >> .gitignore
echo ".env.*" >> .gitignore

# Load .env before running OpenClaw
source .env && openclaw run "your task"

# Or use the --env-file flag
openclaw run "your task" --env-file .env

Protecting Secrets with .gitignore

Add these patterns to your .gitignore to prevent accidental commits:

# API keys and secrets
.env
.env.*
*.env
config.local.yaml
config.secrets.yaml
secrets/
.secrets/

# OpenClaw local config with keys
openclaw.local.yaml
~/.openclaw/config.yaml

API Key Rotation Strategy

Regular rotation limits the blast radius of a leaked key:

Scheduled Rotation (Every 90 Days)

# 1. Generate a new key at the provider dashboard
# 2. Update your secrets manager or env var
export OPENAI_API_KEY="sk-proj-new-key-here"

# 3. Test the new key
openclaw config validate

# 4. Revoke the old key at provider dashboard
# 5. Update all environments (dev, staging, prod)

Emergency Revocation

If you suspect a key is compromised:

1. Immediately revoke the key at the provider dashboard (OpenAI, Anthropic, etc.)
2. Generate a new key
3. Update all environments
4. Review usage logs for unauthorized usage
5. Report to your security team

Scoped API Keys

Where providers support it, create scoped keys with minimal permissions:

# OpenAI: create project-scoped API key
# Go to: platform.openai.com/api-keys → Create new secret key
# Assign to a specific project for isolated billing and usage tracking

Vault Integrations

For team environments and production deployments, use a dedicated secrets manager:

HashiCorp Vault

# Store the key
vault kv put secret/openclaw/openai api_key="sk-proj-..."

# OpenClaw config using Vault
openclaw run "task" --secrets-from vault://secret/openclaw/openai

secrets:
  provider: vault
  vault:
    address: "https://vault.example.com"
    token: "${VAULT_TOKEN}"
    path: "secret/openclaw"

AWS Secrets Manager

# Store
aws secretsmanager create-secret \
  --name "openclaw/openai-api-key" \
  --secret-string "sk-proj-..."

# OpenClaw config
secrets:
  provider: aws_secretsmanager
  aws:
    region: us-east-1
    secret_name: "openclaw/openai-api-key"

Doppler

# Inject secrets via Doppler CLI
doppler run -- openclaw run "your task"

# Or in Docker
doppler run --mount /etc/secrets -- docker run openclaw/openclaw

Detecting Leaked Keys

GitHub Secret Scanning

GitHub automatically scans public repositories for known API key patterns. Enable for private repos:

• Go to repository Settings → Security → Secret scanning
• Enable "Secret scanning" and "Push protection"

Pre-commit Hooks

# Install detect-secrets
pip install detect-secrets

# Create baseline
detect-secrets scan > .secrets.baseline

# Add to .pre-commit-config.yaml
repos:
  - repo: https://github.com/Yelp/detect-secrets
    rev: v1.4.0
    hooks:
      - id: detect-secrets
        args: ['--baseline', '.secrets.baseline']

What's Next

• Sandboxing AI Agents — Container isolation for safer execution
• Secrets Management — Full Vault and cloud SM setup guide
• Audit Logging — Track all API key usage

API Key Lifecycle Management

Every API key should have a defined owner, purpose, and expiration. When you create a key, record it in your internal secrets inventory with: the service it accesses, the permissions it grants, when it was created, who created it, and when it should next be rotated. Without this record, keys accumulate silently — within a year, most teams discover they have dozens of old keys with unknown purpose and unknown exposure.

Rotate keys on a schedule, not just when you suspect compromise. Quarterly rotation is a reasonable baseline for low-risk keys; monthly for keys with broad permissions. Automate rotation where possible — manual rotation processes get skipped under time pressure. When a team member with access to keys leaves the organization, treat it as an immediate rotation event, not something to schedule for next quarter.

When you rotate a key, follow a safe rotation procedure: provision the new key first, update all consumers to use it, verify everything is working, then revoke the old key. Never revoke the old key before the new one is deployed — this creates downtime. Never leave the old key valid indefinitely after the new one is deployed — this extends the window of exposure for the compromised key.

Key Storage Across Environments

Use different API keys for development, staging, and production environments. This separation limits blast radius when a key is accidentally committed to a repository during development — the leaked key accesses only the dev environment, not production. It also lets you apply different rate limits and budget caps per environment: generous limits for production, strict limits for dev to contain costs during testing. If your LLM provider supports it, label each key with the environment and agent it serves — this makes it trivial to identify and revoke the right key during an incident.