Secrets and auth stores#

OpenClaw maintains authentication credentials, device identity, and secret material using a combination of file-based storage and in-memory runtime snapshots.

File-based storage provides durability across restarts. The runtime secrets snapshot materializes resolved values into memory for fast-path access during request handling, model calls, and channel operations.

Storage kinds#

Secrets and auth state use two layers:

File-based — persisted on disk for durability across restarts.
Runtime snapshot — built from files and config, held in memory with fast-path lookup and activation hooks.

The snapshot is prepared during Gateway startup and on config changes. It is cleared on shutdown or explicit reset.

Components#

Component	Description
Auth profiles	Named credential sets for model providers. Support rotation and fallbacks.
Device tokens	Issued during pairing. Used for reconnect authentication of operators and nodes.
Secret files	Filesystem sources read by the runtime (see `secret-file-runtime`).
Runtime secrets snapshot	Resolved secret values with fast-path lookup and activation hooks.

Auth profiles and device tokens are the primary file-backed stores. The snapshot resolves and activates them for use by providers, channels, and plugins.

Runtime behavior#

A runtime secrets snapshot is prepared at startup and on config reload.
Fast-path resolution serves hot paths such as provider auth without repeated disk or config lookups.
Activation makes resolved secrets available to channels, providers, and plugins.
The Gateway records a last-known-good snapshot after each successful startup. Promotion is skipped for snapshots that contain redacted placeholders (***).
On validation failure, the prior last-known-good snapshot remains active (except for diagnostic commands).

Configuration surface#

Secrets configuration lives under the top-level secrets key in ~/.openclaw/openclaw.json (or the path set by OPENCLAW_CONFIG_PATH). The key also works inside $include fragments.

Secret references use SecretRef objects (or environment variables). The config system coerces and validates SecretRef usage. Unresolved refs cause validation failures at startup.

Supported locations include gateway.auth.token and gateway.auth.password (plus legacy environment variables). SecretRef policy enforcement applies during validation.

See Configuration for the full schema and materialization rules.

CLI access#

Inspect the auth store with:

openclaw secrets audit

This runs in read-only mode.

Surface misconfigured or missing auth material with:

openclaw doctor
openclaw doctor --fix

The secrets.* RPC surface is available for programmatic access from the Control UI, CLI, and nodes.

Container paths#

In Docker deployments the auth profile secret directory is mounted at:

Container: /home/node/.config/openclaw
Host (default): ~/.openclaw-auth-profile-secrets

Override the host path with the OPENCLAW_AUTH_PROFILE_SECRET_DIR environment variable.

Security notes#

Treat inbound DMs and webhook payloads as untrusted input.
Do not reuse gateway auth tokens (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN) for hooks or external services.
Device tokens are bound to a specific device identity and role (operator vs. node).

For credential eligibility, resolution order, and probe reason codes, see Auth credential semantics.