secrets.md

summary	Secrets management: SecretRef contract, shared secret store, runtime snapshots, and safe one-way scrubbing
read_when	Configuring SecretRefs for provider credentials and SQLite auth-profile refs Storing team-wide secrets and environment values in the shared SQLite store Operating secrets reload, audit, configure, and apply safely in production Understanding startup fail-fast, inactive-surface filtering, and last-known-good behavior
title	Secrets management
sidebarTitle	Secrets management

OpenClaw supports additive SecretRefs so supported credentials do not need to live as plaintext in configuration.

Plaintext still works. SecretRefs are opt-in per credential. Plaintext credentials remain agent-readable when they sit in files the agent can inspect, including `openclaw.json`, `.env`, retired auth-profile JSON archives, or generated `agents/*/agent/models.json` files. SecretRefs reduce that local blast radius once every supported credential is migrated and `openclaw secrets audit --check` reports no plaintext residue.

This page is an index. Secrets management is documented on five pages, one per reader job. Open the page that matches your task.

Secrets pages

Page	Read it when
Secrets runtime model	Owner isolation, sentinel injection, the agent-access boundary, and active-surface filtering.
SecretRef contract and provider config	The SecretRef contract, id grammars, validation rules, and the env, file, exec, and store provider blocks.
Shared secret store and egress proxy	The shared secret store, the secret egress proxy and its traffic allowlist, and file-backed API keys.
Secrets integration examples	Exec provider recipes for 1Password, Bitwarden, Vault, pass, and sops, plus MCP and sandbox SSH.
Secrets operations and behavior	Supported surfaces, precedence, activation triggers, degraded signals, and the audit and configure workflow.

Where each section moved

Every section, tab, step, and accordion title from the previous single-page version keeps its anchor here, so an existing link such as /gateway/secrets#shared-secret-store still resolves. Each entry points at the page that now holds the content.

• Runtime model
• Egress-time injection (sentinels)
• Agent-access boundary
• Active-surface filtering
• Gateway auth surface diagnostics
• Onboarding reference preflight
• SecretRef contract
• Provider config
• Shared secret store
• Secret egress proxy
• Traffic allowlist
• File-backed API keys
• Exec integration examples
• MCP server environment variables
• Sandbox SSH auth material
• Supported credential surface
• Required behavior and precedence
• Activation triggers
• Degraded and recovered signals
• Command-path resolution
• Audit and configure workflow
• One-way safety policy
• Legacy auth compatibility notes
• Control UI
• Egress-time injection (sentinels)
• Examples of inactive surfaces
• env
• file
• exec
• store
• Env provider
• File provider
• Exec provider
• Store provider
• 1Password
• Bitwarden Secrets Manager (bws)
• HashiCorp Vault CLI
• password-store (pass)
• sops
• Strict command paths
• Read-only command paths
• Audit current state
• Configure and apply SecretRefs
• Re-audit
• secrets audit
• secrets configure
• secrets apply

Related

• Authentication - auth setup
• CLI: secrets - CLI commands
• Vault SecretRefs - HashiCorp Vault provider setup
• Environment Variables - environment precedence
• SecretRef Credential Surface - credential surface
• Secrets Apply Plan Contract - plan contract details
• Security - security posture
• Configuration reference - where each secrets and env setting is documented
• Ask user - asking the operator a non-secret question; never answer it with a credential, use the masked secrets tool for those
• Auth credential semantics - the canonical rules for auth profile ordering and runtime credential resolution