गोपनीय जानकारी का प्रबंधन

​

रनटाइम मॉडल

• Secrets अनुरोध पथों पर विलंबित रूप से नहीं, बल्कि सक्रियण के दौरान तत्परता से इन-मेमोरी रनटाइम स्नैपशॉट में रिज़ॉल्व होते हैं।
• कोल्ड Gateway स्टार्टअप पुनः प्रयास योग्य SecretRef विफलता को किसी ज्ञात गैर-Gateway स्वामी तक सीमित रखता है, बशर्ते वह स्वामी पृथक्करण का समर्थन करता हो। मैप किए गए स्वामी वर्गों में मॉडल प्रदाता और Skills, मीडिया/TTS/Cron प्रदाता, पात्र प्रमाणीकरण प्रोफ़ाइल, प्रति-एजेंट मेमोरी, सैंडबॉक्स SSH, चैनल खाते और मैनिफ़ेस्ट में घोषित Plugin रूट शामिल हैं। Gateway प्रारंभ होता है, स्वामी को कॉन्फ़िगर-किंतु-अनुपलब्ध के रूप में दर्ज करता है और संशोधित अवनति चेतावनी जारी करता है। Gateway इनग्रेस प्रमाणीकरण, संरचनात्मक रूप से अमान्य रेफ़रेंस या रिज़ॉल्व किए गए मान, विफलता पर बंद होने वाले स्वामी और वे रेफ़रेंस जिनका रनटाइम स्वामी मैप नहीं किया गया है, अब भी स्टार्टअप को विफल करते हैं।
• रीलोड प्रत्येक मैप किए गए स्वामी को स्वतंत्र रूप से सत्यापित करता है, फिर एक परमाण्विक स्नैपशॉट प्रकाशित करता है। स्वस्थ स्वामी रीफ़्रेश होते हैं। कोई पात्र विफल स्वामी अपना अंतिम-ज्ञात-सही मान बनाए रखता है और केवल तभी स्टेल होता है, जब उसकी रेफ़रेंस पहचानें, प्रदाता परिभाषाएँ और पूर्ण गैर-गोपनीय स्वामी अनुबंध अपरिवर्तित हों; बदला हुआ या नया विफल स्वामी कोल्ड हो जाता है। कोई कठोर विफलता रीलोड को अस्वीकार करती है और सक्रिय स्नैपशॉट को सुरक्षित रखती है।
• नीति उल्लंघन (उदाहरण के लिए, SecretRef इनपुट के साथ संयुक्त OAuth-मोड प्रमाणीकरण प्रोफ़ाइल) रनटाइम अदला-बदली से पहले सक्रियण को विफल करते हैं।
• रनटाइम अनुरोध केवल सक्रिय इन-मेमोरी स्नैपशॉट को पढ़ते हैं। मॉडल-प्रदाता SecretRef क्रेडेंशियल निर्गमन तक प्रमाणीकरण स्टोरेज और स्ट्रीम विकल्पों से प्रक्रिया-स्थानीय सेंटिनल के रूप में गुजरते हैं। आउटबाउंड डिलीवरी पथ (Discord उत्तर/थ्रेड डिलीवरी, Telegram कार्रवाई प्रेषण) भी उसी स्नैपशॉट को पढ़ते हैं और प्रत्येक प्रेषण पर रेफ़रेंस को दोबारा रिज़ॉल्व नहीं करते।

​

निर्गमन-समय इंजेक्शन (सेंटिनल)

• कस्टम फ़ेच विकल्प वाले SDK को OpenClaw का संरक्षित फ़ेच मिलता है, इसलिए SDK सेंटिनल बनाए रखता है।
• कस्टम फ़ेच विकल्प के बिना SDK क्लाइंट निर्माण के ठीक पहले सेंटिनल को अनरैप करते हैं। Plugin-स्वामित्व वाली प्रदाता स्ट्रीम और एजेंट हार्नेस अंतिम कोर-स्वामित्व वाले हैंडऑफ़ पर अनरैप करते हैं, क्योंकि वे ट्रांसपोर्ट OpenClaw के संरक्षित फ़ेच को साझा नहीं करते।

​

एजेंट-अभिगम सीमा

