> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets management

> Keep credentials out of plaintext config with SecretRefs — env, file, and exec providers, plus the audit and apply workflow.

# Secrets management

WednesdayAI supports **SecretRefs** so supported credentials do not have to live as plaintext in your config. SecretRefs are opt-in, additive, and per-credential — plaintext still works everywhere it did before.

A SecretRef points the gateway at a credential held in an environment variable, a local file, or an external resolver command (1Password, Vault, sops, and so on). The credential is resolved into an in-memory snapshot at activation time, never on the hot request path.

## Runtime model

* Resolution is **eager** during activation, not lazy on each request.
* Startup **fails fast** if an effectively active SecretRef cannot be resolved.
* Reload uses an **atomic swap**: full success, or the last-known-good snapshot is kept.
* Requests read only from the active in-memory snapshot.

This keeps secret-provider outages off the request path. If a reload fails after a healthy start, the gateway enters a degraded state (event `SECRETS_RELOADER_DEGRADED`) and keeps serving from the last good snapshot until a later reload recovers (`SECRETS_RELOADER_RECOVERED`).

## Active-surface filtering

SecretRefs are only validated on surfaces that are actually in use. A ref on a disabled channel, an unselected web-search provider, or an inactive auth path does **not** block startup — it emits a non-fatal diagnostic (`SECRETS_REF_IGNORED_INACTIVE_SURFACE`) instead.

Gateway auth surfaces (`gateway.auth.password`, `gateway.remote.token`, `gateway.remote.password`) log their state explicitly as `active` or `inactive` under `SECRETS_GATEWAY_AUTH_SURFACE`, with the reason, so you can see why a credential was required or skipped.

## SecretRef contract

Every SecretRef uses the same object shape:

```json5 theme={"dark"}
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
```

> [tab] env
>
> ```json5 theme={"dark"}
> { source: "env", provider: "default", id: "OPENAI_API_KEY" }
> ```
>
> * `provider` matches `^[a-z][a-z0-9_-]{0,63}$`
> * `id` matches `^[A-Z][A-Z0-9_]{0,127}$`
> * Missing or empty env values fail resolution.

> [tab] file
>
> ```json5 theme={"dark"}
> { source: "file", provider: "filemain", id: "/providers/openai/apiKey" }
> ```
>
> * `id` is an absolute JSON pointer (`/...`). RFC6901 escaping applies (`~` becomes `~0`, `/` becomes `~1`).
> * The file path must pass ownership and permission checks.

