Skip to main content

การกำหนดค่า Sandbox สำหรับ Bash Tool

เรียนรู้วิธีที่ sandboxed Bash tool ของ Claude Code ให้การแยกระบบไฟล์และเครือข่ายเพื่อการทำงานแบบ agent ที่ปลอดภัยและเป็นอิสระมากขึ้น

Bash sandbox ช่วยให้ Claude รันคำสั่ง shell ส่วนใหญ่ได้โดยไม่ต้องหยุดขอสิทธิ์ แทนที่จะอนุมัติทีละคำสั่ง คุณกำหนดว่าไฟล์และโดเมนเครือข่ายใดที่คำสั่งสามารถเข้าถึงได้ และระบบปฏิบัติการบังคับใช้ขอบเขตนั้นสำหรับคำสั่ง Bash ทุกคำสั่งและ child process ของมัน

หน้านี้ครอบคลุม:

หากต้องการเปรียบเทียบวิธีการแยกอื่น ๆ เช่น dev containers, custom containers และ virtual machines โปรดดู Sandbox environments สำหรับการลดการแจ้งเตือนสิทธิ์สำหรับ tool อื่น ๆ นอกจาก Bash โปรดดู permission modes

เริ่มต้นใช้งาน​

sandbox ถูกสร้างไว้ใน Claude Code และทำงานบน macOS, Linux และ WSL2 Windows แบบ native ไม่รองรับ บน Windows ให้รัน Claude Code ภายใน WSL2 distribution

บน macOS ไม่ต้องติดตั้งอะไรเพิ่มเติม: sandboxing ใช้ Seatbelt framework ที่มีอยู่แล้ว บน Linux และ WSL2 sandbox ต้องใช้สองแพ็คเกจ ครอบคลุมใน Set up Linux and WSL2 แม้ว่ายังไม่ได้ติดตั้ง คุณก็สามารถเริ่มด้วย /sandbox ได้ เพราะแผงจะแสดงว่ามีอะไรขาดอยู่หรือไม่

ขั้นตอนการตั้งค่า​

ขั้นที่ 1: รัน /sandbox

เริ่ม session Claude Code และรันคำสั่ง /sandbox:

/sandbox

ซึ่งจะเปิดแผง sandbox พร้อม 3 แท็บ:

  • Mode: เลือกวิธีอนุมัติคำสั่งใน sandbox
  • Overrides: เลือกว่าคำสั่งที่ล้มเหลวใน sandbox จะถูก fallback ไปรันแบบ unsandboxed หรือไม่
  • Config: ดูการตั้งค่า sandbox ที่ resolve แล้ว

ขั้นที่ 2: เลือก mode

บนแท็บ Mode เลือก auto-allow หรือ regular permissions

ขั้นที่ 3: รันคำสั่ง Bash

ขอให้ Claude รันคำสั่ง เช่น build หรือ test suite

ตั้งค่า Linux และ WSL2​

บน Linux และ WSL2 sandbox ต้องใช้สองแพ็คเกจ:

  • bubblewrap: เครื่องมือ sandboxing แบบ unprivileged ที่บังคับใช้การแยกระบบไฟล์
  • socat: relay สำหรับส่งต่อ traffic เครือข่ายผ่าน sandbox proxy

ติดตั้งด้วย package manager ของ distribution:

# Ubuntu/Debian
sudo apt-get install bubblewrap socat

# Fedora
sudo dnf install bubblewrap socat

โหมด Sandbox​

Claude Code มีสองโหมด sandbox:

Auto-allow mode: คำสั่ง Bash จะพยายามรันใน sandbox และได้รับการอนุมัติอัตโนมัติโดยไม่ต้องขอสิทธิ์

Regular permissions mode: คำสั่ง Bash ทุกคำสั่งผ่านกระบวนการสิทธิ์ปกติ แม้ว่าจะอยู่ใน sandbox

กำหนดค่า Sandboxing​

ปรับแต่งพฤติกรรม sandbox ผ่านไฟล์ settings.json ของคุณ

โดยค่าเริ่มต้น คำสั่งใน sandbox เขียนได้เฉพาะ working directory ปัจจุบันและ session temp directory หากต้องการให้คำสั่งย่อยเช่น kubectl, terraform หรือ npm เขียนนอก directory เหล่านั้น ใช้ sandbox.filesystem.allowWrite:

{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"]
    }
  }
}

ตาราง Path Prefix​

Prefixความหมายตัวอย่าง
/absolute path จาก root/tmp/build ยังคงเป็น /tmp/build
~/relative ต่อ home directory~/.kube กลายเป็น $HOME/.kube
./ หรือไม่มี prefixrelative ต่อ project root สำหรับ project settings./output ใน .claude/settings.json resolve เป็น <project-root>/output

วิธีการทำงานของ Sandboxing​

การแยกระบบไฟล์​

