New Secrets Manager

[frigid cipher]

How do we use the new secrets manager that came out in the latest release?

[limpid girder]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[torpid marsh]

OpenClaw’s “secrets manager” is basically SecretRefs + secret providers. You can keep using plaintext keys, but the new flow lets you store references in config/auth files and have the Gateway resolve the actual secret at startup (and on reload) into an in-memory snapshot.

Docs:

• Secrets overview + config fields: https://docs.openclaw.ai/gateway/secrets
• CLI commands (audit/configure/apply/reload): https://docs.openclaw.ai/cli/secrets

The quickest way (recommended): migrate interactively

Run this on the Gateway host:

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check
openclaw secrets reload

What you get:

• audit tells you where secrets are still stored in plaintext (openclaw.json, auth-profiles.json, .env, legacy auth.json)
• configure walks you through:
  1. setting up secret providers (env, file, or exec)
  2. mapping secret-bearing fields to SecretRefs
  3. preflighting resolution
  4. (optionally) applying + scrubbing old plaintext residues
• reload re-resolves refs and atomically swaps the runtime secrets snapshot (no partial state)

What a SecretRef looks like

Same shape everywhere:

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

Examples:

1) Pull from an env var

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

2) Pull from a local JSON secrets file (JSON pointer)

~/.openclaw/secrets.json:

{ "providers": { "openai": { "apiKey": "sk-..." } } }

Config ref:

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

3) Pull from an external tool (1Password/Vault/sops/etc)