कोड मोड

कोड मोड एक प्रयोगात्मक, ऑप्ट-इन 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 असत्य है, तो सामान्य टूल उपलब्धता जारी रखें।
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" है; स्कीमा इसे सपाट स्ट्रिंग एनम ("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;};

जब अतिथि ऐसी पुनः आरंभ योग्य स्थिति के साथ निलंबित होता है जिसे अभी भी मॉडल-दृश्य निरंतरता की आवश्यकता है—एक स्पष्ट yield_control(...), या ऐसी ब्रिज टूल कॉल जो exec समय-सीमा में हल नहीं हुई—तब exec, waiting लौटाता है। परिणाम में 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&lt;ToolCatalogEntry[]&gt;;  describe(id: string): Promise&lt;ToolCatalogEntryWithSchema&gt;;  callValue(id: string, input?: unknown): Promise<unknown>;  call(id: string, input?: unknown): Promise<unknown>;  [safeToolName: string]: unknown;};

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

const files = await tools.search("read local file");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 code mode" });

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

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

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

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

  const Shipment = Type.Object(  {    id: Type.String(),    paid: Type.Boolean(),    tons: Type.Number(),  },  { additionalProperties: false },); export default defineToolPlugin({  id: "shipping",  name: "Shipping",  description: "Shipment tools.",  tools: (tool) => [    tool({      name: "shipping_list",      description: "List shipments.",      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 लेखन के विवरण के लिए टूल plugins देखें।

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: "रिलीज़" },});

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(...) के समान नीति हुक, अनुमोदन, अबॉर्ट हैंडलिंग, टेलीमेट्री, ट्रांसक्रिप्ट प्रोजेक्शन और निलंबन/पुनरारंभ व्यवहार का उपयोग करते हैं।

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

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

   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 पहचानकर्ता नहीं हैं
• globalName की tools, namespaces, text, json, yield_control, MCP, API, ALL_TOOLS, या __openclaw* जैसे अंतर्निहित कोड-मोड ग्लोबल से टक्कर

जिन मानों को 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 टूल openclaw का उपयोग करते हैं, जिसमें Plugin आईडी <owner> होती है; कोर टूल 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 true हो और कोड मोड सक्रिय हो:

• 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) शेल exec टूल को कॉल कर सकता है।
• tools.exec(...) केवल तभी इंस्टॉल किया जाता है जब शेल 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, और केवल स्वीकृत केवल-प्रत्यक्ष टूल नहीं होते, तो Code Mode भी बंद रहकर विफल होता है।

कार्यान्वयन विन्यास

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

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

सत्यापन जाँच-सूची

Code Mode कवरेज को यह प्रमाणित करना चाहिए:

• अक्षम कॉन्फ़िगरेशन मौजूदा टूल उपलब्धता को अपरिवर्तित रखता है
• enabled: true के बिना ऑब्जेक्ट कॉन्फ़िगरेशन Code Mode को अक्षम रखता है
• सक्षम कॉन्फ़िगरेशन रन के लिए टूल सक्रिय होने पर मॉडल को exec, wait, और केवल आवश्यक केवल-प्रत्यक्ष टूल उपलब्ध कराता है
• मूल टूल-रहित रन, disableTools, और खाली अनुमत-सूचियाँ Code Mode पेलोड प्रवर्तन ट्रिगर नहीं करतीं
• सभी कैटलॉग-योग्य प्रभावी गैर-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 मॉडल से छिपा रहता है, लेकिन अनुमति होने पर कैटलॉग आईडी द्वारा कॉल किया जा सकता है
• पुनरावर्ती Code Mode exec और wait को अतिथि कोड से कॉल नहीं किया जा सकता
• अक्षम या केवल-JavaScript पथों पर TypeScript लोड किए बिना TypeScript इनपुट रूपांतरित और मूल्यांकित होता है
• import, require, फ़ाइल सिस्टम, नेटवर्क, और परिवेश पहुँच विफल होती है
• अनंत लूप की समय-सीमा समाप्त होती है और वे Gateway को अवरुद्ध नहीं कर सकते
• मेमोरी सीमा विफलताएँ अतिथि VM को समाप्त करती हैं
• पूर्ण और निलंबित कॉल के लिए आउटपुट तथा स्नैपशॉट सीमाएँ लागू होती हैं
• wait निलंबित स्नैपशॉट को फिर से शुरू करता है और अंतिम मान लौटाता है
• समाप्त, निरस्त, गलत-सत्र, और अज्ञात runId मान विफल होते हैं
• ट्रांसक्रिप्ट रीप्ले और स्थायित्व Code Mode नियंत्रण कॉल को बनाए रखते हैं
• ट्रांसक्रिप्ट और टेलीमेट्री नेस्टेड टूल कॉल को स्पष्ट रूप से दिखाते हैं

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 में, tools.search, tools.describe, और tools.callValue (या मूल tools.call) के माध्यम से OpenClaw/Plugin/क्लाइंट टूल कॉल करें।
9. exec में, API.list("mcp") और API.read("mcp/<server>.d.ts") कॉल करें और अभिकथित करें कि घोषणा फ़ाइलें दृश्यमान MCP टूल का वर्णन करती हैं।
10. exec में, MCP.<server>.<tool>({ ...input }) के माध्यम से MCP टूल कॉल करें और अभिकथित करें कि प्रत्यक्ष MCP कैटलॉग प्रविष्टियाँ ALL_TOOLS और tools.* से अनुपस्थित हैं।
11. अभिकथित करें कि अस्वीकृत टूल अनुपस्थित हैं और अनुमानित आईडी द्वारा कॉल नहीं किए जा सकते।
12. ऐसा नेस्टेड टूल कॉल शुरू करें जो exec द्वारा waiting लौटाने के बाद हल होता है।
13. wait कॉल करें और अभिकथित करें कि पुनर्स्थापित VM को टूल परिणाम प्राप्त होता है।
14. अभिकथित करें कि अंतिम उत्तर में पुनर्स्थापना के बाद उत्पन्न आउटपुट शामिल है।
15. अभिकथित करें कि समय-सीमा, निरस्तीकरण, और स्नैपशॉट समाप्ति रनटाइम स्थिति साफ़ करते हैं।
16. ट्रैजेक्टरी निर्यात करें और अभिकथित करें कि नेस्टेड कॉल पैरेंट Code Mode कॉल के अंतर्गत दिखाई देते हैं।

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

संबंधित

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