• समर्थित क्रेडेंशियल प्लेनटेक्स्ट मानों के बजाय SecretRefs का उपयोग करते हैं।
• पुराना प्लेनटेक्स्ट अवशेष openclaw.json, auth-profiles.json, .env, और जनरेट की गई models.json फ़ाइलों से मिटा दिया गया है।
• माइग्रेशन के बाद openclaw secrets audit --check स्वच्छ है।
• शेष असमर्थित या घूर्णित क्रेडेंशियल OS पृथक्करण, कंटेनर पृथक्करण या बाहरी क्रेडेंशियल प्रॉक्सी द्वारा सुरक्षित हैं।

​

सक्रिय-सतह फ़िल्टरिंग

• सक्षम सतहें: मैप किए गए, पृथक किए जा सकने वाले स्वामियों की पुनः प्रयास योग्य विफलताएँ कोल्ड या स्टेल अवनति में प्रवेश करती हैं। कठोर, विफलता पर बंद, Gateway-आवश्यक या अमैप्ड विफलताएँ स्टार्टअप/रीलोड को अवरुद्ध करती हैं।
• निष्क्रिय सतहें: अनरिज़ॉल्व्ड रेफ़रेंस स्टार्टअप/रीलोड को अवरुद्ध नहीं करते; वे एक गैर-घातक SECRETS_REF_IGNORED_INACTIVE_SURFACE निदान जारी करते हैं।

​

Gateway प्रमाणीकरण सतह निदान

• active: SecretRef प्रभावी प्रमाणीकरण सतह का हिस्सा है और इसे रिज़ॉल्व होना आवश्यक है।
• inactive: कोई अन्य प्रमाणीकरण सतह जीतती है, या रिमोट प्रमाणीकरण अक्षम/निष्क्रिय है।

​

ऑनबोर्डिंग रेफ़रेंस पूर्व-जाँच

• पर्यावरण रेफ़रेंस: पर्यावरण चर का नाम सत्यापित करता है और पुष्टि करता है कि सेटअप के दौरान कोई गैर-रिक्त मान दिखाई दे रहा है।
• प्रदाता रेफ़रेंस (file या exec): प्रदाता चयन सत्यापित करता है, id को रिज़ॉल्व करता है और रिज़ॉल्व किए गए मान का प्रकार जाँचता है।
• क्विकस्टार्ट प्रवाह: जब gateway.auth.token पहले से SecretRef हो, तो ऑनबोर्डिंग समान त्वरित-विफलता गेट का उपयोग करके प्रोब/डैशबोर्ड बूटस्ट्रैप से पहले उसे (env, file, और exec रेफ़रेंस के लिए) रिज़ॉल्व करती है।

​

SecretRef अनुबंध

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

​

प्रदाता कॉन्फ़िगरेशन

{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json", // या "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",
    },
  },
}

{ "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": { "code": "NOT_FOUND" } }
}

​

फ़ाइल-समर्थित API कुंजियाँ

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

​

Exec इंटीग्रेशन के उदाहरण

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // Homebrew की सिमलिंक की गई बाइनरी के लिए आवश्यक
        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, // Homebrew की सिमलिंक की गई बाइनरी के लिए आवश्यक
        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 node
