OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

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

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

रनटाइम मॉडल

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

इससे गोपनीयता-प्रदाता की अनुपलब्धताएँ हॉट अनुरोध पथों से दूर रहती हैं।

Gateway इनग्रेस सुरक्षा, संरचनात्मक रूप से अमान्य कॉन्फ़िगरेशन या रिज़ॉल्व किए गए मान, नीति उल्लंघन और अज्ञात स्वामित्व अब भी विफलता पर बंद होते हैं। पृथक किए गए स्वामी कभी भी कम-प्राथमिकता वाले क्रेडेंशियल स्रोत पर फ़ॉलबैक नहीं करते।

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

SecretRefs द्वारा समर्थित मॉडल-प्रदाता क्रेडेंशियल के लिए, OpenClaw मॉडल-प्रमाणीकरण रिज़ॉल्यूशन के दौरान एक अपारदर्शी, प्रक्रिया-स्थानीय सेंटिनल बनाता है। इसलिए प्रमाणीकरण स्टोरेज, स्ट्रीम विकल्प, SDK कॉन्फ़िगरेशन, लॉग, त्रुटि ऑब्जेक्ट और अधिकांश रनटाइम निरीक्षण प्रदाता क्रेडेंशियल के बजाय oc-sent-v1-... जैसा मान देखते हैं। संरक्षित मॉडल फ़ेच और प्रबंधित स्थानीय-प्रदाता स्वास्थ्य प्रोब प्रत्येक अनुरोध के प्रक्रिया से बाहर जाने के ठीक पहले URL और हेडर मानों में ज्ञात सेंटिनल को बदल देते हैं।

अज्ञात सेंटिनल-जैसे मान नेटवर्क गतिविधि से पहले विफलता पर बंद हो जाते हैं। OpenClaw किसी अनरिज़ॉल्व्ड सेंटिनल को प्रदाता तक अग्रेषित करने के बजाय अनुरोध भेजने से मना करता है। अतिरिक्त सुरक्षा उपाय के रूप में रिज़ॉल्व किए गए गोपनीय मान भी सटीक-मान लॉग संशोधन के लिए पंजीकृत किए जाते हैं।

प्रदाता अडैप्टर अपने SDK द्वारा समर्थित नवीनतम इंजेक्शन बिंदु का उपयोग करते हैं:

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

सेंटिनल मॉडल-कॉल शृंखला में प्लेनटेक्स्ट अनावरण घटाते हैं, लेकिन वे प्रक्रिया पृथक्करण नहीं हैं। वास्तविक मान अब भी उसी प्रक्रिया की मेमोरी में मौजूद रहता है और अंतिम अडैप्टर सीमा पर दिखाई देता है। SecretRefs के माध्यम से कॉन्फ़िगर न किए गए साधारण पर्यावरण क्रेडेंशियल प्लेनटेक्स्ट बने रहते हैं और इस तंत्र से बाहर हैं।

घटना प्रतिक्रिया या संगतता समस्या-निवारण के दौरान सेंटिनल निर्माण अक्षम करने के लिए OPENCLAW_SECRET_SENTINELS=off सेट करें (0 या false भी स्वीकार किए जाते हैं, अक्षर-स्थिति से निरपेक्ष)। यह किल स्विच सटीक-मान संशोधन पंजीकरण को अक्षम नहीं करता।

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

SecretRefs क्रेडेंशियल को कॉन्फ़िगरेशन और जनरेट की गई मॉडल फ़ाइलों में स्थायी होने से रोकते हैं, लेकिन वे प्रक्रिया-पृथक्करण सीमा नहीं हैं। एजेंट द्वारा पढ़े जा सकने वाले पथ में डिस्क पर छोड़ा गया प्लेनटेक्स्ट क्रेडेंशियल अब भी फ़ाइल या शेल टूल के माध्यम से पढ़ा जा सकता है, जिससे API-स्तरीय संशोधन बायपास हो जाता है।

उन उत्पादन परिनियोजनों के लिए जहाँ एजेंट-अभिगम योग्य फ़ाइलें दायरे में हैं, माइग्रेशन को केवल तभी पूर्ण मानें जब ये सभी शर्तें पूरी हों:

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

