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

Use openclaw secrets to manage SecretRefs and keep the active runtime snapshot healthy.

Command roles:

• reload: gateway RPC (secrets.reload) that re-resolves refs and swaps runtime snapshot only on full success (no config writes).
• audit: read-only scan of configuration/auth/generated-model stores and legacy residues for plaintext, unresolved refs, and precedence drift (exec refs are skipped unless --allow-exec is set).
• configure: interactive planner for provider setup, target mapping, and preflight (TTY required).
• apply: execute a saved plan (--dry-run for validation only; dry-run skips exec checks by default, and write mode rejects exec-containing plans unless --allow-exec is set), then scrub targeted plaintext residues.

Recommended operator loop:

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

If your plan includes exec SecretRefs/providers, pass --allow-exec on both dry-run and write apply commands.

Exit code note for CI/gates:

• audit --check returns 1 on findings.
• unresolved refs return 2.

Related:

• Secrets guide: Secrets Management
• Credential surface: SecretRef Credential Surface
• Security guide: Security

Reload runtime snapshot

Re-resolve secret refs and atomically swap runtime snapshot.

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

Notes:

• Uses gateway RPC method secrets.reload.
• If resolution fails, gateway keeps last-known-good snapshot and returns an error (no partial activation).
• JSON response includes warningCount.

Options:

• --url <url>
• --token <token>
• --timeout <ms>
• --json

Audit

Scan OpenClaw state for:

• plaintext secret storage
• unresolved refs
• precedence drift (SQLite auth-profile credentials shadowing openclaw.json refs)
• stored model catalog residues (provider apiKey values and sensitive provider headers)
• legacy residues (legacy auth store entries, OAuth reminders)

Header residue note:

• Sensitive provider header detection is name-heuristic based (common auth/credential header names and fragments such as authorization, x-api-key, token, secret, password, and credential).

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

Exit behavior:

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

Report shape highlights:

• 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

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.
• --agent <id>: scope SQLite auth-profile target discovery and writes to one agent store.
• --allow-exec: allow exec SecretRef checks during preflight/apply (may execute provider commands).

Notes:

• Requires an interactive TTY.
• You cannot combine --providers-only with --skip-provider-setup.
• configure targets secret-bearing fields in openclaw.json plus SQLite auth-profile rows for the selected agent scope.
• configure supports creating new auth-profile mappings directly in the picker flow.
• Canonical supported surface: SecretRef Credential Surface.
• It performs preflight resolution before apply.
• If preflight/apply includes exec refs, keep --allow-exec set for both steps.
• Generated plans default to scrub options (scrubEnv, scrubAuthProfilesForProviderTargets, scrubLegacyAuthJson all enabled).
• Apply path is one-way for scrubbed plaintext values.
• Without --apply, CLI still prompts Apply this plan now? after preflight.
• With --apply (and no --yes), CLI prompts an extra irreversible confirmation.
• --json prints the plan + preflight report, but the command still requires an interactive TTY.

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"]).
• 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 path security checks.

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 --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

Exec behavior:

• --dry-run validates preflight without writing files.
• exec SecretRef checks are skipped by default in dry-run.
• write mode rejects plans that contain exec SecretRefs/providers unless --allow-exec is set.
• Use --allow-exec to opt in to exec provider checks/execution in either mode.

Plan contract details (allowed target paths, validation rules, and failure semantics):

• Secrets Apply Plan Contract

What apply may update:

• openclaw.json (SecretRef targets + provider upserts/deletes)
• SQLite auth-profile rows (provider-target scrubbing)
• legacy auth.json residues
• ~/.openclaw/.env known 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 + atomic-ish apply 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.

Related

• CLI reference
• Secrets management