सीक्रेट प्रबंधन

OpenClaw additive SecretRefs का समर्थन करता है ताकि समर्थित क्रेडेंशियल्स को कॉन्फ़िगरेशन में plaintext के रूप में संग्रहीत करने की आवश्यकता न हो।

लक्ष्य और रनटाइम मॉडल

Secrets को इन-मेमरी रनटाइम स्नैपशॉट में resolve किया जाता है।

• Resolution activation के दौरान eager होता है, request paths पर lazy नहीं।
• जब कोई प्रभावी रूप से सक्रिय SecretRef resolve नहीं हो पाता, startup तुरंत fail होता है।
• Reload atomic swap का उपयोग करता है: पूर्ण सफलता, या last-known-good snapshot बनाए रखें।
• SecretRef policy violations (उदाहरण के लिए SecretRef input के साथ OAuth-mode auth profiles) runtime swap से पहले activation को fail करते हैं।
• Runtime requests केवल active in-memory snapshot से पढ़ते हैं।
• पहली सफल config activation/load के बाद, runtime code paths उस active in-memory snapshot को तब तक पढ़ते रहते हैं जब तक सफल reload उसे swap नहीं कर देता।
• Outbound delivery paths भी उसी active snapshot से पढ़ते हैं (उदाहरण के लिए Discord reply/thread delivery और Telegram action sends); वे हर send पर SecretRefs को फिर से resolve नहीं करते।

इससे secret-provider outages hot request paths से दूर रहते हैं।

एजेंट-access boundary

SecretRefs समर्थित config और generated model surfaces में credentials को persist होने से बचाते हैं, लेकिन वे process-isolation boundary नहीं हैं। यदि कोई plaintext credential disk पर ऐसे path में रहता है जिसे agent पढ़ सकता है, तो agent file या shell tools का उपयोग करके उस file को inspect कर API-level redaction को bypass कर सकता है।

Production deployments के लिए जहाँ agent-accessible files scope में हैं, SecretRef migration को complete केवल तब मानें जब ये सभी true हों:

• समर्थित credentials plaintext values के बजाय SecretRefs का उपयोग करते हैं
• legacy plaintext residue को openclaw.json, auth-profiles.json, .env, और generated models.json files से scrub किया गया है
• migration के बाद openclaw secrets audit --check clean है
• कोई भी शेष unsupported या rotating credentials operating system isolation, container isolation, या external credential proxy से protected हैं

इसीलिए audit/configure/apply workflow एक security migration gate है, केवल convenience helper नहीं।

Active-surface filtering

SecretRefs केवल प्रभावी रूप से active surfaces पर validate किए जाते हैं।

• Enabled surfaces: unresolved refs startup/reload को block करते हैं।
• Inactive surfaces: unresolved refs startup/reload को block नहीं करते।
• Inactive refs code SECRETS_REF_IGNORED_INACTIVE_SURFACE के साथ non-fatal diagnostics emit करते हैं।

Gateway auth surface diagnostics

जब gateway.auth.token, gateway.auth.password, gateway.remote.token, या gateway.remote.password पर SecretRef configured होता है, gateway startup/reload surface state को explicitly log करता है:

• active: SecretRef effective auth surface का हिस्सा है और must resolve.
• inactive: SecretRef इस runtime के लिए ignored है क्योंकि कोई दूसरी auth surface wins करती है, या remote auth disabled/not active है।

ये entries SECRETS_GATEWAY_AUTH_SURFACE के साथ log की जाती हैं और active-surface policy द्वारा उपयोग किया गया reason शामिल करती हैं, ताकि आप देख सकें कि credential को active या inactive क्यों treat किया गया।

Onboarding reference preflight

जब onboarding interactive mode में चलता है और आप SecretRef storage चुनते हैं, OpenClaw saving से पहले preflight validation चलाता है:

• Env refs: env var name validate करता है और confirm करता है कि setup के दौरान non-empty value visible है।
• Provider refs (file या exec): provider selection validate करता है, id resolve करता है, और resolved value type check करता है।
• Quickstart reuse path: जब gateway.auth.token पहले से SecretRef है, onboarding probe/dashboard bootstrap से पहले उसे resolve करता है (env, file, और exec refs के लिए) उसी fail-fast gate का उपयोग करके।

यदि validation fail होता है, onboarding error दिखाता है और आपको retry करने देता है।

SecretRef contract

हर जगह एक object shape का उपयोग करें:

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

Provider config

Providers को secrets.providers के अंतर्गत define करें:

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

File-backed API keys

Config env block में file:... strings न डालें। env block literal और non-overriding है, इसलिए file:... resolve नहीं होता।

इसके बजाय supported credential field पर file SecretRef का उपयोग करें:

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

mode: "singleValue" के लिए, SecretRef id "value" है। mode: "json" के लिए, "/providers/xai/apiKey" जैसा absolute JSON pointer उपयोग करें।

SecretRefs accept करने वाले config fields के लिए SecretRef credential surface देखें।

Exec integration examples