इसी कारण ऑडिट/कॉन्फ़िगर/लागू करें कार्यप्रवाह केवल सुविधाजनक सहायक नहीं, बल्कि सुरक्षा माइग्रेशन गेट है।

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

SecretRefs केवल प्रभावी रूप से सक्रिय सतहों पर सत्यापित किए जाते हैं:

  • सक्षम सतहें: मैप किए गए, पृथक किए जा सकने वाले स्वामियों की पुनः प्रयास योग्य विफलताएँ कोल्ड या स्टेल अवनति में प्रवेश करती हैं। कठोर, विफलता पर बंद, Gateway-आवश्यक या अमैप्ड विफलताएँ स्टार्टअप/रीलोड को अवरुद्ध करती हैं।
  • निष्क्रिय सतहें: अनरिज़ॉल्व्ड रेफ़रेंस स्टार्टअप/रीलोड को अवरुद्ध नहीं करते; वे एक गैर-घातक SECRETS_REF_IGNORED_INACTIVE_SURFACE निदान जारी करते हैं।
निष्क्रिय सतहों के उदाहरण
  • अक्षम चैनल/खाता प्रविष्टियाँ।
  • शीर्ष-स्तरीय चैनल क्रेडेंशियल जिन्हें कोई सक्षम खाता इनहेरिट नहीं करता।
  • अक्षम टूल/फ़ीचर सतहें।
  • वेब खोज प्रदाता-विशिष्ट कुंजियाँ जिन्हें tools.web.search.provider द्वारा चयनित नहीं किया गया है। स्वचालित मोड में (प्रदाता अनसेट), स्वतः-पहचान के लिए कुंजियों को प्राथमिकता के क्रम में तब तक देखा जाता है जब तक कोई रिज़ॉल्व न हो जाए; चयन के बाद, गैर-चयनित प्रदाता कुंजियाँ निष्क्रिय होती हैं।
  • सैंडबॉक्स SSH प्रमाणीकरण सामग्री (agents.defaults.sandbox.ssh.identityData, certificateData, knownHostsData, और प्रति-एजेंट ओवरराइड) केवल तभी सक्रिय होती है, जब प्रभावी सैंडबॉक्स बैकएंड ssh हो और सैंडबॉक्स मोड off न हो—डिफ़ॉल्ट एजेंट या किसी सक्षम एजेंट के लिए।
  • gateway.remote.token / gateway.remote.password SecretRefs सक्रिय होते हैं यदि इनमें से कोई शर्त पूरी हो:
  • gateway.mode=remote
  • gateway.remote.url कॉन्फ़िगर किया गया है
  • gateway.tailscale.mode, serve या funnel है
  • उन रिमोट सतहों के बिना स्थानीय मोड में: gateway.remote.token तब सक्रिय होता है जब टोकन प्रमाणीकरण जीत सकता हो और कोई पर्यावरण/प्रमाणीकरण टोकन कॉन्फ़िगर न हो; gateway.remote.password केवल तभी सक्रिय होता है जब पासवर्ड प्रमाणीकरण जीत सकता हो और कोई पर्यावरण/प्रमाणीकरण पासवर्ड कॉन्फ़िगर न हो।
  • स्टार्टअप प्रमाणीकरण रिज़ॉल्यूशन के लिए gateway.auth.token SecretRef तब निष्क्रिय होता है जब OPENCLAW_GATEWAY_TOKEN सेट हो, क्योंकि उस रनटाइम के लिए पर्यावरण टोकन इनपुट जीतता है।

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

जब gateway.auth.token, gateway.auth.password, gateway.remote.token, या gateway.remote.password पर SecretRef सेट होता है, तो Gateway स्टार्टअप/रीलोड कोड SECRETS_GATEWAY_AUTH_SURFACE के अंतर्गत सतह की स्थिति लॉग करता है:

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

लॉग प्रविष्टि में सक्रिय-सतह नीति द्वारा उपयोग किया गया कारण शामिल होता है।

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

