OpenShell

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.

​

ข้อกำหนดเบื้องต้น

• ติดตั้ง CLI openshell และอยู่บน PATH (หรือตั้งค่าพาธแบบกำหนดเองผ่าน plugins.entries.openshell.config.command)
• บัญชี OpenShell ที่มีสิทธิ์เข้าถึง sandbox
• OpenClaw Gateway กำลังรันบนโฮสต์

​

เริ่มต้นอย่างรวดเร็ว

1. เปิดใช้ Plugin และตั้งค่าแบ็กเอนด์ sandbox:

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

2. รีสตาร์ท Gateway ในรอบถัดไปของ agent OpenClaw จะสร้าง sandbox OpenShell และส่งการเรียกใช้เครื่องมือผ่าน sandbox นั้น
3. ตรวจสอบ:

openclaw sandbox list
openclaw sandbox explain

​

โหมด workspace

​

mirror

• ก่อน exec OpenClaw จะซิงก์ workspace ในเครื่องเข้าไปยัง sandbox OpenShell
• หลัง exec OpenClaw จะซิงก์ workspace ระยะไกลกลับมายัง workspace ในเครื่อง
• เครื่องมือไฟล์ยังคงทำงานผ่านบริดจ์ sandbox แต่ workspace ในเครื่อง ยังคงเป็นแหล่งข้อมูลจริงระหว่างรอบ

• คุณแก้ไขไฟล์ในเครื่องนอก OpenClaw และต้องการให้การเปลี่ยนแปลงเหล่านั้นปรากฏใน sandbox โดยอัตโนมัติ
• คุณต้องการให้ sandbox OpenShell ทำงานใกล้เคียงกับแบ็กเอนด์ Docker มากที่สุด
• คุณต้องการให้ workspace ของโฮสต์สะท้อนการเขียนใน sandbox หลังแต่ละรอบ exec

​

remote

• เมื่อ sandbox ถูกสร้างครั้งแรก OpenClaw จะ seed workspace ระยะไกลจาก workspace ในเครื่องหนึ่งครั้ง
• หลังจากนั้น exec, read, write, edit และ apply_patch จะทำงาน กับ workspace OpenShell ระยะไกลโดยตรง
• OpenClaw จะไม่ ซิงก์การเปลี่ยนแปลงระยะไกลกลับมายัง workspace ในเครื่อง
• การอ่านสื่อในช่วง prompt ยังคงทำงานได้ เพราะเครื่องมือไฟล์และสื่ออ่านผ่าน บริดจ์ sandbox

• sandbox ควรอยู่ฝั่งระยะไกลเป็นหลัก
• คุณต้องการลดภาระการซิงก์ต่อรอบ
• คุณไม่ต้องการให้การแก้ไขในเครื่องของโฮสต์เขียนทับสถานะ sandbox ระยะไกลโดยไม่รู้ตัว

​

การเลือกโหมด

​

อ้างอิงการตั้งค่า

​

ตัวอย่าง

​

การตั้งค่า remote ขั้นต่ำ

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}

​

โหมด Mirror พร้อม GPU

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "agent",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "mirror",
          gpu: true,
          providers: ["openai"],
          timeoutSeconds: 180,
        },
      },
    },
  },
}

​

OpenShell ต่อ agent พร้อม Gateway แบบกำหนดเอง

{
  agents: {
    defaults: {
      sandbox: { mode: "off" },
    },
    list: [
      {
        id: "researcher",
        sandbox: {
          mode: "all",
          backend: "openshell",
          scope: "agent",
          workspaceAccess: "rw",
        },
      },
    ],
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
          gateway: "lab",
          gatewayEndpoint: "https://lab.example",
          policy: "strict",
        },
      },
    },
  },
}

​

การจัดการวงจรชีวิต

# List all sandbox runtimes (Docker + OpenShell)
openclaw sandbox list

# Inspect effective policy
openclaw sandbox explain

# Recreate (deletes remote workspace, re-seeds on next use)
openclaw sandbox recreate --all

​

เมื่อใดควร recreate

• agents.defaults.sandbox.backend
• plugins.entries.openshell.config.from
• plugins.entries.openshell.config.mode
• plugins.entries.openshell.config.policy

openclaw sandbox recreate --all

​

การเพิ่มความแข็งแกร่งด้านความปลอดภัย

​

ข้อจำกัดปัจจุบัน

• ไม่รองรับเบราว์เซอร์ sandbox บนแบ็กเอนด์ OpenShell
• sandbox.docker.binds ไม่มีผลกับ OpenShell
• ปุ่มปรับแต่ง runtime เฉพาะ Docker ใต้ sandbox.docker.* มีผลเฉพาะกับแบ็กเอนด์ Docker เท่านั้น

​

วิธีทำงาน

1. OpenClaw เรียก openshell sandbox create (พร้อมแฟล็ก --from, --gateway, --policy, --providers, --gpu ตามที่กำหนดค่า)
2. OpenClaw เรียก openshell sandbox ssh-config <name> เพื่อรับรายละเอียดการเชื่อมต่อ SSH สำหรับ sandbox
3. core เขียนการตั้งค่า SSH ไปยังไฟล์ชั่วคราวและเปิดเซสชัน SSH โดยใช้ บริดจ์ระบบไฟล์ระยะไกลเดียวกันกับแบ็กเอนด์ SSH ทั่วไป
4. ในโหมด mirror: ซิงก์จากในเครื่องไปยังระยะไกลก่อน exec, รัน, ซิงก์กลับหลัง exec
5. ในโหมด remote: seed หนึ่งครั้งตอนสร้าง จากนั้นทำงานโดยตรงบน workspace ระยะไกล

​

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

• Sandboxing — โหมด, scope และการเปรียบเทียบแบ็กเอนด์
• Sandbox vs Tool Policy vs Elevated — การดีบักเครื่องมือที่ถูกบล็อก
• Multi-Agent Sandbox and Tools — การ override ต่อ agent
• Sandbox CLI — คำสั่ง openclaw sandbox