{"id":607,"date":"2026-03-21T22:52:56","date_gmt":"2026-03-21T14:52:56","guid":{"rendered":"https:\/\/pa.yingzhi8.cn\/index.php\/2026\/03\/21\/cli-secrets\/"},"modified":"2026-03-21T23:08:57","modified_gmt":"2026-03-21T15:08:57","slug":"cli-secrets","status":"publish","type":"post","link":"https:\/\/pa.yingzhi8.cn\/index.php\/2026\/03\/21\/cli-secrets\/","title":{"rendered":"secrets"},"content":{"rendered":"<h1>secrets<\/h1>\n<h1><code>openclaw secrets<\/code><\/h1>\n<p>Use <code>openclaw secrets<\/code> to manage SecretRefs and keep the active runtime snapshot healthy.<\/p>\n<p>Command roles:<\/p>\n<ul>\n<li><code>reload<\/code>: gateway RPC (<code>secrets.reload<\/code>) that re-resolves refs and swaps runtime snapshot only on full success (no config writes).<\/li>\n<li><code>audit<\/code>: read-only scan of configuration\/auth\/generated-model stores and legacy residues for plaintext, unresolved refs, and precedence drift (exec refs are skipped unless <code>--allow-exec<\/code> is set).<\/li>\n<li><code>configure<\/code>: interactive planner for provider setup, target mapping, and preflight (TTY required).<\/li>\n<li><code>apply<\/code>: execute a saved plan (<code>--dry-run<\/code> for validation only; dry-run skips exec checks by default, and write mode rejects exec-containing plans unless <code>--allow-exec<\/code> is set), then scrub targeted plaintext residues.<\/li>\n<\/ul>\n<p>Recommended operator loop:<\/p>\n<p>&#8220;`bash  theme={&#8220;theme&#8221;:{&#8220;light&#8221;:&#8221;min-light&#8221;,&#8221;dark&#8221;:&#8221;min-dark&#8221;}}<br \/>\nopenclaw secrets audit &#8211;check<br \/>\nopenclaw secrets configure<br \/>\nopenclaw secrets apply &#8211;from \/tmp\/openclaw-secrets-plan.json &#8211;dry-run<br \/>\nopenclaw secrets apply &#8211;from \/tmp\/openclaw-secrets-plan.json<br \/>\nopenclaw secrets audit &#8211;check<br \/>\nopenclaw secrets reload<\/p>\n<pre><code>\nIf your plan includes `exec` SecretRefs\/providers, pass `--allow-exec` on both dry-run and write apply commands.\n\nExit code note for CI\/gates:\n\n* `audit --check` returns `1` on findings.\n* unresolved refs return `2`.\n\nRelated:\n\n* Secrets guide: [Secrets Management](\/gateway\/secrets)\n* Credential surface: [SecretRef Credential Surface](\/reference\/secretref-credential-surface)\n* Security guide: [Security](\/gateway\/security)\n\n## Reload runtime snapshot\n\nRe-resolve secret refs and atomically swap runtime snapshot.\n\n```bash  theme={&quot;theme&quot;:{&quot;light&quot;:&quot;min-light&quot;,&quot;dark&quot;:&quot;min-dark&quot;}}\nopenclaw secrets reload\nopenclaw secrets reload --json\n<\/code><\/pre>\n<p>Notes:<\/p>\n<ul>\n<li>Uses gateway RPC method <code>secrets.reload<\/code>.<\/li>\n<li>If resolution fails, gateway keeps last-known-good snapshot and returns an error (no partial activation).<\/li>\n<li>JSON response includes <code>warningCount<\/code>.<\/li>\n<\/ul>\n<h2>Audit<\/h2>\n<p>Scan OpenClaw state for:<\/p>\n<ul>\n<li>plaintext secret storage<\/li>\n<li>unresolved refs<\/li>\n<li>precedence drift (<code>auth-profiles.json<\/code> credentials shadowing <code>openclaw.json<\/code> refs)<\/li>\n<li>generated <code>agents\/*\/agent\/models.json<\/code> residues (provider <code>apiKey<\/code> values and sensitive provider headers)<\/li>\n<li>legacy residues (legacy auth store entries, OAuth reminders)<\/li>\n<\/ul>\n<p>Header residue note:<\/p>\n<ul>\n<li>Sensitive provider header detection is name-heuristic based (common auth\/credential header names and fragments such as <code>authorization<\/code>, <code>x-api-key<\/code>, <code>token<\/code>, <code>secret<\/code>, <code>password<\/code>, and <code>credential<\/code>).<\/li>\n<\/ul>\n<p>&#8220;`bash  theme={&#8220;theme&#8221;:{&#8220;light&#8221;:&#8221;min-light&#8221;,&#8221;dark&#8221;:&#8221;min-dark&#8221;}}<br \/>\nopenclaw secrets audit<br \/>\nopenclaw secrets audit &#8211;check<br \/>\nopenclaw secrets audit &#8211;json<br \/>\nopenclaw secrets audit &#8211;allow-exec<\/p>\n<pre><code>\nExit behavior:\n\n* `--check` exits non-zero on findings.\n* unresolved refs exit with higher-priority non-zero code.\n\nReport shape highlights:\n\n* `status`: `clean | findings | unresolved`\n* `resolution`: `refsChecked`, `skippedExecRefs`, `resolvabilityComplete`\n* `summary`: `plaintextCount`, `unresolvedRefCount`, `shadowedRefCount`, `legacyResidueCount`\n* finding codes:\n  * `PLAINTEXT_FOUND`\n  * `REF_UNRESOLVED`\n  * `REF_SHADOWED`\n  * `LEGACY_RESIDUE`\n\n## Configure (interactive helper)\n\nBuild provider and SecretRef changes interactively, run preflight, and optionally apply:\n\n```bash  theme={&quot;theme&quot;:{&quot;light&quot;:&quot;min-light&quot;,&quot;dark&quot;:&quot;min-dark&quot;}}\nopenclaw secrets configure\nopenclaw secrets configure --plan-out \/tmp\/openclaw-secrets-plan.json\nopenclaw secrets configure --apply --yes\nopenclaw secrets configure --providers-only\nopenclaw secrets configure --skip-provider-setup\nopenclaw secrets configure --agent ops\nopenclaw secrets configure --json\n<\/code><\/pre>\n<p>Flow:<\/p>\n<ul>\n<li>Provider setup first (<code>add\/edit\/remove<\/code> for <code>secrets.providers<\/code> aliases).<\/li>\n<li>Credential mapping second (select fields and assign <code>{source, provider, id}<\/code> refs).<\/li>\n<li>Preflight and optional apply last.<\/li>\n<\/ul>\n<p>Flags:<\/p>\n<ul>\n<li><code>--providers-only<\/code>: configure <code>secrets.providers<\/code> only, skip credential mapping.<\/li>\n<li><code>--skip-provider-setup<\/code>: skip provider setup and map credentials to existing providers.<\/li>\n<li><code>--agent &lt;id&gt;<\/code>: scope <code>auth-profiles.json<\/code> target discovery and writes to one agent store.<\/li>\n<li><code>--allow-exec<\/code>: allow exec SecretRef checks during preflight\/apply (may execute provider commands).<\/li>\n<\/ul>\n<p>Notes:<\/p>\n<ul>\n<li>Requires an interactive TTY.<\/li>\n<li>You cannot combine <code>--providers-only<\/code> with <code>--skip-provider-setup<\/code>.<\/li>\n<li><code>configure<\/code> targets secret-bearing fields in <code>openclaw.json<\/code> plus <code>auth-profiles.json<\/code> for the selected agent scope.<\/li>\n<li><code>configure<\/code> supports creating new <code>auth-profiles.json<\/code> mappings directly in the picker flow.<\/li>\n<li>Canonical supported surface: <a href=\"\/reference\/secretref-credential-surface\">SecretRef Credential Surface<\/a>.<\/li>\n<li>It performs preflight resolution before apply.<\/li>\n<li>If preflight\/apply includes exec refs, keep <code>--allow-exec<\/code> set for both steps.<\/li>\n<li>Generated plans default to scrub options (<code>scrubEnv<\/code>, <code>scrubAuthProfilesForProviderTargets<\/code>, <code>scrubLegacyAuthJson<\/code> all enabled).<\/li>\n<li>Apply path is one-way for scrubbed plaintext values.<\/li>\n<li>Without <code>--apply<\/code>, CLI still prompts <code>Apply this plan now?<\/code> after preflight.<\/li>\n<li>With <code>--apply<\/code> (and no <code>--yes<\/code>), CLI prompts an extra irreversible confirmation.<\/li>\n<\/ul>\n<p>Exec provider safety note:<\/p>\n<ul>\n<li>Homebrew installs often expose symlinked binaries under <code>\/opt\/homebrew\/bin\/*<\/code>.<\/li>\n<li>Set <code>allowSymlinkCommand: true<\/code> only when needed for trusted package-manager paths, and pair it with <code>trustedDirs<\/code> (for example <code>[\"\/opt\/homebrew\"]<\/code>).<\/li>\n<li>On Windows, if ACL verification is unavailable for a provider path, OpenClaw fails closed. For trusted paths only, set <code>allowInsecurePath: true<\/code> on that provider to bypass path security checks.<\/li>\n<\/ul>\n<h2>Apply a saved plan<\/h2>\n<p>Apply or preflight a plan generated previously:<\/p>\n<p>&#8220;`bash  theme={&#8220;theme&#8221;:{&#8220;light&#8221;:&#8221;min-light&#8221;,&#8221;dark&#8221;:&#8221;min-dark&#8221;}}<br \/>\nopenclaw secrets apply &#8211;from \/tmp\/openclaw-secrets-plan.json<br \/>\nopenclaw secrets apply &#8211;from \/tmp\/openclaw-secrets-plan.json &#8211;allow-exec<br \/>\nopenclaw secrets apply &#8211;from \/tmp\/openclaw-secrets-plan.json &#8211;dry-run<br \/>\nopenclaw secrets apply &#8211;from \/tmp\/openclaw-secrets-plan.json &#8211;dry-run &#8211;allow-exec<br \/>\nopenclaw secrets apply &#8211;from \/tmp\/openclaw-secrets-plan.json &#8211;json<\/p>\n<pre><code>\nExec behavior:\n\n* `--dry-run` validates preflight without writing files.\n* exec SecretRef checks are skipped by default in dry-run.\n* write mode rejects plans that contain exec SecretRefs\/providers unless `--allow-exec` is set.\n* Use `--allow-exec` to opt in to exec provider checks\/execution in either mode.\n\nPlan contract details (allowed target paths, validation rules, and failure semantics):\n\n* [Secrets Apply Plan Contract](\/gateway\/secrets-plan-contract)\n\nWhat `apply` may update:\n\n* `openclaw.json` (SecretRef targets + provider upserts\/deletes)\n* `auth-profiles.json` (provider-target scrubbing)\n* legacy `auth.json` residues\n* `~\/.openclaw\/.env` known secret keys whose values were migrated\n\n## Why no rollback backups\n\n`secrets apply` intentionally does not write rollback backups containing old plaintext values.\n\nSafety comes from strict preflight + atomic-ish apply with best-effort in-memory restore on failure.\n\n## Example\n\n```bash  theme={&quot;theme&quot;:{&quot;light&quot;:&quot;min-light&quot;,&quot;dark&quot;:&quot;min-dark&quot;}}\nopenclaw secrets audit --check\nopenclaw secrets configure\nopenclaw secrets audit --check\n<\/code><\/pre>\n<p>If <code>audit --check<\/code> still reports plaintext findings, update the remaining reported target paths and rerun audit.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>secrets openclaw secrets Use openclaw secrets to manage [&hellip;]<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-607","post","type-post","status-publish","format-standard","hentry","category-docs"],"_links":{"self":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/607","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/comments?post=607"}],"version-history":[{"count":2,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/607\/revisions"}],"predecessor-version":[{"id":742,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/607\/revisions\/742"}],"wp:attachment":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/media?parent=607"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/categories?post=607"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/tags?post=607"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}