API Key Management

API keys are the credentials that connect ClawBook to your LLM providers. Proper management is critical for security and cost control.

Key Security Principles

1. Treat keys like passwords - Never share or expose them
2. Rotate regularly - Every 90 days recommended
3. Use minimal permissions - Only grant what's needed
4. Monitor usage - Detect unauthorized use early
5. Have revocation plan - Know how to disable quickly

Storing Keys Securely

In ClawBook

ClawBook encrypts all API keys at rest:

# Keys are stored encrypted, not in plain text
# Never visible in logs or exports
# Only decrypted in memory when needed

Never Store Keys In:

• Git repositories
• Plain text files
• Environment variables (for production)
• Backup files (use encrypted backups)
• Chat messages or emails

Adding API Keys

Via Dashboard

1. Go to Settings → AI Providers
2. Click Add Provider
3. Select provider (Anthropic, OpenAI, etc.)
4. Paste API key
5. Click Save

Via Configuration

# /etc/openclaw/config.yaml
ai:
  providers:
    - name: anthropic
      api_key_encrypted: "encrypted:AES256:xxxxx..."
      # Never use plain text keys in config

Key Validation

ClawBook validates keys on save:

✓ API key format valid
✓ Authentication successful
✓ Model access confirmed
✓ Rate limits: 100 req/min

Key Rotation

Why Rotate?

• Limit damage from undetected breaches
• Comply with security policies
• Revoke access from former team members
• Reset after suspicious activity

Rotation Process

1. Generate new key at provider
2. Add new key to ClawBook (don't remove old yet)
3. Test new key with a sample message
4. Remove old key from ClawBook
5. Revoke old key at provider

Via Dashboard

1. Settings → AI Providers
2. Click ⋮ → Rotate Key
3. Enter new API key
4. Click Test & Save
5. Confirm old key revocation

Rotation Schedule

Environment	Frequency
Production	Every 90 days
Development	Every 30 days
After incident	Immediately

Access Control

Provider-Side Restrictions

Configure at your LLM provider:

Anthropic

Console → API Keys → Key Settings
- Rate limits
- Model restrictions
- IP allowlist

OpenAI

Platform → API Keys → Permissions
- Project restrictions
- Usage limits
- Model access

ClawBook-Side Limits

# /etc/openclaw/config.yaml
ai:
  cost_controls:
    daily_limit_usd: 10.00
    monthly_limit_usd: 100.00
    alert_threshold_percent: 80
    action_at_limit: block  # or 'switch_model'

Monitoring Usage

Dashboard View

Settings → AI Providers → Usage

This Month's Usage
==================
Provider: Anthropic
Requests: 5,432
Input tokens: 1,234,567
Output tokens: 543,210
Cost: $12.34

API Usage Alerts

# /etc/openclaw/config.yaml
alerts:
  api_usage:
    enabled: true
    thresholds:
      - percent: 50
        notify: email
      - percent: 80
        notify: email, slack
      - percent: 100
        action: block

Anomaly Detection

ClawBook monitors for unusual patterns:

• Sudden usage spikes
• Requests from new IPs
• Unusual request patterns
• Failed authentication attempts

Multiple Keys

Different Keys for Different Purposes

ai:
  providers:
    - name: anthropic-production
      api_key_encrypted: "..."
      environment: production

    - name: anthropic-development
      api_key_encrypted: "..."
      environment: development

Failover Keys

Configure backup providers:

ai:
  primary:
    provider: anthropic
    api_key_encrypted: "..."

  fallback:
    provider: openai
    api_key_encrypted: "..."
    trigger_on:
      - rate_limit
      - service_unavailable

Emergency Revocation

If Key Is Compromised

1. Immediately revoke at provider

   • Anthropic: Console → API Keys → Delete
   • OpenAI: Platform → API Keys → Revoke

2. Generate new key

3. Update in ClawBook

   # Quick update via CLI
   clawbook-config set ai.api_key "new-key-here"
   systemctl restart openclaw

4. Investigate

   • Check logs for unauthorized use
   • Review cost reports
   • Identify exposure source

5. Report to provider if abuse detected

Quick Disable

Temporarily disable AI without removing key:

clawbook-ai disable
# Responds with "AI temporarily unavailable"

clawbook-ai enable
# Restores normal operation

Audit Trail

All key operations are logged:

# /var/log/openclaw/security.log
[2026-01-30 10:15:00] API_KEY_ADDED provider=anthropic user=admin
[2026-01-30 10:16:00] API_KEY_TESTED provider=anthropic result=success
[2026-02-15 14:30:00] API_KEY_ROTATED provider=anthropic user=admin
[2026-02-15 14:30:05] API_KEY_OLD_REMOVED provider=anthropic user=admin

Best Practices Checklist

• Keys stored only in ClawBook's encrypted storage
• Rotation calendar set (every 90 days)
• Usage alerts configured
• Cost limits set
• Emergency revocation procedure documented
• Audit logging enabled
• Team members know not to share keys
• Backup provider configured

Troubleshooting

"Invalid API Key"

1. Check for extra spaces when copying
2. Verify key hasn't been revoked
3. Confirm key has required permissions
4. Check provider account is in good standing

"Rate Limit Exceeded"

1. Wait for rate limit reset
2. Reduce message frequency
3. Upgrade provider plan
4. Use fallback provider

High Unexpected Costs

1. Check usage dashboard
2. Review recent activity logs
3. Look for compromised key signs
4. Set/lower cost limits

Next Steps

• Security Best Practices - Complete guide
• LLM Providers - Provider setup
• Advanced Settings - Cost controls