Secrets management

​

Runtime model

• Secrets resolve into an in-memory runtime snapshot, eagerly during activation, not lazily on request paths.
• Cold Gateway startup isolates a retryable SecretRef failure to a known non-Gateway owner when that owner supports isolation. Mapped owner classes include model providers and skills, media/TTS/cron providers, eligible auth profiles, per-agent memory, sandbox SSH, channel accounts, and manifest-declared plugin routes. The Gateway starts, records the owner as configured-unavailable, and emits a redacted degradation warning. Gateway ingress auth, structurally invalid refs or resolved values, fail-closed owners, and refs whose runtime owner is not mapped still fail startup.
• Reload validates each mapped owner independently, then publishes one atomic snapshot. Healthy owners refresh. An eligible failed owner keeps its last-known-good value and becomes stale only when its ref identities, provider definitions, and complete non-secret owner contract are unchanged; a changed or new failed owner becomes cold. A strict failure rejects the reload and preserves the active snapshot.
• Policy violations (for example an OAuth-mode auth profile combined with SecretRef input) fail activation before the runtime swap.
• Runtime requests read only the active in-memory snapshot. Model-provider SecretRef credentials pass through auth storage and stream options as process-local sentinels until egress. Outbound delivery paths (Discord reply/thread delivery, Telegram action sends) also read that snapshot and do not re-resolve refs per send.
• Read-only channel capability discovery evaluates accounts independently. A configured-but-unavailable account does not hide healthy sibling accounts’ message actions, while direct sends through the unavailable account still fail closed.

​

Egress-time injection (sentinels)

• SDKs with a custom fetch option receive OpenClaw’s guarded fetch, so the SDK retains the sentinel.
• SDKs without a custom fetch option unwrap the sentinel immediately before client construction. Plugin-owned provider streams and agent harnesses unwrap at the final core-owned handoff because those transports do not share OpenClaw’s guarded fetch.

​

Agent-access boundary

• Supported credentials use SecretRefs instead of plaintext values.
• Legacy plaintext residue is scrubbed from openclaw.json, the SQLite auth-profile store, .env, and generated models.json files. Retired auth JSON is doctor-owned migration input and is never rewritten by secrets apply.
• openclaw secrets audit --check is clean after migration.
• Any remaining unsupported or rotating credentials are protected by OS isolation, container isolation, or an external credential proxy.

​

Active-surface filtering

• Enabled surfaces: retryable failures for mapped, isolatable owners enter cold or stale degradation. Strict, fail-closed, Gateway-required, or unmapped failures block startup/reload.
• Inactive surfaces: unresolved refs do not block startup/reload; they emit a non-fatal SECRETS_REF_IGNORED_INACTIVE_SURFACE diagnostic.

​

Gateway auth surface diagnostics

• active: the SecretRef is part of the effective auth surface and must resolve.
• inactive: another auth surface wins, or remote auth is disabled/not active.

​

Onboarding reference preflight

• Env refs: validates the env var name and confirms a non-empty value is visible during setup.
• Provider refs (file, exec, or store): validates provider selection, resolves id, and checks the resolved value type.
• Quickstart flow: when gateway.auth.token is already a SecretRef, onboarding resolves it before probe/dashboard bootstrap (for env, file, exec, and store refs) using the same fail-fast gate.
• Generated gateway token: setup mints gateway.auth.token itself, so reference mode has nothing to prompt for. With OPENCLAW_GATEWAY_TOKEN exported it writes an env ref to that variable, keeping a later rotation authoritative; otherwise it writes the token to the secret store under OPENCLAW_GATEWAY_TOKEN and stores a store ref. An existing store entry is reused rather than rotated, so re-running setup never invalidates already-paired clients.

​

SecretRef contract

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

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

"${OPENAI_API_KEY}"
"$OPENAI_API_KEY"

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

{ source: "exec", provider: "vault", id: "providers/openai/apiKey#value" }

{ source: "store", provider: "default", id: "OPENAI_API_KEY" }

​

Provider config

{
  secrets: {
    providers: {
      default: { source: "env" },
      teamstore: { source: "store" },
      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,
      },
      "team-secrets": {
        source: "exec",
        pluginIntegration: {
          pluginId: "acme-secrets",
          integrationId: "secret-store",
        },
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
      store: "teamstore",
    },
  },
}

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

{
  "protocolVersion": 1,
  "values": {},
  "errors": { "providers/openai/apiKey": { "code": "NOT_FOUND" } }
}

​

Shared secret store