Sandboxed Bash tool จำกัดการเข้าถึงระบบไฟล์:

  • พฤติกรรมการเขียนเริ่มต้น: อ่านและเขียน working directory ปัจจุบันและ subdirectory รวมถึง session temp directory
  • พฤติกรรมการอ่านเริ่มต้น: อ่านได้ทั้งเครื่อง ยกเว้น directory บางแห่งที่ถูก deny
  • การเข้าถึงที่ถูกบล็อก: ไม่สามารถแก้ไขไฟล์นอก working directory และ session temp directory

คำเตือน: โดยค่าเริ่มต้นยังอนุญาตให้อ่านไฟล์ credential เช่น ~/.aws/credentials และ ~/.ssh/ เพิ่มไฟล์เหล่านี้ใน denyRead เพื่อบล็อก

การแยกเครือข่าย​

การเข้าถึงเครือข่ายควบคุมผ่าน proxy server ที่รันนอก sandbox:

  • ข้อจำกัดโดเมน: ไม่มีโดเมนที่อนุญาตไว้ล่วงหน้า ครั้งแรกที่คำสั่งต้องการโดเมนใหม่ Claude Code จะขอการอนุมัติ
  • Managed lockdown: หาก allowManagedDomainsOnly ถูกตั้งค่าใน managed settings โดเมนที่ไม่ได้รับอนุญาตจะถูกบล็อกอัตโนมัติ

วิธีที่ Sandboxing เกี่ยวข้องกับ Permissions และ Permission Modes​

กฎ Permission​

กฎ permission และ sandboxing ควบคุมสิ่งที่แตกต่างกัน:

  • กฎ permission ควบคุมว่า tool ใดที่ Claude Code สามารถใช้ได้
  • Sandboxing ให้การบังคับใช้ระดับ OS ที่จำกัดสิ่งที่คำสั่ง Bash สามารถเข้าถึงได้

ตารางการตั้งค่าและกฎ​

การตั้งค่าหรือกฎสิ่งที่ทำ
sandbox.filesystem.allowWriteให้สิทธิ์ subprocess เขียน path นอก working directory
sandbox.filesystem.denyWrite และ sandbox.filesystem.denyReadบล็อก subprocess จาก path เฉพาะ
sandbox.filesystem.allowReadอนุญาตอ่าน path เฉพาะภายในพื้นที่ที่ถูก deny

กำหนดค่า Sandbox สำหรับองค์กร​

บังคับใช้ Sandboxing ด้วย Managed Settings​

การตั้งค่า managed settings ต่อไปนี้เปิดใช้ sandbox ปฏิเสธที่จะเริ่ม Claude Code หากไม่สามารถ initialize sandbox และป้องกันการ retry คำสั่งนอก sandbox:

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false
  }
}

Custom Proxy Configuration​

สำหรับองค์กรที่ต้องการความปลอดภัยเครือข่ายขั้นสูง:

{
  "sandbox": {
    "network": {
      "httpProxyPort": 8080,
      "socksProxyPort": 8081
    }
  }
}

การแก้ไขปัญหา​

  • คำสั่งล้มเหลวพร้อม host-not-allowed error: CLI tools หลายตัวต้องเข้าถึง host เฉพาะ ให้สิทธิ์เมื่อมีการแจ้งเตือน
  • jest ค้างหรือล้มเหลว: watchman เข้ากันไม่ได้กับ sandbox รัน jest --no-watchman แทน
  • docker commands ล้มเหลว: docker เข้ากันไม่ได้กับ sandbox เพิ่ม docker * ใน excludedCommands

ข้อจำกัด​

ข้อจำกัดด้านความปลอดภัย​

  • Network filtering: proxy ในตัวไม่ terminate หรือ inspect TLS traffic
  • Privilege escalation via Unix sockets: การตั้งค่า allowUnixSockets อาจให้สิทธิ์เข้าถึง system services ที่มีพลัง
  • Filesystem permission escalation: การให้สิทธิ์เขียนกว้างเกินไปอาจเปิดช่องโหว่

ขอบเขต​

Sandbox แยก Bash subprocesses เท่านั้น:

  • Built-in file tools: Read, Edit และ Write ใช้ระบบสิทธิ์โดยตรง ไม่ผ่าน sandbox
  • Computer use: รันบน desktop จริงของคุณ
  • Subagents: รันในกระบวนการเดียวกับ parent session และใช้การตั้งค่า sandbox เดียวกัน

ดูเพิ่มเติม​

  • Sandbox environments: เปรียบเทียบ sandbox ในตัวกับ dev containers, containers และ VMs
  • Security: คุณสมบัติความปลอดภัยและ best practices
  • Permissions: การกำหนดค่าสิทธิ์
  • Settings: เอกสารอ้างอิงการกำหนดค่าแบบสมบูรณ์