OpenClaw को एम्बेड करना

एक एम्बेडिंग होस्ट को इंस्टॉल किए गए openclaw एक्ज़िक्यूटेबल की निगरानी करनी चाहिए, Gateway WebSocket प्रोटोकॉल को अपने नियंत्रण तल के रूप में उपयोग करना चाहिए, और चाइल्ड प्रोसेस को बदले जा सकने वाले रनटाइम के रूप में मानना चाहिए। इससे OpenClaw के निजी स्टेट लेआउट पर निर्भर हुए बिना प्रोसेस का स्वामित्व, तत्परता, विफलता से पुनर्प्राप्ति और अपग्रेड स्पष्ट बने रहते हैं।

क्लाइंट प्रमाणीकरण और पुनः कनेक्शन की स्थिति के लिए, Gateway क्लाइंट बनाना पढ़ें।

एम्बेडिंग प्रीसेट के साथ चाइल्ड शुरू करें

वास्तविक node_modules इंस्टॉलेशन का उपयोग करें और पैकेज एक्ज़िक्यूटेबल को स्पॉन करें। डिस्कवरी, रीस्टार्ट और चैनल जीवनचक्र का स्वामित्व रखने वाले होस्ट के लिए एक उपयोगी आधारभूत विन्यास यह है:

   // होस्ट एप्लिकेशन द्वारा प्रबंधित वास्तविक Node रनटाइम का निरपेक्ष पथ दें।declare const hostNodeExecutable: string; const packageEntry = fileURLToPath(import.meta.resolve("openclaw"));const openclawEntry = resolve(dirname(packageEntry), "..", "openclaw.mjs");const gateway = spawn(hostNodeExecutable, [openclawEntry, "gateway", "--allow-unconfigured"], {  env: {    ...process.env,    OPENCLAW_DISABLE_BONJOUR: "1",    OPENCLAW_EXEC_SHELL_SNAPSHOT: "0",    OPENCLAW_NO_RESPAWN: "1",    OPENCLAW_SKIP_CHANNELS: "1",  },  stdio: ["ignore", "inherit", "inherit"],});

दिखाए गए तरीके से इंस्टॉल किए गए पैकेज के माध्यम से OpenClaw को रिज़ॉल्व करें; यह न मानें कि प्रोजेक्ट-स्थानीय openclaw बाइनरी होस्ट प्रोसेस के PATH में उपलब्ध है। उदाहरण आउटपुट को इनहेरिट करता है ताकि पूर्ण stdout या stderr पाइप के कारण चाइल्ड अवरुद्ध न हो सके। यदि होस्ट इसके बजाय उन स्ट्रीम को कैप्चर करता है, तो स्पॉन करने के तुरंत बाद कंज़्यूमर संलग्न करें।

--allow-unconfigured केवल gateway.mode=local स्टार्टअप गार्ड को बायपास करता है। यह कॉन्फ़िगरेशन नहीं लिखता या अमान्य फ़ाइल की मरम्मत नहीं करता। जब एम्बेडिंग ऐप ऑनबोर्डिंग, config CLI या Gateway RPC के माध्यम से सामान्य स्थानीय कॉन्फ़िगरेशन का प्रावधान करता हो, तो इसे छोड़ दें।

Electron शेल स्नैपशॉट चेतावनी

शेल स्नैपशॉट कैप्चर लॉगिन शेल से process.execPath -e <script> चलाता है। सामान्य Node प्रोसेस में, process.execPath Node एक्ज़िक्यूटेबल होता है। Electron के अंतर्गत, यह Electron बाइनरी होती है, जो इनवोकेशन को एप्लिकेशन लॉन्च के रूप में समझ सकती है और "Unable to find Electron app" पॉपअप दिखा सकती है। OPENCLAW_EXEC_SHELL_SNAPSHOT=0 को केवल रेंडरर प्रोसेस में नहीं, बल्कि Gateway चाइल्ड के एनवायरनमेंट में सेट करें। इसी कारण, hostNodeExecutable को Electron के process.execPath के बजाय वास्तविक Node रनटाइम की ओर इंगित करना चाहिए।

एग्ज़िट कोड के अनुसार अमान्य कॉन्फ़िगरेशन संभालें

Gateway स्टार्टअप अमान्य कॉन्फ़िगरेशन सहित कॉन्फ़िगरेशन-श्रेणी की स्टार्टअप विफलताओं के लिए एग्ज़िट कोड 78 (EX_CONFIG) का उपयोग करता है। मानव-पठनीय stderr को स्क्रैप करने के बजाय एग्ज़िट कोड के अनुसार शाखा बनाएँ:

1. Gateway चाइल्ड के समान कॉन्फ़िगरेशन और स्टेट एनवायरनमेंट के साथ openclaw doctor --fix --yes --non-interactive चलाएँ।
2. doctor के सफलतापूर्वक समाप्त होने के बाद Gateway स्टार्टअप का एक बार पुनः प्रयास करें।
3. यदि चाइल्ड फिर से 78 के साथ समाप्त होता है, तो मरम्मत लूप रोकें और उपयोगकर्ता को कॉन्फ़िगरेशन विफलता दिखाएँ।

डायग्नोस्टिक्स के लिए stderr रखें, लेकिन उसके शब्दों के आधार पर जीवनचक्र संबंधी निर्णय न लें।