const { 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(`अनुरोध पार्स करने में विफल: ${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 ${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 --check
openclaw secrets audit --allow-exec

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        allowSymlinkCommand: true, // Homebrew की सिमलिंक की गई बाइनरी के लिए आवश्यक
        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 सर्वर परिवेश चर

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

​

Sandbox SSH प्रमाणीकरण सामग्री

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

• OpenClaw इन संदर्भों को प्रत्येक SSH कॉल पर विलंबित रूप से नहीं, बल्कि सैंडबॉक्स सक्रियण के दौरान हल करता है।
• हल किए गए मान प्रतिबंधात्मक फ़ाइल अनुमतियों (0o600) के साथ एक अस्थायी डायरेक्टरी में लिखे जाते हैं और जनरेट किए गए SSH कॉन्फ़िगरेशन में उपयोग होते हैं।
• यदि प्रभावी सैंडबॉक्स बैकएंड ssh नहीं है (या सैंडबॉक्स मोड off है), तो ये संदर्भ निष्क्रिय रहते हैं और स्टार्टअप को अवरुद्ध नहीं करते।

​

समर्थित क्रेडेंशियल सतह

​

आवश्यक व्यवहार और प्राथमिकता

• संदर्भ के बिना फ़ील्ड: अपरिवर्तित।
• संदर्भ वाला फ़ील्ड: सक्रियण के दौरान सक्रिय सतहों पर आवश्यक।
• यदि प्लेनटेक्स्ट और संदर्भ दोनों मौजूद हैं, तो समर्थित प्राथमिकता पथों पर संदर्भ को प्राथमिकता मिलती है।
• रेडैक्शन सेंटिनल __OPENCLAW_REDACTED__ आंतरिक कॉन्फ़िगरेशन रेडैक्शन/पुनर्स्थापन के लिए आरक्षित है और शाब्दिक रूप से सबमिट किए गए कॉन्फ़िगरेशन डेटा के रूप में अस्वीकार किया जाता है।

• SECRETS_REF_OVERRIDES_PLAINTEXT (रनटाइम चेतावनी)
• REF_SHADOWED (जब auth-profiles.json क्रेडेंशियल openclaw.json संदर्भों पर प्राथमिकता लेते हैं, तब ऑडिट निष्कर्ष)

​

सक्रियण ट्रिगर

• स्टार्टअप (प्रीफ़्लाइट और अंतिम सक्रियण)
• कॉन्फ़िगरेशन रीलोड हॉट-अप्लाई पथ
• कॉन्फ़िगरेशन रीलोड रीस्टार्ट-जाँच पथ
• secrets.reload के माध्यम से मैन्युअल रीलोड
• Gateway कॉन्फ़िगरेशन लेखन RPC प्रीफ़्लाइट (config.set / config.apply / config.patch), जो संपादनों को स्थायी करने से पहले सबमिट किए गए कॉन्फ़िगरेशन पेलोड में सक्रिय-सतह SecretRefs को सत्यापित करता है

• सफलता स्नैपशॉट को परमाण्विक रूप से बदल देती है।
• सख्त स्टार्टअप विफलता Gateway स्टार्टअप को रोक देती है।
• कोल्ड स्टार्टअप के दौरान, मैप किए गए और पृथक किए जा सकने वाले गैर-Gateway स्वामी की पुनःप्रयास-योग्य समाधान विफलता स्नैपशॉट को उस सटीक स्वामी के कॉन्फ़िगर-अनुपलब्ध होने के साथ प्रकाशित कर सकती है। उस स्वामी के अनुरोध SECRET_SURFACE_UNAVAILABLE के साथ विफल होते हैं; स्पष्ट संदर्भ विफल होने के बाद मॉडल-प्रदाता स्वामी एनवायरनमेंट या प्रमाणीकरण-प्रोफ़ाइल क्रेडेंशियल पर फ़ॉलबैक नहीं करते।
• रीलोड और रीस्टार्ट-जाँच योग्य मैप किए गए स्वामियों को पृथक करते हैं। अपरिवर्तित प्रदाता परिभाषाओं और अपरिवर्तित पूर्ण गैर-गोपनीय स्वामी अनुबंध वाली अपरिवर्तित संदर्भ पहचानें अपने सटीक अंतिम-ज्ञात-सही मानों को स्टेल रूप में बनाए रखती हैं; बदले हुए या नए कॉन्फ़िगर किए गए अनसुलझे संदर्भ केवल उस स्वामी के लिए कोल्ड प्रकाशित होते हैं। सख्त रीलोड विफलता पहले से सक्रिय स्नैपशॉट को सुरक्षित रखती है।
• config.set, config.apply, और config.patch पृथक किए जा सकने वाले स्वामियों के लिए वाक्य-विन्यास की दृष्टि से मान्य अनसुलझे संदर्भ स्वीकार करते हैं और रेडैक्ट की गई degradedSecretOwners रिपोर्ट लौटाते हैं। Gateway इनग्रेस प्रमाणीकरण, संरचनात्मक रूप से अमान्य कॉन्फ़िगरेशन या हल किए गए मान, नीति उल्लंघन और अज्ञात स्वामी अब भी डिस्क परिवर्तन से पहले अस्वीकार होते हैं।
• किसी अन्य स्वामी के कोल्ड या स्टेल होने पर भी स्वस्थ सहोदर स्वामी सामान्य रूप से हल और प्रकाशित होते हैं।
• आउटबाउंड सहायक/टूल कॉल को स्पष्ट प्रति-कॉल चैनल टोकन देने से SecretRef सक्रियण ट्रिगर नहीं होता; सक्रियण बिंदु स्टार्टअप, रीलोड और स्पष्ट secrets.reload ही रहते हैं।

​

अवनत और पुनर्प्राप्त संकेत

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

• अवनत: स्वस्थ स्वामी रीफ़्रेश होते हैं, स्टेल स्वामी अंतिम-ज्ञात-सही मान बनाए रखते हैं और कोल्ड स्वामी अनुपलब्ध रहते हैं।
• पुनर्प्राप्त: अगले सफल सक्रियण के बाद एक बार उत्सर्जित होता है।
• पहले से अवनत स्थिति में बार-बार होने वाली विफलताएँ चेतावनियाँ लॉग करती हैं, लेकिन इवेंट दोबारा उत्सर्जित नहीं करतीं।
• सख्त स्टार्टअप विफलता कभी अवनत इवेंट उत्सर्जित नहीं करती, क्योंकि रनटाइम कभी सक्रिय नहीं हुआ। कोल्ड स्वामियों वाला सफल स्टार्टअप स्वामी के अवनत होने को लॉग करता है, लेकिन रीलोडर इवेंट उत्सर्जित नहीं करता।
• संदर्भ-सीमित स्टार्टअप और रीलोड विफलताएँ प्रत्येक प्रभावित स्वामी के लिए संरचित SECRETS_DEGRADED चेतावनी उत्सर्जित करती हैं। प्रदाता-सीमित आउटेज प्रत्येक स्वामी के लिए प्रदाता विफलता दोहराने के बजाय प्रदाता और प्रभावित स्वामियों की पूर्ण सूची सहित एक SECRETS_PROVIDER_DEGRADED चेतावनी उत्सर्जित करते हैं। चेतावनियों में रेडैक्ट किया गया कारण, cold या stale स्वामी स्थिति और openclaw secrets reload पुनःप्रयास संकेत शामिल होते हैं। इनमें कभी हल किए गए मान या SecretRef आईडी शामिल नहीं होते।
• openclaw doctor कोल्ड और स्टेल स्वामियों को उनके प्रभावित कॉन्फ़िगरेशन पथों, रेडैक्ट किए गए कारण और पुनःप्रयास मार्गदर्शन के साथ सूचीबद्ध करता है।

​

कमांड-पथ समाधान

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

​

ऑडिट और कॉन्फ़िगरेशन कार्यप्रवाह

openclaw secrets audit --check

openclaw secrets configure --apply

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

​

एक-तरफ़ा सुरक्षा नीति

• लेखन मोड से पहले प्रीफ़्लाइट सफल होना आवश्यक है।
• कमिट से पहले रनटाइम सक्रियण सत्यापित किया जाता है।
• लागू करने की प्रक्रिया परमाण्विक फ़ाइल प्रतिस्थापन और विफलता पर सर्वोत्तम-प्रयास पुनर्स्थापन का उपयोग करके फ़ाइलें अपडेट करती है।

​

लीगेसी प्रमाणीकरण संगतता टिप्पणियाँ

• रनटाइम क्रेडेंशियल स्रोत हल किया गया इन-मेमोरी स्नैपशॉट है।
• लीगेसी स्थिर api_key प्रविष्टियाँ मिलने पर हटा दी जाती हैं।
• OAuth-संबंधित संगतता व्यवहार अलग रहता है।

​

वेब UI टिप्पणी

​

संबंधित

• प्रमाणीकरण - प्रमाणीकरण सेटअप
• CLI: सीक्रेट्स - CLI कमांड
• Vault SecretRefs - HashiCorp Vault प्रदाता सेटअप
• पर्यावरण चर - पर्यावरण वरीयता क्रम
• SecretRef क्रेडेंशियल सतह - क्रेडेंशियल सतह
• सीक्रेट्स लागू करने की योजना का अनुबंध - योजना अनुबंध का विवरण
• सुरक्षा - सुरक्षा स्थिति