> [tab] exec
>
> ```json5 theme={"dark"}
> { source: "exec", provider: "vault", id: "providers/openai/apiKey" }
> ```
>
> * `id` matches `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
> * Runs a configured absolute binary path (no shell).

## Defining providers

Providers live under `secrets.providers`, with defaults selecting one provider per source:

```json5 theme={"dark"}
{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json", // or "singleValue"
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
        jsonOnly: true,
      },
    },
    defaults: { env: "default", file: "filemain", exec: "vault" },
  },
}
```

The **file** provider reads `path`: `mode: "json"` resolves `id` as a JSON pointer; `mode: "singleValue"` returns the whole file for `id: "value"`. The **exec** provider runs an absolute binary path; by default the command must be a regular file (not a symlink). For package-manager shims (such as Homebrew), set `allowSymlinkCommand: true` and pair it with `trustedDirs`.

> [!WARNING]
>
> On Windows, secret resolution **fails closed** when ACL verification is unavailable for a file or command path. For trusted paths only, set `allowInsecurePath: true` on that provider to bypass path security checks.

### Env allowlist

`allowlist` (env providers only) restricts which environment variable names that provider may resolve. Default: unset — any env ref id resolves. When set (up to 256 names, each matching `^[A-Z][A-Z0-9_]{0,127}$`), a ref whose `id` is not in the list fails resolution:

```json5 theme={"dark"}
{
  secrets: {
    providers: {
      default: { source: "env", allowlist: ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"] },
    },
  },
}
```

### Timeouts and size limits

Each provider enforces read/command limits. All are positive integers in milliseconds or bytes; exceeding one fails that provider's resolution (and activation fails fast on active surfaces).

| Key | Applies to | Default | Max | Effect |
| - | - | - | - | - |
| `timeoutMs` | file, exec | `5000` | `120000` | File read / resolver command timeout |
| `noOutputTimeoutMs` | exec | same as `timeoutMs` | `120000` | Kill the resolver after this long with no output |
| `maxBytes` | file | `1048576` (1 MiB) | `20971520` (20 MiB) | Max secrets-file size |
| `maxOutputBytes` | exec | `1048576` (1 MiB) | `20971520` (20 MiB) | Max resolver stdout size |

### Resolution tuning

`secrets.resolution` bounds each activation-time resolution pass:

```json5 theme={"dark"}
{
  secrets: {
    resolution: { maxProviderConcurrency: 8, maxRefsPerProvider: 1024 },
  },
}
```

| Key | Default | Max | Effect |
| - | - | - | - |
| `maxProviderConcurrency` | `4` | `16` | How many providers resolve in parallel |
| `maxRefsPerProvider` | `512` | `4096` | Max refs routed to one provider per pass; more fails that provider |
| `maxBatchBytes` | `262144` (256 KiB) | `5242880` (5 MiB) | Max size of the JSON batch request payload sent to exec providers |

These apply at the next activation/reload — see [Runtime model](#runtime-model).

## Exec integration examples

> [accordion] 1Password CLI
>
> ```json5 theme={"dark"}
> {
>   secrets: {
>     providers: {
>       onepassword_openai: {
>         source: "exec",
>         command: "/opt/homebrew/bin/op",
>         allowSymlinkCommand: true,
>         trustedDirs: ["/opt/homebrew"],
>         args: ["read", "op://Personal/OpenClaw API Key/password"],
>         passEnv: ["HOME"],
>         jsonOnly: false,
>       },
>     },
>   },
>   models: {
>     providers: {
>       openai: {
>         baseUrl: "https://api.openai.com/v1",
>         models: [{ id: "gpt-5", name: "gpt-5" }],
>         apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
>       },
>     },
>   },
> }
> ```

> [accordion] HashiCorp Vault CLI
>
> ```json5 theme={"dark"}
> {
>   secrets: {
>     providers: {
>       vault_openai: {
>         source: "exec",
>         command: "/opt/homebrew/bin/vault",
>         allowSymlinkCommand: true,
>         trustedDirs: ["/opt/homebrew"],
>         args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
>         passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
>         jsonOnly: false,
>       },
>     },
>   },
> }
> ```

> [accordion] sops
>
> ```json5 theme={"dark"}
> {
>   secrets: {
>     providers: {
>       sops_openai: {
>         source: "exec",
>         command: "/opt/homebrew/bin/sops",
>         allowSymlinkCommand: true,
>         trustedDirs: ["/opt/homebrew"],
>         args: ["-d", "--extract", "[\"providers\"][\"openai\"][\"apiKey\"]", "/path/to/secrets.enc.json"],
>         passEnv: ["SOPS_AGE_KEY_FILE"],
>         jsonOnly: false,
>       },
>     },
>   },
> }
> ```

## Precedence

* A field without a ref is left unchanged.
* A field with a ref is required on active surfaces during activation.
* If both plaintext and a ref are present, the **ref wins** on supported precedence paths and the gateway logs `SECRETS_REF_OVERRIDES_PLAINTEXT`.
* When `auth-profiles.json` credentials shadow an `openclaw.json` ref, the audit reports `REF_SHADOWED`.

> [!NOTE]
>
> Runtime-minted or rotating credentials and OAuth refresh material are intentionally **excluded** from read-only SecretRef resolution. Use the auth profile flows for those.

## Audit and configure workflow

The standard operator flow:

```bash theme={"dark"}
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check
```

* **`secrets audit`** reports plaintext values at rest (in `openclaw.json`, `auth-profiles.json`, `.env`), unresolved refs, precedence shadowing, and legacy residues.
* **`secrets configure`** is an interactive helper: set up `secrets.providers`, pick the secret-bearing fields to convert, capture the SecretRef details, run preflight resolution, and optionally apply. Useful modes: `--providers-only`, `--skip-provider-setup`, `--agent <id>`.

Applying a saved plan:

```bash theme={"dark"}
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
```

After rotating a backend secret, refresh the gateway snapshot:

```bash theme={"dark"}
openclaw secrets reload
```

## One-way safety policy

WednesdayAI deliberately does **not** write rollback backups containing historical plaintext secrets. Preflight must succeed before write mode, runtime activation is validated before commit, and applies use atomic file replacement with best-effort restore on failure. When you convert a field to a SecretRef, `configure --apply` scrubs the matching plaintext from `auth-profiles.json`, legacy `auth.json`, and `<config-dir>/.env`.

***

**Related:** [Authentication](https://docs.wednesdayai.dev/next/admin/gateway/authentication.md) · [Gateway configuration](https://docs.wednesdayai.dev/next/admin/gateway/configuration.md) · [Security hardening](https://docs.wednesdayai.dev/next/admin/security.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.