แซนด์บ็อกซ์

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

สิ่งที่ทำงานในแซนด์บ็อกซ์

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

สิ่งที่ไม่ทำงานในแซนด์บ็อกซ์:

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

โหมด ขอบเขต และแบ็กเอนด์

การตั้งค่าอิสระสามรายการควบคุมลักษณะการทำงานของแซนด์บ็อกซ์:

โหมด ควบคุมว่าจะใช้การแซนด์บ็อกซ์เมื่อใด:

• off: ไม่มีการแซนด์บ็อกซ์
• non-main: แซนด์บ็อกซ์ทุกเซสชันยกเว้นเซสชันหลักของเอเจนต์ คีย์เซสชันหลักคือ agent:<agentId>:main เสมอ (หรือ global เมื่อ session.scope เป็น "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" ค่านี้จะถูกส่งไปยังแฟล็ก --gpus ของ Docker และต้องใช้รันไทม์โฮสต์ที่เข้ากันได้ เช่น NVIDIA Container Toolkit

เบราว์เซอร์ในแซนด์บ็อกซ์

• เบราว์เซอร์แซนด์บ็อกซ์จะเริ่มโดยอัตโนมัติ (เพื่อให้แน่ใจว่าสามารถเข้าถึง CDP ได้) เมื่อเครื่องมือเบราว์เซอร์ต้องใช้งาน กำหนดค่าผ่าน agents.defaults.sandbox.browser.autoStart (ค่าเริ่มต้น true) และ autoStartTimeoutMs (ค่าเริ่มต้น 12 วินาที)
• คอนเทนเนอร์เบราว์เซอร์แซนด์บ็อกซ์ใช้เครือข่าย Docker เฉพาะ (openclaw-sandbox-browser) แทนเครือข่ายส่วนกลาง bridge กำหนดค่าด้วย agents.defaults.sandbox.browser.network
• agents.defaults.sandbox.browser.cdpSourceRange จำกัดการรับส่ง CDP ขาเข้าที่ขอบคอนเทนเนอร์ด้วยรายการ CIDR ที่อนุญาต (ตัวอย่างเช่น 172.21.0.1/32)
• การเข้าถึงตัวสังเกตการณ์ noVNC ได้รับการป้องกันด้วยรหัสผ่านโดยค่าเริ่มต้น OpenClaw จะสร้าง URL โทเค็นอายุสั้นซึ่งให้บริการหน้าบูตสแตรปในเครื่องและเปิด noVNC โดยใส่รหัสผ่านไว้ในส่วนแฟรกเมนต์ของ URL (ไม่ใช่สตริงคำขอหรือบันทึกส่วนหัว)
• agents.defaults.sandbox.browser.allowHostControl (ค่าเริ่มต้น false) อนุญาตให้เซสชันที่อยู่ในแซนด์บ็อกซ์กำหนดเป้าหมายเบราว์เซอร์ของโฮสต์ได้อย่างชัดเจน
• รายการอนุญาตเสริมใช้ควบคุม target: "custom" ได้แก่ allowedControlUrls, allowedControlHosts, allowedControlPorts

แบ็กเอนด์ SSH

ใช้ backend: "ssh" เพื่อแซนด์บ็อกซ์ 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" },        },      },    },  },}

ค่าเริ่มต้น: 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

ใช้ backend: "openshell" เพื่อแซนด์บ็อกซ์เครื่องมือในสภาพแวดล้อมระยะไกลที่จัดการโดย 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", // mirror | 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/prune จะปฏิบัติต่อรันไทม์ OpenShell เช่นเดียวกับรันไทม์ Docker โดยตรรกะการตัดทิ้งจะรับรู้แบ็กเอนด์

สำหรับข้อกำหนดเบื้องต้นทั้งหมด เอกสารอ้างอิงการกำหนดค่า การเปรียบเทียบโหมดพื้นที่ทำงาน และรายละเอียดวงจรชีวิต โปรดดู OpenShell

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

agents.defaults.sandbox.workspaceAccess ควบคุมสิ่งที่แซนด์บ็อกซ์สามารถมองเห็นได้:

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

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

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

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

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

agents.defaults.sandbox.browser.binds เมานต์ไดเรกทอรีเพิ่มเติมจากโฮสต์เข้าไปในคอนเทนเนอร์ เบราว์เซอร์ sandbox เท่านั้น เมื่อตั้งค่า (รวมถึง []) ค่านี้จะแทนที่ 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 sandbox จะทำงานโดย ไม่มีเครือข่าย ลบล้างได้ด้วย agents.defaults.sandbox.docker.network

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

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

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

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

พาธ:

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

นโยบายเครื่องมือและช่องทางหลบออก

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

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

การแก้ไขข้อบกพร่อง:

• openclaw sandbox list แสดงคอนเทนเนอร์ sandbox, สถานะ, ความตรงกันของอิมเมจ, อายุ, เวลาที่ไม่ได้ใช้งาน และเซสชัน/เอเจนต์ที่เชื่อมโยง
• openclaw sandbox explain [--session <key>] [--agent <id>] ตรวจสอบโหมด sandbox ที่มีผล พื้นที่ทำงานบนโฮสต์ ไดเรกทอรีทำงานของรันไทม์ การเมานต์ Docker นโยบายเครื่องมือ และคีย์คอนฟิกสำหรับแก้ไข ฟิลด์ workspaceRoot จะยังคงเป็นราก sandbox ที่กำหนดค่าไว้ ส่วน effectiveHostWorkspaceRoot จะแสดงตำแหน่งจริงของพื้นที่ทำงานที่ใช้งานอยู่
• openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] ลบคอนเทนเนอร์/สภาพแวดล้อม เพื่อให้สร้างขึ้นใหม่ด้วยคอนฟิกปัจจุบันในการใช้งานครั้งถัดไป
• ดู Sandbox เทียบกับนโยบายเครื่องมือเทียบกับสิทธิ์ยกระดับ สำหรับกรอบความคิดในการวิเคราะห์ว่า "เหตุใดสิ่งนี้จึงถูกบล็อก"

การลบล้างสำหรับหลายเอเจนต์

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

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

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

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

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