Geheimenbeheer

OpenClaw ondersteunt additieve SecretRefs, zodat ondersteunde referenties niet als platte tekst in configuratie hoeven te worden opgeslagen.

Doelen en runtime-model

Secrets worden opgelost naar een runtime-snapshot in het geheugen.

• Resolutie gebeurt eager tijdens activering, niet lazy op aanvraagpaden.
• Opstarten faalt snel wanneer een effectief actieve SecretRef niet kan worden opgelost.
• Herladen gebruikt een atomische wissel: volledig succes, of de laatst bekende goede snapshot behouden.
• SecretRef-beleidsschendingen (bijvoorbeeld auth-profielen in OAuth-modus gecombineerd met SecretRef-invoer) laten activering falen vóór de runtime-wissel.
• Runtime-aanvragen lezen alleen uit de actieve snapshot in het geheugen.
• Na de eerste succesvolle configuratieactivering/-load blijven runtime-codepaden die actieve snapshot in het geheugen lezen totdat een succesvolle herlaadactie deze vervangt.
• Uitgaande leveringspaden lezen ook uit die actieve snapshot (bijvoorbeeld Discord-antwoord-/threadlevering en Telegram-actieverzendingen); ze lossen SecretRefs niet bij elke verzending opnieuw op.

Dit houdt storingen bij secret-providers weg van hot request paths.

Grens voor agenttoegang

SecretRefs beschermen referenties tegen persistentie in ondersteunde configuratie en gegenereerde modeloppervlakken, maar ze vormen geen procesisolatiegrens. Als een referentie in platte tekst op schijf blijft staan in een pad dat de agent kan lezen, kan de agent API-niveau-redactie omzeilen door bestands- of shell-tools te gebruiken om dat bestand te inspecteren.

Voor productie-implementaties waarin voor agents toegankelijke bestanden binnen scope vallen, behandel SecretRef-migratie alleen als voltooid wanneer al het volgende waar is:

• ondersteunde referenties gebruiken SecretRefs in plaats van waarden in platte tekst
• legacy-resten in platte tekst zijn opgeschoond uit openclaw.json, auth-profiles.json, .env, en gegenereerde models.json-bestanden
• openclaw secrets audit --check is schoon na de migratie
• resterende niet-ondersteunde of roterende referenties worden beschermd door isolatie van het besturingssysteem, containerisolatie, of een externe referentieproxy

Daarom is de audit-/configure-/apply-workflow een beveiligingsmigratiepoort, niet alleen een handige helper.

Filtering van actieve oppervlakken

SecretRefs worden alleen gevalideerd op effectief actieve oppervlakken.

• Ingeschakelde oppervlakken: niet-opgeloste refs blokkeren opstarten/herladen.
• Inactieve oppervlakken: niet-opgeloste refs blokkeren opstarten/herladen niet.
• Inactieve refs geven niet-fatale diagnostiek met code SECRETS_REF_IGNORED_INACTIVE_SURFACE.

Diagnostiek voor Gateway-authoppervlak

Wanneer een SecretRef is geconfigureerd op gateway.auth.token, gateway.auth.password, gateway.remote.token, of gateway.remote.password, logt Gateway-opstarten/-herladen de oppervlaktestatus expliciet:

• active: de SecretRef maakt deel uit van het effectieve auth-oppervlak en moet worden opgelost.
• inactive: de SecretRef wordt genegeerd voor deze runtime omdat een ander auth-oppervlak wint, of omdat remote auth is uitgeschakeld/niet actief is.

Deze vermeldingen worden gelogd met SECRETS_GATEWAY_AUTH_SURFACE en bevatten de reden die door het beleid voor actieve oppervlakken wordt gebruikt, zodat je kunt zien waarom een referentie als actief of inactief is behandeld.

Onboarding-referentiepreflight

Wanneer onboarding in interactieve modus draait en je SecretRef-opslag kiest, voert OpenClaw preflight-validatie uit voordat er wordt opgeslagen:

• Env-refs: valideert de naam van de env-var en bevestigt dat een niet-lege waarde zichtbaar is tijdens setup.
• Provider-refs (file of exec): valideert providerselectie, lost id op, en controleert het type van de opgeloste waarde.
• Quickstart-hergebruikpad: wanneer gateway.auth.token al een SecretRef is, lost onboarding deze op vóór probe-/dashboard-bootstrap (voor env-, file-, en exec-refs) met dezelfde fail-fast-poort.

