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 · 1Password plugin · SecretRef Credential Surface · Security

​
Reload runtime snapshot

Uses gateway RPC method secrets.reload. Healthy owners refresh independently. Eligible failed owners become stale only when their ref identities, provider definitions, and complete non-secret owner contract are unchanged; new or changed failures become cold. This degraded activation succeeds and reports warningCount. Strict or unmapped failures return an error and preserve the previously active snapshot. 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)
The .env scan covers the effective state directory and the directory containing the active config. When both paths name the same file, it is scanned once. 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.
  • --plan-out refuses to create a plan whose UTF-8 serialized form exceeds 16 MiB (16,777,216 bytes), matching the apply --from input limit.
  • 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. --from must point to a regular file no larger than 16 MiB (16,777,216 bytes). The byte limit applies to the complete serialized file, including whitespace. What apply may update:
  • openclaw.json (SecretRef targets + provider upserts/deletes)
  • auth-profiles.json (provider-target scrubbing)
  • legacy auth.json residues
  • .env files in the effective state and active-config directories, for 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.