• Protected secret (kind: "secret") values are write-only after saving. Gateway list results, the Control UI, and CLI list/get output never include them; there is no reveal RPC. A protected value is inert until a supported config field references it with a SecretRef or an enabled, destination-bound secret egress proxy uses it.
• Agent-readable environment (kind: "env") values remain visible to administrators in the Control UI and can be returned by store list and store get. OpenClaw adds them as plaintext to Gateway-hosted commands run through its exec tool, after inherited process values and before explicit per-call env. The agent can print, transmit, or persist these values. Protected host keys are ignored with a visible warning.

{
  models: {
    providers: {
      openai: {
        apiKey: { source: "store", provider: "default", id: "OPENAI_API_KEY" },
      },
    },
  },
}

​

Secret egress proxy

openclaw secrets store set OPENAI_API_KEY --allow-host api.openai.com

openclaw config set secrets.egressProxy.enabled true --strict-json
openclaw gateway restart

openclaw secrets store set OPENAI_API_KEY --allow-host api.openai.com
openclaw config set secrets.egressProxy.enabled true --strict-json

curl -sS https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"

{
  secrets: {
    egressProxy: {
      enabled: true,
      bypassHosts: ["pinned-api.example.com"],
    },
  },
}

• HTTPS_PROXY and HTTP_PROXY, with per-run credentials embedded in the loopback proxy URL
• NODE_USE_ENV_PROXY=1, which makes supported Node.js global fetch clients honor HTTP_PROXY and HTTPS_PROXY without using NODE_OPTIONS
• NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, CURL_CA_BUNDLE, and REQUESTS_CA_BUNDLE, pointing at the ephemeral CA certificate
• each team-store secret entry as an oc-sent-v2...end sentinel; env entries keep their existing behavior and precedence

• HTTP/2 upstream connections are not supported; the proxy uses HTTP/1.1 upstream.
• WebSocket rewriting is not supported.
• Non-443 HTTPS substitution is not a supported compatibility target.
• Identity-scoped secrets are not supported; only the team store participates.
• Allowed-host policy is exact-hostname authorization only. It does not validate the resolved IP or prevent an allowed origin from reflecting credentials.
• Plain HTTP is refused; it is not upgraded or substituted.
• Secret egress applies only to Gateway-hosted exec. Sandbox and remote node exec receive neither proxy variables nor sentinels, so shared-store secret entries are unavailable there. Provider-native harness subprocesses also do not use this proxy.
• Background subprocesses lose proxy authorization when their owning agent run ends, even if the process itself is still alive.

​

File-backed API keys

{
  secrets: {
    providers: {
      xai_key_file: {
        source: "file",
        path: "~/.openclaw/secrets/xai-api-key.txt",
        mode: "singleValue",
      },
    },
  },
  models: {
    providers: {
      xai: {
        apiKey: { source: "file", provider: "xai_key_file", id: "value" },
      },
    },
  },
}

​

Exec integration examples

{
  plugins: {
    entries: {
      onepassword: {
        enabled: true,
      },
    },
  },
  secrets: {
    providers: {
      onepassword: {
        source: "exec",
        pluginIntegration: {
          pluginId: "onepassword",
          integrationId: "onepassword",
        },
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: {
          source: "exec",
          provider: "onepassword",
          id: "op://Engineering/OpenAI/apiKey",
        },
      },
    },
  },
}

{
  secrets: {
    providers: {
      bws: {
        source: "exec",
        command: "/usr/local/bin/openclaw-bws-resolver.mjs",
        passEnv: ["BWS_ACCESS_TOKEN", "BWS_SERVER_URL", "PATH", "BWS_BIN"],
        jsonOnly: true,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: {
          source: "exec",
          provider: "bws",
          id: "openclaw/providers/openai/apiKey",
        },
      },
    },
  },
}

openclaw secrets audit --allow-exec

{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/absolute/non-symlink/path/to/vault",
        trustedDirs: ["/absolute/non-symlink/path/to"],
        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "vault_openai", id: "value" },
      },
    },
  },
}

#!/usr/bin/env node
const { spawnSync } = require("node:child_process");

let stdin = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => {
  stdin += chunk;
});
process.stdin.on("error", (err) => {
  process.stderr.write(`${err.message}\n`);
  process.exit(1);
});
process.stdin.on("end", () => {
  let request;
  try {
    request = JSON.parse(stdin || "{}");
  } catch (err) {
    process.stderr.write(`Failed to parse request: ${err.message}\n`);
    process.exit(1);
  }

  const passBin = process.env.PASS_BIN || "pass";
  const values = {};
  const errors = {};

  for (const id of request.ids ?? []) {
    const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });
    if (result.status === 0) {
      values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";
    } else {
      errors[id] = { message: (result.stderr || `pass exited ${result.status}`).trim() };
    }
  }

  process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));
});

