openclaw secrets CLI Reference

`openclaw secrets`

Keep SecretRefs in order and preserve a healthy active runtime snapshot.

Command	Role
`reload`	Gateway RPC (`secrets.reload`): re-resolves refs and atomically publishes the owner-aware runtime snapshot (no config writes); eligible owner failures may publish as cold or stale warnings
`store`	Manages team-scoped secret and environment values in the local shared state SQLite database
`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

When your plan includes exec SecretRefs/providers, add --allow-exec to both the dry-run and write apply commands.

Exit codes for CI/gates:

audit --check yields 1 when findings exist.
Unresolved refs produce 2 (independent of --check).
Store validation and disclosure-policy issues give 2; store get gives 3 when the name is absent.

Shared secret store

openclaw secrets store targets the local shared state database for direct writes. The store spans the whole Gateway and is scoped per team; only --scope team is accepted in this release. --scope me gets rejected because identity scoping is not yet supported.

Entries can also come from Settings -> Secrets in the Control UI, or via the agent's secrets tool, which prompts for a credential in a masked input and saves it without the model ever seeing the value.

openclaw secrets store list
openclaw secrets store set <NAME>
openclaw secrets store get <NAME>
openclaw secrets store rm <NAME>...
openclaw secrets store import [--from <file>]

Names must conform to ^[A-Z][A-Z0-9_]{0,127}$. Values cap out at 64 KiB (65,536 UTF-8 bytes); anything larger is refused with exit code 2, whether it arrives through stdin, --value, or --value-file. A secret entry cannot be empty, since an empty credential offers no way to diagnose it later (get blocks secret kinds and listings hide them); env entries may be empty. --kind secret|env takes precedence over automatic kind detection; otherwise names that end in common credential suffixes such as _API_KEY, _TOKEN, _PASSWORD, _PRIVATE_KEY, or _SECRET are classified as secret, and everything else becomes env.

Set values safely

--value is only permitted when the resolved kind is env:

openclaw secrets store set LOG_LEVEL --kind env --value debug

For secret values, --value is denied with exit code 2 because command-line arguments can leak through shell history and process listings. Pick one of the three safe input paths instead:

Feed stdin when stdin is not a TTY.
Use --value-file <path>; --value-file - denotes stdin.
Go interactive and type the value into the no-echo prompt.

Examples:

op read 'op://Engineering/OpenAI/apiKey' | \
  openclaw secrets store set OPENAI_API_KEY --kind secret

openclaw secrets store set TLS_PRIVATE_KEY \
  --kind secret \
  --value-file ./client-key.pem

set is idempotent and refreshes an existing name. Add --dry-run to validate and preview the operation without writing. After a successful write, you are reminded to run openclaw secrets reload before a config-referenced value can take effect.

Secret egress substitution fails closed until every secret has at least one exact allowed host. Bind or replace hosts with repeatable --allow-host flags; this policy-only form does not ask for or replace an existing secret value:

openclaw secrets store set OPENAI_API_KEY --allow-host api.openai.com
openclaw secrets store set SERVICE_TOKEN \
  --allow-host api.example.com \
  --allow-host uploads.example.com
openclaw secrets store set SERVICE_TOKEN --clear-allowed-hosts

Hosts get normalized to lowercase ASCII or punycode form. Anything with a scheme, path, port, or wildcard gets turned away. store list lists the hosts that pass, since these are policy metadata rather than secret material.

Read values

openclaw secrets store list --json
openclaw secrets store list --plain
openclaw secrets store get LOG_LEVEL

Secret values stay out of human-readable, --json, and --plain output. By design, store get treats a secret entry as write-only, rejecting it and terminating with 2; when the name is absent, it terminates with 3. Values of the environment kind remain readable.

env entries scoped to a team reach Gateway-hosted commands that OpenClaw's own exec tool runs, which includes OpenClaw Code Mode calls into openclaw:core:exec and Codex gateway_exec. Store values lose out to explicit per-call environment variables. Sandbox, remote node, ACP, and Codex-native shell execution do not get these entries. By default, secret entries stay out of subprocesses. With secrets.egressProxy.enabled: true, Gateway-hosted exec only receives authenticated sentinels, and the Gateway swaps them out at HTTPS egress; refer to Secret egress proxy.

Warning

Commands executed inside an external agent harness never see store entries. The Codex app-server, its sandbox exec-server, and ACP children like Claude Code construct their own child environment and bypass OpenClaw's exec preparation entirely. For eligible Codex turns, use gateway_exec to reach the OpenClaw-managed Gateway environment path instead.

Remove values

openclaw secrets store rm OLD_TOKEN
openclaw secrets store rm OLD_TOKEN LEGACY_PASSWORD --yes
openclaw secrets store rm OLD_TOKEN --dry-run

Removal is idempotent, so a name that does not exist succeeds without complaint. Without --yes, the CLI prompts for confirmation. Removed rows are soft-deleted and get purged after 30 days.

Import dotenv files

Bring in dotenv-format assignments from a regular file or stdin:

openclaw secrets store import --from .env
openclaw secrets store import --from .env --dry-run
openclaw secrets store import --from .env --yes
op read 'op://Engineering/service-account/dotenv' | openclaw secrets store import --yes

The importer handles quoted values and multiline quoted values, such as PEM keys. Use --yes to bypass confirmation and --dry-run to preview the import without committing. Kind detection follows the same name-based rule as store set.

The store CLI commands reject --url and --token and do not go through the Gateway. The Control UI relies on the admin-scoped secrets.store.* RPC methods instead; those methods refresh the runtime automatically when active config references a changed name.

Reload runtime snapshot

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

Calls gateway RPC method secrets.reload. Healthy owners refresh on their own schedule. Eligible failed owners turn stale only when their ref identities, provider definitions, and complete non-secret owner contract stay unchanged; new or altered failures become cold. This degraded activation succeeds and reports warningCount. Strict or unmapped failures return 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 refs
precedence drift (auth profile store credentials shadowing openclaw.json refs)
store residue (a team store value duplicated by plaintext in openclaw.json)
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. When both paths point to the same file, it gets scanned once.

Sensitive provider header detection relies on name heuristics: it flags 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 shape:

status: clean | findings | unresolved
resolution: refsChecked, skippedExecRefs, resolvabilityComplete
summary: plaintextCount, unresolvedRefCount, shadowedRefCount, storeResidueCount, legacyResidueCount
finding codes: PLAINTEXT_FOUND, REF_UNRESOLVED, REF_SHADOWED, STORE_PLAINTEXT_RESIDUE, LEGACY_RESIDUE

Configure (interactive helper)

Use the interactive flow to modify provider and SecretRef settings, execute preflight checks, and, if desired, apply changes:

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

The sequence starts with provider configuration (adding, editing, or removing secrets.providers aliases), proceeds to credential mapping (choosing fields and assigning {source, provider, id} refs), and concludes with preflight and an optional apply.

Flags:

--providers-only: set up secrets.providers exclusively, bypassing credential mapping
--skip-provider-setup: skip provider configuration, attach credentials to existing providers
--agent <id>: limit auth profile target discovery and writes to a single agent store
--allow-exec: enable exec SecretRef checks during preflight/apply, which may run provider commands

Combining --providers-only and --skip-provider-setup is not permitted.

Notes:

An interactive TTY is mandatory.
It targets secret-bearing fields in openclaw.json along with the chosen agent's auth profile store; the canonical supported surface is: SecretRef Credential Surface.
New auth profile mappings can be created directly within the picker flow.
Preflight resolution runs before any apply.
Generated plans default to scrub options being enabled (scrubEnv, scrubAuthProfilesForProviderTargets, scrubLegacyAuthJson). Scrubbed plaintext values are one-way on apply.
--plan-out will not generate a plan whose UTF-8 serialized form exceeds 16 MiB (16,777,216 bytes), aligning with the apply --from input limit.
In the absence of --apply, the CLI still asks for Apply this plan now? after preflight.
When --apply is present (and --yes is absent), the CLI requests an additional irreversible-migration confirmation.
--json outputs the plan plus preflight report, yet an interactive TTY remains a requirement.

Exec provider safety

Package managers frequently expose symlinked command paths. Determine the actual binary location (for instance, with realpath "$(command -v vault)") and set that absolute, non-symlink path; use trustedDirs to limit executables to approved directories. On the Gateway host, run openclaw config validate to verify manual exec command paths without executing providers. On Windows, provider paths fail closed when ACL verification is unavailable, with no provider-level override.

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 runs preflight validation without writing files; exec SecretRef checks are off by default in dry-run. Write mode rejects plans that include exec SecretRefs/providers unless --allow-exec. To enable exec provider checks/execution in either mode, use --allow-exec.

--from must reference a regular file no larger than 16 MiB (16,777,216 bytes). This byte cap covers the entire serialized file, including whitespace.

What apply can update:

openclaw.json (SecretRef targets plus provider upserts/deletes)
auth profile store (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 specifics (allowed target paths, validation rules, failure semantics): Secrets Apply Plan Contract.

Why no rollback backups

secrets apply deliberately avoids writing rollback backups that hold old plaintext values. Safety relies on strict preflight combined with atomic-ish apply, plus best-effort in-memory restore on failure.

Example

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

If audit --check continues to show plaintext findings, update the remaining reported target paths and rerun the audit.