⬆️ Existing Users: Upgrade to v2.x

Already using openclaw-secure? Here's how to upgrade:

# 1. Update the package
npm install -g openclaw-secure@latest

# 2. Done! Migration happens automatically on next start.

What Changed

| v1.x | v2.x | |------|------| | Hardcoded secret paths | Auto-discovers all secrets | | Manual DEFAULT_SECRET_MAP | Scans your entire config | | Fixed keychain names | Dynamic names from paths |

Migration Details

Your existing secrets are automatically migrated on first start:

🚀 Secure gateway start (keychain, auto-discovery)...

  ✔ Migrated 2 legacy key(s)
  → Restoring keys from keychain...

To migrate manually (optional):

openclaw-secure migrate
openclaw-secure check    # verify everything moved

LaunchAgent (macOS Boot)

No action needed. Your existing LaunchAgent calls openclaw-secure start, which now auto-migrates and auto-discovers.

🚀 New Users: Quick Start

# 1. Install
npm install -g openclaw-secure

# 2. Store your secrets (auto-discovers everything)
openclaw-secure store

# 3. Start the gateway securely
openclaw-secure start

Your config file now has [STORED_IN_KEYCHAIN] placeholders. Secrets exist only in memory while the gateway runs.

For Boot Security (macOS)

openclaw-secure install    # patches LaunchAgent
# Now every reboot is secure

📋 TL;DR — Usage Reference

Commands

| Command | What it does | |---------|--------------| | discover | Preview secrets found in your config | | store | Move secrets to backend, replace with placeholders | | start | Restore → start gateway → scrub (for boot) | | check | Verify all secrets exist in backend | | restore | Write real values back to config | | migrate | Move v1.x keychain names to v2.x | | install | Patch LaunchAgent for secure boot | | uninstall | Restore original LaunchAgent |

Common Flags

--backend <name>     # keychain, 1password, bitwarden, aws, gcloud, azure, pass, doppler, vault
--exclude <path>     # Skip paths (e.g., "channels.dev.*")
--also <path>        # Add custom paths
--no-auto            # Use legacy hardcoded paths

Backends by Security Level

| Level | Backend | Why | |-------|---------|-----| | 🟢 Easy | keychain | Zero setup, macOS only | | 🟡 Better | aws, gcloud, azure | Audit logs | | 🔴 Best | 1password | Biometric = hardware gate |

🔐 Why This Exists

Your AI agent can run shell commands and read files. Your API keys are in ~/.openclaw/openclaw.json:

channels.telegram.botToken: "7234891:AAF..."   ← agent can cat this
gateway.auth.token: "sk-proj-..."               ← prompt injection = game over

Prompt injection attacks trick your AI into exfiltrating secrets. One malicious webpage can instruct the agent to read and send your keys.

OpenClaw Secure moves secrets to hardware-protected storage. Config files only have placeholders.

🔒 Backend Setup

No setup. Just works on macOS.

openclaw-secure store

brew install --cask 1password-cli
op signin
openclaw-secure store --backend 1password --vault Private

Enable biometric unlock for Touch ID on every secret read.

npm install -g @bitwarden/cli
bw login && bw unlock
export BW_SESSION="..."
openclaw-secure store --backend bitwarden

aws configure
openclaw-secure store --backend aws --region us-east-1

gcloud auth login
openclaw-secure store --backend gcloud --project my-project

az login
openclaw-secure store --backend azure --vault-name my-vault

pass init <gpg-id>
openclaw-secure store --backend pass

doppler login
openclaw-secure store --backend doppler --doppler-project myapp --doppler-config prd

vault login
openclaw-secure store --backend vault --addr http://127.0.0.1:8200

⚙️ Config

Save defaults to ~/.openclaw-secure.json:

{
  "backend": "1password",
  "vault": "Private"
}

📦 API

import { discoverSecrets, autoStoreKeys, createBackend } from 'openclaw-secure';

const backend = createBackend('1password', { vault: 'Private' });
const results = await autoStoreKeys('~/.openclaw/openclaw.json', backend);

🛡️ Security Model

Protects against:

• ✅ Config file reads (placeholders only)
• ✅ Prompt injection exfiltration
• ✅ Accidental git commits
• ✅ Shoulder surfing

Does NOT protect against:

• ❌ Memory inspection (secrets in RAM while running)
• ❌ Root access
• ❌ Backend compromise

⚠️ Hot-Reload Limitation

Config changes while running will crash the gateway.

OpenClaw hot-reloads openclaw.json when it detects changes. After openclaw-secure start, the config contains [STORED_IN_KEYCHAIN] placeholders. If OpenClaw reloads, it tries to use these placeholders as actual API keys — and fails.

This is inherent to wrapping OpenClaw externally. Secrets must stay off disk to prevent prompt injection.

🔄 Changing Models

# 1. Restore your secrets
openclaw-secure restore

Now OpenClaw works normally. Use /model to switch models, change settings, whatever you need.

# 2. When you're done, lock it back down
openclaw-secure start

That's it. Restore → make changes → start.

Bottom line: With 1Password biometric, even a fully compromised agent session cannot extract secrets without your fingerprint.

License

MIT © Michael Waltman