{
  secrets: {
    providers: {
      pass_store: {
        source: "exec",
        command: "/usr/local/bin/openclaw-pass-resolver",
        passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],
        jsonOnly: true,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: {
          source: "exec",
          provider: "pass_store",
          id: "openclaw/providers/openai/apiKey",
        },
      },
    },
  },
}

openclaw secrets audit --check
openclaw secrets audit --allow-exec

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/absolute/non-symlink/path/to/sops",
        trustedDirs: ["/absolute/non-symlink/path/to"],
        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
        passEnv: ["SOPS_AGE_KEY_FILE"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "sops_openai", id: "value" },
      },
    },
  },
}

​

MCP server environment variables

{
  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",
                },
              },
            },
          },
        },
      },
    },
  },
}

​

Sandbox 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" },
        },
      },
    },
  },
}

• OpenClaw resolves these refs during sandbox activation, not lazily on each SSH call.
• Resolved values are written to a temp directory with restrictive file permissions (0o600) and used in the generated SSH config.
• If the effective sandbox backend is not ssh (or sandbox mode is off), these refs stay inactive and do not block startup.

​

Supported 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, the ref takes precedence on supported precedence paths.
• The redaction sentinel __OPENCLAW_REDACTED__ is reserved for internal config redaction/restore and is rejected as literal submitted config data.

• SECRETS_REF_OVERRIDES_PLAINTEXT (runtime warning)
• REF_SHADOWED (audit finding when SQLite auth-profile credentials take precedence over openclaw.json refs)
• STORE_PLAINTEXT_RESIDUE (audit finding when a stored name still has an equivalent plaintext config value)

​

Activation triggers

• Startup (preflight plus final activation)
• Config reload hot-apply path
• Config reload restart-check path
• Manual reload via secrets.reload
• Gateway config write RPC preflight (config.set / config.apply / config.patch), validating active-surface SecretRefs within the submitted config payload before persisting edits

• Success swaps the snapshot atomically.
• A strict startup failure aborts Gateway startup.
• During cold startup, a retryable resolution failure for a mapped, isolatable non-Gateway owner may publish the snapshot with that exact owner configured-unavailable. Requests for the owner fail with SECRET_SURFACE_UNAVAILABLE; model-provider owners do not fall back to environment or auth-profile credentials after an explicit ref fails.
• Reload and restart-check isolate eligible mapped owners. Unchanged ref identities with unchanged provider definitions and an unchanged complete non-secret owner contract retain their exact last-known-good values as stale; changed or newly configured unresolved refs publish cold for only that owner. A strict reload failure preserves the previously active snapshot.
• config.set, config.apply, and config.patch accept syntactically valid unresolved refs for isolatable owners and return a redacted degradedSecretOwners report. Gateway ingress auth, structurally invalid config or resolved values, policy violations, and unknown owners still reject before disk mutation.
• Healthy sibling owners resolve and publish normally even when another owner is cold or stale.
• 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 secrets.reload.

​

Degraded and recovered signals

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

• Degraded: healthy owners refresh, stale owners keep last-known-good, and cold owners remain unavailable.
• Recovered: emitted once after the next successful activation.
• Repeated failures while already degraded log warnings but do not re-emit the event.
• A strict startup failure never emits a degraded event, because runtime never became active. A successful startup with cold owners logs the owner degradation but does not emit a reloader event.
• Ref-scoped startup and reload failures emit a structured SECRETS_DEGRADED warning for each affected owner. Provider-scoped outages emit one SECRETS_PROVIDER_DEGRADED warning with the provider and complete affected-owner list instead of repeating the provider failure per owner. Warnings include a redacted reason, cold or stale owner state, and the openclaw secrets reload retry hint. They never include resolved values or SecretRef ids.
• openclaw doctor lists cold and stale owners with their affected config paths, redacted reason, and retry guidance.

​

Command-path resolution

• Snapshot refresh after backend secret rotation is handled by openclaw secrets reload.
• Gateway RPC method used by these command paths: secrets.resolve.

​

Audit and configure workflow

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

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

​

One-way safety policy

• 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

• Runtime credential source is the resolved in-memory snapshot.
• Legacy static api_key entries are scrubbed when discovered.
• OAuth-related compatibility behavior remains separate.

​

Control UI

​

Related

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