Als validatie faalt, toont onboarding de fout en kun je het opnieuw proberen.

SecretRef-contract

Gebruik overal één objectvorm:

{ source: "env" | "file" | "exec", 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" }

Providerconfiguratie

Definieer providers onder 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,      },      "team-secrets": {        source: "exec",        pluginIntegration: {          pluginId: "acme-secrets",          integrationId: "secret-store",        },      },    },    defaults: {      env: "default",      file: "filemain",      exec: "vault",    },    resolution: {      maxProviderConcurrency: 4,      maxRefsPerProvider: 512,      maxBatchBytes: 262144,    },  },}

{ "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": { "message": "not found" } }}

Bestandsgebaseerde API-sleutels

Plaats geen file:...-strings in het configuratieblok env. Het blok env is letterlijk en niet-overschrijvend, dus file:... wordt niet opgelost.

Gebruik in plaats daarvan een file-SecretRef op een ondersteund referentieveld:

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

Voor mode: "singleValue" is de SecretRef-id "value". Voor mode: "json" gebruik je een absolute JSON-pointer zoals "/providers/xai/apiKey".

Zie SecretRef-referentieoppervlak voor de configuratievelden die SecretRefs accepteren.

Exec-integratievoorbeelden

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // required for Homebrew symlinked binaries        trustedDirs: ["/opt/homebrew"],        args: ["read", "op://Personal/OpenClaw QA 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" },      },    },  },}

