Summary

Add external secrets management as an additive superset of existing credential behavior.

This branch introduces provider-based SecretRefs (env, file, exec) for static credentials, eager in-memory runtime snapshot activation, strict startup fail-fast for unresolved required refs, and atomic reload with last-known-good fallback.

Plaintext remains supported and default; refs are opt-in.

What ships

1. SecretRef contract + provider model

• Value-level SecretRef contract: { source, provider, id }.
• Core provider transports:
  • env
  • file
  • exec
• Schema/validation updates for ref ids, provider aliases, and provider-specific options.

2. Runtime activation model

• Eager secret resolution into an in-memory runtime snapshot.
• Startup fail-fast when required refs are unresolved.
• Atomic activation/swap on startup and reload.
• Last-known-good retention when reload activation fails.
• One-shot operator event/log codes:
  • SECRETS_RELOADER_DEGRADED
  • SECRETS_RELOADER_RECOVERED

3. In-scope static secret fields

• models.providers.<provider>.apiKey
• skills.entries.<skillKey>.apiKey
• channels.googlechat.serviceAccount
• channels.googlechat.accounts.<accountId>.serviceAccount
• auth-profiles.json value refs:
  • api_key.keyRef
  • token.tokenRef

4. Resolver behavior + hardening

• env: explicit var resolution with optional allowlist.
• file: secure path checks, timeout/maxBytes, and modes:
  • json (JSON Pointer ids)
  • singleValue (id must be value)
• exec: no-shell absolute command execution with fixed argv semantics, minimal env by default, timeout/no-output timeout, output-size limits, protocol-versioned JSON contract, and strict path checks.
• Symlink command paths are denied by default; explicit allowSymlinkCommand is required (for example Homebrew shim paths), with resolved-target validation.

5. Gateway + CLI surfaces

• Gateway method: secrets.reload.
• CLI commands:
  • openclaw secrets reload
  • openclaw secrets audit
  • openclaw secrets configure
  • openclaw secrets apply --from <plan.json>
• secrets configure supports provider setup, SecretRef mapping, preflight, and optional immediate apply.

6. Apply/audit workflow (replaces migrate flow)

• secrets apply executes one-way ref migration for selected targets in a plan.
• Apply includes scoped scrubbing for targeted static credential residues (auth-profiles, legacy static auth.json, known .env lines) where applicable.
• No rollback command that re-materializes plaintext secrets is provided by design.

7. Onboarding/auth UX updates

• Explicit credential storage mode in onboarding/auth choice paths:
  • plaintext (default)
  • ref
• Ref mode preflight validation added for env/provider-backed refs.
• Non-interactive and interactive paths updated so env/ref persistence is explicit and predictable.

8. Redaction + persistence safety

• Extended masking/redaction coverage for secret-bearing surfaces.
• Resolved external secret values are not serialized back into config snapshots.

9. Documentation

• Added dedicated docs:
  • docs/gateway/secrets.md
  • docs/cli/secrets.md
• Updated related docs (onboarding, configuration reference, security, auth, skills, Google Chat, environment/help) for behavior parity.

Compatibility guarantees

• Existing plaintext setups continue to work without opt-in changes.
• Mixed plaintext + ref configurations are supported.
• Credential modes remain unchanged (api_key, token, oauth); refs are value-level additions.
• Runtime never drops to empty/no-secrets state on reload failure.

Out of scope

• Durable encrypted writable OAuth token backend.
• First-class vendor SDK integrations for remote managers (Vault/1Password/AWS/Azure/etc).

Validation

• Local quality/test coverage added and updated across:
  • secrets runtime/resolve/apply/audit
  • CLI secrets command surface
  • onboarding/auth-choice ref flows
  • gateway reload/degraded/recovered behavior
• VM integration and failure-injection validation completed for:
  • plaintext baseline compatibility
  • mixed-mode compatibility
  • env/file/exec provider flows
  • degraded/recovered transitions with runtime continuity
  • migration/scrub behavior and leakage checks

Rollback / operational note

• This design intentionally avoids writing rollback artifacts that contain pre-migration plaintext credentials.
• Operational rollback is configuration-level (switch refs back to plaintext or restore pre-change config from your own backups) rather than automated plaintext rehydration.