openclaw/docs/cli/secrets.md

summary, read_when, title

summary	read_when	title
CLI reference for `openclaw secrets` (reload, audit, configure, apply)	Re-resolving secret refs at runtime Auditing plaintext residues and unresolved refs Configuring SecretRefs and applying one-way scrub changes	secrets

openclaw secrets

Secrets runtime controls.

Related:

• Secrets guide: Secrets Management
• Security guide: Security

Reload runtime snapshot

Re-resolve secret refs and atomically swap runtime snapshot.

openclaw secrets reload
openclaw secrets reload --json

Notes:

• Uses gateway RPC method secrets.reload.
• If resolution fails, gateway keeps last-known-good snapshot.
• JSON response includes warningCount.

Audit

Scan OpenClaw state for:

• plaintext secret storage
• unresolved refs
• precedence drift (auth-profiles shadowing config refs)
• legacy residues (auth.json, OAuth out-of-scope notes)

openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json

Exit behavior:

• --check exits non-zero on findings.
• unresolved refs exit with a higher-priority non-zero code.

Configure (interactive helper)

Build provider + 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 --json

Flow:

• Provider setup first (add/edit/remove for secrets.providers aliases).
• Credential mapping second (select fields and assign {source, provider, id} refs).
• Preflight and optional apply last.

Flags:

• --providers-only: configure secrets.providers only, skip credential mapping.
• --skip-provider-setup: skip provider setup and map credentials to existing providers.

Notes:

• configure targets secret-bearing fields in openclaw.json.
• Include all secret-bearing fields you intend to migrate (for example both models.providers.*.apiKey and skills.entries.*.apiKey) so audit can reach a clean state.
• It performs preflight resolution before apply.
• Apply path is one-way for migrated plaintext values.

Exec provider safety note:

• Homebrew installs often expose symlinked binaries under /opt/homebrew/bin/*.
• Set allowSymlinkCommand: true only when needed for trusted package-manager paths, and pair it with trustedDirs (for example ["/opt/homebrew"]).

Apply a saved plan

Apply or preflight a plan generated previously:

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

Plan contract details (allowed target paths, validation rules, and 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 + atomic-ish apply with best-effort in-memory restore on failure.

Example

# Audit first, then configure, then confirm clean:
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

If audit --check still reports plaintext findings after a partial migration, verify you also migrated skill keys (skills.entries.*.apiKey) and any other reported target paths.