Secrets runtime model

This page covers how secrets behave at runtime: owner isolation, egress-time sentinel injection, the agent-access boundary, active-surface filtering, and the preflight diagnostics that report on them.

Runtime model

• Secrets resolve into an in-memory runtime snapshot, eagerly during activation, not lazily on request paths.
• Cold Gateway startup isolates a retryable SecretRef failure to a known non-Gateway owner when that owner supports isolation. Mapped owner classes include model providers and skills, media/TTS/cron providers, eligible auth profiles, per-agent memory, sandbox SSH, channel accounts, and manifest-declared plugin routes. The Gateway starts, records the owner as configured-unavailable, and emits a redacted degradation warning. Gateway ingress auth, structurally invalid refs or resolved values, fail-closed owners, and refs whose runtime owner is not mapped still fail startup.
• Reload validates each mapped owner independently, then publishes one atomic snapshot. Healthy owners refresh. An eligible failed owner keeps its last-known-good value and becomes stale only when its ref identities, provider definitions, and complete non-secret owner contract are unchanged; a changed or new failed owner becomes cold. A strict failure rejects the reload and preserves the active snapshot.
• Config reload also reconciles channel connections when a secret-provider edit changes resolved credentials. Plugins that support account-scoped reload restart only the affected named accounts; shared, default, removed, or unresolved account changes use the plugin's whole-channel restart policy. Cold accounts stop, eligible stale accounts keep using their last-known-good credentials, and recovery preserves manual stops.
• Policy violations (for example an OAuth-mode auth profile combined with SecretRef input) fail activation before the runtime swap.
• Runtime requests read only the active in-memory snapshot. Model-provider SecretRef credentials pass through auth storage and stream options as process-local sentinels until egress. Outbound delivery paths (Discord reply/thread delivery, Telegram action sends) also read that snapshot and do not re-resolve refs per send.
• Read-only channel capability discovery evaluates accounts independently. A configured-but-unavailable account does not hide healthy sibling accounts' message actions, while direct sends through the unavailable account still fail closed.

This keeps secret-provider outages off hot request paths.

Gateway ingress protection, structurally invalid config or resolved values, policy violations, and unknown ownership still fail closed. Isolated owners never fall through to a lower-precedence credential source.

When startup database admission marks an agent unavailable, secrets preparation omits that exact database's auth store without substituting an empty credential store. Pending background inspection is not a secret failure: the admission owner resolves and publishes the agent's credentials and prepares its models before admitting the agent. No manual secrets reload is needed after successful preparation. Failed inspections and ownership refusals remain cold store owners with repair guidance. Unreadable stores without a matching admission refusal still fail preparation; a secrets reload alone cannot readmit the agent.

Background preparation preserves the saved model configuration separately from runtime catalog defaults, so recovery does not disable otherwise compatible runtime choices such as Codex.

Egress-time injection (sentinels)

For model-provider credentials backed by SecretRefs, OpenClaw mints an opaque, process-local sentinel during model-auth resolution. Auth storage, stream options, SDK configuration, logs, error objects, and most runtime introspection therefore see a value such as oc-sent-v2.<authenticated-ciphertext>.end, not the provider credential. The guarded model fetch and managed local-provider health checks replace known sentinels in URL and header values immediately before each request leaves the process.

Unknown sentinel-shaped values fail closed before network activity. OpenClaw refuses to send the request rather than forwarding an unresolved sentinel to a provider. Resolved secret values are also registered for exact-value log redaction as a defense in depth measure.

Provider adapters use the latest injection point their SDK supports:

• SDKs with a custom fetch option receive OpenClaw's guarded fetch, so the SDK retains the sentinel.
• SDKs without a custom fetch option unwrap the sentinel immediately before client construction. Plugin-owned provider streams and agent harnesses unwrap at the final core-owned handoff because those transports do not share OpenClaw's guarded fetch.

Sentinels reduce plaintext exposure across the model-call chain, but they are not process isolation. The real value still exists in same-process memory and appears at the final adapter boundary. Plain environment credentials that are not configured through SecretRefs remain plaintext and are outside this mechanism.

