การแซนด์บ็อกซ์

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 socket (/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 ใช้ SSH transport แกนกลางและ 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 local ยังคงเป็น canonical OpenClaw ซิงก์ไฟล์ local เข้า OpenShell ก่อน exec และซิงก์ workspace ระยะไกลกลับหลัง exec
• remote: workspace OpenShell เป็น canonical หลังจากสร้าง sandbox แล้ว OpenClaw seed workspace ระยะไกลหนึ่งครั้งจาก workspace local จากนั้นเครื่องมือไฟล์และ exec จะทำงานกับ sandbox ระยะไกลโดยตรงโดยไม่ซิงก์การเปลี่ยนแปลงกลับ

โหมดเวิร์กสเปซ

OpenShell มีโมเดลเวิร์กสเปซสองแบบ นี่คือส่วนที่สำคัญที่สุดในการใช้งานจริง

เลือก mirror หากคุณมองว่า sandbox เป็นสภาพแวดล้อมการประมวลผลชั่วคราว เลือก remote หากคุณมองว่า sandbox เป็นเวิร์กสเปซจริง

วงจรชีวิตของ OpenShell

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

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

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

• recreate จะลบเวิร์กสเปซระยะไกล canonical สำหรับขอบเขตนั้น
• การใช้งานครั้งถัดไปจะ seed เวิร์กสเปซระยะไกลใหม่จากเวิร์กสเปซภายในเครื่อง

สำหรับโหมด mirror การสร้างใหม่หลัก ๆ คือรีเซ็ตสภาพแวดล้อมการประมวลผลระยะไกล เพราะเวิร์กสเปซภายในเครื่องยังเป็น canonical อยู่ดี

การเข้าถึงเวิร์กสเปซ

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

เมื่อใช้แบ็กเอนด์ OpenShell:

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

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

การเมานต์ bind แบบกำหนดเอง

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

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

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

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

อิมเมจและการตั้งค่า

อิมเมจ 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

โดยค่าเริ่มต้น คอนเทนเนอร์ sandbox ของ Docker จะรันโดย ไม่มีเครือข่าย แทนที่ด้วย agents.defaults.sandbox.docker.network

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

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

setupCommand (การตั้งค่าคอนเทนเนอร์ครั้งเดียว)

setupCommand ทำงาน ครั้งเดียว หลังจากสร้างคอนเทนเนอร์แซนด์บ็อกซ์แล้ว (ไม่ใช่ทุกครั้งที่รัน) โดยจะทำงานภายในคอนเทนเนอร์ผ่าน sh -lc

พาธ:

• ส่วนกลาง: agents.defaults.sandbox.docker.setupCommand
• รายเอเจนต์: agents.list[].sandbox.docker.setupCommand

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

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

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

การดีบัก:

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

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

การแทนที่สำหรับหลายเอเจนต์

แต่ละเอเจนต์สามารถแทนที่แซนด์บ็อกซ์ + เครื่องมือได้: agents.list[].sandbox และ agents.list[].tools (รวมถึง agents.list[].tools.sandbox.tools สำหรับนโยบายเครื่องมือของแซนด์บ็อกซ์) ดู แซนด์บ็อกซ์และเครื่องมือสำหรับหลายเอเจนต์ สำหรับลำดับความสำคัญ

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

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

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

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