openclaw secrets CLI reference

`openclaw secrets`

Oversee SecretRefs and maintain a healthy active runtime snapshot.

Command	Role
`reload`	Gateway RPC (`secrets.reload`): re-resolves references and atomically publishes the owner-aware runtime snapshot without writing config; eligible owner failures may produce cold or stale warnings
`audit`	Read-only inspection of config, auth, generated-model stores, and legacy residues for plaintext, unresolved references, and precedence drift (exec references are excluded unless `--allow-exec`)
`configure`	Interactive planner for provider configuration, target mapping, and preflight checks (requires a TTY)
`apply`	Runs a stored plan (`--dry-run` only validates and skips exec checks by default; write mode rejects plans with exec references unless `--allow-exec`), then removes targeted plaintext residues

Recommended operator cycle:

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload

When your plan contains exec SecretRefs or providers, supply --allow-exec on both the dry-run and write apply commands.

Exit codes for CI or gating:

audit --check returns 1 when findings exist.
Unresolved references return 2 (irrespective of --check).

Reload runtime snapshot

openclaw secrets reload
openclaw secrets reload --json
openclaw secrets reload --url ws://127.0.0.1:18789 --token <token>

Uses the gateway RPC method secrets.reload. Healthy owners refresh independently. Eligible failed owners become stale only when their ref identities, provider definitions, and the complete non-secret owner contract remain unchanged; new or changed failures turn cold. This degraded activation succeeds and reports warningCount. Strict or unmapped failures produce an error and keep the previously active snapshot.

Options: --url <url>, --token <token>, --timeout <ms>, --json.

Audit

Scans OpenClaw state for:

plaintext secret storage
unresolved references
precedence drift (auth-profiles.json credentials overshadowing openclaw.json references)
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 holding the active config. If both paths point to the same file, it is scanned once.

Sensitive provider header detection uses a name heuristic: it marks headers whose name matches common auth or credential fragments (authorization, x-api-key, token, secret, password, credential).

openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec

Report structure:

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:

openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json

Workflow: configure providers first (add, edit, or remove secrets.providers aliases), then map credentials (select fields, assign {source, provider, id} references), then preflight and optionally apply.

Flags:

--providers-only: sets only secrets.providers, skips credential mapping
--skip-provider-setup: bypasses provider setup, maps credentials to already existing providers
--agent <id>: limits auth-profiles.json target discovery and writes to a single agent store
--allow-exec: enables exec SecretRef checks during preflight/apply (may trigger provider commands)

--providers-only and --skip-provider-setup are mutually exclusive.

Notes:

An interactive TTY is required.
Targets secret-bearing fields in openclaw.json and auth-profiles.json for the chosen agent scope; the canonical supported surface is: SecretRef Credential Surface.
New auth-profiles.json mappings can be created directly within the picker flow.
Preflight resolution runs before apply.
Generated plans have scrub options enabled by default (scrubEnv, scrubAuthProfilesForProviderTargets, scrubLegacyAuthJson). Apply is irreversible for scrubbed plaintext values.
--plan-out will not generate 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.
When --apply is set (and --yes is not), the CLI prompts an additional irreversible-migration confirmation.
--json outputs the plan and preflight report, but still requires an interactive TTY.

Exec provider safety

Symlinked binaries from Homebrew installs often reside under /opt/homebrew/bin/*. Only set allowSymlinkCommand: true when needed for trusted package-manager paths, and pair it 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

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json

--dry-run validates preflight without writing files; exec SecretRef checks are skipped by default in dry-run. Write mode rejects plans that include exec SecretRefs or providers unless --allow-exec is present. Use --allow-exec to opt into exec provider checks or 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 entire serialized file, including whitespace.

What apply may update:

openclaw.json (SecretRef targets and provider upserts or 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 avoids writing rollback backups that contain old plaintext values. Safety is achieved through strict preflight combined with atomic-ish apply, along with best-effort in-memory restore on failure.

Example

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

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