Set OPENCLAW_SECRET_SENTINELS=off (also accepts 0 or false, case-insensitive) to disable model-provider sentinel minting during incident response or compatibility troubleshooting. This switch disables neither exact-value redaction registration nor protected-store sealing for Gateway-hosted subprocesses.

Agent-access boundary

SecretRefs stop credentials from being persisted in config and generated model files, but they are not a process-isolation boundary. A plaintext credential left on disk in a path the agent can read is still readable via file or shell tools, bypassing API-level redaction.

For production deployments where agent-accessible files are in scope, treat migration as complete only when all of these hold:

• Supported credentials use SecretRefs instead of plaintext values.
• Legacy plaintext residue is scrubbed from openclaw.json, the SQLite auth-profile store, .env, and generated models.json files. Retired auth JSON is doctor-owned migration input and is never rewritten by secrets apply.
• openclaw secrets audit --check is clean after migration.
• Any remaining unsupported or rotating credentials are protected by OS isolation, container isolation, or an external credential proxy.

This is why the audit/configure/apply workflow is a security migration gate, not just a convenience helper.

Active-surface filtering

SecretRefs are validated only on effectively active surfaces:

• Enabled surfaces: retryable failures for mapped, isolatable owners enter cold or stale degradation. Strict, fail-closed, Gateway-required, or unmapped failures block startup/reload.
• Inactive surfaces: unresolved refs do not block startup/reload; they emit a non-fatal SECRETS_REF_IGNORED_INACTIVE_SURFACE diagnostic.

Examples of inactive surfaces

• Disabled channel/account entries.
• Top-level channel credentials that no enabled account inherits.
• Disabled tool/feature surfaces.
• Web search provider-specific keys not selected by tools.web.search.provider. In auto mode (provider unset), keys are consulted by precedence for auto-detection until one resolves; after selection, non-selected provider keys are inactive.
• Sandbox SSH auth material (agents.defaults.sandbox.ssh.identityData, certificateData, knownHostsData, plus per-agent overrides) is active only when the effective sandbox backend is ssh and sandbox mode is not off, for the default agent or an enabled agent.
• gateway.remote.token / gateway.remote.password SecretRefs are active if any of these hold:
  • gateway.mode=remote
  • gateway.remote.url is configured
  • gateway.tailscale.mode is serve or funnel
  • In local mode without those remote surfaces: gateway.remote.token is active when token auth can win and no env/auth token is configured; gateway.remote.password is active only when password auth can win and no env/auth password is configured.
• Active gateway.auth.token / gateway.auth.password SecretRefs stay authoritative over OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD; environment credentials are fallbacks when the corresponding local config input is absent.

Gateway auth surface diagnostics

When a SecretRef is set on gateway.auth.token, gateway.auth.password, gateway.remote.token, or gateway.remote.password, gateway startup/reload logs the surface state under code SECRETS_GATEWAY_AUTH_SURFACE:

• active: the SecretRef is part of the effective auth surface and must resolve.
• inactive: another auth surface wins, or remote auth is disabled/not active.

The log entry includes the reason the active-surface policy used.

Onboarding reference preflight

In interactive onboarding, choosing SecretRef storage runs preflight validation before saving:

• Env refs: validates the env var name and confirms a non-empty value is visible during setup.
• Provider refs (file, exec, or store): validates provider selection, resolves id, and checks the resolved value type.
• Quickstart flow: when gateway.auth.token is already a SecretRef, onboarding resolves it before check/dashboard bootstrap (for env, file, exec, and store refs) using the same fail-fast gate.
• Generated gateway token: setup mints gateway.auth.token itself, so reference mode has nothing to prompt for. With OPENCLAW_GATEWAY_TOKEN exported it writes an env ref to that variable, keeping a later rotation authoritative; otherwise it writes the token to the secret store under OPENCLAW_GATEWAY_TOKEN and stores a store ref. An existing store entry is reused rather than rotated, so re-running setup never invalidates already-paired clients.

Validation failure shows the error and lets you retry.