การทำงานในแซนด์บ็อกซ์

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

สิ่งที่จะถูก sandbox

• การเรียกใช้เครื่องมือ (exec, read, write, edit, apply_patch, process ฯลฯ)
• เบราว์เซอร์ใน sandbox ที่เป็นตัวเลือก (agents.defaults.sandbox.browser)

• โพรเซส Gateway เอง
• เครื่องมือใดก็ตามที่อนุญาตอย่างชัดเจนให้ทำงานนอก sandbox (เช่น tools.elevated)
  • Elevated exec จะข้าม sandboxing และใช้เส้นทาง escape ที่กำหนดค่าไว้ (gateway โดยค่าเริ่มต้น หรือ node เมื่อเป้าหมาย exec คือ node)
  • หากปิด sandboxing อยู่ tools.elevated จะไม่เปลี่ยนแปลงการเรียกใช้ (อยู่บนโฮสต์อยู่แล้ว) ดู โหมด Elevated

​

โหมด

​

ขอบเขต

• "agent" (ค่าเริ่มต้น): หนึ่งคอนเทนเนอร์ต่อ agent
• "session": หนึ่งคอนเทนเนอร์ต่อเซสชัน
• "shared": หนึ่งคอนเทนเนอร์ที่แชร์โดยทุกเซสชันที่ถูก sandbox

​

แบ็กเอนด์

• "docker" (ค่าเริ่มต้นเมื่อเปิดใช้งาน sandboxing): runtime sandbox ที่รองรับด้วย Docker ภายในเครื่อง
• "ssh": runtime sandbox ระยะไกลทั่วไปที่รองรับด้วย SSH
• "openshell": runtime sandbox ที่รองรับด้วย OpenShell

​

การเลือกแบ็กเอนด์

​

แบ็กเอนด์ Docker

​

แบ็กเอนด์ 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",
          // Or use SecretRefs / inline contents instead of local files:
          // 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" },
        },
      },
    },
  },
}

​

แบ็กเอนด์ OpenShell

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // mirror | remote
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
        },
      },
    },
  },
}

• mirror (ค่าเริ่มต้น): workspace ภายในเครื่องยังคงเป็น canonical OpenClaw จะซิงก์ไฟล์ภายในเครื่องเข้า OpenShell ก่อน exec และซิงก์ workspace ระยะไกลกลับหลัง exec
• remote: workspace ของ OpenShell เป็น canonical หลังจากสร้าง sandbox แล้ว OpenClaw จะ seed workspace ระยะไกลหนึ่งครั้งจาก workspace ภายในเครื่อง จากนั้นเครื่องมือไฟล์และ exec จะทำงานกับ sandbox ระยะไกลโดยตรงโดยไม่ซิงก์การเปลี่ยนแปลงกลับ

​

โหมด workspace

​

วงจรชีวิต OpenShell

• openclaw sandbox list แสดง OpenShell runtime รวมถึง Docker runtime
• openclaw sandbox recreate ลบ runtime ปัจจุบันและให้ OpenClaw สร้างใหม่เมื่อใช้งานครั้งถัดไป
• ตรรกะ prune ก็รับรู้ backend เช่นกัน

• การสร้างใหม่จะลบพื้นที่ทำงานระยะไกลที่เป็นแหล่งข้อมูลหลักสำหรับ scope นั้น
• การใช้งานครั้งถัดไปจะเติมข้อมูลพื้นที่ทำงานระยะไกลใหม่จากพื้นที่ทำงานภายในเครื่อง

​

การเข้าถึงพื้นที่ทำงาน

• โหมด mirror ยังคงใช้พื้นที่ทำงานภายในเครื่องเป็นแหล่งข้อมูลหลักระหว่างเทิร์น exec
• โหมด remote ใช้พื้นที่ทำงาน OpenShell ระยะไกลเป็นแหล่งข้อมูลหลักหลังการเติมข้อมูลเริ่มต้น
• workspaceAccess: "ro" และ "none" ยังคงจำกัดพฤติกรรมการเขียนในแบบเดียวกัน

​

bind mount แบบกำหนดเอง

• เมื่อตั้งค่าไว้ (รวมถึง []) ค่านี้จะแทนที่ agents.defaults.sandbox.docker.binds สำหรับ browser container
• เมื่อละไว้ browser container จะ fallback ไปใช้ agents.defaults.sandbox.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"],
          },
        },
      },
    ],
  },
}

​

Images และการตั้งค่า

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 (การตั้งค่า container แบบครั้งเดียว)

• Global: agents.defaults.sandbox.docker.setupCommand
• ต่อ agent: agents.list[].sandbox.docker.setupCommand

​

นโยบายเครื่องมือและทางออกฉุกเฉิน

• ใช้ openclaw sandbox explain เพื่อตรวจสอบโหมด sandbox ที่มีผลจริง นโยบายเครื่องมือ และคีย์ config สำหรับแก้ไข
• ดู Sandbox เทียบกับนโยบายเครื่องมือเทียบกับ Elevated สำหรับกรอบคิด “ทำไมสิ่งนี้จึงถูกบล็อก?”

​

การ override สำหรับหลาย agent

​

ตัวอย่างเปิดใช้งานขั้นต่ำ

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

​

ที่เกี่ยวข้อง

• Sandbox และเครื่องมือสำหรับหลาย Agent — การ override ราย agent และลำดับความสำคัญ
• OpenShell — การตั้งค่า backend sandbox ที่มีการจัดการ โหมด workspace และเอกสารอ้างอิง config
• การกำหนดค่า Sandbox
• Sandbox เทียบกับนโยบายเครื่องมือเทียบกับ Elevated — การดีบัก “ทำไมสิ่งนี้จึงถูกบล็อก?”
• ความปลอดภัย