Gateway
Beheer van geheimen
OpenClaw ondersteunt additieve SecretRefs, zodat ondersteunde inloggegevens niet als platte tekst in de configuratie hoeven te staan.
Runtimemodel
- Geheimen worden tijdens de activering direct omgezet in een runtime-snapshot in het geheugen, niet pas wanneer aanvraagpaden ze nodig hebben.
- Bij een koude start van de Gateway wordt een opnieuw te proberen SecretRef-fout geïsoleerd tot een bekende eigenaar buiten de Gateway wanneer die eigenaar isolatie ondersteunt. Toegewezen eigenaarsklassen omvatten modelproviders en skills, media-/TTS-/cronproviders, geschikte authenticatieprofielen, geheugen per agent, sandbox-SSH, kanaalaccounts en door het manifest gedeclareerde Plugin-routes. De Gateway start, registreert de eigenaar als geconfigureerd maar niet beschikbaar en geeft een geredigeerde waarschuwing over de verminderde werking. Gateway-ingangsauthenticatie, structureel ongeldige refs of omgezette waarden, fail-closed-eigenaren en refs waarvan de runtime-eigenaar niet is toegewezen, laten het opstarten nog steeds mislukken.
- Bij opnieuw laden wordt elke toegewezen eigenaar afzonderlijk gevalideerd, waarna één atomische snapshot wordt gepubliceerd. Gezonde eigenaren worden vernieuwd. Een geschikte eigenaar waarbij een fout optreedt, behoudt zijn laatst bekende werkende waarde en wordt alleen verouderd wanneer zijn ref-identiteiten, providerdefinities en volledige niet-geheime eigenaarscontract ongewijzigd zijn; een gewijzigde of nieuwe eigenaar met een fout wordt koud. Een strikte fout wijst het opnieuw laden af en behoudt de actieve snapshot.
- Beleidsschendingen (bijvoorbeeld een authenticatieprofiel in OAuth-modus in combinatie met SecretRef-invoer) laten de activering mislukken vóór de runtimewissel.
- Runtime-aanvragen lezen uitsluitend de actieve snapshot in het geheugen. SecretRef-inloggegevens van modelproviders worden via authenticatieopslag en streamopties als proceslokale sentinels doorgegeven tot aan de uitgang. Paden voor uitgaande aflevering (Discord-antwoorden/threadaflevering, Telegram-actieverzendingen) lezen die snapshot eveneens en zetten refs niet voor elke verzending opnieuw om.
Hierdoor blijven storingen bij geheimenproviders buiten veelgebruikte aanvraagpaden.
Gateway-ingangsbeveiliging, structureel ongeldige configuratie of omgezette waarden, beleidsschendingen en onbekend eigenaarschap blijven fail-closed mislukken. Geïsoleerde eigenaren vallen nooit terug op een bron van inloggegevens met een lagere prioriteit.
Injectie bij uitgang (sentinels)
Voor inloggegevens van modelproviders die door SecretRefs worden ondersteund, genereert OpenClaw tijdens de omzetting van modelauthenticatie een ondoorzichtige, proceslokale sentinel. Authenticatieopslag, streamopties, SDK-configuratie, logboeken, foutobjecten en de meeste runtime-inspectie zien daarom een waarde zoals oc-sent-v1-..., niet het inloggegeven van de provider. De beveiligde model-fetch en beheerde statuscontroles van lokale providers vervangen bekende sentinels in URL- en headerwaarden onmiddellijk voordat elke aanvraag het proces verlaat.
Onbekende waarden met de vorm van een sentinel mislukken fail-closed voordat netwerkactiviteit plaatsvindt. OpenClaw weigert de aanvraag te verzenden in plaats van een niet-omgezette sentinel naar een provider door te sturen. Omgezette geheime waarden worden ook geregistreerd voor logredactie op basis van exacte waarden, als aanvullende beveiligingsmaatregel.
Provideradapters gebruiken het laatst mogelijke injectiepunt dat hun SDK ondersteunt:
- SDK's met een aangepaste fetch-optie ontvangen de beveiligde fetch van OpenClaw, zodat de SDK de sentinel behoudt.
- SDK's zonder aangepaste fetch-optie pakken de sentinel onmiddellijk vóór het maken van de client uit. Providerstreams en agentharnassen die eigendom zijn van een Plugin pakken deze uit bij de laatste overdracht die eigendom is van de kern, omdat deze transporten de beveiligde fetch van OpenClaw niet delen.
Sentinels beperken blootstelling van platte tekst in de keten van modelaanroepen, maar bieden geen procesisolatie. De echte waarde bestaat nog steeds in het geheugen van hetzelfde proces en verschijnt bij de laatste adaptergrens. Gewone inloggegevens uit de omgeving die niet via SecretRefs zijn geconfigureerd, blijven platte tekst en vallen buiten dit mechanisme.
Stel OPENCLAW_SECRET_SENTINELS=off in (accepteert ook 0 of false, niet hoofdlettergevoelig) om het genereren van sentinels tijdens incidentrespons of compatibiliteitsprobleemoplossing uit te schakelen. De noodschakelaar schakelt de registratie voor redactie op basis van exacte waarden niet uit.
Grens voor agenttoegang
SecretRefs voorkomen dat inloggegevens in configuratiebestanden en gegenereerde modelbestanden worden opgeslagen, maar vormen geen grens voor procesisolatie. Een inloggegeven in platte tekst dat op schijf achterblijft op een pad dat de agent kan lezen, blijft leesbaar via bestands- of shelltools, waarbij redactie op API-niveau wordt omzeild.
Beschouw voor productie-implementaties waarbij voor de agent toegankelijke bestanden binnen het bereik vallen, de migratie alleen als voltooid wanneer aan al deze voorwaarden is voldaan:
- Ondersteunde inloggegevens gebruiken SecretRefs in plaats van waarden in platte tekst.
- Achtergebleven verouderde platte tekst is verwijderd uit
openclaw.json,auth-profiles.json,.enven gegenereerdemodels.json-bestanden. openclaw secrets audit --checkis na de migratie schoon.- Alle resterende niet-ondersteunde of roterende inloggegevens worden beschermd door isolatie van het besturingssysteem, containerisolatie of een externe proxy voor inloggegevens.
Daarom is de workflow voor controleren/configureren/toepassen een beveiligingspoort voor migratie en niet alleen een gemakshulpmiddel.
Filteren op actieve oppervlakken
SecretRefs worden alleen gevalideerd op daadwerkelijk actieve oppervlakken:
- Ingeschakelde oppervlakken: opnieuw te proberen fouten voor toegewezen, isoleerbare eigenaren leiden tot koude of verouderde verminderde werking. Strikte, fail-closed, voor de Gateway vereiste of niet-toegewezen fouten blokkeren het opstarten/opnieuw laden.
- Inactieve oppervlakken: niet-omgezette refs blokkeren het opstarten/opnieuw laden niet; ze geven een niet-fatale
SECRETS_REF_IGNORED_INACTIVE_SURFACE-diagnose.
Voorbeelden van inactieve oppervlakken
- Uitgeschakelde kanaal-/accountvermeldingen.
- Kanaalinloggegevens op het hoogste niveau die door geen enkel ingeschakeld account worden overgenomen.
- Uitgeschakelde tool-/functieoppervlakken.
- Providerspecifieke sleutels voor zoeken op het web die niet door
tools.web.search.providerzijn geselecteerd. In de automatische modus (provider niet ingesteld) worden sleutels volgens prioriteit geraadpleegd voor automatische detectie totdat er één wordt omgezet; na selectie zijn sleutels van niet-geselecteerde providers inactief. - Sandbox-SSH-authenticatiemateriaal (
agents.defaults.sandbox.ssh.identityData,certificateData,knownHostsData, plus overschrijvingen per agent) is alleen actief wanneer de effectieve sandbox-backendsshis en de sandboxmodus nietoffis, voor de standaardagent of een ingeschakelde agent. gateway.remote.token/gateway.remote.passwordSecretRefs zijn actief als aan een van deze voorwaarden wordt voldaan:gateway.mode=remotegateway.remote.urlis geconfigureerdgateway.tailscale.modeisserveoffunnel- In lokale modus zonder die externe oppervlakken:
gateway.remote.tokenis actief wanneer tokenauthenticatie kan prevaleren en er geen omgevings-/authenticatietoken is geconfigureerd;gateway.remote.passwordis alleen actief wanneer wachtwoordauthenticatie kan prevaleren en er geen omgevings-/authenticatiewachtwoord is geconfigureerd. gateway.auth.tokenSecretRef is inactief voor de omzetting van opstartauthenticatie wanneerOPENCLAW_GATEWAY_TOKENis ingesteld, omdat tokeninvoer uit de omgeving voor die runtime prevaleert.
Diagnostiek voor Gateway-authenticatieoppervlakken
Wanneer een SecretRef is ingesteld op gateway.auth.token, gateway.auth.password, gateway.remote.token of gateway.remote.password, registreert het opstarten/opnieuw laden van de Gateway de toestand van het oppervlak onder code SECRETS_GATEWAY_AUTH_SURFACE:
active: de SecretRef maakt deel uit van het effectieve authenticatieoppervlak en moet worden omgezet.inactive: een ander authenticatieoppervlak prevaleert, of externe authenticatie is uitgeschakeld/niet actief.
De logboekvermelding bevat de reden die het beleid voor actieve oppervlakken heeft gebruikt.
Voorafgaande controle van onboardingverwijzingen
Wanneer tijdens interactieve onboarding voor SecretRef-opslag wordt gekozen, wordt vóór het opslaan een voorafgaande validatie uitgevoerd:
- Omgevingsrefs: valideert de naam van de omgevingsvariabele en bevestigt dat tijdens de installatie een niet-lege waarde zichtbaar is.
- Providerrefs (
fileofexec): valideert de providerselectie, zetidom en controleert het type van de omgezette waarde. - Snelstartworkflow: wanneer
gateway.auth.tokenal een SecretRef is, zet onboarding deze vóór de initialisatie van de probe/het dashboard om (voorenv-,file- enexec-refs) met dezelfde direct afbrekende poort.
Bij een validatiefout wordt de fout weergegeven en kun je het opnieuw proberen.
SecretRef-contract
Overal één objectvorm:
{ source: "env" | "file" | "exec", provider: "default", id: "..." }env
{ source: "env", provider: "default", id: "OPENAI_API_KEY" }Verkorte tekenreeksen worden ook geaccepteerd voor SecretInput-velden:
"${OPENAI_API_KEY}""$OPENAI_API_KEY"Validatie:
providermoet overeenkomen met^[a-z][a-z0-9_-]{0,63}$idmoet overeenkomen met^[A-Z][A-Z0-9_]{0,127}$
file
{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }Validatie:
providermoet overeenkomen met^[a-z][a-z0-9_-]{0,63}$idmoet een absolute JSON-pointer (/...) zijn, of de letterlijke waardevaluevoorsingleValue-providers- RFC 6901-escaping in segmenten:
~wordt~0,/wordt~1
exec
{ source: "exec", provider: "vault", id: "providers/openai/apiKey#value" }Validatie:
providermoet overeenkomen met^[a-z][a-z0-9_-]{0,63}$idmoet overeenkomen met^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$(ondersteunt selectors zoalssecret#json_key)idmag geen.of..bevatten als door schuine strepen gescheiden padsegmenten (a/../bwordt bijvoorbeeld afgewezen)
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", }, },}Omgevingsprovider
- Optionele acceptatielijst met exacte namen via
allowlist. - Ontbrekende of lege omgevingswaarden laten de omzetting mislukken.
Bestandsprovider
- Leest het lokale bestand op
path. mode: "json"(standaard) verwacht een JSON-object als payload en zetidom als een JSON-pointer.mode: "singleValue"verwacht ref-id"value"en retourneert de onbewerkte bestandsinhoud (afsluitende nieuwe regel verwijderd).- Het pad moet de controles op eigenaarschap/machtigingen doorstaan;
timeoutMs(standaard 5000) enmaxBytes(standaard 1 MiB) begrenzen het lezen. - Fail-closed op Windows: als ACL-verificatie niet beschikbaar is voor het pad, mislukt de omzetting. Stel uitsluitend voor vertrouwde paden
allowInsecurePath: truein voor die provider om de controle over te slaan.
Exec-provider
- Voert het geconfigureerde absolute binaire pad rechtstreeks uit, zonder shell.
- Standaard moet
commandeen gewoon bestand zijn, geen symbolische koppeling. StelallowSymlinkCommand: truein om opdrachtpaden met symbolische koppelingen toe te staan (bijvoorbeeld Homebrew-shims) en combineer dit mettrustedDirs(bijvoorbeeld["/opt/homebrew"]), zodat alleen paden van pakketbeheerders in aanmerking komen. - Ondersteunt
timeoutMs(standaard 5000),noOutputTimeoutMs(standaard gelijk aantimeoutMs),maxOutputBytes(standaard 1 MiB), de toelatingslijstenv/passEnventrustedDirs. jsonOnlyis standaardtrue. MetjsonOnly: falseen één aangevraagde id wordt gewone niet-JSON-standaarduitvoer geaccepteerd als de waarde van die id.- Windows werkt gesloten bij fouten: als ACL-verificatie niet beschikbaar is voor het opdrachtpad, mislukt de omzetting. Stel uitsluitend voor vertrouwde paden
allowInsecurePath: truein voor die provider om de controle over te slaan. - Door plugins beheerde exec-providers kunnen
pluginIntegrationgebruiken in plaats van een gekopieerdecommand/args. OpenClaw haalt tijdens het starten/herladen de actuele opdrachtgegevens uit het manifest van de geïnstalleerde plugin; als de plugin is uitgeschakeld, verwijderd of niet vertrouwd wordt, of de integratie niet meer declareert, werken actieve SecretRefs bij die provider gesloten bij fouten.
Aanvraagpayload (stdin):
{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }Antwoordpayload (stdout):
{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secretOptionele fouten per id:
{"protocolVersion": 1,"values": {},"errors": { "providers/openai/apiKey": { "code": "NOT_FOUND" } }}code is een optionele, machineleesbare diagnose. OpenClaw toont de herkende
codes NOT_FOUND en AMBIGUOUS_DUPLICATE_KEY met de provider en ref-id. Andere
codes en vrije velden zoals message worden geaccepteerd voor compatibiliteit met protocol-v1,
maar worden niet weergegeven omdat resolveruitvoer referentiemateriaal kan bevatten.
API-sleutels uit bestanden
Plaats geen file:...-tekenreeksen in het env-blok van de configuratie. Dat blok is letterlijk en niet-overschrijvend, dus file:... wordt daar nooit omgezet.
Gebruik in plaats daarvan een SecretRef naar een bestand in 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 gelijk aan "value". Gebruik voor mode: "json" een absolute JSON-pointer, zoals "/providers/xai/apiKey".
Zie SecretRef-referentieoppervlak voor de velden die SecretRefs accepteren.
Voorbeelden van exec-integraties
Zie 1Password voor een specifieke 1Password-handleiding over serviceaccounts, de meegeleverde agent-Skill en probleemoplossing.
1Password CLI
{ secrets: { providers: { onepassword_openai: { source: "exec", command: "/opt/homebrew/bin/op", allowSymlinkCommand: true, // vereist voor binaire Homebrew-bestanden met symbolische koppelingen 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" }, }, }, },}Bitwarden Secrets Manager (`bws`)
Gebruik een resolverwrapper om SecretRef-id's toe te wijzen aan itemsleutels van Bitwarden Secrets Manager. De repository bevat scripts/secrets/openclaw-bws-resolver.mjs; installeer of kopieer deze naar een absoluut vertrouwd pad op de host waarop de Gateway draait.
Vereisten:
- Bitwarden Secrets Manager CLI (
bws) geïnstalleerd op de Gateway-host. BWS_ACCESS_TOKENbeschikbaar voor de Gateway-service.PATHdoorgegeven aan de resolver, ofBWS_BINingesteld op het absolute pad van het binaire bestandbws.BWS_SERVER_URLingesteld in de omgeving bij gebruik van een zelfgehoste Bitwarden-instantie.
{ 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", }, }, }, },}De resolver verwerkt aangevraagde id's in batches, voert bws secret list uit en retourneert waarden voor overeenkomende geheime key-velden. Gebruik sleutels die voldoen aan het id-contract voor exec-SecretRefs, zoals openclaw/providers/openai/apiKey; sleutels in de stijl van omgevingsvariabelen met onderstrepingstekens worden geweigerd voordat de resolver wordt uitgevoerd. Als meer dan één zichtbaar Bitwarden-geheim de aangevraagde sleutel deelt, laat de resolver die id mislukken wegens ambiguïteit in plaats van te gokken. Verifieer na het bijwerken van de configuratie het resolverpad:
openclaw secrets audit --allow-execHashiCorp Vault CLI
{ secrets: { providers: { vault_openai: { source: "exec", command: "/opt/homebrew/bin/vault", allowSymlinkCommand: true, // vereist voor binaire Homebrew-bestanden met symbolische koppelingen 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" }, }, }, },}password-store (`pass`)
Gebruik een kleine resolverwrapper om SecretRef-id's rechtstreeks toe te wijzen aan pass-vermeldingen. Sla deze op als een uitvoerbaar bestand op een absoluut pad dat de padcontroles van je exec-provider doorstaat, bijvoorbeeld /usr/local/bin/openclaw-pass-resolver. De #!/usr/bin/env node-shebang zoekt node via de PATH van het resolverproces, dus neem PATH op in passEnv. Als pass niet in die PATH staat, stel dan PASS_BIN in de bovenliggende omgeving in en neem deze ook op in passEnv:
#!/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(`Kan aanvraag niet ontleden: ${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 is afgesloten met ${result.status}`).trim() }; } } process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));});Configureer vervolgens de exec-provider en laat apiKey verwijzen naar het pad van de pass-vermelding:
{ 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", }, }, }, },}Bewaar het geheim op de eerste regel van de pass-vermelding, of pas de wrapper aan om in plaats daarvan de volledige pass show-uitvoer te retourneren. Verifieer na het bijwerken van de configuratie zowel de statische audit als het pad van de exec-resolver:
openclaw secrets audit --checkopenclaw secrets audit --allow-execsops
{ secrets: { providers: { sops_openai: { source: "exec", command: "/opt/homebrew/bin/sops", allowSymlinkCommand: true, // vereist voor binaire Homebrew-bestanden met symbolische koppelingen 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" }, }, }, },}Omgevingsvariabelen van MCP-servers
Omgevingsvariabelen van MCP-servers die via plugins.entries.acpx.config.mcpServers zijn geconfigureerd, accepteren SecretInput, zodat API-sleutels en tokens buiten de configuratie in platte tekst blijven:
{ 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", }, }, }, }, }, }, }, },}Tekenreekswaarden in platte tekst blijven werken. Verwijzingen naar omgevingssjablonen zoals ${MCP_SERVER_API_KEY} en SecretRef-objecten worden omgezet tijdens de activering van de Gateway, voordat het MCP-serverproces wordt gestart. Net als bij andere SecretRef-oppervlakken blokkeren niet-omgezette verwijzingen de activering alleen wanneer de plugin acpx daadwerkelijk actief is.
SSH-authenticatiemateriaal voor de sandbox
De kernbackend ssh voor de sandbox 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 de activering van de sandbox, niet pas bij elke SSH-aanroep.
- Opgeloste waarden worden naar een tijdelijke map met beperkende bestandsmachtigingen (
0o600) geschreven en in de gegenereerde SSH-configuratie gebruikt. - Als de effectieve sandbox-backend niet
sshis (of de sandboxmodusoffis), blijven deze verwijzingen inactief en blokkeren ze het opstarten niet.
Ondersteund referentiebereik voor inloggegevens
De canonieke ondersteunde en niet-ondersteunde inloggegevens staan vermeld in Referentiebereik voor SecretRef-inloggegevens.
Vereist gedrag en voorrang
- Veld zonder verwijzing: ongewijzigd.
- Veld met een verwijzing: vereist op actieve oppervlakken tijdens activering.
- Als zowel platte tekst als een verwijzing aanwezig is, krijgt de verwijzing voorrang op ondersteunde voorrangspaden.
- De redactiesentinel
__OPENCLAW_REDACTED__is gereserveerd voor interne redactie en herstel van configuratie en wordt geweigerd als letterlijk ingediende configuratiegegevens.
Waarschuwings- en auditsignalen:
SECRETS_REF_OVERRIDES_PLAINTEXT(runtimewaarschuwing)REF_SHADOWED(auditbevinding wanneerauth-profiles.json-inloggegevens voorrang krijgen opopenclaw.json-verwijzingen)
Google Chat serviceAccount accepteert inline-JSON of een SecretRef. Doctor verplaatst het buiten gebruik gestelde nevenveld serviceAccountRef naar dit canonieke veld wanneer dit niet is ingesteld.
Activeringstriggers
Geheimactivering wordt uitgevoerd bij:
- Opstarten (voorcontrole plus definitieve activering)
- Hot-apply-pad voor het opnieuw laden van de configuratie
- Pad voor herstartcontrole bij het opnieuw laden van de configuratie
- Handmatig opnieuw laden via
secrets.reload - Voorcontrole van de Gateway-RPC voor het schrijven van configuratie (
config.set/config.apply/config.patch), waarbij SecretRefs op actieve oppervlakken binnen de ingediende configuratiepayload worden gevalideerd voordat wijzigingen worden opgeslagen
Activeringscontract:
- Bij succes wordt de momentopname atomair vervangen.
- Een strikte opstartfout breekt het opstarten van de Gateway af.
- Tijdens een koude start kan een opnieuw te proberen resolutiefout voor een toegewezen, isoleerbare eigenaar die niet de Gateway is, de momentopname publiceren waarbij precies die eigenaar als geconfigureerd maar niet beschikbaar wordt gemarkeerd. Aanvragen voor de eigenaar mislukken met
SECRET_SURFACE_UNAVAILABLE; eigenaars van modelproviders vallen na het mislukken van een expliciete verwijzing niet terug op inloggegevens uit de omgeving of een authenticatieprofiel. - Opnieuw laden en herstartcontrole isoleren daarvoor geschikte toegewezen eigenaars. Ongewijzigde verwijzingsidentiteiten met ongewijzigde providerdefinities en een ongewijzigd, volledig, niet-geheim eigenaarscontract behouden hun exacte laatst bekende werkende waarden als verouderd; gewijzigde of nieuw geconfigureerde niet-opgeloste verwijzingen worden alleen voor die eigenaar koud gepubliceerd. Een strikte fout tijdens opnieuw laden behoudt de eerder actieve momentopname.
config.set,config.applyenconfig.patchaccepteren syntactisch geldige, niet-opgeloste verwijzingen voor isoleerbare eigenaars en retourneren een geredigeerddegradedSecretOwners-rapport. Gateway-ingangsauthenticatie, structureel ongeldige configuratie of opgeloste waarden, beleidsschendingen en onbekende eigenaars worden nog steeds geweigerd voordat de schijf wordt gewijzigd.- Gezonde neveneigenaars worden normaal opgelost en gepubliceerd, zelfs wanneer een andere eigenaar koud of verouderd is.
- Het opgeven van een expliciet kanaaltoken per aanroep aan een uitgaande helper-/toolaanroep activeert SecretRef-activering niet; de activeringspunten blijven opstarten, opnieuw laden en expliciete
secrets.reload.
Signalen voor verminderde werking en herstel
Wanneer activering tijdens opnieuw laden na een gezonde toestand mislukt, gaat OpenClaw over naar een toestand met verminderde werking van geheimen en worden eenmalige systeemgebeurtenissen en logcodes uitgezonden:
SECRETS_RELOADER_DEGRADEDSECRETS_RELOADER_RECOVERED
Gedrag:
- Verminderde werking: gezonde eigenaars worden vernieuwd, verouderde eigenaars behouden hun laatst bekende werkende waarde en koude eigenaars blijven niet beschikbaar.
- Hersteld: eenmaal uitgezonden na de volgende geslaagde activering.
- Herhaalde fouten terwijl de werking al verminderd is, worden als waarschuwing vastgelegd, maar de gebeurtenis wordt niet opnieuw uitgezonden.
- Een strikte opstartfout zendt nooit een gebeurtenis voor verminderde werking uit, omdat de runtime nooit actief is geworden. Een geslaagde opstart met koude eigenaars legt de verminderde werking van de eigenaar vast, maar zendt geen gebeurtenis van de herlader uit.
- Opstart- en herlaadfouten die tot een verwijzing beperkt zijn, zenden voor elke getroffen eigenaar een gestructureerde waarschuwing
SECRETS_DEGRADEDuit. Storingen die tot een provider beperkt zijn, zenden één waarschuwingSECRETS_PROVIDER_DEGRADEDuit met de provider en de volledige lijst van getroffen eigenaars, in plaats van de providerfout per eigenaar te herhalen. Waarschuwingen bevatten een geredigeerde reden, de eigenaarstoestandcoldofstaleen de aanwijzing voor opnieuw proberenopenclaw secrets reload. Ze bevatten nooit opgeloste waarden of SecretRef-id's. openclaw doctorvermeldt koude en verouderde eigenaars met hun getroffen configuratiepaden, geredigeerde reden en richtlijnen voor opnieuw proberen.
Resolutie van opdrachtpaden
Opdrachtpaden kunnen via een Gateway-momentopname-RPC ondersteunde SecretRef-resolutie inschakelen. Er gelden twee algemene gedragingen:
Strikte opdrachtpaden
Bijvoorbeeld externe-geheugenpaden van openclaw memory en openclaw qr --remote wanneer hiervoor externe gedeelde-geheimverwijzingen nodig zijn. Ze lezen uit de actieve momentopname en mislukken onmiddellijk wanneer een vereiste SecretRef niet beschikbaar is.
Alleen-lezen opdrachtpaden
Bijvoorbeeld openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, openclaw security audit en alleen-lezen herstelstromen voor Doctor/configuratie. Ook zij geven de voorkeur aan de actieve momentopname, maar werken met verminderde functionaliteit door in plaats van af te breken wanneer een gerichte SecretRef niet beschikbaar is.
Alleen-lezen gedrag:
- Wanneer de Gateway actief is, lezen deze opdrachten eerst uit de actieve momentopname.
- Als de Gateway-resolutie onvolledig is of de Gateway niet beschikbaar is, proberen ze een gerichte lokale terugval voor dat opdrachtoppervlak.
- Als een gerichte SecretRef nog steeds niet beschikbaar is, gaat de opdracht door met alleen-lezen uitvoer met verminderde functionaliteit en een expliciete diagnose dat de verwijzing is geconfigureerd maar niet beschikbaar is in dit opdrachtpad.
- Dit gedrag met verminderde functionaliteit is alleen lokaal voor de opdracht; het verzwakt de runtimepaden voor opstarten, opnieuw laden of verzenden/authenticatie niet.
Overige opmerkingen:
- Het vernieuwen van de momentopname na rotatie van een backendgeheim wordt afgehandeld door
openclaw secrets reload. - Gateway-RPC-methode die door deze opdrachtpaden wordt gebruikt:
secrets.resolve.
Workflow voor audit en configuratie
Standaardworkflow voor operators:
Huidige toestand auditen
openclaw secrets audit --checkSecretRefs configureren en toepassen
openclaw secrets configure --applyOpnieuw auditen
openclaw secrets audit --checkBeschouw de migratie pas als voltooid wanneer de nieuwe audit geen bevindingen oplevert. Als de audit nog steeds plattetekstwaarden in opslag meldt, blijft het risico op toegang door agenten bestaan, zelfs wanneer runtime-API's geredigeerde waarden retourneren.
Als je tijdens configure een plan opslaat in plaats van het toe te passen, pas je dat opgeslagen plan vóór de nieuwe audit toe met openclaw secrets apply --from <plan-path>.
geheimen auditen
Bevindingen omvatten:
- Plattetekstwaarden in opslag (
openclaw.json,auth-profiles.json,.enven gegenereerdeagents/*/agent/models.json). - Resterende gevoelige providerheaders in gegenereerde
models.json-vermeldingen. - Niet-opgeloste verwijzingen.
- Overschaduwing door voorrang (
auth-profiles.jsonkrijgt voorrang opopenclaw.json-verwijzingen). - Restanten van verouderde configuratie (
auth.json, OAuth-herinneringen).
Opmerking over exec: standaard slaat de audit controles op de oplosbaarheid van exec-SecretRefs over om neveneffecten van opdrachten te voorkomen. Gebruik openclaw secrets audit --allow-exec om exec-providers tijdens de audit uit te voeren.
Opmerking over resterende headers: detectie van gevoelige providerheaders is gebaseerd op heuristieken voor namen (veelvoorkomende namen en fragmenten van authenticatie-/inloggegevensheaders, zoals authorization, x-api-key, token, secret, password en credential).
geheimen configureren
Interactieve helper die:
- Eerst
secrets.providersconfigureert (env/file/exec, toevoegen/bewerken/verwijderen). - Je ondersteunde velden met geheimen laat selecteren in
openclaw.jsonplusauth-profiles.jsonvoor één agentbereik. - Rechtstreeks in de doelkiezer een nieuwe
auth-profiles.json-toewijzing kan maken. - SecretRef-gegevens vastlegt (
source,provider,id). - Voorafgaande resolutie uitvoert en deze onmiddellijk kan toepassen.
Opmerking over exec: de voorcontrole slaat controles van exec-SecretRefs over, tenzij --allow-exec is ingesteld. Als je rechtstreeks vanuit configure --apply toepast en het plan exec-verwijzingen/-providers bevat, laat je --allow-exec ook voor de toepassingsstap ingesteld.
Handige modi:
openclaw secrets configure --providers-onlyopenclaw secrets configure --skip-provider-setupopenclaw secrets configure --agent <id>
Standaardinstellingen voor toepassen met configure:
- Overeenkomende statische inloggegevens uit
auth-profiles.jsonverwijderen voor de geselecteerde providers. - Verouderde statische
api_key-vermeldingen uitauth.jsonverwijderen. - Overeenkomende bekende geheimregels verwijderen uit de bestanden
.envvan de effectieve toestand en actieve configuratie (ontdubbeld wanneer beide paden overeenkomen).
geheimen toepassen
Een opgeslagen plan toepassen:
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-execOpmerking over exec: een proefuitvoering slaat exec-controles over, tenzij --allow-exec is ingesteld; de schrijfmodus weigert plannen die exec-SecretRefs/-providers bevatten, tenzij --allow-exec is ingesteld.
Zie Contract voor het toepassingsplan van geheimen voor details over het strikte doel-/padcontract en de exacte weigeringsregels.
Eenrichtingsveiligheidsbeleid
Veiligheidsmodel:
- De voorcontrole moet slagen vóór de schrijfmodus.
- Runtimeactivering wordt vóór de commit gevalideerd.
- Toepassen werkt bestanden bij met atomische bestandsvervanging en herstel naar beste vermogen bij fouten.
Opmerkingen over compatibiliteit met verouderde authenticatie
Voor statische inloggegevens is de runtime niet langer afhankelijk van verouderde authenticatieopslag in platte tekst.
- De bron voor runtime-inloggegevens is de opgeloste momentopname in het geheugen.
- Verouderde statische
api_key-vermeldingen worden verwijderd wanneer ze worden aangetroffen. - OAuth-gerelateerd compatibiliteitsgedrag blijft afzonderlijk.
Opmerking over de webinterface
Sommige SecretInput-unions zijn gemakkelijker te configureren in de onbewerkte editormodus dan in de formuliermodus.
Gerelateerd
- Authenticatie - authenticatie instellen
- CLI: geheimen - CLI-opdrachten
- Vault SecretRefs - HashiCorp Vault-provider instellen
- Omgevingsvariabelen - prioriteit van omgevingsvariabelen
- Referentie voor SecretRef-inloggegevens - referentie voor inloggegevens
- Contract voor het toepassen van het geheimenplan - details van het plancontract
- Beveiliging - beveiligingsbeleid