openclaw secrets
Manage SecretRefs and keep the active runtime snapshot healthy.
| Command | Role |
|---|---|
reload | Gateway RPC (secrets.reload): re-resolves refs and swaps the runtime snapshot only on full success (no config writes) |
audit | Read-only scan of config/auth/generated-model stores and legacy residues for plaintext, unresolved refs, and precedence drift (exec refs skipped unless --allow-exec) |
configure | Interactive planner for provider setup, target mapping, and preflight (requires a TTY) |
apply | Executes a saved plan (--dry-run validates only and skips exec checks by default; write mode rejects exec-containing plans unless --allow-exec), then scrubs targeted plaintext residues |
exec SecretRefs/providers, pass --allow-exec on both the dry-run and write apply commands.
Exit codes for CI/gates:
audit --checkreturns1on findings.- Unresolved refs return
2(regardless of--check).
Reload runtime snapshot
secrets.reload. If resolution fails, the gateway keeps its last-known-good snapshot and returns an error (no partial activation). JSON response includes warningCount.
Options: --url <url>, --token <token>, --timeout <ms>, --json.
Audit
Scans OpenClaw state for:- plaintext secret storage
- unresolved refs
- precedence drift (
auth-profiles.jsoncredentials shadowingopenclaw.jsonrefs) - generated
agents/*/agent/models.jsonresidues (providerapiKeyvalues and sensitive provider headers) - legacy residues (legacy auth store entries, OAuth reminders)
authorization, x-api-key, token, secret, password, credential).
status:clean | findings | unresolvedresolution:refsChecked,skippedExecRefs,resolvabilityCompletesummary:plaintextCount,unresolvedRefCount,shadowedRefCount,legacyResidueCount- finding codes:
PLAINTEXT_FOUND,REF_UNRESOLVED,REF_SHADOWED,LEGACY_RESIDUE
Configure (interactive helper)
Build provider and SecretRef changes interactively, run preflight, and optionally apply:secrets.providers aliases), then credential mapping (select fields, assign {source, provider, id} refs), then preflight and optional apply.
Flags:
--providers-only: configuresecrets.providersonly, skip credential mapping--skip-provider-setup: skip provider setup, map credentials to existing providers--agent <id>: scopeauth-profiles.jsontarget discovery and writes to one agent store--allow-exec: allow exec SecretRef checks during preflight/apply (may execute provider commands)
--providers-only and --skip-provider-setup cannot be combined.
Notes:
- Requires an interactive TTY.
- Targets secret-bearing fields in
openclaw.jsonplusauth-profiles.jsonfor the selected agent scope; canonical supported surface: SecretRef Credential Surface. - Supports creating new
auth-profiles.jsonmappings directly in the picker flow. - Runs preflight resolution before apply.
- Generated plans default to scrub options enabled (
scrubEnv,scrubAuthProfilesForProviderTargets,scrubLegacyAuthJson). Apply is one-way for scrubbed plaintext values. - Without
--apply, the CLI still promptsApply this plan now?after preflight. - With
--apply(and no--yes), the CLI prompts an extra irreversible-migration confirmation. --jsonprints the plan + preflight report, but still requires an interactive TTY.
Exec provider safety
Homebrew installs often expose symlinked binaries under/opt/homebrew/bin/*. Set allowSymlinkCommand: true only when needed for trusted package-manager paths, paired with trustedDirs (for example ["/opt/homebrew"]). On Windows, if ACL verification is unavailable for a provider path, OpenClaw fails closed; for trusted paths only, set allowInsecurePath: true on that provider to bypass the path security check.
Apply a saved plan
--dry-run validates preflight without writing files; exec SecretRef checks are skipped by default in dry-run. Write mode rejects plans containing exec SecretRefs/providers unless --allow-exec. Use --allow-exec to opt in to exec provider checks/execution in either mode.
What apply may update:
openclaw.json(SecretRef targets + provider upserts/deletes)auth-profiles.json(provider-target scrubbing)- legacy
auth.jsonresidues ~/.openclaw/.envknown secret keys whose values were migrated
Why no rollback backups
secrets apply intentionally does not write rollback backups containing old plaintext values. Safety comes from strict preflight plus atomic-ish apply, with best-effort in-memory restore on failure.
Example
audit --check still reports plaintext findings, update the remaining reported target paths and rerun audit.