सफल स्टार्टअप के बाद, लाइव कॉन्फ़िगरेशन में किया गया अमान्य संपादन कम विनाशकारी होता है। कॉन्फ़िगरेशन वॉचर लॉग करता है कि रीलोड छोड़ दिया गया था और अंतिम स्वीकृत इन-मेमोरी कॉन्फ़िगरेशन के साथ सेवा देना जारी रखता है। फ़ाइल की मरम्मत करें, फिर वॉचर को अगला मान्य स्नैपशॉट स्वीकार करने दें।

प्रोटोकॉल की तत्परता की प्रतीक्षा करें

लॉग सबस्ट्रिंग के बजाय WebSocket सिग्नल का उपयोग करें:

1. Gateway WebSocket खोलें।
2. connect.challenge इवेंट की प्रतीक्षा करें। यह प्रमाणित करता है कि लिसनर ने WebSocket स्वीकार कर लिया है और चैलेंज हैंडशेक शुरू हो सकता है।
3. चैलेंज-बाउंड डिवाइस हस्ताक्षर के साथ connect भेजें।
4. प्रमाणीकृत RPC के लिए hello-ok को एप्लिकेशन की तत्परता मानें।

चैलेंज जानबूझकर पूर्ण इनिशियलाइज़ेशन से पहले होता है। यदि स्टार्टअप साइडकार अभी भी लंबित हैं, तो connect, details.reason: "startup-sidecars", एक सीमित retryAfterMs के साथ पुनः प्रयास योग्य UNAVAILABLE त्रुटि लौटाता है और फिर कोड 1013 तथा कारण gateway starting के साथ बंद हो जाता है। @openclaw/gateway-protocol/startup-unavailable से resolveGatewayStartupRetryAfterMs या संदर्भ क्लाइंट की अंतर्निहित नीति का उपयोग करें, फिर पुनः कनेक्ट करें।

रीस्टार्ट और शटडाउन की व्याख्या करें

व्यवस्थित रूप से बंद होने से पहले, Gateway reason और restartExpectedMs के साथ shutdown इवेंट प्रसारित करता है। गैर-नल restartExpectedMs का अर्थ है कि इन-प्रोसेस या पर्यवेक्षित रीस्टार्ट अपेक्षित है; null का अर्थ अंतिम शटडाउन है।

इसके बाद का WebSocket क्लोज़ कोड दोनों मामलों में 1012 होता है। सामान्य क्लाइंट क्लोज़ कारण भी दोनों मामलों में service restart होता है, इसलिए न तो क्लोज़ कोड और न ही कारण रीस्टार्ट को शटडाउन से अलग करता है। पूर्ववर्ती shutdown पेलोड आने पर उसे सुरक्षित रखें और उसे होस्ट के अपने स्टॉप आशय तथा चाइल्ड एग्ज़िट स्थिति के साथ मिलाएँ। यदि इवेंट के बिना कनेक्शन समाप्त हो जाता है, तो सामान्य सीमित पुनः कनेक्शन और चाइल्ड-पर्यवेक्षण नीति का उपयोग करें।

स्टेट फ़ाइलों के बजाय RPC का उपयोग करें

Gateway को OpenClaw स्टेट का एकमात्र स्वामी बनाए रखें। सामान्य एम्बेडिंग परिचालनों के लिए पहले से RPC विधियाँ उपलब्ध हैं:

config.get स्नैपशॉट लौटाने से पहले संवेदनशील मानों और SecretRef पहचानकर्ताओं को संपादित करता है। लिखने वाली विधियाँ भी संपादित कॉन्फ़िगरेशन लौटाती हैं। क्लाइंट को संपादन सेंटिनल को अपारदर्शी मानना चाहिए और दस्तावेजीकृत कॉन्फ़िगरेशन लेखन अनुबंध का उपयोग करना चाहिए; उसे कभी भी Gateway से प्लेनटेक्स्ट सीक्रेट लौटाने की अपेक्षा नहीं करनी चाहिए।

ऐप सुविधाएँ लागू करने के लिए ~/.openclaw के अंतर्गत फ़ाइलों, SQLite तालिकाओं, ट्रांसक्रिप्ट फ़ाइलों या कैश डायरेक्टरियों को न पढ़ें और न बदलें। वे लेआउट निजी रनटाइम कार्यान्वयन विवरण हैं और प्रोटोकॉल संगतता के बिना स्थानांतरित या परिवर्तित हो सकते हैं।

इंस्टॉल करें; समतल न करें

रूट openclaw पैकेज एकल-फ़ाइल वेंडरिंग लक्ष्य नहीं है। dist/extensions के अंतर्गत बंडल की गई रनटाइम फ़ाइलें openclaw/plugin-sdk/* जैसे बेयर सेल्फ़-इंपोर्ट बनाए रखती हैं, जबकि npm पैकेज जानबूझकर प्रति-एक्सटेंशन node_modules ट्री को शामिल नहीं करता।

OpenClaw को npm, pnpm या किसी अन्य सामान्य Node पैकेज इंस्टॉलेशन के माध्यम से इंस्टॉल करें ताकि Node पैकेज एक्सपोर्ट और रूट डिपेंडेंसी ट्री को रिज़ॉल्व कर सके। इंस्टॉल किए गए openclaw एक्ज़िक्यूटेबल को स्पॉन करें। केवल dist की प्रतिलिपि न बनाएँ, पैकेज को ऐप बंडल में समतल न करें और चुनी गई एक्सटेंशन फ़ाइलों की वेंडरिंग न करें।

संबंधित

• Gateway क्लाइंट बनाना
• Gateway प्रोटोकॉल
• Gateway CLI
• बाहरी ऐप्स के लिए Gateway एकीकरण