कोड मोड

कोड मोड एक प्रायोगिक, ऑप्ट-इन OpenClaw एजेंट-रनटाइम सुविधा है। इसे सक्षम करने पर, मॉडल को अब प्रत्येक सक्षम टूल स्कीमा नहीं दिखता; इसके बजाय, उसे exec, wait, और ऐसा प्रत्येक केवल-प्रत्यक्ष टूल दिखता है जिसका संरचित परिणाम केवल-JSON गेस्ट ब्रिज को पार नहीं कर सकता। मॉडल एक छोटा JavaScript या TypeScript प्रोग्राम लिखता है जो छिपी हुई टूल कैटलॉग को खोजता है, उसका वर्णन करता है और उसे कॉल करता है।

यह पृष्ठ OpenClaw कोड मोड का दस्तावेज़ीकरण करता है, Codex Code Mode का नहीं। दोनों सुविधाओं का नाम और नियंत्रण-टूल नाम (exec, wait) समान हैं, लेकिन वे अलग-अलग कार्यान्वयन हैं:

• Codex Code Mode, Codex कोडिंग हार्नेस के भीतर चलता है। इसका exec टूल एक मुक्त-रूप व्याकरण टूल है: मॉडल कच्चा JavaScript स्रोत लिखता है (वैकल्पिक रूप से निष्पादन विकल्पों के लिए // @exec: {...} प्रैग्मा पंक्ति से आरंभ), जिसे Codex के इन-प्रोसेस V8 Code Mode रनटाइम में निष्पादित किया जाता है।
• OpenClaw कोड मोड सामान्य OpenClaw एजेंट रनटाइम में चलता है और tools.codeMode.enabled: true कॉन्फ़िगर न होने तक अक्षम रहता है। इसका exec टूल JSON { code, language } पेलोड लेता है, जिसे QuickJS-WASI वर्कर में निष्पादित किया जाता है।

दोनों JavaScript निष्पादन सतहें हैं, शेल-कमांड सतहें नहीं। इन्हें स्वतंत्र, अलग-अलग ढंग से कार्यान्वित सुविधाओं के रूप में मानें, जो संयोग से समान नाम वाले exec/wait टूल उजागर करती हैं।

यह क्या करता है

• मॉडल को दिखाई देने वाली टूल सूची exec, wait, और प्रत्येक केवल-प्रत्यक्ष टूल बन जाती है, जैसे computer या नेटिव-विज़न image लोडर, जिसका इमेज परिणाम गेस्ट ब्रिज से सुरक्षित नहीं गुजर सकता।
• exec मॉडल द्वारा जनरेट किए गए JavaScript या TypeScript का एक पृथक QuickJS-WASI वर्कर थ्रेड में मूल्यांकन करता है।
• कैटलॉग के लिए योग्य प्रत्येक सक्षम टूल (OpenClaw कोर, Plugin, MCP, क्लाइंट) को स्वतंत्र मॉडल टूल के रूप में छिपाया जाता है और गेस्ट प्रोग्राम के भीतर ALL_TOOLS और tools के माध्यम से उजागर किया जाता है।
• exec विवरण में सटीक OpenClaw/Plugin कैटलॉग आईडी की सीमित त्वरित अनुक्रमणिका, संक्षिप्त इनपुट संकेत और, जब कोई विश्वसनीय टूल आउटपुट स्कीमा प्रदान करता है, तो संक्षिप्त घोषित आउटपुट संकेत होते हैं। इसमें विवरण, पूर्ण स्कीमा, MCP प्रविष्टियाँ और सीमा से अधिक प्रविष्टियाँ शामिल नहीं होतीं; गेस्ट-साइड कैटलॉग लुकअप फ़ॉलबैक बना रहता है।
• गेस्ट कोड छिपी हुई कैटलॉग खोजता है, किसी टूल के स्कीमा का वर्णन करता है और सामान्य एजेंट टर्न द्वारा उपयोग किए जाने वाले समान निष्पादन पथ से टूल कॉल करता है (नीति, अनुमोदन, हुक और टेलीमेट्री सभी अब भी लागू होते हैं)।
• MCP टूल MCP नेमस्पेस के अंतर्गत समूहीकृत होते हैं; कोड मोड में उन्हें कॉल करने का यही एकमात्र समर्थित तरीका है।
• जब नेस्टेड टूल कॉल अब भी लंबित हों, तो wait निलंबित कोड-मोड रन को फिर से शुरू करता है।

कोड मोड केवल मॉडल-संबंधी ऑर्केस्ट्रेशन सतह बदलता है। यह टूल, Plugin टूल, MCP टूल, प्रमाणीकरण, अनुमोदन नीति, चैनल व्यवहार या मॉडल चयन को प्रतिस्थापित नहीं करता।

इसका उपयोग क्यों करें

• छोटी प्रॉम्प्ट सतह: प्रदाताओं को दर्जनों या सैकड़ों पूर्ण टूल स्कीमा के बजाय दो नियंत्रण टूल, एक सीमित नेटिव-टूल अनुक्रमणिका और केवल कुछ आवश्यक प्रत्यक्ष टूल मिलते हैं।
• बेहतर ऑर्केस्ट्रेशन: मॉडल एक कोड सेल के भीतर लूप, जॉइन, छोटे रूपांतरण, सशर्त तर्क और समानांतर नेस्टेड टूल कॉल का उपयोग कर सकता है।
• कम मॉडल राउंड ट्रिप: घोषित आउटपुट अनुबंध मॉडल को एक ही exec में किसी टूल परिणाम को कॉल और रूपांतरित करने देता है; अज्ञात आउटपुट पहले कच्चे रूप में रहते हैं।
• प्रदाता-निरपेक्ष: प्रदाता-नेटिव कोड निष्पादन पर निर्भर हुए बिना OpenClaw, Plugin, MCP और क्लाइंट टूल के लिए काम करता है।
• सुरक्षित रूप से विफल: यदि कोड मोड सक्षम है लेकिन QuickJS-WASI रनटाइम उपलब्ध नहीं है, तो व्यापक प्रत्यक्ष टूल एक्सपोज़र पर चुपचाप फ़ॉलबैक करने के बजाय रन विफल हो जाता है।

यह बड़ी सक्षम टूल कैटलॉग वाले एजेंटों या ऐसे कार्यप्रवाहों के लिए सर्वाधिक उपयोगी है जहाँ मॉडल को उत्तर देने से पहले कई टूल खोजने, संयोजित करने और कॉल करने की आवश्यकता होती है।

छोटी कैटलॉग या ऐसे मॉडल के लिए प्रत्यक्ष टूल एक्सपोज़र बनाए रखें जो विश्वसनीय रूप से छोटे प्रोग्राम नहीं लिखता। जब आपको संक्षिप्त कैटलॉग चाहिए, लेकिन QuickJS-WASI गेस्ट के बजाय संरचित खोज/वर्णन/कॉल नियंत्रण पसंद हों, तो टूल खोज का उपयोग करें।

त्वरित आरंभ

कोड मोड सक्षम करें

{  tools: {    codeMode: {      enabled: true,    },  },}

संक्षिप्त रूप:

{  tools: {    codeMode: true,  },}

tools.codeMode हटाए जाने, false होने या enabled: true रहित ऑब्जेक्ट होने पर कोड मोड बंद रहता है।

यदि आप कॉन्फ़िगर किए गए MCP सर्वर वाले सैंडबॉक्स एजेंटों का उपयोग करते हैं, तो सैंडबॉक्स टूल नीति में बंडल किए गए MCP Plugin को भी अनुमति दें, उदाहरण के लिए tools.sandbox.tools.alsoAllow: ["bundle-mcp"]। देखें कॉन्फ़िगरेशन - टूल और कस्टम प्रदाता।

अधिक कड़ी सीमाओं के लिए स्पष्ट सीमाएँ निर्धारित करें:

{  tools: {    codeMode: {      enabled: true,      timeoutMs: 10000,      memoryLimitBytes: 67108864,      maxOutputBytes: 65536,      maxSnapshotBytes: 10485760,      maxPendingToolCalls: 16,      snapshotTtlSeconds: 900,      searchDefaultLimit: 8,      maxSearchLimit: 50,    },  },}

मॉडल क्या करता है

घोषित आउटपुट वाले किसी टूल के लिए, जैसे Array<{ id: string; paid: boolean; tons: number }>, एक गेस्ट प्रोग्राम उसे चुन, कॉल और रूपांतरित कर सकता है:

const [shipmentTool] = await tools.search("list shipments");const shipments = await tools.callValue(shipmentTool.id, {});return shipments.filter((shipment) => !shipment.paid && shipment.tons > 10);

जब कोई त्वरित-अनुक्रमणिका पंक्ति -> ? पर समाप्त होती है, तो आउटपुट आकार अज्ञात होता है। पहला exec, await tools.callValue(...) को अपरिवर्तित लौटाएगा। बाद का exec प्रेक्षित मान को रूपांतरित कर सकता है। इसमें एक अतिरिक्त मॉडल टर्न लगता है, लेकिन यह मॉडल को फ़ील्ड नामों का अनुमान लगाने से रोकता है।

सक्रिय सतह सत्यापित करें

डीबगिंग के दौरान मॉडल पेलोड के आकार की पुष्टि करने के लिए, Gateway को लक्षित लॉगिंग के साथ चलाएँ:

OPENCLAW_DEBUG_CODE_MODE=1 \OPENCLAW_DEBUG_MODEL_TRANSPORT=1 \OPENCLAW_DEBUG_MODEL_PAYLOAD=tools \openclaw gateway

कोड मोड सक्रिय होने पर, लॉग किए गए मॉडल-संबंधी टूल नाम exec और wait होने चाहिए। पूर्ण संशोधित प्रदाता पेलोड के लिए, छोटे डीबगिंग सत्र हेतु OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted जोड़ें।

एजेंट फ़ैन-आउट के लिए Swarm का उपयोग करें

Swarm Code Mode स्क्रिप्ट से समवर्ती उप-एजेंटों को ऑर्केस्ट्रेट करने के लिए agents.run(), phase(), और log() गेस्ट ग्लोबल जोड़ता है। tools.codeMode और tools.swarm दोनों सक्षम करें, फिर फ़ैन-आउट, निर्णय गेट और संरचित संग्रह के लिए सामान्य JavaScript नियंत्रण प्रवाह का उपयोग करें। Swarm एक अलग ऑप्ट-इन गेट है; केवल Code Mode सक्षम करने से agents.* API उजागर नहीं होता।

तकनीकी अवलोकन

इस पृष्ठ का शेष भाग रनटाइम अनुबंध और कार्यान्वयन विवरणों को समेटता है, जो रखरखावकर्ताओं, टूल एक्सपोज़र डीबग करने वाले Plugin लेखकों और उच्च-जोखिम डिप्लॉयमेंट सत्यापित करने वाले ऑपरेटरों के लिए है।

रनटाइम स्थिति

दायरा

कोड मोड तैयार रन के लिए मॉडल-संबंधी ऑर्केस्ट्रेशन आकार का स्वामी है। यह मॉडल चयन, चैनल व्यवहार, प्रमाणीकरण, टूल नीति या टूल कार्यान्वयन का स्वामी नहीं है।

दायरे में: मॉडल को दिखाई देने वाली नियंत्रण/प्रत्यक्ष टूल परिभाषाएँ, छिपी हुई टूल कैटलॉग निर्माण, JavaScript/TypeScript गेस्ट निष्पादन, QuickJS-WASI वर्कर रनटाइम, खोज/वर्णन/कॉल के लिए होस्ट कॉलबैक, निलंबित गेस्ट प्रोग्रामों के लिए पुनः आरंभ योग्य स्थिति, आउटपुट/टाइमआउट/मेमोरी/लंबित-कॉल/स्नैपशॉट सीमाएँ, और नेस्टेड टूल कॉल के लिए टेलीमेट्री/ट्रैजेक्टरी प्रोजेक्शन।

दायरे से बाहर: प्रदाता-नेटिव दूरस्थ कोड निष्पादन, शेल निष्पादन सिमेंटिक्स, मौजूदा टूल प्राधिकरण बदलना, उपयोगकर्ता द्वारा लिखी गई स्थायी स्क्रिप्ट, गेस्ट कोड में पैकेज मैनेजर/फ़ाइल/नेटवर्क/मॉड्यूल पहुँच और Codex Code Mode आंतरिक भागों का प्रत्यक्ष पुनः उपयोग।

दूरस्थ Python सैंडबॉक्स जैसे प्रदाता-स्वामित्व वाले टूल अलग टूल हैं। देखें कोड निष्पादन।

शब्दावली

• कोड मोड: OpenClaw रनटाइम मोड, जो कैटलॉग-संगत मॉडल टूल छिपाता है और exec, wait, तथा आवश्यक केवल-प्रत्यक्ष टूल उजागर करता है।
• गेस्ट रनटाइम: QuickJS-WASI JavaScript VM, जो मॉडल कोड का मूल्यांकन करता है।
• होस्ट ब्रिज: गेस्ट कोड से वापस OpenClaw तक की संकीर्ण JSON-संगत कॉलबैक सतह।
• कैटलॉग: सामान्य टूल नीति, Plugin, MCP और क्लाइंट-टूल रिज़ॉल्यूशन के बाद प्रभावी टूल की रन-दायरे वाली सूची।
• नेस्टेड टूल कॉल: होस्ट ब्रिज के माध्यम से गेस्ट कोड द्वारा की गई टूल कॉल।
• स्नैपशॉट: क्रमबद्ध QuickJS-WASI VM स्थिति, जिसे सहेजा जाता है ताकि wait निलंबित कोड-मोड रन जारी रख सके।

कॉन्फ़िगरेशन

tools.codeMode.enabled सक्रियण गेट है; अन्य फ़ील्ड सेट करने से सुविधा अपने आप सक्षम नहीं होती।

यदि कोड मोड सक्षम है लेकिन QuickJS-WASI लोड नहीं हो सकता, तो OpenClaw उस रन के लिए सुरक्षित रूप से विफल होता है; यह फ़ॉलबैक के रूप में सामान्य टूल चुपचाप उजागर नहीं करता।

सक्रियण

प्रभावी टूल नीति ज्ञात होने के बाद और अंतिम मॉडल अनुरोध संयोजित होने से पहले कोड मोड का मूल्यांकन किया जाता है:

1. एजेंट, मॉडल, प्रदाता, सैंडबॉक्स, चैनल, प्रेषक और रन नीति का निर्धारण करें।
2. योग्य plugin, MCP और क्लाइंट टूल जोड़ते हुए प्रभावी OpenClaw टूल सूची बनाएँ।
3. अनुमति/निषेध नीति लागू करें।
4. यदि tools.codeMode.enabled false है, तो सामान्य टूल एक्सपोज़र जारी रखें।
5. यदि सक्षम है और रन के लिए टूल सक्रिय हैं, तो आवश्यक केवल-प्रत्यक्ष टूल बनाए रखें और कोड-मोड कैटलॉग में प्रत्येक कैटलॉग-योग्य प्रभावी टूल पंजीकृत करें।
6. कैटलॉग किए गए टूल को मॉडल-दृश्य सूची से हटाएँ; बनाए रखे गए केवल-प्रत्यक्ष टूल के साथ exec और wait जोड़ें।

जिन रन में जानबूझकर कोई टूल नहीं होता (रॉ मॉडल कॉल, disableTools: true, या खाली tools.allow सूची), उनमें tools.codeMode.enabled: true कॉन्फ़िगर होने पर भी कोड-मोड सतह सक्रिय नहीं होती। किसी रन के लिए कोड मोड और OpenClaw टूल सर्च परस्पर अनन्य हैं; यदि कोड मोड सक्रिय होता है, तो टूल सर्च का Compaction नहीं होता।

कोड-मोड कैटलॉग रन-स्कोप वाला होता है और इसमें किसी अन्य एजेंट, सत्र, प्रेषक या रन के टूल लीक नहीं होने चाहिए।

मॉडल-दृश्य टूल

कोड मोड सक्रिय होने पर, मॉडल को exec, wait और कोई भी आवश्यक केवल-प्रत्यक्ष टूल दिखाई देता है। अन्य सभी सक्षम टूल मॉडल-सामना करने वाली टूल सूची से छिपाए जाते हैं और कोड-मोड कैटलॉग में पंजीकृत किए जाते हैं।

टूल समन्वयन, डेटा संयोजन, लूप, समानांतर नेस्टेड कॉल और संरचित रूपांतरणों के लिए exec का उपयोग करें। wait का उपयोग केवल तब करें जब exec फिर से शुरू किया जा सकने वाला waiting परिणाम लौटाता है।

exec

exec एक कोड-मोड सेल शुरू करता है और एक परिणाम लौटाता है। इनपुट कोड मॉडल द्वारा जनरेट किया जाता है और उसे दुर्भावनापूर्ण माना जाना चाहिए।

इनपुट:

type CodeModeExecInput = {  code?: string;  command?: string;  language?: "javascript" | "typescript";};

नियम:

• code या command में से एक गैर-रिक्त होना चाहिए।
• code दस्तावेज़ीकृत मॉडल-सामना करने वाला फ़ील्ड है।
• command को हुक नीतियों और विश्वसनीय पुनर्लेखनों के लिए exec-संगत उपनाम के रूप में स्वीकार किया जाता है (सामान्य OpenClaw शेल exec टूल भी command फ़ील्ड का उपयोग करता है); दोनों मौजूद होने पर मान समान होने चाहिए।
• language का डिफ़ॉल्ट "javascript" है; स्कीमा इसे सपाट स्ट्रिंग enum ("javascript" | "typescript") के रूप में प्रदर्शित करता है, oneOf/anyOf यूनियन के रूप में नहीं, क्योंकि कुछ प्रदाता उन आकृतियों को अस्वीकार करते हैं।
• यदि language, "typescript" है, तो OpenClaw मूल्यांकन से पहले ट्रांसपाइल करता है।
• exec, import, require, डायनेमिक इंपोर्ट और मॉड्यूल-लोडर पैटर्न अस्वीकार करता है।
• exec सामान्य शेल exec कार्यान्वयन को कभी पुनरावर्ती रूप से प्रदर्शित नहीं करता।
• बाहरी कोड-मोड exec हुक इवेंट में toolKind: "code_mode_exec" और toolInputKind: "javascript" | "typescript" (जब ज्ञात हों) होते हैं, ताकि नीतियाँ कोड-मोड सेल को समान टूल नाम साझा करने वाले शेल-शैली के exec कॉल से अलग कर सकें।

परिणाम:

type CodeModeResult = CodeModeCompletedResult | CodeModeWaitingResult | CodeModeFailedResult; type CodeModeCompletedResult = {  status: "completed";  value: unknown;  output?: CodeModeOutput[];  telemetry: CodeModeTelemetry;}; type CodeModeWaitingResult = {  status: "waiting";  runId: string;  reason: "pending_tools" | "yield";  pendingToolCalls?: CodeModePendingToolCall[];  output?: CodeModeOutput[];  telemetry: CodeModeTelemetry;}; type CodeModeFailedResult = {  status: "failed";  error: string;  code?: CodeModeErrorCode;  output?: CodeModeOutput[];  telemetry: CodeModeTelemetry;};

exec, waiting तब लौटाता है जब गेस्ट ऐसी पुनः आरंभ योग्य स्थिति के साथ निलंबित होता है जिसे अभी भी मॉडल-दृश्य निरंतरता की आवश्यकता होती है—एक स्पष्ट yield_control(...), या ऐसा ब्रिज टूल कॉल जो exec समय-सीमा के भीतर हल नहीं हुआ है। परिणाम में wait के लिए एक runId शामिल होता है। ब्रिज टूल कॉल—tools.search/describe/ call और नेमस्पेस कॉल, जिनमें MCP नेमस्पेस कॉल भी शामिल हैं—यदि समय-सीमा के भीतर हल हो जाते हैं, तो उसी exec/wait कॉल के अंदर स्वतः पूरे किए जाते हैं, ताकि कई टूल की प्रतीक्षा करने वाला संक्षिप्त कोड ब्लॉक प्रत्येक प्रतीक्षा के लिए अलग मॉडल टूल कॉल को बाध्य करने के बजाय एक मॉडल टर्न में पूर्ण हो जाए। रीस्टार्ट-सुरक्षित रन कभी स्वतः पूरे नहीं किए जाते; उनका लंबित कार्य अभी भी रीप्ले-सुरक्षित जाँचों से गुजरता है।

exec, completed केवल तब लौटाता है जब गेस्ट VM में कोई लंबित कार्य न हो और OpenClaw का आउटपुट अडैप्टर चलने के बाद अंतिम मान JSON-संगत हो।

wait

wait निलंबित कोड-मोड VM को जारी रखता है।

इनपुट:

type CodeModeWaitInput = {  runId: string;};

आउटपुट वही CodeModeResult यूनियन है जो exec द्वारा लौटाया जाता है।

wait इसलिए मौजूद है क्योंकि नेस्टेड OpenClaw टूल धीमे, इंटरैक्टिव, अनुमोदन द्वारा नियंत्रित हो सकते हैं या आंशिक अपडेट स्ट्रीम कर सकते हैं; बाहरी कार्य की प्रतीक्षा करते समय मॉडल को एक लंबा exec कॉल खुला रखने की आवश्यकता नहीं होनी चाहिए।

QuickJS-WASI स्नैपशॉट/रीस्टोर पुनः आरंभ करने की व्यवस्था है:

1. exec कोड का मूल्यांकन पूर्णता, विफलता या निलंबन तक करता है।
2. निलंबन पर, OpenClaw QuickJS VM का स्नैपशॉट लेता है और लंबित होस्ट कार्य रिकॉर्ड करता है।
3. लंबित कार्य पूरा होने पर, wait VM स्नैपशॉट को रीस्टोर करता है और स्थिर नामों द्वारा होस्ट कॉलबैक को फिर से पंजीकृत करता है।
4. OpenClaw नेस्टेड टूल परिणामों को रीस्टोर किए गए VM में पहुँचाता है और QuickJS के लंबित जॉब पूरे करता है।
5. wait, completed, failed या कोई अन्य waiting परिणाम लौटाता है।

स्नैपशॉट रनटाइम स्थिति हैं, उपयोगकर्ता आर्टिफ़ैक्ट नहीं: वे केवल इन-प्रोसेस मैप में रहते हैं (कोई डेटाबेस या डिस्क लेखन नहीं), आकार-सीमित होते हैं, उनकी समय-सीमा समाप्त होती है और वे उन्हें बनाने वाले रन और सत्र तक सीमित होते हैं।

wait विफल होता है (failed परिणाम के रूप में) जब:

• runId अज्ञात हो या उसके स्नैपशॉट की समय-सीमा पहले ही समाप्त हो गई हो।
• कॉलर निलंबित रन के समान रन/सत्र स्कोप में न हो।
• उस runId के लिए एक wait पहले से प्रगति पर हो।
• QuickJS-WASI रीस्टोर विफल हो।
• पुनः आरंभ करने से maxOutputBytes या maxSnapshotBytes पार हो जाएगा।

गेस्ट रनटाइम API

declare const ALL_TOOLS: ToolCatalogEntry[];declare const tools: ToolCatalog;declare const MCP: Record<string, unknown>;declare const namespaces: Record<string, unknown>; declare function text(value: unknown): void;declare function json(value: unknown): void;declare function yield_control(reason?: string): Promise<void>;

ALL_TOOLS रन-स्कोप वाले कैटलॉग के लिए संक्षिप्त मेटाडेटा है; इसमें डिफ़ॉल्ट रूप से पूर्ण स्कीमा नहीं होते। मॉडल-दृश्य exec विवरण में सटीक OpenClaw/plugin आईडी का एक सीमित, नियतात्मक उपसमुच्चय, संक्षिप्त इनपुट संकेत और विश्वसनीय घोषित आउटपुट संकेत भी शामिल होते हैं। विवरण स्थगित रहते हैं, ताकि विरोधात्मक कैटलॉग गद्य मॉडल को निर्देशित न कर सके। जब उस इंडेक्स में कोई टूल शामिल न हो, तो गेस्ट प्रोग्राम के भीतर ALL_TOOLS पढ़ें या tools.search(...) कॉल करें।

प्रत्येक त्वरित-इंडेक्स पंक्ति का तीर tools.callValue(...) मान का वर्णन करता है। -> Array<{ id: string }> एक घोषित आउटपुट संकेत है; -> ? का अर्थ आउटपुट अज्ञात है। अज्ञात आउटपुट में पहले रॉ मान रखें: मान को अपरिवर्तित लौटाएँ, उसका निरीक्षण करें, फिर फ़ील्ड नामों का अनुमान लगाने के बजाय बाद के exec में उसे फ़िल्टर या मैप करें। यह तब भी लागू होता है जब घोषित-आउटपुट रीड अंतिम -> ? कॉल को इनपुट देता है: उस कॉल के रॉ मान को अनुरोधित उत्तर आकृति में लपेटे बिना लौटाएँ।

type ToolCatalogEntry = {  id: string;  name: string;  label?: string;  description: string;  source: "openclaw" | "mcp" | "client";  sourceName?: string;  input: string;  output?: string;};

input सामान्य स्थिति के लिए सीमित TypeScript-शैली का सिग्नेचर है। जब सटीक पूर्ण स्कीमा की अभी भी आवश्यकता हो, तो tools.describe(...) का उपयोग करें। दूरस्थ MCP और क्लाइंट प्रविष्टियाँ input: "unknown" का उपयोग करती हैं, ताकि उनके अविश्वसनीय स्कीमा describe तक स्थगित रहें। output केवल विश्वसनीय OpenClaw कोर या plugin outputSchema से प्राप्त पूर्ण संक्षिप्त संकेत के लिए मौजूद होता है। MCP और क्लाइंट आउटपुट-स्कीमा दावों को इस विश्वसनीय कैटलॉग संकेत में उन्नत नहीं किया जाता।

Plugin टूल source: "openclaw" का उपयोग करते हैं, जिसमें sourceName को स्वामी plugin आईडी पर सेट किया जाता है; कोई अलग "plugin" स्रोत मान नहीं है। source: "mcp" का उपयोग केवल sourceName/mcp मेटाडेटा में MCP प्रविष्टियों के लिए किया जाता है (और इसे ALL_TOOLS/tools.* से फ़िल्टर कर दिया जाता है, नीचे देखें)।

पूर्ण स्कीमा केवल माँग पर लोड किया जाता है:

type ToolCatalogEntryWithSchema = ToolCatalogEntry & {  parameters: unknown;  outputSchema?: unknown;};

कैटलॉग सहायक:

type ToolCatalog = {  search(query: string, options?: { limit?: number }): Promise<ToolCatalogEntry[]>;  describe(id: string): Promise<ToolCatalogEntryWithSchema>;  callValue(id: string, input?: unknown): Promise<unknown>;  call(id: string, input?: unknown): Promise<unknown>;  [safeToolName: string]: unknown;};

सुविधाजनक टूल फ़ंक्शन केवल असंदिग्ध सुरक्षित नामों के लिए इंस्टॉल किए जाते हैं:

const files = await tools.search("स्थानीय फ़ाइल पढ़ें");const fileRead = await tools.describe(files[0].id);const content = await tools.callValue(fileRead.id, { path: "README.md" }); // यदि छिपे हुए कैटलॉग में एक असंदिग्ध `web_search` प्रविष्टि है:const hits = await tools.web_search({ query: "OpenClaw कोड मोड" });

tools.callValue(...) किसी सामान्य टूल का JSON details मान सीधे लौटाता है। tools.call(...) उन कॉलर के लिए रॉ { tool, result } एनवेलप सुरक्षित रखता है जिन्हें कंटेंट ब्लॉक या अन्य परिणाम मेटाडेटा की आवश्यकता होती है।

घोषित आउटपुट अनुबंध

OpenClaw टूल AgentToolResult.details में रखे गए संरचित मान के लिए outputSchema घोषित कर सकते हैं। यह कोड मोड और टूल सर्च के लिए उपयोगी है; यह प्रदाता-नेटिव टूल प्रतिक्रिया स्कीमा नहीं है और प्रत्यक्ष टूल एक्सपोज़र को नहीं बदलता।

defineToolPlugin से बनाए गए टूल के लिए, parameters के साथ स्कीमा घोषित करें:

import { Type } from "typebox";import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin"; const Shipment = Type.Object(  {    id: Type.String(),    paid: Type.Boolean(),    tons: Type.Number(),  },  { additionalProperties: false },); export default defineToolPlugin({  id: "shipping",  name: "शिपिंग",  description: "शिपमेंट टूल।",  tools: (tool) => [    tool({      name: "shipping_list",      description: "शिपमेंट सूचीबद्ध करें।",      parameters: Type.Object({}),      outputSchema: Type.Array(Shipment),      execute: async () => loadShipments(),    }),  ],});

api.registerTool(...) या फ़ैक्टरी टूल के लिए, लौटाए गए AnyAgentTool ऑब्जेक्ट पर समान outputSchema प्रॉपर्टी रखें।

वर्तमान अंतर्निहित अनुबंधों में agents_list, apply_patch, conversations_list, conversations_send, conversations_turn, edit, openclaw, read, screen, sessions_history, sessions_list, sessions_search, sessions_send, session_status, spawn_task, terminal, web_fetch, और web_search शामिल हैं। सटीक पासथ्रू केवल मॉडल के लिए अनुबंध की प्रतिलिपि बनाने के बजाय अपने स्वामी प्रोटोकॉल स्कीमा का पुनः उपयोग कर सकते हैं। उदाहरण के लिए, वार्तालाप टूल conversations.list, conversations.send, और conversations.turn द्वारा उपयोग किए जाने वाले समान Gateway परिणाम स्कीमा प्रदर्शित करते हैं; web_fetch एक टूल-स्थानीय स्कीमा का स्वामी है, जिसका संकेत स्थिर मेटाडेटा, टेक्स्ट, कैश स्थिति और नेस्टेड स्पिल मेटाडेटा प्रदर्शित करता है; web_search अपने सटीक सामान्यीकृत परिणाम/उत्तर/त्रुटि/रॉ यूनियन को एक पूर्ण त्वरित-सूचकांक संकेत के रूप में घोषित करता है। फ़ाइल-सिस्टम अनुबंध संरचित पठन टेक्स्ट, छवि, ट्रंकेशन और वैकल्पिक रूप से न-मिलने वाले परिणाम; स्पष्ट संपादन परिवर्तन स्थिति के साथ डिफ़/पैच डेटा; और अप्लाई-पैच पथ सारांश लौटाते हैं। जब त्वरित सूचकांक फ़ील्ड घोषित करता है, तो एक सेल अलग निरीक्षण चरण के बिना खोज और डिलीवरी को संयोजित कर सकता है:

const listed = await tools.conversations_list({ query: "बिल्ड बॉट" });const target = listed.conversations.find((item) => item.label === "बिल्ड बॉट");if (!target) throw new Error("वार्तालाप नहीं मिला");return await tools.conversations_send({  conversationRef: target.conversationRef,  message: "बिल्ड पूरा हुआ।",});

नेस्टेड कॉल अभी भी सामान्य टूल नीति, हुक और अनुमोदनों का उपयोग करती हैं। यदि कोई पूर्ण अनुबंध सटीक है, लेकिन सीमाबद्ध त्वरित सूचकांक के लिए बहुत बड़ा है, तो वह tools.describe(...) के माध्यम से उपलब्ध रहता है और तीर -> ? ही रहता है।

अनुबंध के नियम सख्त हैं:

• रेंडर किए गए content ब्लॉक या प्रदाता एनवेलप के बजाय सटीक JSON-संगत details मान का वर्णन करें।
• प्रत्येक ऐसी सफलता या त्रुटि वैरिएंट शामिल करें जो थ्रो नहीं करती। जब टूल का कोई स्थिर संरचित परिणाम न हो, तब outputSchema छोड़ दें।
• पूर्ण त्वरित-सूचकांक संकेत के लिए ऑब्जेक्ट परतों को { additionalProperties: false } से बंद करें। खुले, अत्यधिक बड़े या अन्यथा आंशिक स्कीमा tools.describe(...) के माध्यम से उपलब्ध रहते हैं, लेकिन एक चरण में फ़ील्ड उपयोग सक्षम नहीं करते।
• OpenClaw टूल चलाने से पहले स्कीमा को कंपाइल करता है, फिर सामान्य टूल हुक के बाद और कैटलॉग कॉल लौटने से पहले अंतिम details को सत्यापित करता है। अमान्य स्कीमा टूल को चला नहीं सकता; बेमेल होने पर मान प्रिंट किए बिना विफलता होती है।
• संक्षिप्त संकेत निर्धारक और सीमाबद्ध होते हैं। जब संक्षिप्त संकेत अपर्याप्त हो, तब tools.describe(...) पूर्ण विश्वसनीय स्कीमा प्रदर्शित करता है।
• इंस्टॉल किया गया plugin कोड पहले से ही विश्वसनीय स्थानीय कोड होता है। दूरस्थ MCP और क्लाइंट मेटाडेटा अविश्वसनीय रहते हैं और इन त्वरित-सूचकांक संकेतों को चुन नहीं सकते।

Plugin लेखन के विवरण के लिए टूल plugin देखें।

MCP कैटलॉग प्रविष्टियों को कोड मोड में tools.callValue(...), tools.call(...), या सुविधा फ़ंक्शनों के माध्यम से कॉल नहीं किया जा सकता; वे केवल जनरेट किए गए MCP नेमस्पेस के माध्यम से प्रदर्शित होती हैं। TypeScript-शैली की घोषणा फ़ाइलें केवल-पठन API वर्चुअल फ़ाइल सतह के माध्यम से उपलब्ध होती हैं, ताकि एजेंट प्रॉम्प्ट में MCP स्कीमा जोड़े बिना MCP सिग्नेचर का निरीक्षण कर सकें:

const files = await API.list("mcp");const githubApi = await API.read("mcp/github.d.ts"); const issue = await MCP.github.createIssue({  owner: "openclaw",  repo: "openclaw",  title: "Gateway लॉग की जाँच करें",}); const snapshot = await MCP.chromeDevtools.takeSnapshot({ output: "markdown" });const resource = await MCP.docs.resources.read({ uri: "memo://one" });const prompt = await MCP.docs.prompts.get({  name: "brief",  arguments: { topic: "release" },});

API.read("mcp/<server>.d.ts") MCP टूल मेटाडेटा से अनुमानित संक्षिप्त घोषणाएँ लौटाता है:

type McpToolResult = {  content?: unknown[];  structuredContent?: unknown;  isError?: boolean;  [key: string]: unknown;}; declare namespace MCP.github {  /** यह TypeScript-शैली का API हेडर लौटाएँ। */  function $api(toolName?: string, options?: { schema?: boolean }): Promise<McpApiHeader>;   /**   * एक GitHub इश्यू बनाएँ।   * @param owner रिपॉज़िटरी स्वामी   * @param repo रिपॉज़िटरी नाम   * @param title इश्यू शीर्षक   */  function createIssue(input: {    owner: string;    repo: string;    title: string;    body?: string;  }): Promise<McpToolResult>;}

घोषणा फ़ाइलें वर्चुअल होती हैं, उन्हें वर्कस्पेस या स्थिति डायरेक्टरी में नहीं लिखा जाता। प्रत्येक कोड-मोड exec कॉल के लिए, OpenClaw रन-स्कोप वाला टूल कैटलॉग बनाता है, दृश्यमान MCP प्रविष्टियाँ रखता है, mcp/index.d.ts और प्रत्येक दृश्यमान सर्वर के लिए एक mcp/<server>.d.ts रेंडर करता है, और उस छोटी केवल-पठन तालिका को QuickJS वर्कर में इंजेक्ट करता है। अतिथि कोड केवल API ऑब्जेक्ट देखता है: API.list(prefix?) फ़ाइल मेटाडेटा लौटाता है और API.read(path) चयनित घोषणा सामग्री लौटाता है। अज्ञात पथ और ./.. खंड अस्वीकार कर दिए जाते हैं।

इससे बड़े MCP स्कीमा मॉडल प्रॉम्प्ट से बाहर रहते हैं: एजेंट को exec टूल विवरण से पता चलता है कि वर्चुअल API मौजूद है, वह केवल आवश्यक घोषणा फ़ाइल पढ़ता है, फिर एक ऑब्जेक्ट आर्गुमेंट के साथ MCP.<server>.<tool>() को कॉल करता है। प्रोग्राम के भीतर एकल-टूल स्कीमा प्रतिक्रिया के लिए MCP.<server>.$api() इनलाइन फ़ॉलबैक के रूप में उपलब्ध रहता है।

अतिथि रनटाइम कभी भी होस्ट ऑब्जेक्ट सीधे नहीं देखता। इनपुट और आउटपुट स्पष्ट आकार सीमाओं वाले JSON-संगत मानों के रूप में ब्रिज पार करते हैं।

आंतरिक नेमस्पेस

आंतरिक नेमस्पेस अधिक मॉडल-दृश्यमान टूल जोड़े बिना कोड मोड को एक संक्षिप्त डोमेन API प्रदान करते हैं। लोडर-स्वामित्व वाला कोई एकीकरण Issues या Calendar जैसा नेमस्पेस पंजीकृत करता है; फिर अतिथि कोड QuickJS प्रोग्राम के भीतर उस नेमस्पेस को कॉल करता है, जबकि मॉडल को अब भी संक्षिप्त नियंत्रण/प्रत्यक्ष सतह ही दिखाई देती है।

फ़िलहाल नेमस्पेस आंतरिक हैं। कोई सार्वजनिक plugin SDK नेमस्पेस API नहीं है: बाहरी plugin नेमस्पेस को लोडर-स्वामित्व वाले अनुबंध की आवश्यकता होती है, ताकि plugin पहचान, इंस्टॉल किए गए मैनिफ़ेस्ट, प्रमाणीकरण स्थिति और कैश किए गए कैटलॉग डिस्क्रिप्टर उन plugin टूल से अलग न हो जाएँ जो नेमस्पेस का आधार हैं। कोर कोड मोड केवल सैंडबॉक्स, सीरियलाइज़ेशन, कैटलॉग गेटिंग और ब्रिज डिस्पैच का स्वामी है।

अतिथि कोड प्रत्यक्ष ग्लोबल या namespaces मैप में से किसी का भी उपयोग कर सकता है:

const open = await Issues.list({ state: "open" });const alsoOpen = await namespaces.Issues.list({ state: "open" });return { count: open.length, alsoCount: alsoOpen.length };

रजिस्ट्री जीवनचक्र

नेमस्पेस रजिस्ट्री प्रक्रिया-स्थानीय है और नेमस्पेस आईडी द्वारा कुंजीबद्ध है:

1. एक विश्वसनीय लोडर registerCodeModeNamespaceForPlugin(pluginId, registration) को कॉल करता है।
2. कोड मोड रन के लिए छिपा हुआ ToolSearchRuntime बनाता है और उसका रन-स्कोप वाला कैटलॉग पढ़ता है।
3. createCodeModeNamespaceRuntime(ctx, catalog) केवल उन पंजीकरणों को रखता है जिनके सभी requiredToolNames दृश्यमान हैं और उसी pluginId के स्वामित्व में हैं।
4. प्रत्येक दृश्यमान नेमस्पेस वर्तमान रन के लिए createScope(ctx) को कॉल करता है, और agentId, sessionKey, sessionId, runId, कॉन्फ़िगरेशन और निरस्तीकरण स्थिति जैसे रन संदर्भ प्राप्त करता है।
5. स्कोप डेटा को एक साधारण डिस्क्रिप्टर में सीरियलाइज़ किया जाता है और प्रत्यक्ष ग्लोबल तथा namespaces.<globalName> के रूप में QuickJS में इंजेक्ट किया जाता है।
6. अतिथि कॉल वर्कर ब्रिज के माध्यम से निलंबित होती हैं, होस्ट पर नेमस्पेस पथ रिज़ॉल्व करती हैं, कॉल को घोषित plugin-स्वामित्व वाले कैटलॉग टूल से मैप करती हैं और उस टूल को ToolSearchRuntime.callExactId के माध्यम से निष्पादित करती हैं।
7. तैयार नेमस्पेस ब्रिज कॉल सक्रिय exec/wait कॉल के भीतर स्वतः ड्रेन हो जाती हैं; यदि टाइमआउट पर नेमस्पेस कार्य अब भी लंबित हो या अतिथि स्पष्ट रूप से यील्ड करे, तो wait बाद में उसी नेमस्पेस रनटाइम को फिर से शुरू करता है।
8. Plugin रोलबैक या अनइंस्टॉल clearCodeModeNamespacesForPlugin(pluginId) को कॉल करता है, ताकि विफल plugin लोड के बाद पुराने ग्लोबल बने न रहें।

नेमस्पेस कॉल कैटलॉग टूल कॉल होती हैं: वे tools.call(...) जैसी ही नीति हुक, अनुमोदन, निरस्तीकरण प्रबंधन, टेलीमेट्री, ट्रांस्क्रिप्ट प्रोजेक्शन और निलंबन/पुनरारंभ व्यवहार का उपयोग करती हैं।

पंजीकरण संरचना

नेमस्पेस को उस एकीकरण से पंजीकृत करें जो आधारभूत टूल का स्वामी है। स्कोप छोटा रखें और केवल उन्हीं डोमेन क्रियाओं को प्रदर्शित करें जो घोषित कैटलॉग टूल से मैप होती हैं।

import {  createCodeModeNamespaceTool,  registerCodeModeNamespaceForPlugin,} from "../agents/code-mode-namespaces.js"; const pluginId = "github"; registerCodeModeNamespaceForPlugin(pluginId, {  id: "github-issues",  globalName: "Issues",  description: "वर्तमान रिपॉज़िटरी के लिए GitHub इश्यू सहायक।",  requiredToolNames: ["github_list_issues", "github_update_issue"],  prompt: "Issues.list(params) और Issues.update(number, patch) का उपयोग करें।",  createScope: (ctx) => ({    repository: ctx.config,    list: createCodeModeNamespaceTool("github_list_issues", ([params]) => params ?? {}),    update: createCodeModeNamespaceTool("github_update_issue", ([number, patch]) => ({      number,      patch,    })),  }),});

createCodeModeNamespaceTool(toolName, inputMapper) किसी स्कोप सदस्य को कॉल करने योग्य नेमस्पेस फ़ंक्शन के रूप में चिह्नित करता है। वैकल्पिक inputMapper अतिथि आर्गुमेंट प्राप्त करता है और आधारभूत कैटलॉग टूल के लिए इनपुट ऑब्जेक्ट लौटाता है; इसके बिना, पहला अतिथि आर्गुमेंट उपयोग किया जाता है, या छोड़े जाने पर {} उपयोग होता है।

अतिथि कोड चलने से पहले रॉ होस्ट फ़ंक्शन अस्वीकार कर दिए जाते हैं:

createScope: () => ({  // गलत: यह कैटलॉग टूल जीवनचक्र को बायपास करता है और अस्वीकार कर दिया जाएगा।  list: async () => githubClient.listIssues(),});

स्वामित्व और दृश्यता

नेमस्पेस स्वामित्व पंजीकरण कॉलर के pluginId से बँधा होता है। requiredToolNames दृश्यता गेट और स्वामित्व जाँच दोनों है:

• प्रत्येक आवश्यक टूल रन कैटलॉग में मौजूद होना चाहिए
• प्रत्येक आवश्यक टूल में sourceName === pluginId होना चाहिए
• जब कोई आवश्यक टूल अनुपस्थित हो या किसी अन्य plugin के स्वामित्व में हो, तो नेमस्पेस छिपा दिया जाता है
• प्रत्येक कॉल करने योग्य पथ केवल requiredToolNames में नामित टूल को लक्षित कर सकता है

यह किसी अन्य plugin को समान नाम वाला टूल पंजीकृत करके नेमस्पेस प्रदर्शित करने से रोकता है और नेमस्पेस को सामान्य एजेंट नीति के अनुरूप रखता है: यदि रन आधारभूत टूल नहीं देख सकता, तो वह नेमस्पेस भी नहीं देख सकता।

उदाहरण के लिए, GitHub नेमस्पेस ऐसे GitHub-स्वामित्व वाले plugin के पीछे होना चाहिए जो GitHub प्रमाणीकरण, REST/GraphQL क्लाइंट, दर सीमाओं, लेखन अनुमोदनों और परीक्षणों का स्वामी हो। कोर कोड मोड में GitHub-विशिष्ट API, टोकन प्रबंधन या प्रदाता नीति एम्बेड नहीं करनी चाहिए।

स्कोप सीरियलाइज़ेशन नियम

createScope(ctx) एक साधारण ऑब्जेक्ट लौटा सकता है, जिसमें JSON-संगत मान, एरे, नेस्टेड ऑब्जेक्ट और createCodeModeNamespaceTool(...) कॉल मार्कर हों। होस्ट ऑब्जेक्ट कभी भी सीधे QuickJS में प्रवेश नहीं करते।

सीरियलाइज़र इन्हें अस्वीकार करता है:

• रॉ फ़ंक्शन
• चक्रीय ऑब्जेक्ट ग्राफ़
• असुरक्षित पथ खंड: __proto__, constructor, prototype, रिक्त कुंजियाँ, या आंतरिक पथ विभाजक वाली कुंजियाँ
• globalName मान जो JavaScript पहचानकर्ता नहीं हैं
• अंतर्निहित कोड-मोड ग्लोबल जैसे tools, namespaces, text, json, yield_control, MCP, API, ALL_TOOLS, या __openclaw* के साथ globalName टकराव

जिन मानों को JSON-सीरियलाइज़ नहीं किया जा सकता, उन्हें ब्रिज पार करने से पहले JSON-सुरक्षित फ़ॉलबैक मानों में परिवर्तित कर दिया जाता है। बाइनरी डेटा, हैंडल, सॉकेट, क्लाइंट और क्लास इंस्टेंस सामान्य कैटलॉग टूल के पीछे ही रहने चाहिए।

प्रॉम्प्ट

नेमस्पेस description और वैकल्पिक prompt को मॉडल-दृश्यमान exec स्कीमा में केवल तभी जोड़ा जाता है, जब नेमस्पेस उस रन के लिए दृश्यमान हो। इनका उपयोग सबसे छोटी उपयोगी सतह सिखाने के लिए करें:

{  description: "कथा निर्माण सेवा सहायक।",  prompt:    "Fictions.riskAudit(), Fictions.promoteIfReady(id, status), और Fictions.unpaidOver(amount) का उपयोग करें।",}

प्रॉम्प्ट को नेमस्पेस अनुबंध के बारे में रखें, प्रमाणीकरण सेटअप, कार्यान्वयन इतिहास या असंबंधित Plugin व्यवहार के बारे में नहीं।

सफ़ाई

नेमस्पेस प्रक्रिया-स्थानीय पंजीकरण हैं। स्वामी Plugin के अक्षम, अनइंस्टॉल या रोल बैक होने पर उन्हें हटाएँ:

clearCodeModeNamespacesForPlugin(pluginId);

कोड-मोड सफ़ाई का स्वामित्व Plugin के पास है; प्रत्येक नेमस्पेस के लिए टियरडाउन हैंडल रखने के बजाय Plugin का जीवनचक्र समाप्त होने पर उसके नेमस्पेस पंजीकरण साफ़ करें। परीक्षण अलग-अलग मामलों में पंजीकरण लीक होने से बचाने के लिए clearCodeModeNamespacesForTest() को कॉल कर सकते हैं।

परीक्षण जाँच-सूची

नेमस्पेस परिवर्तनों में सुरक्षा सीमा और गेस्ट व्यवहार शामिल होने चाहिए:

• नेमस्पेस प्रॉम्प्ट टेक्स्ट केवल तभी दिखाई देता है जब सहायक टूल दृश्यमान हों
• किसी अन्य sourceName के समान नाम वाले टूल नेमस्पेस को उजागर नहीं करते
• रॉ स्कोप फ़ंक्शन अस्वीकार किए जाते हैं
• जाली नेमस्पेस आईडी और जाली पथ अस्वीकार किए जाते हैं
• कॉल करने योग्य पथ अघोषित टूल को लक्षित नहीं कर सकते
• नेस्टेड ऑब्जेक्ट और साझा संदर्भ सही ढंग से क्रमबद्ध होते हैं
• नेमस्पेस कॉल कैटलॉग टूल के माध्यम से निष्पादित होती हैं और JSON-सुरक्षित विवरण लौटाती हैं
• विफलताओं को गेस्ट कोड द्वारा पकड़ा जा सकता है
• निलंबित नेमस्पेस कॉल wait के माध्यम से फिर शुरू होती हैं
• Plugin रोलबैक स्वामी नेमस्पेस पंजीकरणों को साफ़ करता है

नेमस्पेस सामान्य tools.search/tools.call कैटलॉग के पूरक हैं: मनमाने ढंग से सक्षम OpenClaw, Plugin और क्लाइंट टूल के लिए कैटलॉग का उपयोग करें; MCP टूल के लिए MCP का उपयोग करें; अन्य नेमस्पेस का उपयोग Plugin-स्वामित्व वाली, दस्तावेज़ीकृत डोमेन API के लिए करें, जहाँ संक्षिप्त कोड बार-बार स्कीमा लुकअप करने से अधिक विश्वसनीय होता है।

आउटपुट API

• text(value) मानव-पठनीय आउटपुट को output ऐरे में जोड़ता है।
• json(value) JSON-संगत क्रमबद्धता के बाद एक संरचित आउटपुट आइटम जोड़ता है।
• गेस्ट कोड का अंतिम लौटाया गया मान completed परिणाम में value बन जाता है।

type CodeModeOutput = { type: "text"; text: string } | { type: "json"; value: unknown };

नियम: आउटपुट क्रम गेस्ट कॉल के क्रम से मेल खाता है; आउटपुट maxOutputBytes द्वारा सीमित है; क्रमबद्ध न किए जा सकने वाले मान सादे स्ट्रिंग या त्रुटियों में बदले जाते हैं; बाइनरी मान समर्थित नहीं हैं। छवियाँ और फ़ाइलें सामान्य OpenClaw टूल के माध्यम से जाती हैं, कोड-मोड ब्रिज के माध्यम से नहीं।

टूल कैटलॉग

छिपे हुए कैटलॉग में प्रभावी नीति फ़िल्टरिंग के बाद टूल इस क्रम में शामिल होते हैं: OpenClaw कोर टूल, बंडल किए गए Plugin टूल, बाहरी Plugin टूल, MCP टूल, फिर वर्तमान रन के लिए क्लाइंट द्वारा प्रदान किए गए टूल।

एक रन के भीतर कैटलॉग आईडी स्थिर होती हैं और जहाँ संभव हो, समान टूल सेट के बीच नियतात्मक होती हैं। वास्तविक स्वरूप:

<source>:<owner>:<tool-name>

जहाँ <source>, openclaw, mcp, या client है (Plugin टूल Plugin आईडी को <owner> के रूप में रखते हुए openclaw का उपयोग करते हैं; कोर टूल openclaw:core:* का उपयोग करते हैं)। उदाहरण:

openclaw:core:messageopenclaw:browser:browser_requestmcp:github:create_issueclient:app:select_file

कैटलॉग कोड-मोड नियंत्रण टूल (exec, wait, tool_search_code, tool_search, tool_describe, tool_call) और केवल-प्रत्यक्ष टूल को छोड़ देता है। नियंत्रणों को कैटलॉग के माध्यम से पुनरावर्ती कॉल नहीं करना चाहिए; केवल-प्रत्यक्ष टूल मॉडल को दृश्यमान बने रहते हैं क्योंकि उनके संरचित परिणाम QuickJS ब्रिज को पार नहीं कर सकते।

MCP प्रविष्टियाँ रन-स्कोप वाले कैटलॉग में बनी रहती हैं ताकि नीति, अनुमोदन, हुक, टेलीमेट्री, ट्रांसक्रिप्ट प्रक्षेपण और सटीक टूल आईडी सामान्य टूल निष्पादन के साथ साझा रहें। गेस्ट को दिखाई देने वाले ALL_TOOLS, tools.search(...), tools.describe(...), tools.callValue(...), और tools.call(...) दृश्य MCP प्रविष्टियों को छोड़ देते हैं। जनरेट किया गया MCP.<server>.<tool>({ ...input }) नेमस्पेस वापस सटीक कैटलॉग आईडी में रिज़ॉल्व होता है और उसी निष्पादक पथ के माध्यम से डिस्पैच करता है।

टूल खोज की अंतःक्रिया

जहाँ कोड मोड सक्रिय होता है, उन रन के लिए कोड मोड OpenClaw टूल खोज मॉडल सतह का स्थान लेता है।

जब tools.codeMode.enabled सत्य हो और कोड मोड सक्रिय हो:

• OpenClaw tool_search_code, tool_search, tool_describe, या tool_call को मॉडल-दृश्यमान टूल के रूप में उजागर नहीं करता।
• वही कैटलॉगिंग अवधारणा गेस्ट रनटाइम के भीतर चली जाती है।
• गेस्ट रनटाइम को गैर-MCP टूल के लिए संक्षिप्त ALL_TOOLS मेटाडेटा और खोज/वर्णन/ कॉल सहायक मिलते हैं।
• MCP कॉल tools.call(...) के बजाय जनरेट किए गए MCP नेमस्पेस और उसके $api() हेडर का उपयोग करती हैं।
• नेस्टेड कॉल उसी OpenClaw निष्पादक पथ के माध्यम से डिस्पैच होती हैं जिसका उपयोग टूल खोज करती है।

सक्रिय रन के लिए कोड मोड जिस OpenClaw संक्षिप्त कैटलॉग ब्रिज का स्थान लेता है, उसके बारे में जानने के लिए टूल खोज देखें।

टूल नाम और टकराव

मॉडल-दृश्यमान exec टूल कोड-मोड टूल है। यदि सामान्य OpenClaw शेल exec टूल सक्षम है, तो उसे मॉडल से छिपाया जाता है और किसी अन्य टूल की तरह कैटलॉग में रखा जाता है।

गेस्ट रनटाइम के भीतर:

• यदि नीति अनुमति देती है, तो tools.call("openclaw:core:exec", input) शेल निष्पादन टूल को कॉल कर सकता है।
• tools.exec(...) केवल तभी इंस्टॉल किया जाता है जब शेल निष्पादन कैटलॉग प्रविष्टि का एक स्पष्ट सुरक्षित नाम हो।
• कोड-मोड exec टूल tools के माध्यम से कभी भी पुनरावर्ती रूप से उपलब्ध नहीं होता।

यदि दो टूल एक ही सुरक्षित सुविधाजनक नाम में सामान्यीकृत होते हैं, तो OpenClaw सुविधाजनक फ़ंक्शन को छोड़ देता है और tools.call(id, input) आवश्यक बनाता है।

नेस्टेड टूल निष्पादन

प्रत्येक नेस्टेड टूल कॉल होस्ट ब्रिज को पार करती है और OpenClaw में पुनः प्रवेश करती है, इनको संरक्षित रखते हुए: सक्रिय एजेंट आईडी, सत्र आईडी और कुंजी, प्रेषक और चैनल संदर्भ, सैंडबॉक्स नीति, अनुमोदन नीति, Plugin before_tool_call हुक, निरस्तीकरण सिग्नल, जहाँ उपलब्ध हों वहाँ स्ट्रीमिंग अपडेट, और ट्रैजेक्टरी/ऑडिट इवेंट।

नेस्टेड कॉल ट्रांसक्रिप्ट में वास्तविक टूल कॉल के रूप में प्रक्षेपित होती हैं, ताकि सहायता बंडल दिखा सकें कि क्या हुआ, और प्रक्षेपण मूल कोड-मोड टूल कॉल तथा नेस्टेड टूल आईडी की पहचान करता है।

maxPendingToolCalls तक समानांतर नेस्टेड कॉल की अनुमति है।

रन और स्नैपशॉट जीवनचक्र

प्रत्येक कोड-मोड रन को runId द्वारा कुंजीबद्ध इन-प्रोसेस मैप में ट्रैक किया जाता है (डिस्क या डेटाबेस में स्थायी नहीं किया जाता)। exec/wait तीन परिणाम स्थितियों में से एक लौटाते हैं: completed, waiting, या failed।

• एक waiting परिणाम QuickJS स्नैपशॉट, लंबित ब्रिज अनुरोध और स्कोपिंग मेटाडेटा (एजेंट रन आईडी, सत्र आईडी/कुंजी) तब तक संग्रहीत करता है जब तक wait उसे फिर शुरू नहीं करता या उसकी समय-सीमा समाप्त नहीं हो जाती।
• समय-सीमा समाप्त, गलत-सत्र, गलत-रन और अज्ञात/पहले से-पुनः-शुरू हो रहे runId मान कोई अलग अंतिम स्थिति उत्पन्न नहीं करते; वे code mode run is unavailable or expired. या code mode run belongs to a different session. जैसे संदेश के साथ failed परिणाम (code: "invalid_input") के रूप में सामने आते हैं।
• जैसे ही कोई रन completed या failed पर स्थिर होता है, उसका स्नैपशॉट मैप से हटा दिया जाता है, या Gateway बंद होने पर छोड़ दिया जाता है (पुनरारंभ के बाद कुछ भी नहीं बचता: यह अस्थायी रनटाइम स्थिति है)।
• केवल-पठन कार्य के लिए, exec, restartSafe: true सेट कर सकता है। इसके बाद OpenClaw निष्पादन से पहले दुष्प्रभाव उत्पन्न करने वाली कैटलॉग कॉल और Plugin नेमस्पेस को अस्वीकार करता है तथा निलंबित परिणामों को रीप्ले-सुरक्षित चिह्नित करता है। यदि पुनरारंभ wait को बाधित करता है, तो पुनरारंभ पुनर्प्राप्ति प्रक्रिया-स्थानीय स्नैपशॉट को पुनर्स्थापित करने के बजाय ट्रांसक्रिप्ट से टर्न का पुनर्निर्माण करती है। पुनर्प्राप्ति टर्न स्वयं ऑडिट किए गए केवल-पठन कोर टूल और स्पष्ट रूप से रीप्ले-सुरक्षित Plugin टूल तक सीमित रहता है।
• OpenClaw प्रति प्रक्रिया एक साथ निलंबित रन की संख्या (64) तक सीमित करता है और इस सीमा से आगे नए निलंबनों को too many suspended code mode runs. के साथ अस्वीकार करता है।

स्नैपशॉट भंडारण प्रति रन maxSnapshotBytes, ऊपर दी गई प्रति-प्रक्रिया निलंबित-रन सीमा और snapshotTtlSeconds द्वारा सीमित है।

QuickJS-WASI रनटाइम

OpenClaw स्वामी पैकेज में quickjs-wasi को प्रत्यक्ष निर्भरता के रूप में लोड करता है; यह किसी असंबंधित निर्भरता के लिए इंस्टॉल की गई ट्रांज़िटिव प्रति पर निर्भर नहीं करता।

रनटाइम की ज़िम्मेदारियाँ: QuickJS-WASI WebAssembly मॉड्यूल को कंपाइल/लोड करना; प्रत्येक कोड-मोड रन या पुनः आरंभ के लिए एक पृथक VM बनाना; स्थिर नामों द्वारा होस्ट कॉलबैक पंजीकृत करना; मेमोरी और इंटरप्ट सीमाएँ सेट करना; JavaScript का मूल्यांकन करना; लंबित जॉब समाप्त करना; निलंबित VM स्थिति का स्नैपशॉट लेना; wait के लिए स्नैपशॉट पुनर्स्थापित करना; अंतिम स्थितियों के बाद VM हैंडल और स्नैपशॉट नष्ट करना।

रनटाइम OpenClaw के मुख्य इवेंट लूप के बाहर Node.js वर्कर थ्रेड में निष्पादित होता है। गेस्ट का अनंत लूप Gateway प्रक्रिया को अनिश्चित काल तक अवरुद्ध नहीं करना चाहिए; वर्कर का इंटरप्ट हैंडलर गेस्ट कोड के सहयोग से स्वतंत्र रूप से वास्तविक-समय टाइमआउट लागू करता है।

TypeScript

TypeScript समर्थन केवल स्रोत रूपांतरण है: स्वीकृत इनपुट एक TypeScript कोड स्ट्रिंग है; आउटपुट QuickJS-WASI द्वारा मूल्यांकित JavaScript स्ट्रिंग है। कोई टाइप जाँच, मॉड्यूल रिज़ॉल्यूशन और import/require नहीं है। निदान failed परिणामों के रूप में लौटाए जाते हैं।

TypeScript कंपाइलर केवल TypeScript सेल के लिए लेज़ी रूप से लोड किया जाता है; सामान्य JavaScript सेल और अक्षम कोड मोड इसे कभी लोड नहीं करते।

सुरक्षा सीमा

मॉडल कोड शत्रुतापूर्ण है। रनटाइम बहुस्तरीय सुरक्षा का उपयोग करता है:

• QuickJS-WASI को मुख्य इवेंट लूप के बाहर, वर्कर थ्रेड में चलाता है
• quickjs-wasi को Codex या किसी ट्रांज़िटिव पैकेज के माध्यम से नहीं, बल्कि प्रत्यक्ष निर्भरता के रूप में लोड करता है
• गेस्ट में कोई फ़ाइल सिस्टम, नेटवर्क, उप-प्रक्रिया, मॉड्यूल आयात, पर्यावरण चर या होस्ट वैश्विक ऑब्जेक्ट नहीं होते
• मूल प्रक्रिया के वास्तविक-समय टाइमआउट के साथ QuickJS मेमोरी और इंटरप्ट सीमाओं का उपयोग करता है
• आउटपुट, स्नैपशॉट, लॉग और लंबित-कॉल सीमाएँ लागू करता है
• एक संकीर्ण JSON अडैप्टर के माध्यम से होस्ट ब्रिज मानों को क्रमबद्ध करता है
• होस्ट त्रुटियों को सादी गेस्ट त्रुटियों में बदलता है, होस्ट रियल्म ऑब्जेक्ट में कभी नहीं
• टाइमआउट, निरस्तीकरण, सत्र समाप्ति या समय-सीमा समाप्ति पर स्नैपशॉट छोड़ देता है
• exec, wait और टूल खोज नियंत्रण टूल तक पुनरावर्ती पहुँच अस्वीकार करता है
• सुविधाजनक-नाम टकरावों को कैटलॉग सहायकों पर छाया डालने से रोकता है

सैंडबॉक्स सुरक्षा की एक परत है; उच्च-जोखिम परिनियोजनों के लिए ऑपरेटरों को फिर भी OS-स्तरीय सुदृढ़ीकरण की आवश्यकता हो सकती है।

त्रुटि कोड

type CodeModeErrorCode =  | "invalid_input"  | "runtime_unavailable"  | "timeout"  | "output_limit_exceeded"  | "snapshot_limit_exceeded"  | "internal_error";

invalid_input गलत exec/wait आर्ग्युमेंट, अक्षम भाषाओं, अस्वीकृत मॉड्यूल पहुँच, TypeScript रूपांतरण विफलताओं, अज्ञात/समय-सीमा समाप्त/ गलत-स्कोप runId मानों और बहुत अधिक निलंबित रन को कवर करता है। runtime_unavailable ऐसे QuickJS वर्कर को कवर करता है जो शुरू होने में विफल रहता है या गैर-शून्य स्थिति के साथ बाहर निकलता है।

गेस्ट को लौटाई गई त्रुटियाँ सादा डेटा होती हैं; होस्ट Error इंस्टेंस, स्टैक ऑब्जेक्ट, प्रोटोटाइप और होस्ट फ़ंक्शन QuickJS में प्रवेश नहीं करते।

टेलीमेट्री

प्रत्येक परिणाम का telemetry फ़ील्ड यह रिपोर्ट करता है: छिपे हुए कैटलॉग का आकार और स्रोत विभाजन (openclaw/mcp/client गणनाएँ), रन के कैटलॉग के लिए संचयी खोज/वर्णन/कॉल गणनाएँ, और मॉडल-दृश्यमान टूल नाम (exec, wait, तथा बनाए रखे गए केवल-प्रत्यक्ष टूल)।

टेलीमेट्री में मौजूदा OpenClaw ट्रैजेक्टरी नीति से परे रहस्य, रॉ पर्यावरण मान या बिना संशोधन वाले टूल इनपुट शामिल नहीं होने चाहिए।

डीबगिंग

जब कोड मोड सामान्य टूल रन से अलग व्यवहार करता है, तो लक्षित मॉडल ट्रांसपोर्ट लॉगिंग का उपयोग करें:

OPENCLAW_DEBUG_CODE_MODE=1 \OPENCLAW_DEBUG_MODEL_TRANSPORT=1 \OPENCLAW_DEBUG_MODEL_PAYLOAD=tools \OPENCLAW_DEBUG_SSE=events \openclaw gateway

पेलोड-आकार की डीबगिंग के लिए, OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted का उपयोग करें। यह मॉडल अनुरोध का सीमित, संशोधित JSON स्नैपशॉट लॉग करता है; इसका उपयोग केवल डीबगिंग करते समय करें, क्योंकि प्रॉम्प्ट और संदेश का टेक्स्ट फिर भी दिखाई दे सकता है।

स्ट्रीम डीबगिंग के लिए, पहले पाँच संशोधित SSE इवेंट लॉग करने हेतु OPENCLAW_DEBUG_SSE=peek का उपयोग करें। कोड मोड भी विफलता पर बंद हो जाता है, यदि अंतिम प्रोवाइडर पेलोड में ठीक एक exec, एक wait, और कोड-मोड सतह सक्रिय होने के बाद केवल अनुमोदित प्रत्यक्ष-केवल टूल न हों।

कार्यान्वयन लेआउट

• कॉन्फ़िगरेशन अनुबंध: tools.codeMode
• कैटलॉग बिल्डर: प्रभावी टूल को संक्षिप्त प्रविष्टियों और आईडी मैप में बदलना
• मॉडल-सतह एडाप्टर: दृश्यमान टूल को नियंत्रण/प्रत्यक्ष टूल से बदलना
• QuickJS-WASI रनटाइम एडाप्टर: लोड, मूल्यांकन, स्नैपशॉट, पुनर्स्थापन, निपटान
• वर्कर पर्यवेक्षक: टाइमआउट, निरस्तीकरण, क्रैश पृथक्करण
• ब्रिज एडाप्टर: JSON-सुरक्षित होस्ट कॉलबैक और परिणाम वितरण
• TypeScript रूपांतरण एडाप्टर
• स्नैपशॉट स्टोर: TTL, आकार सीमाएँ, रन/सत्र दायरा
• नेस्टेड टूल कॉल के लिए ट्रैजेक्टरी प्रक्षेपण
• टेलीमेट्री काउंटर और निदान

कार्यान्वयन Tool Search की कैटलॉग और निष्पादक अवधारणाओं का पुनः उपयोग करता है, लेकिन सैंडबॉक्स के रूप में node:vm चाइल्ड का उपयोग नहीं करता।

सत्यापन चेकलिस्ट

कोड मोड कवरेज से यह सिद्ध होना चाहिए:

• अक्षम कॉन्फ़िगरेशन मौजूदा टूल एक्सपोज़र को अपरिवर्तित रखता है
• enabled: true के बिना ऑब्जेक्ट कॉन्फ़िगरेशन कोड मोड को अक्षम रखता है
• सक्षम कॉन्फ़िगरेशन, रन के लिए टूल सक्रिय होने पर, मॉडल के समक्ष exec, wait, और केवल आवश्यक प्रत्यक्ष-केवल टूल उजागर करता है
• कच्चे टूल-रहित रन, disableTools, और खाली अनुमति-सूचियाँ कोड-मोड पेलोड प्रवर्तन सक्रिय नहीं करते
• कैटलॉग के योग्य सभी प्रभावी गैर-MCP टूल ALL_TOOLS में दिखाई देते हैं
• प्रत्यक्ष-केवल टूल मॉडल को दृश्यमान रहते हैं और ALL_TOOLS में दिखाई नहीं देते
• अस्वीकृत टूल ALL_TOOLS में दिखाई नहीं देते
• tools.search, tools.describe, tools.callValue, और tools.call OpenClaw टूल के लिए काम करते हैं
• API.list("mcp") और API.read("mcp/<server>.d.ts") बिना ब्रिज/टूल कॉल के TypeScript-शैली की MCP घोषणाएँ उजागर करते हैं
• स्कीमा के लिए MCP नेमस्पेस $api() इनलाइन फ़ॉलबैक के रूप में उपलब्ध रहता है
• MCP नेमस्पेस कॉल एक ऑब्जेक्ट इनपुट वाले दृश्यमान MCP टूल के लिए काम करती हैं, जबकि प्रत्यक्ष MCP कैटलॉग प्रविष्टियाँ tools.* में अनुपस्थित रहती हैं
• Tool Search नियंत्रण टूल मॉडल सतह और छिपे हुए कैटलॉग, दोनों से छिपे रहते हैं
• नेस्टेड कॉल अनुमोदन और हुक व्यवहार को बनाए रखती हैं
• शेल exec मॉडल से छिपा रहता है, लेकिन अनुमति मिलने पर कैटलॉग आईडी द्वारा कॉल किया जा सकता है
• पुनरावर्ती कोड-मोड exec और wait गेस्ट कोड से कॉल नहीं किए जा सकते
• अक्षम या केवल-JavaScript पथों पर TypeScript लोड किए बिना TypeScript इनपुट रूपांतरित और मूल्यांकित किया जाता है
• import, require, फ़ाइल सिस्टम, नेटवर्क, और परिवेश एक्सेस विफल होते हैं
• अनंत लूप टाइम आउट होते हैं और Gateway को अवरुद्ध नहीं कर सकते
• मेमोरी सीमा की विफलताएँ गेस्ट VM को समाप्त करती हैं
• पूर्ण और निलंबित कॉल के लिए आउटपुट और स्नैपशॉट सीमाएँ लागू की जाती हैं
• wait निलंबित स्नैपशॉट को पुनः शुरू करता है और अंतिम मान लौटाता है
• समाप्त, निरस्त, गलत-सत्र, और अज्ञात runId मान विफल होते हैं
• ट्रांसक्रिप्ट रीप्ले और स्थायित्व कोड-मोड नियंत्रण कॉल को संरक्षित रखते हैं
• ट्रांसक्रिप्ट और टेलीमेट्री नेस्टेड टूल कॉल को स्पष्ट रूप से दिखाते हैं

E2E परीक्षण योजना

रनटाइम बदलते समय इन्हें एकीकरण या एंड-टू-एंड परीक्षणों के रूप में चलाएँ:

1. tools.codeMode.enabled: false के साथ Gateway शुरू करें।
2. छोटे प्रत्यक्ष टूल सेट के साथ एक एजेंट टर्न भेजें।
3. अभिकथित करें कि मॉडल को दृश्यमान टूल अपरिवर्तित हैं।
4. tools.codeMode.enabled: true के साथ पुनः आरंभ करें।
5. OpenClaw, Plugin, MCP, और क्लाइंट परीक्षण टूल के साथ एक एजेंट टर्न भेजें।
6. अभिकथित करें कि मॉडल को दृश्यमान टूल सूची exec, wait, और केवल कॉन्फ़िगर किए गए प्रत्यक्ष-केवल टूल हैं।
7. exec में, ALL_TOOLS पढ़ें और अभिकथित करें कि कैटलॉग-योग्य प्रभावी परीक्षण टूल मौजूद हैं, जबकि प्रत्यक्ष-केवल टूल अनुपस्थित हैं।
8. exec में, OpenClaw/Plugin/क्लाइंट टूल को tools.search, tools.describe, और tools.callValue (या कच्चे tools.call) के माध्यम से कॉल करें।
9. exec में, API.list("mcp") और API.read("mcp/<server>.d.ts") को कॉल करें और अभिकथित करें कि घोषणा फ़ाइलें दृश्यमान MCP टूल का वर्णन करती हैं।
10. exec में, MCP टूल को MCP.<server>.<tool>({ ...input }) के माध्यम से कॉल करें और अभिकथित करें कि प्रत्यक्ष MCP कैटलॉग प्रविष्टियाँ ALL_TOOLS और tools.* में अनुपस्थित हैं।
11. अभिकथित करें कि अस्वीकृत टूल अनुपस्थित हैं और अनुमानित आईडी द्वारा कॉल नहीं किए जा सकते।
12. एक नेस्टेड टूल कॉल शुरू करें, जो exec द्वारा waiting लौटाए जाने के बाद हल होती है।
13. wait को कॉल करें और अभिकथित करें कि पुनर्स्थापित VM को टूल परिणाम प्राप्त होता है।
14. अभिकथित करें कि अंतिम उत्तर में पुनर्स्थापन के बाद उत्पन्न आउटपुट शामिल है।
15. अभिकथित करें कि टाइमआउट, निरस्तीकरण, और स्नैपशॉट समाप्ति रनटाइम स्थिति साफ़ करते हैं।
16. ट्रैजेक्टरी निर्यात करें और अभिकथित करें कि नेस्टेड कॉल पैरेंट कोड-मोड कॉल के अंतर्गत दृश्यमान हैं।

इस पृष्ठ में केवल दस्तावेज़ी बदलावों के लिए भी pnpm check:docs चलाया जाना चाहिए।

संबंधित

• कोड मोड स्क्रिप्ट से फ़ैन-आउट एजेंट ऑर्केस्ट्रेशन के लिए Swarm
• Tool Search
• एजेंट रनटाइम
• Exec टूल
• कोड निष्पादन