{  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 सर्वर environment variables

plugins.entries.acpx.config.mcpServers के माध्यम से configured MCP सर्वर env vars SecretInput का समर्थन करते हैं। इससे API keys और tokens plaintext config से बाहर रहते हैं:

{  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 string values अभी भी काम करते हैं। ${MCP_SERVER_API_KEY} जैसे env-template refs और SecretRef objects, MCP सर्वर process spawn होने से पहले gateway activation के दौरान resolve किए जाते हैं। अन्य SecretRef surfaces की तरह, unresolved refs activation को केवल तब block करते हैं जब acpx plugin प्रभावी रूप से active हो।

Sandbox SSH auth material

core ssh sandbox backend SSH auth material के लिए SecretRefs का भी समर्थन करता है:

{  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 व्यवहार:

• OpenClaw इन refs को sandbox activation के दौरान resolve करता है, हर SSH call के दौरान lazily नहीं।
• Resolved values restrictive permissions के साथ temp files में लिखे जाते हैं और generated SSH config में उपयोग होते हैं।
• यदि effective sandbox backend ssh नहीं है, तो ये refs inactive रहते हैं और startup block नहीं करते।

समर्थित credential surface

Canonical supported और unsupported credentials यहां सूचीबद्ध हैं:

• SecretRef Credential Surface

आवश्यक व्यवहार और precedence

• ref के बिना field: unchanged।
• ref वाला field: activation के दौरान active surfaces पर required।
• यदि plaintext और ref दोनों मौजूद हैं, तो supported precedence paths पर ref precedence लेता है।
• redaction sentinel __OPENCLAW_REDACTED__ internal config redaction/restore के लिए reserved है और literal submitted config data के रूप में rejected है।

Warning और audit signals:

• SECRETS_REF_OVERRIDES_PLAINTEXT (runtime warning)
• REF_SHADOWED (audit finding जब auth-profiles.json credentials openclaw.json refs पर precedence लेते हैं)

Google Chat compatibility behavior:

• serviceAccountRef plaintext serviceAccount पर precedence लेता है।
• sibling ref set होने पर plaintext value ignored होती है।

Activation triggers

Secret activation इन पर चलता है:

• Startup (preflight plus final activation)
• Config reload hot-apply path
• Config reload restart-check path
• secrets.reload के माध्यम से manual reload
• Gateway config write RPC preflight (config.set / config.apply / config.patch) submitted config payload के भीतर active-surface SecretRef resolvability के लिए, edits persist करने से पहले

Activation contract:

• Success snapshot को atomically swap करता है।
• Startup failure gateway startup abort करता है।
• Runtime reload failure last-known-good snapshot बनाए रखता है।
• Write-RPC preflight failure submitted config को reject करता है और disk config तथा active runtime snapshot दोनों को unchanged रखता है।
• outbound helper/tool call को explicit per-call channel token देने से SecretRef activation trigger नहीं होता; activation points startup, reload, और explicit secrets.reload ही रहते हैं।

Degraded और recovered signals

जब healthy state के बाद reload-time activation fail होता है, OpenClaw degraded secrets state में enter करता है।

One-shot system event और log codes:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Behavior:

• Degraded: runtime last-known-good snapshot बनाए रखता है।
• Recovered: अगले successful activation के बाद एक बार emitted।
• पहले से degraded रहते हुए repeated failures warnings log करते हैं, लेकिन events spam नहीं करते।
• Startup fail-fast degraded events emit नहीं करता क्योंकि runtime कभी active हुआ ही नहीं।

Command-path resolution

Command paths gateway snapshot RPC के माध्यम से supported SecretRef resolution में opt कर सकते हैं।

दो broad behaviors हैं:

अन्य नोट्स:

• backend secret rotation के बाद स्नैपशॉट refresh openclaw secrets reload द्वारा संभाला जाता है।
• इन कमांड पथों द्वारा उपयोग की गई Gateway RPC विधि: secrets.resolve.

ऑडिट और कॉन्फ़िगर वर्कफ़्लो

डिफ़ॉल्ट ऑपरेटर फ़्लो:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

जब तक दोबारा ऑडिट साफ़ न हो, migration को पूरा न मानें। यदि ऑडिट अभी भी at rest plaintext values रिपोर्ट करता है, तो agent-access जोखिम अभी भी मौजूद है भले ही runtime APIs redacted values लौटाएँ।

यदि आप configure के दौरान apply करने के बजाय कोई योजना सहेजते हैं, तो दोबारा ऑडिट से पहले उस सहेजी गई योजना को openclaw secrets apply --from <plan-path> के साथ लागू करें।

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

वन-वे सुरक्षा नीति

सुरक्षा मॉडल:

• write mode से पहले preflight सफल होना चाहिए
• commit से पहले runtime activation validate किया जाता है
• apply atomic file replacement और failure पर best-effort restore का उपयोग करके files update करता है

Legacy auth compatibility नोट्स

static credentials के लिए, runtime अब plaintext legacy auth storage पर निर्भर नहीं है।

• Runtime credential source resolved in-memory snapshot है।
• Legacy static api_key entries मिलने पर scrub की जाती हैं।
• OAuth-related compatibility behavior अलग रहता है।

Web UI नोट

कुछ SecretInput unions को form mode की तुलना में raw editor mode में कॉन्फ़िगर करना आसान होता है।

संबंधित

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