Geheimenbeheer

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

# Doelen en runtime-model

Geheimen worden opgelost naar een in-memory runtime-snapshot.

• Resolutie gebeurt eager tijdens activatie, niet lazy op aanvraagpaden.
• Startup faalt snel wanneer een effectief actieve SecretRef niet kan worden opgelost.
• Reload gebruikt atomic swap: volledig succes, of de laatst bekende goede snapshot behouden.
• SecretRef-beleidsschendingen (bijvoorbeeld auth-profielen in OAuth-modus gecombineerd met SecretRef-invoer) laten activatie falen voordat de runtime-swap plaatsvindt.
• Runtime-aanvragen lezen alleen uit de actieve in-memory snapshot.
• Na de eerste succesvolle configuratieactivatie/load blijven runtime-codepaden die actieve in-memory snapshot lezen totdat een succesvolle reload deze verwisselt.
• Uitgaande afleverpaden lezen ook uit die actieve snapshot (bijvoorbeeld Discord-antwoord/thread-aflevering en Telegram-actieverzendingen); ze lossen SecretRefs niet opnieuw op bij elke verzending.

Dit houdt storingen bij secret-providers buiten hete aanvraagpaden.

# Filteren op actieve oppervlakken

SecretRefs worden alleen gevalideerd op effectief actieve oppervlakken.

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

# Diagnostiek voor Gateway-auth-oppervlak

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

• active: de SecretRef maakt deel uit van het effectieve auth-oppervlak en moet worden opgelost.
• inactive: de SecretRef wordt voor deze runtime genegeerd 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 actieve-oppervlakkenbeleid is gebruikt, zodat je kunt zien waarom een referentie als actief of inactief is behandeld.

# Preflightcontrole voor onboarding-referenties

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

• Env-refs: valideert de env-var-naam en bevestigt dat tijdens setup een niet-lege waarde zichtbaar is.
• 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 gate.

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

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

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

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

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

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

# Sandbox SSH-auth-materiaal

De core ssh sandbox-backend ondersteunt ook SecretRefs voor SSH-auth-materiaal:

{
  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-gedrag:

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

# Ondersteund oppervlak voor inloggegevens

Canonieke ondersteunde en niet-ondersteunde inloggegevens staan vermeld in:

• SecretRef-oppervlak voor inloggegevens

# Vereist gedrag en prioriteit

• Veld zonder ref: ongewijzigd.
• Veld met een ref: vereist op actieve oppervlakken tijdens activering.
• Als zowel platte tekst als ref aanwezig zijn, krijgt ref prioriteit op ondersteunde prioriteitspaden.
• De redactie-sentinel __OPENCLAW_REDACTED__ is gereserveerd voor interne configuratieredactie/-herstel en wordt afgewezen als letterlijke ingediende configuratiegegevens.

Waarschuwings- en auditsignalen:

• SECRETS_REF_OVERRIDES_PLAINTEXT (runtimewaarschuwing)
• REF_SHADOWED (auditbevinding wanneer auth-profiles.json-inloggegevens prioriteit krijgen boven openclaw.json-refs)

Compatibiliteitsgedrag voor Google Chat:

• serviceAccountRef krijgt prioriteit boven platte tekst serviceAccount.
• De plattetekstwaarde wordt genegeerd wanneer de sibling-ref is ingesteld.

# Activeringstriggers

Geheimactivering wordt uitgevoerd bij:

• Opstarten (preflight plus definitieve activering)
• Hot-apply-pad voor configuratieherladen
• Herstartcontrolepad voor configuratieherladen
• Handmatig herladen via secrets.reload
• Preflight van Gateway-configuratieschrijf-RPC (config.set / config.apply / config.patch) voor SecretRef-oplosbaarheid van actief oppervlak binnen de ingediende configuratiepayload voordat bewerkingen worden opgeslagen

Activeringscontract:

• Succes wisselt de snapshot atomair om.
• Opstartfout breekt het opstarten van de Gateway af.
• Fout bij runtimeherladen behoudt de laatst bekende goede snapshot.
• Preflightfout van schrijf-RPC wijst de ingediende configuratie af en houdt zowel de schijfconfiguratie als de actieve runtime-snapshot ongewijzigd.
• Het opgeven van een expliciet kanaaltoken per aanroep aan een uitgaande helper-/toolaanroep triggert geen SecretRef-activering; activeringspunten blijven opstarten, herladen en expliciet secrets.reload.

# Gedegradeerde en herstelde signalen

Wanneer activering tijdens herladen mislukt na een gezonde toestand, gaat OpenClaw naar een gedegradeerde geheimstatus.

Eenmalige systeemevent- en logcodes:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Gedrag:

• Gedegradeerd: runtime behoudt de laatst bekende goede snapshot.
• Hersteld: eenmaal uitgezonden na de volgende succesvolle activering.
• Herhaalde fouten terwijl de status al gedegradeerd is, loggen waarschuwingen maar spammen geen events.
• Fail-fast bij opstarten zendt geen gedegradeerde events uit, omdat runtime nooit actief is geworden.

# Resolutie van commandopaden

Commandopaden kunnen zich aanmelden voor ondersteunde SecretRef-resolutie via Gateway-snapshot-RPC.

Er zijn twee brede gedragingen:

Overige opmerkingen:

• Snapshotverversing na secretrotatie in de backend wordt afgehandeld door openclaw secrets reload.
• Gateway-RPC-methode die door deze commandopaden wordt gebruikt: secrets.resolve.

# Audit- en configuratieworkflow

Standaard operatorflow:

openclaw secrets audit --check

openclaw secrets configure

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

# Eenrichtingsveiligheidsbeleid

Veiligheidsmodel:

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

# Compatibiliteitsopmerkingen voor legacy-authenticatie

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

• Runtimebron voor inloggegevens is de opgeloste in-memory snapshot.
• Legacy statische api_key-vermeldingen worden verwijderd wanneer ze worden ontdekt.
• OAuth-gerelateerd compatibiliteitsgedrag blijft gescheiden.

# Opmerking over Web UI

Sommige SecretInput-unions zijn gemakkelijker te configureren in raw-editormodus dan in formuliermodus.

# Gerelateerd

• Authenticatie — auth-installatie
• CLI: secrets — CLI-commando's
• Omgevingsvariabelen — omgevingsprioriteit
• SecretRef-oppervlak voor inloggegevens — oppervlak voor inloggegevens
• Contract voor Secrets Apply-plan — details van plancontract
• Beveiliging — beveiligingshouding