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

​

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

• टूल निष्पादन: 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 ओवरराइड अनदेखे किए जाते हैं)।

​

Docker बैकएंड

​

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

• जब ब्राउज़र टूल को इसकी आवश्यकता होती है, तो सैंडबॉक्स ब्राउज़र स्वतः शुरू होता है (यह सुनिश्चित करता है कि 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 बैकएंड

{
  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" },
        },
      },
    },
  },
}

• जीवनचक्र: 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 बैकएंड

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

​

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

​

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

host-directory:container-directory:ro
host-directory:container-directory:rw

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

{
  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,
          },
        },
      },
    ],
  },
}

openclaw sandbox recreate --agent research

​

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

{
  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"],
          },
        },
      },
    ],
  },
}

​

इमेज और सेटअप

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
FROM debian:bookworm-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN 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 sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["sleep", "infinity"]
DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

​

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

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

​

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

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

​

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

​

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

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

​

संबंधित

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