Secrets

text

Copy

openclaw secrets

Use

to manage SecretRefs and keep the active runtime snapshot healthy.

Command roles:

• text

  Copy

  reload
  : gateway RPC (
  text

  Copy

  secrets.reload
  ) that re-resolves refs and swaps runtime snapshot only on full success (no config writes).
• text

  Copy

  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
  text

  Copy

  --allow-exec
  is set).
• text

  Copy

  configure
  : interactive planner for provider setup, target mapping, and preflight (TTY required).
• text

  Copy

  apply
  : execute a saved plan (
  text

  Copy

  --dry-run
  for validation only; dry-run skips exec checks by default, and write mode rejects exec-containing plans unless
  text

  Copy

  --allow-exec
  is set), then scrub targeted plaintext residues.

Recommended operator loop:

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

SecretRefs/providers, pass on both dry-run and write apply commands.

Exit code note for CI/gates:

• text

  Copy

  audit --check
  returns
  text

  Copy

  1
  on findings.
• unresolved refs return
  text

  Copy

  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.

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

Notes:

• Uses gateway RPC method
  text

  Copy

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

  Copy

  warningCount
  .

Options:

• text

  Copy

  --url <url>
• text

  Copy

  --token <token>
• text

  Copy

  --timeout <ms>
• text

  Copy

  --json

Audit

Scan OpenClaw state for:

• plaintext secret storage
• unresolved refs
• precedence drift (
  text

  Copy

  auth-profiles.json
  credentials shadowing
  text

  Copy

  openclaw.json
  refs)
• generated
  text

  Copy

  agents/*/agent/models.json
  residues (provider
  text

  Copy

  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
  text

  Copy

  authorization
  ,
  text

  Copy

  x-api-key
  ,
  text

  Copy

  token
  ,
  text

  Copy

  secret
  ,
  text

  Copy

  password
  , and
  text

  Copy

  credential
  ).

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

Exit behavior:

• text

  Copy

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

Report shape highlights:

• text

  Copy

  status
  :
  text

  Copy

  clean | findings | unresolved
• text

  Copy

  resolution
  :
  text

  Copy

  refsChecked
  ,
  text

  Copy

  skippedExecRefs
  ,
  text

  Copy

  resolvabilityComplete
• text

  Copy

  summary
  :
  text

  Copy

  plaintextCount
  ,
  text

  Copy

  unresolvedRefCount
  ,
  text

  Copy

  shadowedRefCount
  ,
  text

  Copy

  legacyResidueCount
• finding codes:
  • text

    Copy

    PLAINTEXT_FOUND
  • text

    Copy

    REF_UNRESOLVED
  • text

    Copy

    REF_SHADOWED
  • text

    Copy

    LEGACY_RESIDUE

Configure (interactive helper)

Build provider and SecretRef changes interactively, run preflight, and optionally apply:

bash
Copy
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 (
  text

  Copy

  add/edit/remove
  for
  text

  Copy

  secrets.providers
  aliases).
• Credential mapping second (select fields and assign
  text

  Copy

  {source, provider, id}
  refs).
• Preflight and optional apply last.

Flags:

• text

  Copy

  --providers-only
  : configure
  text

  Copy

  secrets.providers
  only, skip credential mapping.
• text

  Copy

  --skip-provider-setup
  : skip provider setup and map credentials to existing providers.
• text

  Copy

  --agent <id>
  : scope
  text

  Copy

  auth-profiles.json
  target discovery and writes to one agent store.
• text

  Copy

  --allow-exec
  : allow exec SecretRef checks during preflight/apply (may execute provider commands).

Notes:

• Requires an interactive TTY.
• You cannot combine
  text

  Copy

  --providers-only
  with
  text

  Copy

  --skip-provider-setup
  .
• text

  Copy

  configure
  targets secret-bearing fields in
  text

  Copy

  openclaw.json
  plus
  text

  Copy

  auth-profiles.json
  for the selected agent scope.
• text

  Copy

  configure
  supports creating new
  text

  Copy

  auth-profiles.json
  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
  text

  Copy

  --allow-exec
  set for both steps.
• Generated plans default to scrub options (
  text

  Copy

  scrubEnv
  ,
  text

  Copy

  scrubAuthProfilesForProviderTargets
  ,
  text

  Copy

  scrubLegacyAuthJson
  all enabled).
• Apply path is one-way for scrubbed plaintext values.
• Without
  text

  Copy

  --apply
  , CLI still prompts
  text

  Copy

  Apply this plan now?
  after preflight.
• With
  text

  Copy

  --apply
  (and no
  text

  Copy

  --yes
  ), CLI prompts an extra irreversible confirmation.
• text

  Copy

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

  Copy

  /opt/homebrew/bin/*
  .
• Set
  text

  Copy

  allowSymlinkCommand: true
  only when needed for trusted package-manager paths, and pair it with
  text

  Copy

  trustedDirs
  (for example
  text

  Copy

  ["/opt/homebrew"]
  ).
• On Windows, if ACL verification is unavailable for a provider path, OpenClaw fails closed. For trusted paths only, set
  text

  Copy

  allowInsecurePath: true
  on that provider to bypass path security checks.

Apply a saved plan

Apply or preflight a plan generated previously:

bash
Copy
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:

• text

  Copy

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

  Copy

  --allow-exec
  is set.
• Use
  text

  Copy

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

may update:

• text

  Copy

  openclaw.json
  (SecretRef targets + provider upserts/deletes)
• text

  Copy

  auth-profiles.json
  (provider-target scrubbing)
• legacy
  text

  Copy

  auth.json
  residues
• text

  Copy

  ~/.openclaw/.env
  known secret keys whose values were migrated

Why no rollback backups

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

bash
Copy
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

If

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

Related

• CLI reference
• Secrets management