Introduction
# 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](CORE-PRINCIPLE.md) - Why this is non-negotiable - [CONSOLIDATION-RULE.md](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 2. **Backs up** existing credential files (timestamped) 3. **Consolidates** into `~/.openclaw/.env` 4. **Secures** with proper permissions (600) 5. **Validates** security and format 6. **Enforces** best practices 7. **Cleans up** old files after migration
## Detection Parameters
The skill automatically detects credentials by scanning for:
**File Patterns:** - `credentials.json` files in config directories - `.env` files - Memory files with `-creds` or `credentials` in the name
**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
**Security Checks:** - File permissions (must be `600`) - Git-ignore protection - Format validation
## Quick Start
### Full Migration (Recommended)
```bash # Scan for credentials ./scripts/scan.py
# Review and consolidate ./scripts/consolidate.py
# Validate security ./scripts/validate.py ```
### Individual Operations
```bash # 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/workspace/memory/*-creds.json ~/.openclaw/workspace/memory/*credentials*.json ~/.env (if exists, merges) ```
## Security Features
✅ **File permissions:** Sets `.env` to mode 600 (owner only) ✅ **Git protection:** Creates/updates `.gitignore` ✅ **Backups:** Timestamped backups before changes ✅ **Validation:** Checks format, permissions, and duplicates ✅ **Template:** Creates `.env.example` (safe to share)
## Output Structure
After migration:
``` ~/.openclaw/ ├── .env # All credentials (secure) ├── .env.example # Template (safe) ├── .gitignore # Protects .env ├── CREDENTIALS.md # Documentation └── backups/ └── credentials-old-YYYYMMDD/ # Backup of old files ```
## Supported Services
Common services auto-detected:
- **X (Twitter):** OAuth 1.0a credentials - **Molten:** Agent intent matching - **Moltbook:** Agent social network - **Botchan/4claw:** Net Protocol - **OpenAI, Anthropic, Google:** AI providers - **GitHub, GitLab:** Code hosting - **Generic:** `API_KEY`, `*_TOKEN`, `*_SECRET` patterns
See [references/supported-services.md](references/supported-services.md) for full list.
## Security Best Practices
See [references/security.md](references/security.md) for detailed security guidelines.
**Quick checklist:** - ✅ `.env` has 600 permissions - ✅ `.env` is git-ignored - ✅ No credentials in code or logs - ✅ Rotate keys periodically - ✅ Use separate keys per environment
## Scripts
All scripts support `--help` for detailed usage.
### scan.py ```bash # Scan and report ./scripts/scan.py
# Include custom paths ./scripts/scan.py --paths ~/.myapp/config ~/.local/share/creds
# JSON output ./scripts/scan.py --format json ```
### consolidate.py ```bash # Interactive mode (prompts before changes) ./scripts/consolidate.py
# Auto-confirm (no prompts) ./scripts/consolidate.py --yes
# Backup only ./scripts/consolidate.py --backup-only
# Specific service ./scripts/consolidate.py --service molten ```
### validate.py ```bash # Full validation ./scripts/validate.py
# Check permissions only ./scripts/validate.py --check permissions
# Fix issues automatically ./scripts/validate.py --fix ```
### cleanup.py ```bash # Dry run (shows what would be deleted) ./scripts/cleanup.py
# Actually delete old files ./scripts/cleanup.py --confirm
# Keep backups ./scripts/cleanup.py --confirm --keep-backups ```
## Migration Workflow
**Step 1: Discovery** ```bash ./scripts/scan.py ``` Review output to see what will be migrated.
**Step 2: Backup & Consolidate** ```bash ./scripts/consolidate.py ``` Creates backups, builds `.env`, sets permissions.
**Step 3: Validation** ```bash ./scripts/validate.py ``` Ensures everything is secure and correct.
**Step 4: Test** Test your applications/skills with the new `.env` file.
**Step 5: Cleanup** ```bash ./scripts/cleanup.py --confirm ``` Removes old credential files (backups remain).
## For Skill Developers: Enforce This Standard
Other OpenClaw skills MUST validate credentials are secure before using them:
### Python Skills ```python #!/usr/bin/env python3 import sys from pathlib import Path
# Add credential-manager scripts to path sys.path.insert(0, str(Path.home() / '.openclaw/skills/credential-manager/scripts'))
# Enforce secure .env (exits if not compliant) from enforce import require_secure_env, get_credential
require_secure_env()
# Now safe to load credentials api_key = get_credential('SERVICE_API_KEY') ```
### Bash Skills ```bash #!/usr/bin/env bash set -euo pipefail
# Validate .env exists and is secure if ! python3 ~/.openclaw/skills/credential-manager/scripts/enforce.py; then exit 1 fi
# Now safe to load source ~/.openclaw/.env ```
**This creates a fail-fast system:** If credentials aren't properly secured, skills refuse to run. Users are forced to fix it.
## Loading Credentials
After migration, load from `.env`:
### Python ```python import os from pathlib import Path
# Load .env env_file = Path.home() / '.openclaw' / '.env' with open(env_file) as f: for line in f: if '=' in line and not line.strip().startswith('#'): key, val = line.strip().split('=', 1) os.environ[key] = val
# Use credentials api_key = os.getenv('SERVICE_API_KEY') ```
### Bash ```bash # Load .env set -a source ~/.openclaw/.env set +a
# Use credentials echo "$SERVICE_API_KEY" ```
### Using Existing Loaders If you migrated using OpenClaw scripts: ```python from load_credentials import get_credentials creds = get_credentials('x') ```
## Adding New Credentials
Edit `~/.openclaw/.env`: ```bash # Add new service NEW_SERVICE_API_KEY=your_key_here NEW_SERVICE_SECRET=your_secret_here ```
Update template too: ```bash # Edit .env.example NEW_SERVICE_API_KEY=your_key_here NEW_SERVICE_SECRET=your_secret_here ```
## Rollback
If something goes wrong:
```bash # Find your backup ls -la ~/.openclaw/backups/
# Restore specific file cp ~/.openclaw/backups/credentials-old-YYYYMMDD/x-credentials.json.bak \ ~/.config/x/credentials.json ```
## Notes
- **Non-destructive by default:** Original files backed up before removal - **Idempotent:** Safe to run multiple times - **Extensible:** Add custom credential patterns in scripts - **Secure:** Never logs full credentials, only metadata