🔐 OpenClaw Secure

Hardware-gated secret management for AI agents.
Your AI can read your config files. This stops that from being a problem.

---

⬆️ 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

macOS Keychain (default)

No setup. Just works on macOS.

openclaw-secure store

1Password (recommended)

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

Enable biometric unlock for Touch ID on every secret read.

Bitwarden

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

AWS Secrets Manager

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

Google Cloud

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

Azure Key Vault

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

pass

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

Doppler

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

HashiCorp Vault

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.

---

🦞 Part of the OpenClaw ecosystem
Secure your crustacean.

License

MIT © Michael Waltman