सैंडबॉक्सिंग

OpenClaw ब्लास्ट रेडियस कम करने के लिए टूल निष्पादन को सैंडबॉक्स बैकएंड के भीतर चला सकता है। सैंडबॉक्सिंग डिफ़ॉल्ट रूप से बंद होती है और इसे agents.defaults.sandbox (वैश्विक) या agents.entries.*.sandbox (प्रति-एजेंट) द्वारा नियंत्रित किया जाता है। Gateway प्रक्रिया हमेशा होस्ट पर रहती है; सक्षम होने पर केवल टूल निष्पादन सैंडबॉक्स में जाता है।

क्या सैंडबॉक्स किया जाता है

• टूल निष्पादन: exec, read, write, edit, apply_patch, process, आदि।
• वैकल्पिक सैंडबॉक्स किया गया ब्राउज़र (agents.defaults.sandbox.browser)।

सैंडबॉक्स नहीं किए जाते:

• स्वयं Gateway प्रक्रिया।
• tools.elevated के माध्यम से सैंडबॉक्स के बाहर चलने की स्पष्ट अनुमति प्राप्त कोई भी टूल। उन्नत exec सैंडबॉक्सिंग को बायपास करता है और कॉन्फ़िगर किए गए एस्केप पथ पर चलता है (डिफ़ॉल्ट रूप से gateway, या जब exec लक्ष्य node हो तब node)। यदि सैंडबॉक्सिंग बंद है, तो tools.elevated से कुछ नहीं बदलता क्योंकि exec पहले से ही होस्ट पर चलता है। उन्नत मोड देखें।

मोड, दायरा और बैकएंड

तीन स्वतंत्र सेटिंग सैंडबॉक्स के व्यवहार को नियंत्रित करती हैं:

मोड नियंत्रित करता है कि सैंडबॉक्सिंग कब लागू होती है:

• off: कोई सैंडबॉक्सिंग नहीं।
• non-main: एजेंट के मुख्य सत्र को छोड़कर प्रत्येक सत्र को सैंडबॉक्स करें। मुख्य सत्र की कुंजी हमेशा agent:<agentId>:main होती है (या जब session.scope, "global" हो तब global); इसे कॉन्फ़िगर नहीं किया जा सकता। समूह/चैनल सत्र अपनी अलग कुंजियों का उपयोग करते हैं, इसलिए उन्हें हमेशा गैर-मुख्य माना जाता है और वे सैंडबॉक्स किए जाते हैं।
• all: प्रत्येक सत्र सैंडबॉक्स में चलता है।

दायरा नियंत्रित करता है कि कितने कंटेनर/परिवेश बनाए जाते हैं:

• agent: प्रति एजेंट एक कंटेनर।
• session: प्रति सत्र एक कंटेनर।
• shared: सभी सैंडबॉक्स किए गए सत्रों द्वारा साझा किया गया एक कंटेनर (इस दायरे में प्रति-एजेंट docker/ssh/browser ओवरराइड अनदेखे किए जाते हैं)।

बैकएंड नियंत्रित करता है कि कौन-सा रनटाइम सैंडबॉक्स किए गए टूल निष्पादित करता है। SSH-विशिष्ट कॉन्फ़िगरेशन agents.defaults.sandbox.ssh के अंतर्गत रहता है; OpenShell-विशिष्ट कॉन्फ़िगरेशन plugins.entries.openshell.config के अंतर्गत रहता है।

Docker बैकएंड

सैंडबॉक्सिंग सक्षम होने के बाद Docker डिफ़ॉल्ट बैकएंड होता है। यह Docker डेमन सॉकेट (/var/run/docker.sock) के माध्यम से टूल और सैंडबॉक्स ब्राउज़र स्थानीय रूप से चलाता है; पृथक्करण Docker नेमस्पेस से मिलता है।

डिफ़ॉल्ट: network: "none" (कोई इग्रेस नहीं), readOnlyRoot: true, capDrop: ["ALL"], इमेज openclaw-sandbox:bookworm-slim।

होस्ट GPU उपलब्ध कराने के लिए, agents.defaults.sandbox.docker.gpus (या प्रति-एजेंट ओवरराइड) को "all" या "device=GPU-uuid" जैसे मान पर सेट करें। इसे Docker के --gpus फ़्लैग में भेजा जाता है और इसके लिए NVIDIA Container Toolkit जैसा संगत होस्ट रनटाइम आवश्यक है।

