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

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

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

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

ไม่ถูก sandbox:

• process ของ Gateway เอง
• tool ใด ๆ ที่อนุญาตอย่างชัดเจนให้ทำงานนอก sandbox (เช่น tools.elevated)
  • Elevated exec จะข้าม sandboxing และใช้ escape path ที่กำหนดค่าไว้ (gateway โดยค่าเริ่มต้น หรือ node เมื่อ exec target คือ node)
  • หากปิด sandboxing ไว้ tools.elevated จะไม่เปลี่ยนการเรียกใช้ (ทำงานบน host อยู่แล้ว) ดู Elevated Mode

# โหมด

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

# ขอบเขต

agents.defaults.sandbox.scope ควบคุมว่า จะสร้าง container กี่ตัว:

• "agent" (ค่าเริ่มต้น): หนึ่ง container ต่อ agent
• "session": หนึ่ง container ต่อ session
• "shared": หนึ่ง container ที่ใช้ร่วมกันโดย session แบบ sandbox ทั้งหมด

# Backend

agents.defaults.sandbox.backend ควบคุมว่า runtime ใด จะให้ sandbox:

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

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

# การเลือก backend

# Docker backend

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

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

# SSH backend

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

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

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

# โหมด workspace

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

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

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

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

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

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

• การสร้างใหม่จะลบ canonical remote workspace สำหรับ scope นั้น
• การใช้งานครั้งถัดไปจะตั้งต้น remote workspace ใหม่จาก local workspace

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

# การเข้าถึง workspace

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

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

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

สื่อขาเข้าจะถูกคัดลอกเข้า active sandbox workspace (media/inbound/*)

# bind mounts แบบกำหนดเอง

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

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

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

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

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

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

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

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

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

พาธ:

• ส่วนกลาง: agents.defaults.sandbox.docker.setupCommand
• ต่อ agent: agents.list[].sandbox.docker.setupCommand

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

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

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

การดีบัก:

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

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

# การ override แบบหลาย agent

แต่ละ agent สามารถ override sandbox + เครื่องมือได้: 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 — การดีบัก "ทำไมสิ่งนี้ถึงถูกบล็อก?"
• ความปลอดภัย