vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-07-23 05:51:15 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
616a657ac64aaa21e3d46efcdcb4003571fcc13e
openclaw/docs/cli/secrets.md
Peter Lee 8539640abc fix(config,secrets): emit JSON errors and cover dotenv roots (#104340) 
* fix(secrets): use resolveStateDir for .env path to cover legacy .clawdbot dir

* fix(secrets): replace override-based legacy .env test with true automatic fallback, add apply-path coverage

* fix(config-cli): emit JSON error on config get --json for missing paths

When  is used with a nonexistent
path, the command emits no JSON on stdout, only a text error on stderr.
This breaks automated consumers that expect machine-readable errors.

Fix: output  JSON to stdout before exit(1) when
opts.json is set. This matches the existing JSON error output pattern
already used by runConfigValidate and handleConfigMutationError.

Also re-throw synthetic exit errors in the catch block so the
--json branch's writeRuntimeJson+exit is not caught and re-emitted
as a text error.

* fix(config-cli): use typed ExitError signal instead of __exit__ string sentinel

* fix(secrets): reuse resolved stateDir for .env path in audit

* fix(secrets): pass resolved stateDir into apply .env scrubbing, add root-switch regression

* test(config-cli): migrate remaining __exit__ sentinel to ExitError

* fix(secrets): cover config and state dotenv roots

* style(secrets): format dotenv path helper

* test(secrets): track temporary directories

* test(config): expect typed exit for missing patch files

---------

Co-authored-by: Peter Steinberger <steipete@gmail.com>
Co-authored-by: Peter Steinberger <peter@steipete.me>
2026-07-17 23:14:05 -07:00

7.7 KiB
Raw Blame History

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

Manage SecretRefs and keep the active runtime snapshot healthy.

Command Role
reload Gateway RPC (secrets.reload): re-resolves refs and swaps the runtime snapshot only on full success (no config writes)
audit Read-only scan of config/auth/generated-model stores and legacy residues for plaintext, unresolved refs, and precedence drift (exec refs skipped unless --allow-exec)
configure Interactive planner for provider setup, target mapping, and preflight (requires a TTY)
apply Executes a saved plan (--dry-run validates only and skips exec checks by default; write mode rejects exec-containing plans unless --allow-exec), then scrubs 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 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 · SecretRef Credential Surface · Security

Reload runtime snapshot

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

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

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

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

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:

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

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 containing exec SecretRefs/providers unless --allow-exec. Use --allow-exec to opt in to exec provider checks/execution in either mode.

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

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

Reference in New Issue View Git Blame Copy Permalink