Secrets management

OpenClaw supports additive SecretRefs so supported credentials do not need to be stored as plaintext in configuration.

Goals and runtime model

Secrets are resolved into an in-memory runtime snapshot.

• Resolution is eager during activation, not lazy on request paths.
• Startup fails fast when an effectively active SecretRef cannot be resolved.
• Reload uses atomic swap: full success, or keep the last-known-good snapshot.
• SecretRef policy violations (for example OAuth-mode auth profiles combined with SecretRef input) fail activation before runtime swap.
• Runtime requests read from the active in-memory snapshot only.
• After the first successful config activation/load, runtime code paths keep reading that active in-memory snapshot until a successful reload swaps it.
• Outbound delivery paths also read from that active snapshot (for example Discord reply/thread delivery and Telegram action sends); they do not re-resolve SecretRefs on each send.

This keeps secret-provider outages off hot request paths.

Active-surface filtering

SecretRefs are validated only on effectively active surfaces.

• Enabled surfaces: unresolved refs block startup/reload.
• Inactive surfaces: unresolved refs do not block startup/reload.
• Inactive refs emit non-fatal diagnostics with code
  text

  Copy

  SECRETS_REF_IGNORED_INACTIVE_SURFACE
  .

Gateway auth surface diagnostics

When a SecretRef is configured on

• text

  Copy

  active
  : the SecretRef is part of the effective auth surface and must resolve.
• text

  Copy

  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

Onboarding reference preflight

When onboarding runs in interactive mode and you choose SecretRef storage, OpenClaw runs preflight validation before saving:

• Env refs: validates env var name and confirms a non-empty value is visible during setup.
• Provider refs (
  text

  Copy

  file
  or
  text

  Copy

  exec
  ): validates provider selection, resolves
  text

  Copy

  id
  , and checks resolved value type.
• Quickstart reuse path: when
  text

  Copy

  gateway.auth.token
  is already a SecretRef, onboarding resolves it before probe/dashboard bootstrap (for
  text

  Copy

  env
  ,
  text

  Copy

  file
  , and
  text

  Copy

  exec
  refs) using the same fail-fast gate.

If validation fails, onboarding shows the error and lets you retry.

SecretRef contract

Use one object shape everywhere:

json5
Copy
{ source: "env" | "file" | "exec", provider: "default", id: "..." }

text
Copy
Validation:

* `provider` must match `^[a-z][a-z0-9_-]{0,63}$`
* `id` must match `^[A-Z][A-Z0-9_]{0,127}$`

text
Copy
Validation:

* `provider` must match `^[a-z][a-z0-9_-]{0,63}$`
* `id` must be an absolute JSON pointer (`/...`)
* RFC6901 escaping in segments: `~` => `~0`, `/` => `~1`

text
Copy
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)

Provider config

Define providers under

json5
Copy
{
  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,
    },
  },
}

Exec integration examples

MCP server environment variables

MCP server env vars configured via

json5
Copy
{
  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

Sandbox SSH auth material

The core

json5
Copy
{
  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:

• OpenClaw resolves these refs during sandbox activation, not lazily during each SSH call.
• Resolved values are written to temp files with restrictive permissions and used in generated SSH config.
• If the effective sandbox backend is not
  text

  Copy

  ssh
  , these refs stay inactive and do not block startup.

Supported credential surface

Canonical supported and unsupported credentials are listed in:

• SecretRef Credential Surface

Required behavior and precedence

• Field without a ref: unchanged.
• Field with a ref: required on active surfaces during activation.
• If both plaintext and ref are present, ref takes precedence on supported precedence paths.
• The redaction sentinel
  text

  Copy

  __OPENCLAW_REDACTED__
  is reserved for internal config redaction/restore and is rejected as literal submitted config data.

Warning and audit signals:

• text

  Copy

  SECRETS_REF_OVERRIDES_PLAINTEXT
  (runtime warning)
• text

  Copy

  REF_SHADOWED
  (audit finding when
  text

  Copy

  auth-profiles.json
  credentials take precedence over
  text

  Copy

  openclaw.json
  refs)

Google Chat compatibility behavior:

• text

  Copy

  serviceAccountRef
  takes precedence over plaintext
  text

  Copy

  serviceAccount
  .
• Plaintext value is ignored when sibling ref is set.

Activation triggers

Secret activation runs on:

• Startup (preflight plus final activation)
• Config reload hot-apply path
• Config reload restart-check path
• Manual reload via
  text

  Copy

  secrets.reload
• Gateway config write RPC preflight (
  text

  Copy

  config.set
  /
  text

  Copy

  config.apply
  /
  text

  Copy

  config.patch
  ) for active-surface SecretRef resolvability within the submitted config payload before persisting edits

Activation contract:

• Success swaps the snapshot atomically.
• Startup failure aborts gateway startup.
• Runtime reload failure keeps the last-known-good snapshot.
• Write-RPC preflight failure rejects the submitted config and keeps both disk config and active runtime snapshot unchanged.
• Providing an explicit per-call channel token to an outbound helper/tool call does not trigger SecretRef activation; activation points remain startup, reload, and explicit
  text

  Copy

  secrets.reload
  .

Degraded and recovered signals

When reload-time activation fails after a healthy state, OpenClaw enters degraded secrets state.

One-shot system event and log codes:

• text

  Copy

  SECRETS_RELOADER_DEGRADED
• text

  Copy

  SECRETS_RELOADER_RECOVERED

Behavior:

• Degraded: runtime keeps last-known-good snapshot.
• Recovered: emitted once after the next successful activation.
• Repeated failures while already degraded log warnings but do not spam events.
• Startup fail-fast does not emit degraded events because runtime never became active.

Command-path resolution

Command paths can opt into supported SecretRef resolution via gateway snapshot RPC.

There are two broad behaviors:

text
Copy
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:

• Snapshot refresh after backend secret rotation is handled by
  text

  Copy

  openclaw secrets reload
  .
• Gateway RPC method used by these command paths:
  text

  Copy

  secrets.resolve
  .

Audit and configure workflow

Default operator flow:

One-way safety policy

Safety model:

• preflight must succeed before write mode
• runtime activation is validated before commit
• apply updates files using atomic file replacement and best-effort restore on failure

Legacy auth compatibility notes

For static credentials, runtime no longer depends on plaintext legacy auth storage.

• Runtime credential source is the resolved in-memory snapshot.
• Legacy static
  text

  Copy

  api_key
  entries are scrubbed when discovered.
• OAuth-related compatibility behavior remains separate.

Web UI note

Some SecretInput unions are easier to configure in raw editor mode than in form mode.

Related

• Authentication — auth setup
• CLI: secrets — CLI commands
• Environment Variables — environment precedence
• SecretRef Credential Surface — credential surface
• Secrets Apply Plan Contract — plan contract details
• Security — security posture