इंटरैक्टिव ऑनबोर्डिंग में SecretRef स्टोरेज चुनने पर सहेजने से पहले पूर्व-जाँच सत्यापन चलता है:

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

सत्यापन विफल होने पर त्रुटि दिखाई जाती है और आपको पुनः प्रयास करने दिया जाता है।

SecretRef अनुबंध

हर स्थान पर एक ही ऑब्जेक्ट आकार:

json5
{ source: "env" | "file" | "exec", provider: "default", id: "..." }

env

json5
{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

SecretInput फ़ील्ड पर संक्षिप्त स्ट्रिंग भी स्वीकार की जाती हैं:

json5
"${OPENAI_API_KEY}""$OPENAI_API_KEY"

सत्यापन:

  • provider, ^[a-z][a-z0-9_-]{0,63}$ से मेल खाना चाहिए
  • id, ^[A-Z][A-Z0-9_]{0,127}$ से मेल खाना चाहिए

file

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

सत्यापन:

  • provider, ^[a-z][a-z0-9_-]{0,63}$ से मेल खाना चाहिए
  • id एक निरपेक्ष JSON पॉइंटर (/...) या singleValue प्रदाताओं के लिए शाब्दिक value होना चाहिए
  • खंडों में RFC 6901 एस्केपिंग: ~, ~0 बन जाता है; /, ~1 बन जाता है

exec

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

सत्यापन:

  • provider, ^[a-z][a-z0-9_-]{0,63}$ से मेल खाना चाहिए
  • id, ^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$ से मेल खाना चाहिए (secret#json_key जैसे चयनकर्ताओं का समर्थन करता है)
  • id में स्लैश-सीमांकित पथ खंडों के रूप में . या .. नहीं होना चाहिए (उदाहरण के लिए, a/../b अस्वीकार किया जाता है)

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

secrets.providers के अंतर्गत प्रदाता परिभाषित करें:

json5
{  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",    },  },}
पर्यावरण प्रदाता
  • allowlist के माध्यम से वैकल्पिक सटीक-नाम अनुमति सूची।
  • अनुपलब्ध या रिक्त पर्यावरण मान रिज़ॉल्यूशन को विफल करते हैं।
फ़ाइल प्रदाता
  • path पर स्थानीय फ़ाइल पढ़ता है।
  • mode: "json" (डिफ़ॉल्ट) JSON ऑब्जेक्ट पेलोड अपेक्षित करता है और id को JSON पॉइंटर के रूप में रिज़ॉल्व करता है।
  • mode: "singleValue" रेफ़रेंस आईडी "value" अपेक्षित करता है और फ़ाइल की अपरिष्कृत सामग्री लौटाता है (अंतिम न्यूलाइन हटाकर)।
  • पथ को स्वामित्व/अनुमति जाँचों में सफल होना चाहिए; timeoutMs (डिफ़ॉल्ट 5000) और maxBytes (डिफ़ॉल्ट 1 MiB) पठन को सीमित करते हैं।
  • Windows में विफलता पर बंद: यदि पथ के लिए ACL सत्यापन उपलब्ध नहीं है, तो रिज़ॉल्यूशन विफल हो जाता है। केवल विश्वसनीय पथों के लिए, जाँच को बायपास करने हेतु उस प्रदाता पर allowInsecurePath: true सेट करें।
Exec प्रदाता
  • कॉन्फ़िगर किए गए निरपेक्ष बाइनरी पथ को बिना किसी शेल के सीधे चलाता है।
  • डिफ़ॉल्ट रूप से command एक नियमित फ़ाइल होनी चाहिए, सिमलिंक नहीं। सिमलिंक कमांड पथों (उदाहरण के लिए Homebrew शिम) की अनुमति देने के लिए allowSymlinkCommand: true सेट करें, और इसे trustedDirs (उदाहरण के लिए ["/opt/homebrew"]) के साथ जोड़ें, ताकि केवल पैकेज-मैनेजर पथ ही योग्य हों।
  • timeoutMs (डिफ़ॉल्ट 5000), noOutputTimeoutMs (डिफ़ॉल्ट timeoutMs के बराबर), maxOutputBytes (डिफ़ॉल्ट 1 MiB), env/passEnv अनुमति-सूची और trustedDirs का समर्थन करता है।
  • jsonOnly का डिफ़ॉल्ट true है। jsonOnly: false और अनुरोधित एकल आईडी के साथ, सामान्य गैर-JSON stdout को उस आईडी के मान के रूप में स्वीकार किया जाता है।
  • Windows में विफलता पर बंद: यदि कमांड पथ के लिए ACL सत्यापन उपलब्ध नहीं है, तो रिज़ॉल्यूशन विफल हो जाता है। केवल विश्वसनीय पथों के लिए, जाँच को बायपास करने हेतु उस प्रदाता पर allowInsecurePath: true सेट करें।
  • Plugin-प्रबंधित exec प्रदाता कॉपी किए गए command/args के बजाय pluginIntegration का उपयोग कर सकते हैं। OpenClaw स्टार्टअप/रीलोड के दौरान इंस्टॉल किए गए Plugin मैनिफ़ेस्ट से वर्तमान कमांड विवरण रिज़ॉल्व करता है; यदि Plugin अक्षम, हटाया गया या अविश्वसनीय हो, अथवा अब इंटीग्रेशन घोषित न करता हो, तो उस प्रदाता के सक्रिय SecretRefs विफलता पर बंद हो जाते हैं।

अनुरोध पेलोड (stdin):

json
{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

प्रतिक्रिया पेलोड (stdout):

jsonc
{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

वैकल्पिक प्रति-आईडी त्रुटियाँ:

json
{"protocolVersion": 1,"values": {},"errors": { "providers/openai/apiKey": { "code": "NOT_FOUND" } }}

code एक वैकल्पिक मशीन-पठनीय निदान है। OpenClaw मान्यता-प्राप्त कोड NOT_FOUND और AMBIGUOUS_DUPLICATE_KEY को प्रदाता और रेफ़रेंस आईडी के साथ प्रदर्शित करता है। अन्य कोड और message जैसे मुक्त-रूप फ़ील्ड protocol-v1 संगतता के लिए स्वीकार किए जाते हैं, लेकिन प्रदर्शित नहीं किए जाते, क्योंकि रिज़ॉल्वर आउटपुट में क्रेडेंशियल सामग्री हो सकती है।

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

कॉन्फ़िगरेशन के env ब्लॉक में file:... स्ट्रिंग न रखें। वह ब्लॉक शाब्दिक और गैर-ओवरराइडिंग है, इसलिए वहाँ file:... कभी रिज़ॉल्व नहीं होता।

इसके बजाय समर्थित क्रेडेंशियल फ़ील्ड पर फ़ाइल SecretRef का उपयोग करें:

json5
{  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" जैसे निरपेक्ष JSON पॉइंटर का उपयोग करें।

SecretRefs स्वीकार करने वाले फ़ील्ड के लिए SecretRef क्रेडेंशियल सतह देखें।

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

सेवा खातों, बंडल किए गए एजेंट Skill और समस्या निवारण को शामिल करने वाली समर्पित 1Password मार्गदर्शिका के लिए 1Password देखें।

1Password CLI
json5
{  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" },      },    },  },}
Bitwarden Secrets Manager (`bws`)

SecretRef आईडी को Bitwarden Secrets Manager आइटम कुंजियों से मैप करने के लिए रिज़ॉल्वर रैपर का उपयोग करें। रिपॉज़िटरी में scripts/secrets/openclaw-bws-resolver.mjs शामिल है; इसे उस होस्ट पर किसी निरपेक्ष विश्वसनीय पथ में इंस्टॉल या कॉपी करें जो Gateway चलाता है।

आवश्यकताएँ:

  • Gateway होस्ट पर Bitwarden Secrets Manager CLI (bws) इंस्टॉल हो।
  • BWS_ACCESS_TOKEN Gateway सेवा के लिए उपलब्ध हो।
  • PATH रिज़ॉल्वर को पास किया गया हो, या BWS_BIN को निरपेक्ष bws बाइनरी पथ पर सेट किया गया हो।
  • स्वयं-होस्ट किए गए Bitwarden इंस्टेंस का उपयोग करते समय परिवेश में BWS_SERVER_URL सेट हो।
json5
{  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",        },      },    },  },}

रिज़ॉल्वर अनुरोधित आईडी को बैच करता है, bws secret list चलाता है और मेल खाने वाले सीक्रेट key फ़ील्ड के मान लौटाता है। ऐसी कुंजियों का उपयोग करें जो exec SecretRef आईडी अनुबंध को पूरा करती हों, जैसे openclaw/providers/openai/apiKey; अंडरस्कोर वाली env-var-शैली की कुंजियाँ रिज़ॉल्वर चलने से पहले ही अस्वीकार कर दी जाती हैं। यदि एक से अधिक दृश्यमान Bitwarden सीक्रेट में अनुरोधित कुंजी समान हो, तो रिज़ॉल्वर अनुमान लगाने के बजाय उस आईडी को अस्पष्ट मानकर विफल कर देता है। कॉन्फ़िगरेशन अपडेट करने के बाद रिज़ॉल्वर पथ सत्यापित करें:

bash
openclaw secrets audit --allow-exec
HashiCorp Vault CLI
json5
{  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" },      },    },  },}
password-store (`pass`)

SecretRef आईडी को सीधे pass प्रविष्टियों से मैप करने के लिए छोटे रिज़ॉल्वर रैपर का उपयोग करें। इसे ऐसे निरपेक्ष पथ पर निष्पादन योग्य फ़ाइल के रूप में सहेजें जो आपकी exec-प्रदाता पथ जाँचों में सफल हो, उदाहरण के लिए /usr/local/bin/openclaw-pass-resolver। #!/usr/bin/env node शेबैंग, रिज़ॉल्वर प्रक्रिया के PATH से node को रिज़ॉल्व करता है, इसलिए passEnv में PATH शामिल करें। यदि pass उस PATH पर नहीं है, तो पैरेंट परिवेश में PASS_BIN सेट करें और उसे भी passEnv में शामिल करें:

js
#!/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(`अनुरोध पार्स करने में विफल: ${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 }));});

फिर exec प्रदाता कॉन्फ़िगर करें और apiKey को pass प्रविष्टि पथ की ओर इंगित करें:

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

सीक्रेट को pass प्रविष्टि की पहली पंक्ति पर रखें, या इसके बजाय पूर्ण pass show आउटपुट लौटाने के लिए रैपर को अनुकूलित करें। कॉन्फ़िगरेशन अपडेट करने के बाद स्थैतिक ऑडिट और exec रिज़ॉल्वर पथ, दोनों सत्यापित करें:

bash
openclaw secrets audit --checkopenclaw secrets audit --allow-exec
sops
json5
{  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.config.mcpServers के माध्यम से कॉन्फ़िगर किए गए MCP सर्वर env vars, SecretInput स्वीकार करते हैं, जिससे API कुंजियाँ और टोकन प्लेनटेक्स्ट कॉन्फ़िगरेशन से बाहर रहते हैं:

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

प्लेनटेक्स्ट स्ट्रिंग मान अब भी काम करते हैं। ${MCP_SERVER_API_KEY} जैसे env-template रेफ़रेंस और SecretRef ऑब्जेक्ट, MCP सर्वर प्रक्रिया शुरू होने से पहले Gateway सक्रियण के दौरान रिज़ॉल्व होते हैं। अन्य SecretRef सतहों की तरह, अनरिज़ॉल्व्ड रेफ़रेंस केवल तभी सक्रियण रोकते हैं जब acpx Plugin प्रभावी रूप से सक्रिय हो।

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

मुख्य ssh Sandbox बैकएंड SSH प्रमाणीकरण सामग्री के लिए भी SecretRefs का समर्थन करता है:

json5
{  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 है), तो ये संदर्भ निष्क्रिय रहते हैं और स्टार्टअप को अवरुद्ध नहीं करते।

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

प्रामाणिक रूप से समर्थित और असमर्थित क्रेडेंशियल SecretRef क्रेडेंशियल सतह में सूचीबद्ध हैं।

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

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

चेतावनी और ऑडिट संकेत:

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

Google Chat serviceAccount इनलाइन JSON या SecretRef स्वीकार करता है। Doctor, हटाए जा चुके सहोदर serviceAccountRef को इस प्रामाणिक फ़ील्ड में ले जाता है, जब यह सेट न हो।

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

Secret सक्रियण इन पर चलता है:

  • स्टार्टअप (प्रीफ़्लाइट और अंतिम सक्रियण)
  • कॉन्फ़िगरेशन रीलोड हॉट-अप्लाई पथ
  • कॉन्फ़िगरेशन रीलोड रीस्टार्ट-जाँच पथ
  • 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 ही रहते हैं।

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

स्वस्थ स्थिति के बाद रीलोड-समय सक्रियण विफल होने पर, OpenClaw अवनत secrets स्थिति में प्रवेश करता है और एक-बार के सिस्टम इवेंट तथा लॉग कोड उत्सर्जित करता है:

  • SECRETS_RELOADER_DEGRADED
  • SECRETS_RELOADER_RECOVERED

व्यवहार:

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

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

कमांड पथ Gateway स्नैपशॉट RPC के माध्यम से समर्थित SecretRef समाधान का विकल्प चुन सकते हैं। दो व्यापक व्यवहार लागू होते हैं:

सख्त कमांड पथ

उदाहरण के लिए openclaw memory रिमोट-मेमोरी पथ और openclaw qr --remote, जब इसे रिमोट साझा-सीक्रेट संदर्भों की आवश्यकता होती है। ये सक्रिय स्नैपशॉट से पढ़ते हैं और आवश्यक SecretRef अनुपलब्ध होने पर तुरंत विफल होते हैं।

केवल-पढ़ने योग्य कमांड पथ

उदाहरण के लिए openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, openclaw security audit, और केवल-पढ़ने योग्य Doctor/कॉन्फ़िगरेशन सुधार प्रवाह। ये भी सक्रिय स्नैपशॉट को प्राथमिकता देते हैं, लेकिन लक्षित SecretRef अनुपलब्ध होने पर रुकने के बजाय अवनत हो जाते हैं।

केवल-पढ़ने योग्य व्यवहार:

  • Gateway चल रहा होने पर, ये कमांड पहले सक्रिय स्नैपशॉट से पढ़ते हैं।
  • यदि Gateway समाधान अधूरा है या Gateway अनुपलब्ध है, तो ये उस कमांड सतह के लिए लक्षित स्थानीय फ़ॉलबैक का प्रयास करते हैं।
  • यदि लक्षित SecretRef अब भी अनुपलब्ध है, तो कमांड अवनत केवल-पढ़ने योग्य आउटपुट और स्पष्ट निदान के साथ जारी रहता है कि संदर्भ कॉन्फ़िगर है, लेकिन इस कमांड पथ में अनुपलब्ध है।
  • यह अवनत व्यवहार केवल कमांड तक सीमित है; यह रनटाइम स्टार्टअप, रीलोड या प्रेषण/प्रमाणीकरण पथों को कमज़ोर नहीं करता।

अन्य टिप्पणियाँ:

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

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

डिफ़ॉल्ट ऑपरेटर प्रवाह:

  • वर्तमान स्थिति का ऑडिट करें

    bash
    openclaw secrets audit --check

  • SecretRefs कॉन्फ़िगर और लागू करें

    bash
    openclaw secrets configure --apply

  • पुनः ऑडिट करें

    bash
    openclaw secrets audit --check

    • पुनः ऑडिट साफ़ होने तक माइग्रेशन को पूर्ण न मानें। यदि ऑडिट अब भी स्थायी रूप से संग्रहीत प्लेनटेक्स्ट मानों की रिपोर्ट करता है, तो एजेंट-पहुँच जोखिम बना रहता है, भले ही रनटाइम API रेडैक्ट किए गए मान लौटाएँ।

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

    secrets audit

    निष्कर्षों में शामिल हैं:

    • स्थायी रूप से संग्रहीत प्लेनटेक्स्ट मान (openclaw.json, auth-profiles.json, .env, और जनरेट किया गया agents/*/agent/models.json)।
    • जनरेट की गई models.json प्रविष्टियों में प्लेनटेक्स्ट संवेदनशील प्रदाता हेडर अवशेष।
    • अनसुलझे संदर्भ।
    • प्राथमिकता शैडोइंग (auth-profiles.json का openclaw.json संदर्भों पर प्राथमिकता लेना)।
    • लीगेसी अवशेष (auth.json, OAuth अनुस्मारक)।

    Exec टिप्पणी: डिफ़ॉल्ट रूप से, कमांड के दुष्प्रभावों से बचने के लिए ऑडिट exec SecretRef समाधान-योग्यता जाँच छोड़ देता है। ऑडिट के दौरान exec प्रदाताओं को निष्पादित करने के लिए openclaw secrets audit --allow-exec का उपयोग करें।

    हेडर अवशेष टिप्पणी: संवेदनशील प्रदाता हेडर पहचान नाम-आधारित अनुमान पर आधारित है (सामान्य प्रमाणीकरण/क्रेडेंशियल हेडर नाम और authorization, x-api-key, token, secret, password, और credential जैसे अंश)।

    secrets configure

    इंटरैक्टिव सहायक जो:

    • पहले secrets.providers कॉन्फ़िगर करता है (env/file/exec, जोड़ें/संपादित करें/हटाएँ)।
    • आपको एक एजेंट स्कोप के लिए openclaw.json और auth-profiles.json में समर्थित secret-धारक फ़ील्ड चुनने देता है।
    • लक्ष्य चयनकर्ता में सीधे नया auth-profiles.json मैपिंग बना सकता है।
    • SecretRef विवरण (source, provider, id) कैप्चर करता है।
    • प्रीफ़्लाइट समाधान चलाता है और तुरंत लागू कर सकता है।

    Exec टिप्पणी: जब तक --allow-exec सेट न हो, प्रीफ़्लाइट exec SecretRef जाँच छोड़ देता है। यदि आप सीधे configure --apply से लागू करते हैं और योजना में exec संदर्भ/प्रदाता शामिल हैं, तो लागू करने के चरण के लिए भी --allow-exec सेट रखें।

    उपयोगी मोड:

    • openclaw secrets configure --providers-only
    • openclaw secrets configure --skip-provider-setup
    • openclaw secrets configure --agent <id>

    configure लागू करने के डिफ़ॉल्ट:

    • लक्षित प्रदाताओं के लिए auth-profiles.json से मेल खाते स्थिर क्रेडेंशियल हटाएँ।
    • auth.json से लीगेसी स्थिर api_key प्रविष्टियाँ हटाएँ।
    • प्रभावी स्थिति और सक्रिय-कॉन्फ़िगरेशन .env फ़ाइलों से मेल खाने वाली ज्ञात secret पंक्तियाँ हटाएँ (जब दोनों पथ मेल खाते हों, तब डुप्लिकेट हटाकर)।
    secrets apply

    सहेजी गई योजना लागू करें:

    bash
    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

    Exec टिप्पणी: जब तक --allow-exec सेट न हो, ड्राई-रन exec जाँच छोड़ देता है; लेखन मोड exec SecretRefs/प्रदाताओं वाली योजनाओं को तब तक अस्वीकार करता है, जब तक --allow-exec सेट न हो।

    सख्त लक्ष्य/पथ अनुबंध विवरण और सटीक अस्वीकृति नियमों के लिए, Secrets Apply योजना अनुबंध देखें।

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

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

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

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

    स्थिर क्रेडेंशियल के लिए रनटाइम अब प्लेनटेक्स्ट लीगेसी प्रमाणीकरण संग्रहण पर निर्भर नहीं है।

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

    वेब UI टिप्पणी

    कुछ SecretInput यूनियनों को फ़ॉर्म मोड की तुलना में रॉ एडिटर मोड में कॉन्फ़िगर करना अधिक आसान है।

    संबंधित

    Was this useful?
    On this page

    On this page