mirror of
https://github.com/openclaw/openclaw.git
synced 2026-03-13 11:00:50 +00:00
806803b7ef
* feat(secrets): expand secret target coverage and gateway tooling * docs(secrets): align gateway and CLI secret docs * chore(protocol): regenerate swift gateway models for secrets methods * fix(config): restore talk apiKey fallback and stabilize runner test * ci(windows): reduce test worker count for shard stability * ci(windows): raise node heap for test shard stability * test(feishu): make proxy env precedence assertion windows-safe * fix(gateway): resolve auth password SecretInput refs for clients * fix(gateway): resolve remote SecretInput credentials for clients * fix(secrets): skip inactive refs in command snapshot assignments * fix(secrets): scope gateway.remote refs to effective auth surfaces * fix(secrets): ignore memory defaults when enabled agents disable search * fix(secrets): honor Google Chat serviceAccountRef inheritance * fix(secrets): address tsgo errors in command and gateway collectors * fix(secrets): avoid auth-store load in providers-only configure * fix(gateway): defer local password ref resolution by precedence * fix(secrets): gate telegram webhook secret refs by webhook mode * fix(secrets): gate slack signing secret refs to http mode * fix(secrets): skip telegram botToken refs when tokenFile is set * fix(secrets): gate discord pluralkit refs by enabled flag * fix(secrets): gate discord voice tts refs by voice enabled * test(secrets): make runtime fixture modes explicit * fix(cli): resolve local qr password secret refs * fix(cli): fail when gateway leaves command refs unresolved * fix(gateway): fail when local password SecretRef is unresolved * fix(gateway): fail when required remote SecretRefs are unresolved * fix(gateway): resolve local password refs only when password can win * fix(cli): skip local password SecretRef resolution on qr token override * test(gateway): cast SecretRef fixtures to OpenClawConfig * test(secrets): activate mode-gated targets in runtime coverage fixture * fix(cron): support SecretInput webhook tokens safely * fix(bluebubbles): support SecretInput passwords across config paths * fix(msteams): make appPassword SecretInput-safe in onboarding/token paths * fix(bluebubbles): align SecretInput schema helper typing * fix(cli): clarify secrets.resolve version-skew errors * refactor(secrets): return structured inactive paths from secrets.resolve * refactor(gateway): type onboarding secret writes as SecretInput * chore(protocol): regenerate swift models for secrets.resolve * feat(secrets): expand extension credential secretref support * fix(secrets): gate web-search refs by active provider * fix(onboarding): detect SecretRef credentials in extension status * fix(onboarding): allow keeping existing ref in secret prompt * fix(onboarding): resolve gateway password SecretRefs for probe and tui * fix(onboarding): honor secret-input-mode for local gateway auth * fix(acp): resolve gateway SecretInput credentials * fix(secrets): gate gateway.remote refs to remote surfaces * test(secrets): cover pattern matching and inactive array refs * docs(secrets): clarify secrets.resolve and remote active surfaces * fix(bluebubbles): keep existing SecretRef during onboarding * fix(tests): resolve CI type errors in new SecretRef coverage * fix(extensions): replace raw fetch with SSRF-guarded fetch * test(secrets): mark gateway remote targets active in runtime coverage * test(infra): normalize home-prefix expectation across platforms * fix(cli): only resolve local qr password refs in password mode * test(cli): cover local qr token mode with unresolved password ref * docs(cli): clarify local qr password ref resolution behavior * refactor(extensions): reuse sdk SecretInput helpers * fix(wizard): resolve onboarding env-template secrets before plaintext * fix(cli): surface secrets.resolve diagnostics in memory and qr * test(secrets): repair post-rebase runtime and fixtures * fix(gateway): skip remote password ref resolution when token wins * fix(secrets): treat tailscale remote gateway refs as active * fix(gateway): allow remote password fallback when token ref is unresolved * fix(gateway): ignore stale local password refs for none and trusted-proxy * fix(gateway): skip remote secret ref resolution on local call paths * test(cli): cover qr remote tailscale secret ref resolution * fix(secrets): align gateway password active-surface with auth inference * fix(cli): resolve inferred local gateway password refs in qr * fix(gateway): prefer resolvable remote password over token ref pre-resolution * test(gateway): cover none and trusted-proxy stale password refs * docs(secrets): sync qr and gateway active-surface behavior * fix: restore stability blockers from pre-release audit * Secrets: fix collector/runtime precedence contradictions * docs: align secrets and web credential docs * fix(rebase): resolve integration regressions after main rebase * fix(node-host): resolve gateway secret refs for auth * fix(secrets): harden secretinput runtime readers * gateway: skip inactive auth secretref resolution * cli: avoid gateway preflight for inactive secret refs * extensions: allow unresolved refs in onboarding status * tests: fix qr-cli module mock hoist ordering * Security: align audit checks with SecretInput resolution * Gateway: resolve local-mode remote fallback secret refs * Node host: avoid resolving inactive password secret refs * Secrets runtime: mark Slack appToken inactive for HTTP mode * secrets: keep inactive gateway remote refs non-blocking * cli: include agent memory secret targets in runtime resolution * docs(secrets): sync docs with active-surface and web search behavior * fix(secrets): keep telegram top-level token refs active for blank account tokens * fix(daemon): resolve gateway password secret refs for probe auth * fix(secrets): skip IRC NickServ ref resolution when NickServ is disabled * fix(secrets): align token inheritance and exec timeout defaults * docs(secrets): clarify active-surface notes in cli docs * cli: require secrets.resolve gateway capability * gateway: log auth secret surface diagnostics * secrets: remove dead provider resolver module * fix(secrets): restore gateway auth precedence and fallback resolution * fix(tests): align plugin runtime mock typings --------- Co-authored-by: Peter Steinberger <steipete@gmail.com>
169 lines
5.7 KiB
Markdown
169 lines
5.7 KiB
Markdown
---
|
|
summary: "CLI reference for `openclaw secrets` (reload, audit, configure, apply)"
|
|
read_when:
|
|
- Re-resolving secret refs at runtime
|
|
- Auditing plaintext residues and unresolved refs
|
|
- Configuring SecretRefs and applying one-way scrub changes
|
|
title: "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 stores and legacy residues for plaintext, unresolved refs, and precedence drift.
|
|
- `configure`: interactive planner for provider setup, target mapping, and preflight (TTY required).
|
|
- `apply`: execute a saved plan (`--dry-run` for validation only), then scrub targeted plaintext residues.
|
|
|
|
Recommended operator loop:
|
|
|
|
```bash
|
|
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
|
|
```
|
|
|
|
Exit code note for CI/gates:
|
|
|
|
- `audit --check` returns `1` on findings.
|
|
- unresolved refs return `2`.
|
|
|
|
Related:
|
|
|
|
- Secrets guide: [Secrets Management](/gateway/secrets)
|
|
- Credential surface: [SecretRef Credential Surface](/reference/secretref-credential-surface)
|
|
- Security guide: [Security](/gateway/security)
|
|
|
|
## Reload runtime snapshot
|
|
|
|
Re-resolve secret refs and atomically swap runtime snapshot.
|
|
|
|
```bash
|
|
openclaw secrets reload
|
|
openclaw secrets reload --json
|
|
```
|
|
|
|
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`.
|
|
|
|
## Audit
|
|
|
|
Scan OpenClaw state for:
|
|
|
|
- plaintext secret storage
|
|
- unresolved refs
|
|
- precedence drift (`auth-profiles.json` credentials shadowing `openclaw.json` refs)
|
|
- legacy residues (legacy auth store entries, OAuth reminders)
|
|
|
|
```bash
|
|
openclaw secrets audit
|
|
openclaw secrets audit --check
|
|
openclaw secrets audit --json
|
|
```
|
|
|
|
Exit behavior:
|
|
|
|
- `--check` exits non-zero on findings.
|
|
- unresolved refs exit with higher-priority non-zero code.
|
|
|
|
Report shape highlights:
|
|
|
|
- `status`: `clean | findings | unresolved`
|
|
- `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:
|
|
|
|
```bash
|
|
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 `auth-profiles.json` target discovery and writes to one agent store.
|
|
|
|
Notes:
|
|
|
|
- Requires an interactive TTY.
|
|
- You cannot combine `--providers-only` with `--skip-provider-setup`.
|
|
- `configure` targets secret-bearing fields in `openclaw.json` plus `auth-profiles.json` for the selected agent scope.
|
|
- `configure` supports creating new `auth-profiles.json` mappings directly in the picker flow.
|
|
- Canonical supported surface: [SecretRef Credential Surface](/reference/secretref-credential-surface).
|
|
- It performs preflight resolution before apply.
|
|
- 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.
|
|
|
|
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:
|
|
|
|
```bash
|
|
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
|
|
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
|
|
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json
|
|
```
|
|
|
|
Plan contract details (allowed target paths, validation rules, and failure semantics):
|
|
|
|
- [Secrets Apply Plan Contract](/gateway/secrets-plan-contract)
|
|
|
|
What `apply` may update:
|
|
|
|
- `openclaw.json` (SecretRef targets + provider upserts/deletes)
|
|
- `auth-profiles.json` (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
|
|
|
|
```bash
|
|
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.
|