{  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: "/opt/homebrew/bin/vault",        allowSymlinkCommand: true, // required for Homebrew symlinked binaries        trustedDirs: ["/opt/homebrew"],        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 nodeconst { 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 --checkopenclaw secrets audit --allow-exec

{  secrets: {    providers: {      sops_openai: {        source: "exec",        command: "/opt/homebrew/bin/sops",        allowSymlinkCommand: true, // required for Homebrew symlinked binaries        trustedDirs: ["/opt/homebrew"],        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-serveromgevingsvariabelen

MCP-server-env vars die via plugins.entries.acpx.config.mcpServers zijn geconfigureerd, ondersteunen SecretInput. Dit houdt API-sleutels en tokens uit plaintext-configuratie:

{  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-tekenreekswaarden blijven werken. Env-templateverwijzingen zoals ${MCP_SERVER_API_KEY} en SecretRef-objecten worden opgelost tijdens Gateway-activering voordat het MCP-serverproces wordt gestart. Net als bij andere SecretRef-oppervlakken blokkeren onopgeloste verwijzingen de activering alleen wanneer de acpx-plugin effectief actief is.

Sandbox-SSH-authenticatiemateriaal

De core ssh-sandboxbackend ondersteunt ook SecretRefs voor SSH-authenticatiemateriaal:

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

Runtimegedrag:

• OpenClaw lost deze verwijzingen op tijdens sandbox-activering, niet lazy tijdens elke SSH-aanroep.
• Opgeloste waarden worden naar tijdelijke bestanden geschreven met beperkende rechten en gebruikt in gegenereerde SSH-configuratie.
• Als de effectieve sandboxbackend niet ssh is, blijven deze verwijzingen inactief en blokkeren ze het opstarten niet.

Ondersteund credential-oppervlak

Canonieke ondersteunde en niet-ondersteunde credentials staan vermeld in:

• SecretRef Credential Surface

Vereist gedrag en voorrang

• Veld zonder verwijzing: ongewijzigd.
• Veld met een verwijzing: vereist op actieve oppervlakken tijdens activering.
• Als zowel plaintext als verwijzing aanwezig zijn, heeft de verwijzing voorrang op ondersteunde voorrangspaden.
• De redaction-sentinel __OPENCLAW_REDACTED__ is gereserveerd voor interne configuratieredactie/herstel en wordt geweigerd als letterlijke ingediende configuratiedata.

Waarschuwings- en auditsignalen:

• SECRETS_REF_OVERRIDES_PLAINTEXT (runtimewaarschuwing)
• REF_SHADOWED (auditbevinding wanneer auth-profiles.json-credentials voorrang hebben op openclaw.json-verwijzingen)

Compatibiliteitsgedrag voor Google Chat:

• serviceAccountRef heeft voorrang op plaintext serviceAccount.
• Plaintext-waarde wordt genegeerd wanneer een naastgelegen verwijzing is ingesteld.

Activeringstriggers

Geheimactivering wordt uitgevoerd bij:

• Opstarten (preflight plus definitieve activering)
• Configuratieherlaadpad met hot-apply
• Configuratieherlaadpad met herstartcontrole
• Handmatig herladen via secrets.reload
• Gateway-configuratieschrijf-RPC-preflight (config.set / config.apply / config.patch) voor SecretRef-oplosbaarheid van actieve oppervlakken binnen de ingediende configuratiepayload voordat wijzigingen worden opgeslagen

Activeringscontract:

• Succes wisselt de snapshot atomisch om.
• Opstartfout breekt het opstarten van de Gateway af.
• Runtime-herlaadfout behoudt de laatst bekende goede snapshot.
• Schrijf-RPC-preflightfout weigert de ingediende configuratie en laat zowel de schijfconfiguratie als de actieve runtime-snapshot ongewijzigd.
• Het opgeven van een expliciet kanaaltoken per aanroep aan een outbound helper/tool-aanroep triggert geen SecretRef-activering; activeringspunten blijven opstarten, herladen en expliciet secrets.reload.

Signalen voor degraded en recovered

Wanneer activering tijdens herladen faalt na een gezonde status, gaat OpenClaw naar een degraded secrets-status.

Eenmalige systeemevent- en logcodes:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Gedrag:

• Degraded: runtime behoudt de laatst bekende goede snapshot.
• Recovered: eenmaal uitgezonden na de volgende succesvolle activering.
• Herhaalde fouten terwijl al degraded wordt waarschuwingen gelogd, maar events worden niet gespamd.
• Fail-fast bij opstarten zendt geen degraded-events uit omdat runtime nooit actief is geworden.

Resolutie van commandopaden

Commandopaden kunnen ondersteunde SecretRef-resolutie inschakelen via Gateway-snapshot-RPC.

Er zijn twee brede gedragingen:

Overige opmerkingen:

• Snapshot-verversing na rotatie van backend-geheimen wordt afgehandeld door openclaw secrets reload.
• Gateway-RPC-methode die door deze opdrachtpaden wordt gebruikt: secrets.resolve.

Audit- en configuratieworkflow

Standaard operatorstroom:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

Behandel de migratie niet als voltooid totdat de nieuwe audit schoon is. Als de audit nog steeds platte-tekstwaarden in rust rapporteert, is het risico op agenttoegang nog steeds aanwezig, zelfs wanneer runtime-API's geredigeerde waarden retourneren.

Als je tijdens configure een plan opslaat in plaats van het toe te passen, pas dat opgeslagen plan dan toe met openclaw secrets apply --from <plan-path> vóór de nieuwe audit.

openclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec

Eenrichtingsveiligheidsbeleid

Veiligheidsmodel:

• preflight moet slagen vóór schrijfmodus
• runtime-activering wordt gevalideerd vóór commit
• toepassen werkt bestanden bij met atomische bestandsvervanging en best-effort herstel bij fouten

Compatibiliteitsopmerkingen voor legacy-authenticatie

Voor statische referentiegegevens is de runtime niet langer afhankelijk van legacy-authenticatieopslag in platte tekst.

• Bron van runtime-referentiegegevens is de opgeloste snapshot in geheugen.
• Legacy statische api_key-items worden opgeschoond wanneer ze worden gevonden.
• OAuth-gerelateerd compatibiliteitsgedrag blijft gescheiden.

Opmerking over de Web-UI

Sommige SecretInput-unies zijn gemakkelijker te configureren in de ruwe-editormodus dan in formuliermodus.

Gerelateerd

• Authenticatie — auth-installatie
• CLI: secrets — CLI-opdrachten
• Omgevingsvariabelen — omgevingsprioriteit
• SecretRef-oppervlak voor referentiegegevens — oppervlak voor referentiegegevens
• Contract voor Secrets Apply-plan — contractdetails voor plannen
• Beveiliging — beveiligingshouding