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

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

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

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

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

import { spawn } from "node:child_process";import { dirname, resolve } from "node:path";import { fileURLToPath } from "node:url"; // होस्ट एप्लिकेशन द्वारा प्रबंधित वास्तविक 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 स्टार्टअप गार्ड को बायपास करता है। यह कॉन्फ़िगरेशन नहीं लिखता या अमान्य फ़ाइल की मरम्मत नहीं करता। जब एम्बेडिंग ऐप ऑनबोर्डिंग, कॉन्फ़िग 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 एकीकरण