OpenClaw secrets

OpenClaw’s secrets pages start from an uncomfortable fact: a plaintext credential in the config file, a dot-env file, an old auth-profile archive or a generated models file is readable by the agent that can inspect those files. SecretRefs are the answer, additive and opt-in per credential: the config holds a reference, and the value is resolved from an environment variable, a file, a command or a shared store. Here is what the references look like, the runtime model that keeps values out of the agent’s reach, the store and its egress proxy, and the workflow that proves no plaintext residue is left.

Plaintext still works. SecretRefs are opt-in per credential.

The four providers

• Env: the reference names an environment variable, resolved on the Gateway host; an explicit provider entry can carry an allowlist of variable names, and an empty allowlist denies all.
• File: the reference points at a file-backed secret, with file-backed API keys as the common case.
• Exec: the reference runs a command that prints the secret, which is how 1Password, Bitwarden, Vault, pass and sops are wired in the docs’ examples; strict and read-only command paths are part of the contract.
• Store: the shared SQLite secret store for team-wide secrets and environment values, with a secret egress proxy and a traffic allowlist in front of it.

The runtime model

Secrets are owned and isolated: values are injected at egress time through sentinels rather than placed in the agent’s context, there is an explicit agent-access boundary, and only active surfaces get their secrets resolved, so a credential for a channel that is not enabled is never loaded. Startup fails fast on a broken reference, degraded and recovered signals are surfaced, and a last-known-good snapshot keeps the Gateway running through a transient resolution failure. The masked secrets tool teaches the agent metadata-first discovery and task-scoped masked requests, and the prompt routes credential collection through masked flows, never chat.

The workflow

• Audit: the secrets audit command with its check flag reports plaintext residue across the supported credential surface, so you know what still needs migrating.
• Configure and apply: the configure command builds a plan of references for supported fields, and apply executes it against a plan contract, with a one-way safety policy that never scrubs a plaintext value until the reference is proven to resolve.
• Re-audit, and keep the legacy notes in mind: older flat auth-profile files are not a runtime format and are imported into the SQLite store by the doctor with a backup.

The OpenClaw config file shows where the references sit in the file, and OpenClaw security best practices lists the audit beside the other checks.

Where they show up

Every credential surface the docs describe accepts them: provider keys, channel tokens, MCP server environment variables and headers, sandbox SSH material, and the plugin configs that carry keys. OpenClaw and MCP servers is the case people meet first, because a server definition is exactly where a key would otherwise sit in the open.

On Diali

On Diali the credentials you add live in the vault, are injected into the instance at the edge, and never appear in a file the assistant can read; the audit the docs describe is the posture we run for you. Hosted OpenClaw on Diali is the assistant and Security on Diali describes the boundary.

• A reference in the config; the value from env, file, exec or store.
• Injected at egress, filtered to active surfaces, never in the agent’s context.
• Audit, configure, apply, re-audit; scrubbing is one-way and last.