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

OpenClaw สามารถเรียกใช้ เครื่องมือภายในแบ็กเอนด์ sandbox เพื่อลดขอบเขตผลกระทบได้ สิ่งนี้เป็น ตัวเลือก และควบคุมด้วยการกำหนดค่า (agents.defaults.sandbox หรือ agents.list[].sandbox) หากปิด sandboxing เครื่องมือจะทำงานบนโฮสต์ Gateway จะยังอยู่บนโฮสต์ ส่วนการเรียกใช้เครื่องมือจะทำงานใน sandbox ที่แยกออกมาเมื่อเปิดใช้งาน

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

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

ไม่ได้ถูก sandbox:

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

โหมด

agents.defaults.sandbox.mode ควบคุมว่าจะใช้ sandboxing เมื่อใด:

ขอบเขต

agents.defaults.sandbox.scope ควบคุมว่าจะสร้าง คอนเทนเนอร์กี่ตัว:

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

แบ็กเอนด์

agents.defaults.sandbox.backend ควบคุมว่า runtime ใด ให้บริการ sandbox:

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

การกำหนดค่าเฉพาะ SSH อยู่ใต้ agents.defaults.sandbox.ssh การกำหนดค่าเฉพาะ OpenShell อยู่ใต้ plugins.entries.openshell.config

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

แบ็กเอนด์ Docker

sandboxing ปิดอยู่โดยค่าเริ่มต้น หากคุณเปิดใช้งาน sandboxing และไม่ได้เลือกแบ็กเอนด์ OpenClaw จะใช้แบ็กเอนด์ Docker ซึ่งเรียกใช้เครื่องมือและเบราว์เซอร์ sandbox ภายในเครื่องผ่านซ็อกเก็ต Docker daemon (/var/run/docker.sock) การแยกคอนเทนเนอร์ sandbox ถูกกำหนดโดย Docker namespaces

หากต้องการเปิดเผย GPU ของโฮสต์ให้ sandbox ของ Docker ตั้งค่า agents.defaults.sandbox.docker.gpus หรือ override ราย agent agents.list[].sandbox.docker.gpus ค่านี้จะถูกส่งให้แฟล็ก --gpus ของ Docker เป็นอาร์กิวเมนต์แยกต่างหาก ตัวอย่างเช่น "all" หรือ "device=GPU-uuid" และต้องใช้ runtime ของโฮสต์ที่เข้ากันได้ เช่น NVIDIA Container Toolkit

แบ็กเอนด์ SSH

ใช้ backend: "ssh" เมื่อคุณต้องการให้ OpenClaw sandbox exec, เครื่องมือไฟล์ และการอ่านสื่อบนเครื่องใดก็ได้ที่เข้าถึงได้ผ่าน 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

ใช้ backend: "openshell" เมื่อคุณต้องการให้ OpenClaw sandbox เครื่องมือในสภาพแวดล้อมระยะไกลที่จัดการโดย OpenShell สำหรับคู่มือการตั้งค่าฉบับเต็ม ข้อมูลอ้างอิงการกำหนดค่า และการเปรียบเทียบโหมด workspace โปรดดู หน้า OpenShell เฉพาะ

OpenShell ใช้ transport SSH หลักและ bridge ระบบไฟล์ระยะไกลเดียวกันกับแบ็กเอนด์ SSH ทั่วไป และเพิ่ม lifecycle เฉพาะ OpenShell (sandbox create/get/delete, sandbox ssh-config) พร้อมโหมด workspace mirror ที่เป็นตัวเลือก

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

โหมด OpenShell:

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

โหมด workspace

OpenShell มีโมเดล workspace สองแบบ นี่คือส่วนที่สำคัญที่สุดในทางปฏิบัติ

เลือก mirror หากคุณมอง sandbox เป็นสภาพแวดล้อมสำหรับการรันงานชั่วคราว เลือก remote หากคุณมอง sandbox เป็นพื้นที่ทำงานจริง

วงจรชีวิต OpenShell

OpenShell sandbox ยังคงถูกจัดการผ่านวงจรชีวิต sandbox ตามปกติ:

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

สำหรับโหมด remote การสร้างใหม่มีความสำคัญเป็นพิเศษ:

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

สำหรับโหมด mirror การสร้างใหม่ส่วนใหญ่จะรีเซ็ตสภาพแวดล้อมการรันงานระยะไกล เพราะพื้นที่ทำงานภายในเครื่องยังคงเป็นแหล่งข้อมูลหลักอยู่แล้ว

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

agents.defaults.sandbox.workspaceAccess ควบคุมว่า sandbox มองเห็นอะไรได้บ้าง:

เมื่อใช้ OpenShell backend:

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

สื่อขาเข้าจะถูกคัดลอกเข้าไปในพื้นที่ทำงาน sandbox ที่ใช้งานอยู่ (media/inbound/*)

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

agents.defaults.sandbox.docker.binds เมานต์ไดเรกทอรีโฮสต์เพิ่มเติมเข้าไปใน container รูปแบบ: host:container:mode (เช่น "/home/user/source:/source:rw")

bind ระดับ global และต่อ agent จะถูก ผสาน กัน (ไม่ใช่แทนที่กัน) ภายใต้ scope: "shared" bind ต่อ agent จะถูกละเว้น

agents.defaults.sandbox.browser.binds เมานต์ไดเรกทอรีโฮสต์เพิ่มเติมเข้าไปใน container sandbox browser เท่านั้น

• เมื่อตั้งค่าไว้ (รวมถึง []) ค่านี้จะแทนที่ 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 และการตั้งค่า

Docker image เริ่มต้น: 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 sandbox container จะรันโดย ไม่มี network แทนที่ได้ด้วย agents.defaults.sandbox.docker.network

การติดตั้ง Docker และ Gateway แบบ container อยู่ที่นี่: Docker

สำหรับการ deploy Docker gateway, scripts/docker/setup.sh สามารถ bootstrap config ของ sandbox ได้ ตั้งค่า OPENCLAW_SANDBOX=1 (หรือ true/yes/on) เพื่อเปิดใช้งาน path นั้น คุณสามารถแทนที่ตำแหน่ง socket ได้ด้วย OPENCLAW_DOCKER_SOCKET การตั้งค่าเต็มรูปแบบและเอกสารอ้างอิง env: Docker

setupCommand (การตั้งค่า container แบบครั้งเดียว)

setupCommand รัน ครั้งเดียว หลังจากสร้าง sandbox container แล้ว (ไม่ใช่ทุกครั้งที่รัน) โดยจะ execute ภายใน container ผ่าน sh -lc

Path:

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

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

นโยบายอนุญาต/ปฏิเสธเครื่องมือยังคงมีผลก่อนกฎ sandbox หากเครื่องมือถูกปฏิเสธแบบทั่วระบบหรือต่อ agent การ sandbox จะไม่นำเครื่องมือนั้นกลับมา

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

การดีบัก:

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

ล็อกให้แน่นหนาไว้

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

แต่ละ agent สามารถ override sandbox + tools ได้: agents.list[].sandbox และ agents.list[].tools (รวมถึง agents.list[].tools.sandbox.tools สำหรับนโยบายเครื่องมือของ sandbox) ดู Sandbox และเครื่องมือสำหรับหลาย Agent สำหรับลำดับความสำคัญ

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

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

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

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