सैंडबॉक्स किया गया ब्राउज़र

• जब ब्राउज़र टूल को इसकी आवश्यकता होती है, तो सैंडबॉक्स ब्राउज़र स्वतः शुरू होता है (यह सुनिश्चित करता है कि CDP पहुँच योग्य है)। इसे agents.defaults.sandbox.browser.autoStart (डिफ़ॉल्ट true) और autoStartTimeoutMs (डिफ़ॉल्ट 12s) के माध्यम से कॉन्फ़िगर करें।
• सैंडबॉक्स ब्राउज़र कंटेनर वैश्विक bridge नेटवर्क के बजाय एक समर्पित Docker नेटवर्क (openclaw-sandbox-browser) का उपयोग करते हैं। इसे agents.defaults.sandbox.browser.network से कॉन्फ़िगर करें।
• agents.defaults.sandbox.browser.cdpSourceRange, CIDR अनुमत-सूची (उदाहरण के लिए 172.21.0.1/32) के साथ कंटेनर-किनारे के CDP इनग्रेस को सीमित करता है।
• noVNC पर्यवेक्षक पहुँच डिफ़ॉल्ट रूप से पासवर्ड-सुरक्षित होती है; OpenClaw एक अल्पकालिक टोकन URL जारी करता है, जो स्थानीय बूटस्ट्रैप पृष्ठ उपलब्ध कराता है और URL फ़्रैगमेंट में पासवर्ड के साथ noVNC खोलता है (क्वेरी स्ट्रिंग या हेडर लॉग में नहीं)।
• agents.defaults.sandbox.browser.allowHostControl (डिफ़ॉल्ट false) सैंडबॉक्स किए गए सत्रों को स्पष्ट रूप से होस्ट ब्राउज़र को लक्ष्य बनाने देता है।
• वैकल्पिक अनुमत-सूचियाँ target: "custom" को नियंत्रित करती हैं: allowedControlUrls, allowedControlHosts, allowedControlPorts।

SSH बैकएंड

