--- name: credential-manager description: MANDATORY security foundation for OpenClaw. Consolidate scattered API keys and credentials into a secure .env file with proper permissions. Includes GPG encryption for high-value secrets, credential rotation tracking, deep scanning, and backup hardening. Use when setting up OpenClaw, migrating credentials, auditing security, or enforcing the .env standard. This is not optional — centralized credential management is a core requirement for secure OpenClaw deployments. ---

Credential Manager

STATUS: MANDATORY SECURITY FOUNDATION

Consolidate scattered API keys and credentials into a secure, centralized .env file.

⚠️ This Is Not Optional

Centralized .env credential management is a core requirement for OpenClaw security. If your credentials are scattered across multiple files, stop and consolidate them now.

THE RULE: All credentials MUST be in ~/.openclaw/.env ONLY. No workspace, no skills, no scripts directories.

See:

• CORE-PRINCIPLE.md - Why this is non-negotiable
• CONSOLIDATION-RULE.md - The single source principle

The Foundation

Every OpenClaw deployment MUST have:

~/.openclaw/.env (mode 600)

This is your single source of truth for all credentials. No exceptions.

Why?

• Single location = easier to secure
• File mode 600 = only you can read
• Git-ignored = won't accidentally commit
• Validated format = catches errors
• Audit trail = know what changed

Scattered credentials = scattered attack surface. This skill fixes that.

What This Skill Does

1. Scans for credentials in common locations (including deep scan for hardcoded secrets)
2. Backs up existing credential files (timestamped, mode 600)
3. Consolidates into ~/.openclaw/.env
4. Secures with proper permissions (600 files, 700 directories)
5. Validates security, format, and entropy
6. Encrypts high-value secrets with GPG (wallet keys, private keys, mnemonics)
7. Tracks credential rotation schedules
8. Enforces best practices via fail-fast checks
9. Cleans up old files after migration

Detection Parameters

The skill automatically detects credentials by scanning for:

File Patterns:

• ~/.config/*/credentials.json — Service config directories
• ~/.config//.credentials.json — Nested credential files
• ~/.openclaw/*.json — Credential files in OpenClaw root
• ~/.openclaw/-credentials — Named credential files (e.g., farcaster-credentials.json)
• ~/.openclaw/workspace/memory/*-creds.json — Memory credential files
• ~/.openclaw/workspace/memory/credentials.json — Memory credential files
• ~/.openclaw/workspace/.env — Workspace env files
• ~/.openclaw/workspace/*/.env — Subdirectory env files
• ~/.openclaw/workspace/skills/*/.env — Skill env files
• ~/.local/share/*/credentials.json — Local share directories

Sensitive Key Patterns:

• API keys, access tokens, bearer tokens
• Secrets, passwords, passphrases
• OAuth consumer keys
• Private keys, signing keys, wallet keys
• Mnemonics and seed phrases

Deep Scan (--deep flag):

• Greps .sh, .js, .py, .mjs, .ts files for hardcoded secrets
• Detects high-entropy strings matching common key prefixes (sk_, pk_, Bearer, 0x + 64 hex)
• Excludes node_modules/, .git/
• Reports file, line number, and key pattern matched

Security Checks:

• File permissions (must be 600 for files, 700 for directories)
• Backup permissions (must be 600 for backup files, 700 for backup dirs)
• Git-ignore protection
• Format validation (allows quoted values with spaces)
• Entropy analysis (flags suspiciously low-entropy secrets)
• Private key detection (flags 0x + 64 hex char values)
• Mnemonic detection (flags 12/24 word values)
• Symlink detection (validates symlinked .env targets)

Quick Start

Full Migration (Recommended)

# Scan for credentials
./scripts/scan.py

# Deep scan (includes hardcoded secrets in scripts)
./scripts/scan.py --deep

# Review and consolidate
./scripts/consolidate.py

# Validate security
./scripts/validate.py

# Encrypt high-value secrets
./scripts/encrypt.py --keys MAIN_WALLET_PRIVATE_KEY,CUSTODY_PRIVATE_KEY

# Check rotation status
./scripts/rotation-check.py

Individual Operations

# Scan only
./scripts/scan.py

# Consolidate specific service
./scripts/consolidate.py --service x

# Backup without removing
./scripts/consolidate.py --backup-only

# Clean up old files
./scripts/cleanup.py --confirm

Common Credential Locations

The skill scans these locations:

~/.config/*/credentials.json
~/.openclaw/*.json
~/.openclaw/*-credentials*
~/.openclaw/workspace/memory/*-creds.json
~/.openclaw/workspace/memory/*credentials*.json
~/.openclaw/workspace/*/.env
~/.openclaw/workspace/skills/*/.env
~/.env (if exists, merges)

Security Features

✅ File permissions: Sets .env to mode 600 (owner only) ✅ Directory permissions: Sets backup dirs to mode 700 (owner only) ✅ Backup permissions: Sets backup files to mode 600 (owner only) ✅ Git protection: Creates/updates .gitignore ✅ Backups: Timestamped backups before changes (secured) ✅ Validation: Checks format, permissions, entropy, and duplicates ✅ Template: Creates .env.example (safe to share) ✅ GPG encryption: Encrypts high-value secrets at rest ✅ Rotation tracking: Warns when credentials need rotation ✅ Deep scan: Detects hardcoded secrets in source files ✅ Symlink-aware: Validates symlinked .env targets

Output Structure

After migration:

~/.openclaw/
├── .env                     # All credentials (secure, mode 600)
├── .env.secrets.gpg         # GPG-encrypted high-value keys (mode 600)
├── .env.meta                # Rotation metadata (mode 600)
├── .env.example             # Template (safe to share)
├── .gitignore               # Protects .env and .env.secrets.gpg
└── backups/                 # (mode 700)
    └── credentials-old-YYYYMMDD/  # (mode 700)
        └── *.bak            # Backup files (mode 600)

GPG Encryption for High-Value Secrets

Private keys, wallet keys, and mnemonics should never exist as plaintext on disk. Use GPG encryption for these.

Setup GPG

# First-time setup (generates OpenClaw GPG key, configures agent cache)
./scripts/setup-gpg.sh

Encrypt High-Value Keys

# Encrypt specific keys (moves them from .env to .env.secrets.gpg)
./scripts/encrypt.py --keys MAIN_WALLET_PRIVATE_KEY,CUSTODY_PRIVATE_KEY,SIGNER_PRIVATE_KEY

# The .env will contain placeholders:
# MAIN_WALLET_PRIVATE_KEY=GPG:MAIN_WALLET_PRIVATE_KEY

How Scripts Access Encrypted Keys

The enforce.py module handles this transparently:

from enforce import get_credential

# Works for both plaintext and GPG-encrypted keys
key = get_credential('MAIN_WALLET_PRIVATE_KEY')
# If value starts with "GPG:", decrypts from .env.secrets.gpg automatically

GPG Agent Caching

On headless servers (VPS), the GPG agent caches the passphrase:

• Default cache TTL: 8 hours
• Configurable via setup-gpg.sh
• Passphrase required once after reboot, then cached

What to Encrypt

| Key Type | Encrypt? | Why | |----------|----------|-----| | Wallet private keys | ✅ Yes | Controls funds | | Custody/signer private keys | ✅ Yes | Controls identity | | Mnemonics / seed phrases | ✅ Yes | Master recovery | | API keys (services) | ❌ No | Revocable, low damage | | Agent IDs, names, URLs | ❌ No | Not secrets |

Credential Rotation Tracking

Setup Rotation Metadata

# Initialize rotation tracking for all keys
./scripts/rotation-check.py --init

...