OpenClaw supports additive SecretRefs so supported credentials do not need to be stored as plaintext in configuration.<\/p>\n
Plaintext still works. SecretRefs are opt-in per credential.<\/p>\n
Secrets are resolved into an in-memory runtime snapshot.<\/p>\n
This keeps secret-provider outages off hot request paths.<\/p>\n
SecretRefs are validated only on effectively active surfaces.<\/p>\n
SECRETS_REF_IGNORED_INACTIVE_SURFACE<\/code>.<\/li>\n<\/ul>\nExamples of inactive surfaces:<\/p>\n
\n- Disabled \u6e20\u9053\/account entries.<\/li>\n
- Top-level \u6e20\u9053 credentials that no enabled account inherits.<\/li>\n
- Disabled tool\/feature surfaces.<\/li>\n
- Web search provider-specific keys that are not selected by
tools.web.search.provider<\/code>.
\n In auto mode (provider unset), keys are consulted by precedence for provider auto-detection until one resolves.
\n After selection, non-selected provider keys are treated as inactive until selected.<\/li>\n- Sandbox SSH auth material (
agents.defaults.sandbox.ssh.identityData<\/code>,
\n certificateData<\/code>, knownHostsData<\/code>, plus per-agent overrides) is active only
\n when the effective sandbox backend is ssh<\/code> for the default agent or an enabled agent.<\/li>\ngateway.remote.token<\/code> \/ gateway.remote.password<\/code> SecretRefs are active if one of these is true:<\/li>\ngateway.mode=remote<\/code><\/li>\ngateway.remote.url<\/code> is configured<\/li>\ngateway.tailscale.mode<\/code> is serve<\/code> or funnel<\/code><\/li>\n- In local mode without those remote surfaces:\n
\ngateway.remote.token<\/code> is active when token auth can win and no env\/auth token is configured.<\/li>\ngateway.remote.password<\/code> is active only when password auth can win and no env\/auth password is configured.<\/li>\n<\/ul>\n<\/li>\ngateway.auth.token<\/code> SecretRef is inactive for startup auth resolution when OPENCLAW_GATEWAY_TOKEN<\/code> (or CLAWDBOT_GATEWAY_TOKEN<\/code>) is set, because env token input wins for that runtime.<\/li>\n<\/ul>\nGateway \u7f51\u5173 auth surface diagnostics<\/h2>\n
When a SecretRef is configured on gateway.auth.token<\/code>, gateway.auth.password<\/code>,
\ngateway.remote.token<\/code>, or gateway.remote.password<\/code>, \u7f51\u5173 startup\/reload logs the
\nsurface state explicitly:<\/p>\n\nactive<\/code>: the SecretRef is part of the effective auth surface and must resolve.<\/li>\ninactive<\/code>: the SecretRef is ignored for this runtime because another auth surface wins, or
\n because remote auth is disabled\/not active.<\/li>\n<\/ul>\nThese entries are logged with SECRETS_GATEWAY_AUTH_SURFACE<\/code> and include the reason used by the
\nactive-surface policy, so you can see why a credential was treated as active or inactive.<\/p>\nOnboarding reference preflight<\/h2>\n
When onboarding runs in interactive mode and you choose SecretRef storage, OpenClaw runs preflight validation before saving:<\/p>\n
\n- Env refs: validates env var name and confirms a non-empty value is visible during setup.<\/li>\n
- Provider refs (
file<\/code> or exec<\/code>): validates provider selection, resolves id<\/code>, and checks resolved value type.<\/li>\n- Quickstart reuse path: when
gateway.auth.token<\/code> is already a SecretRef, onboarding resolves it before probe\/dashboard bootstrap (for env<\/code>, file<\/code>, and exec<\/code> refs) using the same fail-fast gate.<\/li>\n<\/ul>\nIf validation fails, onboarding shows the error and lets you retry.<\/p>\n
SecretRef contract<\/h2>\n
Use one object shape everywhere:<\/p>\n
“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{ source: “env” | “file” | “exec”, provider: “default”, id: “…” }<\/p>\n
\n### `source: "env"`\n\n```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{ source: "env", provider: "default", id: "OPENAI_API_KEY" }\n<\/code><\/pre>\nValidation:<\/p>\n
\nprovider<\/code> must match ^[a-z][a-z0-9_-]{0,63}$<\/code><\/li>\nid<\/code> must match ^[A-Z][A-Z0-9_]{0,127}$<\/code><\/li>\n<\/ul>\nsource: \"file\"<\/code><\/h3>\n“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{ source: “file”, provider: “filemain”, id: “\/providers\/openai\/apiKey” }<\/p>\n
\nValidation:\n\n* `provider` must match `^[a-z][a-z0-9_-]{0,63}$`\n* `id` must be an absolute JSON pointer (`\/...`)\n* RFC6901 escaping in segments: `~` => `~0`, `\/` => `~1`\n\n### `source: "exec"`\n\n```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{ source: "exec", provider: "vault", id: "providers\/openai\/apiKey" }\n<\/code><\/pre>\nValidation:<\/p>\n
\nprovider<\/code> must match ^[a-z][a-z0-9_-]{0,63}$<\/code><\/li>\nid<\/code> must match ^[A-Za-z0-9][A-Za-z0-9._:\/-]{0,255}$<\/code><\/li>\nid<\/code> must not contain .<\/code> or ..<\/code> as slash-delimited path segments (for example a\/..\/b<\/code> is rejected)<\/li>\n<\/ul>\nProvider config<\/h2>\n
Define providers under secrets.providers<\/code>:<\/p>\n“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{
\n secrets: {
\n providers: {
\n default: { source: “env” },
\n filemain: {
\n source: “file”,
\n path: “~\/.openclaw\/secrets.json”,
\n mode: “json”, \/\/ or “singleValue”
\n },
\n vault: {
\n source: “exec”,
\n command: “\/usr\/local\/bin\/openclaw-vault-resolver”,
\n args: [“–profile”, “prod”],
\n passEnv: [“PATH”, “VAULT_ADDR”],
\n jsonOnly: true,
\n },
\n },
\n defaults: {
\n env: “default”,
\n file: “filemain”,
\n exec: “vault”,
\n },
\n resolution: {
\n maxProviderConcurrency: 4,
\n maxRefsPerProvider: 512,
\n maxBatchBytes: 262144,
\n },
\n },
\n}<\/p>\n
\n### Env provider\n\n* Optional allowlist via `allowlist`.\n* Missing\/empty env values fail resolution.\n\n### File provider\n\n* Reads local file from `path`.\n* `mode: "json"` expects JSON object payload and resolves `id` as pointer.\n* `mode: "singleValue"` expects ref id `"value"` and returns file contents.\n* Path must pass ownership\/permission checks.\n* Windows fail-closed note: if ACL verification is unavailable for a path, resolution fails. For trusted paths only, set `allowInsecurePath: true` on that provider to bypass path security checks.\n\n### Exec provider\n\n* Runs configured absolute binary path, no shell.\n* By default, `command` must point to a regular file (not a symlink).\n* Set `allowSymlinkCommand: true` to allow symlink command paths (for example Homebrew shims). OpenClaw validates the resolved target path.\n* Pair `allowSymlinkCommand` with `trustedDirs` for package-manager paths (for example `["\/opt\/homebrew"]`).\n* Supports timeout, no-output timeout, output byte limits, env allowlist, and trusted dirs.\n* Windows fail-closed note: if ACL verification is unavailable for the command path, resolution fails. For trusted paths only, set `allowInsecurePath: true` on that provider to bypass path security checks.\n\nRequest payload (stdin):\n\n```json theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{ "protocolVersion": 1, "provider": "vault", "ids": ["providers\/openai\/apiKey"] }\n<\/code><\/pre>\nResponse payload (stdout):<\/p>\n
“`jsonc theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{ “protocolVersion”: 1, “values”: { “providers\/openai\/apiKey”: “” } } \/\/ pragma: allowlist secret<\/p>\n
\nOptional per-id errors:\n\n```json theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{\n "protocolVersion": 1,\n "values": {},\n "errors": { "providers\/openai\/apiKey": { "message": "not found" } }\n}\n<\/code><\/pre>\nExec integration examples<\/h2>\n1Password CLI<\/h3>\n
“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{
\n secrets: {
\n providers: {
\n onepassword_openai: {
\n source: “exec”,
\n command: “\/opt\/homebrew\/bin\/op”,
\n allowSymlinkCommand: true, \/\/ required for Homebrew symlinked binaries
\n trustedDirs: [“\/opt\/homebrew”],
\n args: [“read”, “op:\/\/Personal\/OpenClaw QA API Key\/password”],
\n passEnv: [“HOME”],
\n jsonOnly: false,
\n },
\n },
\n },
\n models: {
\n providers: {
\n openai: {
\n baseUrl: “https:\/\/api.openai.com\/v1”,
\n models: [{ id: “gpt-5”, name: “gpt-5” }],
\n apiKey: { source: “exec”, provider: “onepassword_openai”, id: “value” },
\n },
\n },
\n },
\n}<\/p>\n
\n### HashiCorp Vault CLI\n\n```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{\n secrets: {\n providers: {\n vault_openai: {\n source: "exec",\n command: "\/opt\/homebrew\/bin\/vault",\n allowSymlinkCommand: true, \/\/ required for Homebrew symlinked binaries\n trustedDirs: ["\/opt\/homebrew"],\n args: ["kv", "get", "-field=OPENAI_API_KEY", "secret\/openclaw"],\n passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],\n jsonOnly: false,\n },\n },\n },\n models: {\n providers: {\n openai: {\n baseUrl: "https:\/\/api.openai.com\/v1",\n models: [{ id: "gpt-5", name: "gpt-5" }],\n apiKey: { source: "exec", provider: "vault_openai", id: "value" },\n },\n },\n },\n}\n<\/code><\/pre>\nsops<\/code><\/h3>\n“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\n{
\n secrets: {
\n providers: {
\n sops_openai: {
\n source: “exec”,
\n command: “\/opt\/homebrew\/bin\/sops”,
\n allowSymlinkCommand: true, \/\/ required for Homebrew symlinked binaries
\n trustedDirs: [“\/opt\/homebrew”],
\n args: [“-d”, “–extract”, ‘[“providers”][“openai”][“apiKey”]’, “\/path\/to\/secrets.enc.json”],
\n passEnv: [“SOPS_AGE_KEY_FILE”],
\n jsonOnly: false,
\n },
\n },
\n },
\n models: {
\n providers: {
\n openai: {
\n baseUrl: “https:\/\/api.openai.com\/v1”,
\n models: [{ id: “gpt-5”, name: “gpt-5” }],
\n apiKey: { source: “exec”, provider: “sops_openai”, id: “value” },
\n },
\n },
\n },
\n}<\/p>\n
\n## Sandbox SSH auth material\n\nThe core `ssh` sandbox backend also supports SecretRefs for SSH auth material:\n\n```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}\n{\n agents: {\n defaults: {\n sandbox: {\n mode: "all",\n backend: "ssh",\n ssh: {\n target: "user@gateway-host:22",\n identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },\n certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },\n knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },\n },\n },\n },\n },\n}\n<\/code><\/pre>\nRuntime behavior:<\/p>\n
\n- OpenClaw resolves these refs during sandbox activation, not lazily during each SSH call.<\/li>\n
- Resolved values are written to temp files with restrictive permissions and used in generated SSH config.<\/li>\n
- If the effective sandbox backend is not
ssh<\/code>, these refs stay inactive and do not block startup.<\/li>\n<\/ul>\nSupported credential surface<\/h2>\n
Canonical supported and unsupported credentials are listed in:<\/p>\n
\n- SecretRef Credential Surface<\/a><\/li>\n<\/ul>\n
Runtime-minted or rotating credentials and OAuth refresh material are intentionally excluded from read-only SecretRef resolution.<\/p>\n
Required behavior and precedence<\/h2>\n\n- Field without a ref: unchanged.<\/li>\n
- Field with a ref: required on active surfaces during activation.<\/li>\n
- If both plaintext and ref are present, ref takes precedence on supported precedence paths.<\/li>\n<\/ul>\n
\u8b66\u544a and audit signals:<\/p>\n
\nSECRETS_REF_OVERRIDES_PLAINTEXT<\/code> (runtime warning)<\/li>\nREF_SHADOWED<\/code> (audit finding when auth-profiles.json<\/code> credentials take precedence over openclaw.json<\/code> refs)<\/li>\n<\/ul>\nGoogle Chat compatibility behavior:<\/p>\n
\nserviceAccountRef<\/code> takes precedence over plaintext serviceAccount<\/code>.<\/li>\n- Plaintext value is ignored when sibling ref is set.<\/li>\n<\/ul>\n
Activation triggers<\/h2>\n
Secret activation runs on:<\/p>\n
\n- Startup (preflight plus final activation)<\/li>\n
- Config reload hot-apply path<\/li>\n
- Config reload restart-check path<\/li>\n
- Manual reload via
secrets.reload<\/code><\/li>\n<\/ul>\nActivation contract:<\/p>\n
\n- Success swaps the snapshot atomically.<\/li>\n
- Startup failure aborts \u7f51\u5173 startup.<\/li>\n
- Runtime reload failure keeps the last-known-good snapshot.<\/li>\n
- Providing an explicit per-call \u6e20\u9053 token to an outbound helper\/tool call does not trigger SecretRef activation; activation points remain startup, reload, and explicit
secrets.reload<\/code>.<\/li>\n<\/ul>\nDegraded and recovered signals<\/h2>\n
When reload-time activation fails after a healthy state, OpenClaw enters degraded secrets state.<\/p>\n
One-shot system event and log codes:<\/p>\n
\nSECRETS_RELOADER_DEGRADED<\/code><\/li>\nSECRETS_RELOADER_RECOVERED<\/code><\/li>\n<\/ul>\nBehavior:<\/p>\n
\n- Degraded: runtime keeps last-known-good snapshot.<\/li>\n
- Recovered: emitted once after the next successful activation.<\/li>\n
- Repeated failures while already degraded log warnings but do not spam events.<\/li>\n
- Startup fail-fast does not emit degraded events because runtime never became active.<\/li>\n<\/ul>\n
Command-path resolution<\/h2>\n
Command paths can opt into supported SecretRef resolution via \u7f51\u5173 snapshot RPC.<\/p>\n
There are two broad behaviors:<\/p>\n
\n- Strict command paths (for example
openclaw memory<\/code> remote-memory paths and openclaw qr --remote<\/code>) read from the active snapshot and fail fast when a required SecretRef is unavailable.<\/li>\n- Read-only command paths (for example
openclaw status<\/code>, openclaw status --all<\/code>, openclaw channels status<\/code>, openclaw channels resolve<\/code>, openclaw security audit<\/code>, and read-only doctor\/config repair flows) also prefer the active snapshot, but degrade instead of aborting when a targeted SecretRef is unavailable in that command path.<\/li>\n<\/ul>\nRead-only behavior:<\/p>\n
\n- When the \u7f51\u5173 is running, these commands read from the active snapshot first.<\/li>\n
- If \u7f51\u5173 resolution is incomplete or the \u7f51\u5173 is unavailable, they attempt targeted local fallback for the specific command surface.<\/li>\n
- If a targeted SecretRef is still unavailable, the command continues with degraded read-only output and explicit diagnostics such as \u201cconfigured but unavailable in this command path\u201d.<\/li>\n
- This degraded behavior is command-local only. It does not weaken runtime startup, reload, or send\/auth paths.<\/li>\n<\/ul>\n
Other notes:<\/p>\n
\n- Snapshot refresh after backend secret rotation is handled by
openclaw secrets reload<\/code>.<\/li>\n- Gateway \u7f51\u5173 RPC method used by these command paths:
secrets.resolve<\/code>.<\/li>\n<\/ul>\nAudit and configure workflow<\/h2>\n
Default operator flow:<\/p>\n
“`bash theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
\nopenclaw secrets audit –check
\nopenclaw secrets configure
\nopenclaw secrets audit –check<\/p>\n
\n### `secrets audit`\n\nFindings include:\n\n* plaintext values at rest (`openclaw.json`, `auth-profiles.json`, `.env`, and generated `agents\/*\/agent\/models.json`)\n* plaintext sensitive provider header residues in generated `models.json` entries\n* unresolved refs\n* precedence shadowing (`auth-profiles.json` taking priority over `openclaw.json` refs)\n* legacy residues (`auth.json`, OAuth reminders)\n\nExec note:\n\n* By default, audit skips exec SecretRef resolvability checks to avoid command side effects.\n* Use `openclaw secrets audit --allow-exec` to execute exec providers during audit.\n\nHeader residue note:\n\n* 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`).\n\n### `secrets configure`\n\nInteractive helper that:\n\n* configures `secrets.providers` first (`env`\/`file`\/`exec`, add\/edit\/remove)\n* lets you select supported secret-bearing fields in `openclaw.json` plus `auth-profiles.json` for one agent scope\n* can create a new `auth-profiles.json` mapping directly in the target picker\n* captures SecretRef details (`source`, `provider`, `id`)\n* runs preflight resolution\n* can apply immediately\n\nExec note:\n\n* Preflight skips exec SecretRef checks unless `--allow-exec` is set.\n* If you apply directly from `configure --apply` and the plan includes exec refs\/providers, keep `--allow-exec` set for the apply step too.\n\nHelpful modes:\n\n* `openclaw secrets configure --providers-only`\n* `openclaw secrets configure --skip-provider-setup`\n* `openclaw secrets configure --agent <id>`\n\n`configure` apply defaults:\n\n* scrub matching static credentials from `auth-profiles.json` for targeted providers\n* scrub legacy static `api_key` entries from `auth.json`\n* scrub matching known secret lines from `<config-dir>\/.env`\n\n### `secrets apply`\n\nApply a saved plan:\n\n```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}\nopenclaw secrets apply --from \/tmp\/openclaw-secrets-plan.json\nopenclaw secrets apply --from \/tmp\/openclaw-secrets-plan.json --allow-exec\nopenclaw secrets apply --from \/tmp\/openclaw-secrets-plan.json --dry-run\nopenclaw secrets apply --from \/tmp\/openclaw-secrets-plan.json --dry-run --allow-exec\n<\/code><\/pre>\nExec note:<\/p>\n
\n- dry-run skips exec checks unless
--allow-exec<\/code> is set.<\/li>\n- write mode rejects plans containing exec SecretRefs\/providers unless
--allow-exec<\/code> is set.<\/li>\n<\/ul>\nFor strict target\/path contract details and exact rejection rules, see:<\/p>\n
\n- Secrets Apply Plan Contract<\/a><\/li>\n<\/ul>\n
One-way safety policy<\/h2>\n
OpenClaw intentionally does not write rollback backups containing historical plaintext secret values.<\/p>\n
Safety model:<\/p>\n
\n- preflight must succeed before write mode<\/li>\n
- runtime activation is validated before commit<\/li>\n
- apply updates files using atomic file replacement and best-effort restore on failure<\/li>\n<\/ul>\n
Legacy auth compatibility notes<\/h2>\n
For static credentials, runtime no longer depends on plaintext legacy auth storage.<\/p>\n
\n- Runtime credential source is the resolved in-memory snapshot.<\/li>\n
- Legacy static
api_key<\/code> entries are scrubbed when discovered.<\/li>\n- OAuth-related compatibility behavior remains separate.<\/li>\n<\/ul>\n
Web UI note<\/h2>\n
Some SecretInput unions are easier to configure in raw editor mode than in form mode.<\/p>\n
Related docs<\/h2>\n\n- CLI commands: secrets<\/a><\/li>\n
- Plan contract details: Secrets Apply Plan Contract<\/a><\/li>\n
- Credential surface: SecretRef Credential Surface<\/a><\/li>\n
- Auth setup: Authentication<\/a><\/li>\n
- Security posture: Security<\/a><\/li>\n
- Environment precedence: Environment Variables<\/a><\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"
Secrets Management Secrets management OpenClaw supports […]<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-611","post","type-post","status-publish","format-standard","hentry","category-docs"],"_links":{"self":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/611","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/comments?post=611"}],"version-history":[{"count":3,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/611\/revisions"}],"predecessor-version":[{"id":812,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/posts\/611\/revisions\/812"}],"wp:attachment":[{"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/media?parent=611"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/categories?post=611"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/pa.yingzhi8.cn\/index.php\/wp-json\/wp\/v2\/tags?post=611"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}