किसी भी SSH-सुलभ मशीन पर exec, फ़ाइल टूल और मीडिया रीड को सैंडबॉक्स करने के लिए backend: "ssh" का उपयोग करें।

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "ssh",        scope: "session",        workspaceAccess: "rw",        ssh: {          target: "user@gateway-host:22",          workspaceRoot: "/tmp/openclaw-sandboxes",          strictHostKeyChecking: true,          updateHostKeys: true,          identityFile: "~/.ssh/id_ed25519",          certificateFile: "~/.ssh/id_ed25519-cert.pub",          knownHostsFile: "~/.ssh/known_hosts",          // या स्थानीय फ़ाइलों के बजाय SecretRefs / इनलाइन सामग्री का उपयोग करें:          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },      },    },  },}

डिफ़ॉल्ट: command: "ssh", workspaceRoot: "/tmp/openclaw-sandboxes", strictHostKeyChecking: true, updateHostKeys: true।

• जीवनचक्र: OpenClaw, sandbox.ssh.workspaceRoot के अंतर्गत प्रति-दायरा रिमोट रूट बनाता है। बनाने या दोबारा बनाने के बाद पहली बार उपयोग करने पर, यह स्थानीय वर्कस्पेस से उस रिमोट वर्कस्पेस को एक बार सीड करता है। उसके बाद, exec, read, write, edit, apply_patch, प्रॉम्प्ट मीडिया रीड और इनबाउंड मीडिया स्टेजिंग सीधे SSH के माध्यम से रिमोट वर्कस्पेस पर चलते हैं। OpenClaw रिमोट बदलावों को स्थानीय वर्कस्पेस में स्वचालित रूप से सिंक नहीं करता।
• प्रमाणीकरण सामग्री: identityFile/certificateFile/knownHostsFile मौजूदा स्थानीय फ़ाइलों को संदर्भित करते हैं। identityData/certificateData/knownHostsData इनलाइन स्ट्रिंग या SecretRefs स्वीकार करते हैं, जिन्हें सामान्य सीक्रेट रनटाइम स्नैपशॉट के माध्यम से रिज़ॉल्व किया जाता है, मोड 0600 वाली अस्थायी फ़ाइलों में लिखा जाता है और SSH सत्र समाप्त होने पर हटा दिया जाता है। यदि एक ही आइटम के लिए *File और *Data दोनों प्रकार सेट हैं, तो उस सत्र के लिए *Data प्रभावी होता है।
• रिमोट-कैनोनिकल के परिणाम: प्रारंभिक सीड के बाद रिमोट SSH वर्कस्पेस वास्तविक सैंडबॉक्स स्थिति बन जाता है। सीड चरण के बाद OpenClaw के बाहर किए गए होस्ट-स्थानीय संपादन तब तक रिमोट पर दिखाई नहीं देते, जब तक आप सैंडबॉक्स को दोबारा नहीं बनाते। openclaw sandbox recreate प्रति-दायरा रिमोट रूट को हटा देता है और अगले उपयोग पर स्थानीय से फिर सीड करता है। इस बैकएंड पर ब्राउज़र सैंडबॉक्सिंग समर्थित नहीं है और sandbox.docker.* सेटिंग इस पर लागू नहीं होतीं।

OpenShell बैकएंड

OpenShell द्वारा प्रबंधित रिमोट परिवेश में टूल सैंडबॉक्स करने के लिए backend: "openshell" का उपयोग करें। OpenShell सामान्य SSH बैकएंड के समान SSH ट्रांसपोर्ट और रिमोट फ़ाइल सिस्टम ब्रिज का पुनः उपयोग करता है, और इसमें OpenShell जीवनचक्र (sandbox create/get/delete/ssh-config) के साथ वैकल्पिक mirror वर्कस्पेस सिंक मोड जोड़ता है।

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "openshell",        scope: "session",        workspaceAccess: "rw",      },    },  },  plugins: {    entries: {      openshell: {        enabled: true,        config: {          from: "openclaw",          mode: "remote", // मिरर | रिमोट        },      },    },  },}

mode: "mirror" (डिफ़ॉल्ट) स्थानीय वर्कस्पेस को कैनोनिकल बनाए रखता है: OpenClaw, exec से पहले स्थानीय सामग्री को सैंडबॉक्स में सिंक करता है और बाद में वापस सिंक करता है। mode: "remote" रिमोट वर्कस्पेस को स्थानीय सामग्री से एक बार आरंभ करता है, फिर वापस सिंक किए बिना exec/read/write/edit/apply_patch को सीधे रिमोट वर्कस्पेस पर चलाता है; आरंभिक प्रतिलिपि के बाद किए गए स्थानीय संपादन तब तक दिखाई नहीं देते, जब तक आप openclaw sandbox recreate नहीं करते। scope: "agent" या scope: "shared" के अंतर्गत, वह रिमोट वर्कस्पेस उसी दायरे में साझा किया जाता है। वर्तमान सीमाएँ: सैंडबॉक्स ब्राउज़र अभी समर्थित नहीं है और sandbox.docker.binds इस बैकएंड पर लागू नहीं होता।

openclaw sandbox list/recreate/प्रून सभी OpenShell रनटाइम को Docker रनटाइम के समान मानते हैं; प्रून लॉजिक बैकएंड से अवगत है।

सभी पूर्वापेक्षाओं, कॉन्फ़िगरेशन संदर्भ, वर्कस्पेस-मोड तुलना और लाइफ़साइकल विवरण के लिए OpenShell देखें।

वर्कस्पेस एक्सेस

agents.defaults.sandbox.workspaceAccess नियंत्रित करता है कि सैंडबॉक्स क्या देख सकता है:

OpenShell बैकएंड के साथ, mirror मोड अभी भी एक्ज़ेक टर्न के बीच स्थानीय वर्कस्पेस को कैनोनिकल स्रोत के रूप में उपयोग करता है, remote मोड आरंभिक प्रतिलिपि के बाद रिमोट OpenShell वर्कस्पेस को कैनोनिकल स्रोत के रूप में उपयोग करता है और workspaceAccess: "ro"/"none" अभी भी लिखने के व्यवहार को उसी प्रकार सीमित करते हैं।

आने वाला मीडिया सक्रिय सैंडबॉक्स वर्कस्पेस (media/inbound/*) में कॉपी किया जाता है।

एक एजेंट के लिए अनेक फ़ोल्डर

जब किसी सैंडबॉक्स किए गए एजेंट को उसके प्राथमिक वर्कस्पेस से अधिक की आवश्यकता हो, तो Docker बाइंड माउंट का उपयोग करें। प्रत्येक प्रविष्टि एक होस्ट फ़ोल्डर को स्पष्ट एक्सेस मोड वाले कंटेनर पथ से मैप करती है:

host-directory:container-directory:rohost-directory:container-directory:rw

• ro माउंट किए गए फ़ोल्डर को सैंडबॉक्स के भीतर केवल-पढ़ने योग्य बनाता है।
• rw सैंडबॉक्स किए गए टूल और प्रक्रियाओं को होस्ट फ़ोल्डर बदलने देता है।
• कंटेनर पथ वह पथ है जिसका एजेंट उपयोग करता है। होस्ट पथ स्वचालित रूप से उजागर नहीं होते।

यह उदाहरण research एजेंट को लिखने योग्य प्राथमिक वर्कस्पेस, /reference पर केवल-पढ़ने योग्य संदर्भ सामग्री और /drafts पर एक अलग लिखने योग्य आउटपुट फ़ोल्डर देता है:

{  agents: {    defaults: {      sandbox: {        mode: "all",        scope: "agent",      },    },    list: [      {        id: "research",        workspace: "/srv/openclaw/research-workspace",        sandbox: {          workspaceAccess: "rw",          docker: {            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],            // आवश्यक है क्योंकि ये स्रोत एजेंट वर्कस्पेस के बाहर हैं।            dangerouslyAllowExternalBindSources: true,          },        },      },    ],  },}

workspaceAccess और बाइंड मोड एक-दूसरे से स्वतंत्र हैं:

workspaceAccess बदलने से कोई अतिरिक्त बाइंड ro से rw या इसके विपरीत नहीं बदलता। वैश्विक और प्रति-एजेंट docker.binds मर्ज किए जाते हैं। प्रति-एजेंट बाइंड के लिए scope: "agent" या "session" रखें; scope: "shared" सभी प्रति-एजेंट Docker ओवरराइड की उपेक्षा करता है और केवल वैश्विक बाइंड का उपयोग करता है।

बाइंड माउंट समर्थित बहु-फ़ोल्डर सीमा हैं क्योंकि Docker माउंट आइसोलेशन के साथ कंटेनर का फ़ाइल सिस्टम दृश्य बनाता है और ro/rw मोड सैंडबॉक्स की प्रत्येक प्रक्रिया पर लागू होता है। यह सीमा प्रत्येक OpenClaw कोड पथ में पथ-अधिकरण जाँचों को दोहराए बिना exec, फ़ाइल सिस्टम टूल, चाइल्ड प्रक्रियाओं और लाइब्रेरी को कवर करती है। जब कोई अनुमत शेल या निर्भरता सीधे फ़ाइलों को एक्सेस कर सकती है, तब होस्ट-साइड पथ अनुमति-सूची वही संपूर्ण सीमा प्रदान नहीं कर सकती।

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

openclaw sandbox recreate --agent research

अन्य बाइंड व्यवहार

agents.defaults.sandbox.docker.binds वैश्विक माउंट कॉन्फ़िगर करता है। प्रारूप वही host:container:mode रूप है (उदाहरण के लिए, "/home/user/source:/source:rw")।

agents.defaults.sandbox.browser.binds अतिरिक्त होस्ट डायरेक्टरियों को केवल सैंडबॉक्स ब्राउज़र कंटेनर में माउंट करता है। सेट किए जाने पर ([] सहित), यह ब्राउज़र कंटेनर के लिए docker.binds को प्रतिस्थापित करता है; छोड़े जाने पर, ब्राउज़र कंटेनर docker.binds पर फ़ॉलबैक करता है।

{  agents: {    defaults: {      sandbox: {        docker: {          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],        },      },    },    list: [      {        id: "build",        sandbox: {          docker: {            binds: ["/mnt/cache:/cache:rw"],          },        },      },    ],  },}

इमेज और सेटअप

डिफ़ॉल्ट Docker इमेज: openclaw-sandbox:bookworm-slim

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'FROM debian:bookworm-slimENV DEBIAN_FRONTEND=noninteractiveRUN apt-get update && apt-get install -y --no-install-recommends \  bash ca-certificates curl git jq python3 ripgrep \  && rm -rf /var/lib/apt/lists/*RUN useradd --create-home --shell /bin/bash sandboxUSER sandboxWORKDIR /home/sandboxCMD ["sleep", "infinity"]DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

डिफ़ॉल्ट रूप से, Docker सैंडबॉक्स कंटेनर बिना नेटवर्क के चलते हैं। agents.defaults.sandbox.docker.network से ओवरराइड करें।

Docker इंस्टॉलेशन और कंटेनरीकृत Gateway यहाँ उपलब्ध हैं: Docker

Docker Gateway डिप्लॉयमेंट के लिए, scripts/docker/setup.sh सैंडबॉक्स कॉन्फ़िगरेशन को बूटस्ट्रैप कर सकता है। उस पथ को सक्षम करने के लिए OPENCLAW_SANDBOX=1 (या true/yes/on) सेट करें। सॉकेट स्थान को OPENCLAW_DOCKER_SOCKET से ओवरराइड करें। पूर्ण सेटअप और पर्यावरण चर संदर्भ: Docker।

setupCommand (एक-बार का कंटेनर सेटअप)

सैंडबॉक्स कंटेनर बनने के बाद setupCommand एक बार चलता है (हर रन पर नहीं)। यह कंटेनर के भीतर sh -lc के माध्यम से निष्पादित होता है।

पथ:

• वैश्विक: agents.defaults.sandbox.docker.setupCommand
• प्रति-एजेंट: agents.entries.*.sandbox.docker.setupCommand

टूल नीति और आपातकालीन निकास

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

tools.elevated एक स्पष्ट आपातकालीन निकास है, जो exec को सैंडबॉक्स के बाहर चलाता है (डिफ़ॉल्ट रूप से gateway, या जब निष्पादन लक्ष्य node हो तब node)। /exec निर्देश केवल अधिकृत प्रेषकों पर लागू होते हैं और प्रत्येक सत्र में बने रहते हैं; exec को पूर्णतः अक्षम करने के लिए टूल नीति में अस्वीकृति का उपयोग करें (सैंडबॉक्स बनाम टूल नीति बनाम उन्नत देखें)।

डीबगिंग:

• openclaw sandbox list सैंडबॉक्स कंटेनर, स्थिति, इमेज मिलान, आयु, निष्क्रिय समय और संबद्ध सत्र/एजेंट दिखाता है।
• openclaw sandbox explain [--session <key>] [--agent <id>] प्रभावी सैंडबॉक्स मोड, होस्ट कार्यक्षेत्र, रनटाइम कार्यशील निर्देशिका, Docker माउंट, टूल नीति और सुधार कॉन्फ़िगरेशन कुंजियों का निरीक्षण करता है। इसका workspaceRoot फ़ील्ड कॉन्फ़िगर किया गया सैंडबॉक्स रूट ही रहता है; effectiveHostWorkspaceRoot दिखाता है कि सक्रिय कार्यक्षेत्र वास्तव में कहाँ स्थित है।
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] कंटेनर/परिवेश हटा देता है, ताकि अगले उपयोग पर वे वर्तमान कॉन्फ़िगरेशन के साथ पुनः बनाए जाएँ।
• “यह क्यों अवरुद्ध है?” को समझने के मानसिक मॉडल के लिए सैंडबॉक्स बनाम टूल नीति बनाम उन्नत देखें।

बहु-एजेंट ओवरराइड

प्रत्येक एजेंट सैंडबॉक्स और टूल को ओवरराइड कर सकता है: agents.entries.*.sandbox और agents.entries.*.tools (साथ ही सैंडबॉक्स टूल नीति के लिए agents.entries.*.tools.sandbox.tools)। प्राथमिकता क्रम के लिए बहु-एजेंट सैंडबॉक्स और टूल देखें।

न्यूनतम सक्षमीकरण उदाहरण

{  agents: {    defaults: {      sandbox: {        mode: "non-main",        scope: "session",        workspaceAccess: "none",      },    },  },}

संबंधित

• बहु-एजेंट सैंडबॉक्स और टूल -- प्रति-एजेंट ओवरराइड और प्राथमिकता क्रम
• OpenShell -- प्रबंधित सैंडबॉक्स बैकएंड सेटअप, कार्यक्षेत्र मोड और कॉन्फ़िगरेशन संदर्भ
• सैंडबॉक्स कॉन्फ़िगरेशन
• सैंडबॉक्स बनाम टूल नीति बनाम उन्नत -- “यह क्यों अवरुद्ध है?” की डीबगिंग
• सुरक्षा