docs/gateway/secrets.md
OpenClaw supports additive SecretRefs so supported credentials do not need to be stored as plaintext in configuration.
<Note> Plaintext still works. SecretRefs are opt-in per credential. </Note>Secrets are resolved into an in-memory runtime snapshot.
This keeps secret-provider outages off hot request paths.
SecretRefs are validated only on effectively active surfaces.
SECRETS_REF_IGNORED_INACTIVE_SURFACE.When a SecretRef is configured on gateway.auth.token, gateway.auth.password, gateway.remote.token, or gateway.remote.password, gateway startup/reload logs the surface state explicitly:
active: the SecretRef is part of the effective auth surface and must resolve.inactive: the SecretRef is ignored for this runtime because another auth surface wins, or because remote auth is disabled/not active.These entries are logged with SECRETS_GATEWAY_AUTH_SURFACE and include the reason used by the active-surface policy, so you can see why a credential was treated as active or inactive.
When onboarding runs in interactive mode and you choose SecretRef storage, OpenClaw runs preflight validation before saving:
file or exec): validates provider selection, resolves id, and checks resolved value type.gateway.auth.token is already a SecretRef, onboarding resolves it before probe/dashboard bootstrap (for env, file, and exec refs) using the same fail-fast gate.If validation fails, onboarding shows the error and lets you retry.
Use one object shape everywhere:
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
Validation:
- `provider` must match `^[a-z][a-z0-9_-]{0,63}$`
- `id` must match `^[A-Z][A-Z0-9_]{0,127}$`
Validation:
- `provider` must match `^[a-z][a-z0-9_-]{0,63}$`
- `id` must be an absolute JSON pointer (`/...`)
- RFC6901 escaping in segments: `~` => `~0`, `/` => `~1`
Validation:
- `provider` must match `^[a-z][a-z0-9_-]{0,63}$`
- `id` must match `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- `id` must not contain `.` or `..` as slash-delimited path segments (for example `a/../b` is rejected)
Define providers under secrets.providers:
{
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",
},
resolution: {
maxProviderConcurrency: 4,
maxRefsPerProvider: 512,
maxBatchBytes: 262144,
},
},
}
Request payload (stdin):
```json
{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }
```
Response payload (stdout):
```jsonc
{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret
```
Optional per-id errors:
```json
{
"protocolVersion": 1,
"values": {},
"errors": { "providers/openai/apiKey": { "message": "not found" } }
}
```
MCP server env vars configured via plugins.entries.acpx.config.mcpServers support SecretInput. This keeps API keys and tokens out of plaintext config:
{
plugins: {
entries: {
acpx: {
enabled: true,
config: {
mcpServers: {
github: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: {
GITHUB_PERSONAL_ACCESS_TOKEN: {
source: "env",
provider: "default",
id: "MCP_GITHUB_PAT",
},
},
},
},
},
},
},
},
}
Plaintext string values still work. Env-template refs like ${MCP_SERVER_API_KEY} and SecretRef objects are resolved during gateway activation before the MCP server process is spawned. As with other SecretRef surfaces, unresolved refs only block activation when the acpx plugin is effectively active.
The core ssh sandbox backend also supports SecretRefs for SSH auth material:
{
agents: {
defaults: {
sandbox: {
mode: "all",
backend: "ssh",
ssh: {
target: "user@gateway-host:22",
identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
},
},
},
},
}
Runtime behavior:
ssh, these refs stay inactive and do not block startup.Canonical supported and unsupported credentials are listed in:
<Note> Runtime-minted or rotating credentials and OAuth refresh material are intentionally excluded from read-only SecretRef resolution. </Note>__OPENCLAW_REDACTED__ is reserved for internal config redaction/restore and is rejected as literal submitted config data.Warning and audit signals:
SECRETS_REF_OVERRIDES_PLAINTEXT (runtime warning)REF_SHADOWED (audit finding when auth-profiles.json credentials take precedence over openclaw.json refs)Google Chat compatibility behavior:
serviceAccountRef takes precedence over plaintext serviceAccount.Secret activation runs on:
secrets.reloadconfig.set / config.apply / config.patch) for active-surface SecretRef resolvability within the submitted config payload before persisting editsActivation contract:
secrets.reload.When reload-time activation fails after a healthy state, OpenClaw enters degraded secrets state.
One-shot system event and log codes:
SECRETS_RELOADER_DEGRADEDSECRETS_RELOADER_RECOVEREDBehavior:
Command paths can opt into supported SecretRef resolution via gateway snapshot RPC.
There are two broad behaviors:
<Tabs> <Tab title="Strict command paths"> For example `openclaw memory` remote-memory paths and `openclaw qr --remote` when it needs remote shared-secret refs. They read from the active snapshot and fail fast when a required SecretRef is unavailable. </Tab> <Tab title="Read-only command paths"> For example `openclaw status`, `openclaw status --all`, `openclaw channels status`, `openclaw channels resolve`, `openclaw security audit`, and read-only doctor/config repair flows. They also prefer the active snapshot, but degrade instead of aborting when a targeted SecretRef is unavailable in that command path.Read-only behavior:
- When the gateway is running, these commands read from the active snapshot first.
- If gateway resolution is incomplete or the gateway is unavailable, they attempt targeted local fallback for the specific command surface.
- If a targeted SecretRef is still unavailable, the command continues with degraded read-only output and explicit diagnostics such as "configured but unavailable in this command path".
- This degraded behavior is command-local only. It does not weaken runtime startup, reload, or send/auth paths.
Other notes:
openclaw secrets reload.secrets.resolve.Default operator flow:
<Steps> <Step title="Audit current state"> ```bash openclaw secrets audit --check ``` </Step> <Step title="Configure SecretRefs"> ```bash openclaw secrets configure ``` </Step> <Step title="Re-audit"> ```bash openclaw secrets audit --check ``` </Step> </Steps> <AccordionGroup> <Accordion title="secrets audit"> Findings include:- plaintext values at rest (`openclaw.json`, `auth-profiles.json`, `.env`, and generated `agents/*/agent/models.json`)
- plaintext sensitive provider header residues in generated `models.json` entries
- unresolved refs
- precedence shadowing (`auth-profiles.json` taking priority over `openclaw.json` refs)
- legacy residues (`auth.json`, OAuth reminders)
Exec note:
- By default, audit skips exec SecretRef resolvability checks to avoid command side effects.
- Use `openclaw secrets audit --allow-exec` to execute exec providers during audit.
Header residue note:
- Sensitive provider header detection is name-heuristic based (common auth/credential header names and fragments such as `authorization`, `x-api-key`, `token`, `secret`, `password`, and `credential`).
- configures `secrets.providers` first (`env`/`file`/`exec`, add/edit/remove)
- lets you select supported secret-bearing fields in `openclaw.json` plus `auth-profiles.json` for one agent scope
- can create a new `auth-profiles.json` mapping directly in the target picker
- captures SecretRef details (`source`, `provider`, `id`)
- runs preflight resolution
- can apply immediately
Exec note:
- Preflight skips exec SecretRef checks unless `--allow-exec` is set.
- If you apply directly from `configure --apply` and the plan includes exec refs/providers, keep `--allow-exec` set for the apply step too.
Helpful modes:
- `openclaw secrets configure --providers-only`
- `openclaw secrets configure --skip-provider-setup`
- `openclaw secrets configure --agent <id>`
`configure` apply defaults:
- scrub matching static credentials from `auth-profiles.json` for targeted providers
- scrub legacy static `api_key` entries from `auth.json`
- scrub matching known secret lines from `<config-dir>/.env`
```bash
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
```
Exec note:
- dry-run skips exec checks unless `--allow-exec` is set.
- write mode rejects plans containing exec SecretRefs/providers unless `--allow-exec` is set.
For strict target/path contract details and exact rejection rules, see [Secrets Apply Plan Contract](/gateway/secrets-plan-contract).
Safety model:
For static credentials, runtime no longer depends on plaintext legacy auth storage.
api_key entries are scrubbed when discovered.Some SecretInput unions are easier to configure in raw editor mode than in form mode.