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

</Note>

<Warning>

Plaintext credentials remain agent-readable if they are stored in files the

agent can inspect, including `openclaw.json`, `auth-profiles.json`, `.env`, or

generated `agents/*/agent/models.json` files. SecretRefs reduce that local blast

radius only after every supported credential has been migrated and

`openclaw secrets audit --check` reports no plaintext secret residue.

</Warning>

## Goals and runtime model

Secrets are resolved into an in-memory runtime snapshot.

This keeps secret-provider outages off hot request paths.

## Agent-access boundary

SecretRefs protect credentials from being persisted in supported config and

generated model surfaces, but they are not a process-isolation boundary. If a

plaintext credential remains on disk in a path the agent can read, the agent can

bypass API-level redaction by using file or shell tools to inspect that file.

For production deployments where agent-accessible files are in scope, treat

SecretRef migration as complete only when all of these are true:

- supported credentials use SecretRefs instead of plaintext values

- legacy plaintext residue has been scrubbed from `openclaw.json`,

`auth-profiles.json`, `.env`, and generated `models.json` files

- `openclaw secrets audit --check` is clean after the migration

- any remaining unsupported or rotating credentials are protected by operating

system 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.

<Warning>

SecretRefs do not make arbitrary readable files safe. Backups, copied configs,

old generated model catalogs, and unsupported credential classes must be treated

as production secrets until they are deleted, moved outside the agent trust

boundary, or protected by a separate isolation layer.

</Warning>

## Active-surface filtering

SecretRefs are validated only on effectively active surfaces.

openclaw secrets audit --check

```

</Step>

<Step title="Configure SecretRefs">

<Step title="Configure and apply SecretRefs">

```bash

openclaw secrets configure

openclaw secrets configure --apply

```

</Step>

<Step title="Re-audit">

</Step>

</Steps>

Do not treat the migration as complete until the re-audit is clean. If the audit

still reports plaintext values at rest, the agent-access risk is still present

even when runtime APIs return redacted values.

If you save a plan instead of applying during `configure`, apply that saved plan

with `openclaw secrets apply --from <plan-path>` before the re-audit.

<AccordionGroup>

<Accordion title="secrets audit">

Findings include: