Skip to main content

​
openclaw secrets

Manage SecretRefs and keep the active runtime snapshot healthy. Recommended operator loop:
If your plan includes exec SecretRefs/providers, pass --allow-exec on both the dry-run and write apply commands. Exit codes for CI/gates:
  • audit --check returns 1 on findings.
  • Unresolved refs return 2 (regardless of --check).
Related: Secrets Management · SecretRef Credential Surface · Security

​
Reload runtime snapshot

Uses gateway RPC method 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.json credentials shadowing openclaw.json refs)
  • generated agents/*/agent/models.json residues (provider apiKey values and sensitive provider headers)
  • legacy residues (legacy auth store entries, OAuth reminders)
Sensitive provider header detection is name-heuristic based: it flags headers whose name matches common auth/credential fragments (authorization, x-api-key, token, secret, password, credential).
Report shape:
  • status: clean | findings | unresolved
  • resolution: refsChecked, skippedExecRefs, resolvabilityComplete
  • summary: 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:
Flow: provider setup first (add/edit/remove secrets.providers aliases), then credential mapping (select fields, assign {source, provider, id} refs), then preflight and optional apply. Flags:
  • --providers-only: configure secrets.providers only, skip credential mapping
  • --skip-provider-setup: skip provider setup, map credentials to existing providers
  • --agent <id>: scope auth-profiles.json target 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.json plus auth-profiles.json for the selected agent scope; canonical supported surface: SecretRef Credential Surface.
  • Supports creating new auth-profiles.json mappings 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 prompts Apply this plan now? after preflight.
  • With --apply (and no --yes), the CLI prompts an extra irreversible-migration confirmation.
  • --json prints 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.json residues
  • ~/.openclaw/.env known secret keys whose values were migrated
Plan contract details (allowed target paths, validation rules, failure semantics): Secrets Apply Plan Contract.

​
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

If audit --check still reports plaintext findings, update the remaining reported target paths and rerun audit.