การดำเนินการกับไฟล์อย่างปลอดภัย

OpenClaw ใช้ @openclaw/fs-safe สำหรับการดำเนินการกับไฟล์ภายในเครื่องที่ไวต่อความปลอดภัย: การอ่าน/เขียนที่จำกัดอยู่ภายในราก, การแทนที่แบบอะตอมมิก, การแตกไฟล์เก็บถาวร, พื้นที่ทำงานชั่วคราว, สถานะ JSON และการจัดการไฟล์ลับ

เป้าหมายคือ แนวป้องกันระดับไลบรารี ที่สม่ำเสมอสำหรับโค้ด OpenClaw ที่เชื่อถือได้ซึ่งรับชื่อพาธที่ไม่น่าเชื่อถือเข้ามา นี่ไม่ใช่แซนด์บ็อกซ์ สิทธิ์ของระบบไฟล์โฮสต์, ผู้ใช้ OS, คอนเทนเนอร์ และนโยบาย agent/tool ยังคงเป็นตัวกำหนดขอบเขตผลกระทบจริง

# ค่าเริ่มต้น: ไม่มีตัวช่วย Python

OpenClaw ตั้งค่าเริ่มต้นให้ตัวช่วย POSIX Python ของ fs-safe เป็น ปิด

เหตุผล:

• Gateway ไม่ควรสร้าง Python sidecar แบบถาวร เว้นแต่ผู้ปฏิบัติงานจะเลือกใช้เอง;
• การติดตั้งจำนวนมากไม่ต้องการการเสริมความแข็งแรงเพิ่มเติมสำหรับการกลายพันธุ์ของไดเรกทอรีแม่;
• การปิดใช้ Python ทำให้พฤติกรรมของแพ็กเกจ/รันไทม์คาดเดาได้มากขึ้นในสภาพแวดล้อมเดสก์ท็อป, Docker, CI และแอปที่บันเดิลมา

OpenClaw เปลี่ยนเฉพาะค่าเริ่มต้นเท่านั้น หากคุณตั้งโหมดไว้อย่างชัดเจน fs-safe จะเคารพค่านั้น:

# Default OpenClaw behavior: Node-only fs-safe fallbacks.
OPENCLAW_FS_SAFE_PYTHON_MODE=off

# Opt into the helper when available, falling back if unavailable.
OPENCLAW_FS_SAFE_PYTHON_MODE=auto

# Fail closed if the helper cannot start.
OPENCLAW_FS_SAFE_PYTHON_MODE=require

# Optional explicit interpreter.
OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3

ชื่อ fs-safe ทั่วไปก็ใช้งานได้เช่นกัน: FS_SAFE_PYTHON_MODE และ FS_SAFE_PYTHON

# สิ่งที่ยังได้รับการป้องกันเมื่อไม่มี Python

เมื่อตัวช่วยปิดอยู่ OpenClaw ยังคงใช้พาธ Node ของ fs-safe สำหรับ:

• ปฏิเสธการหลุดออกจากพาธสัมพัทธ์ เช่น .., พาธสัมบูรณ์ และตัวคั่นพาธในจุดที่อนุญาตเฉพาะชื่อ;
• แก้ไขการดำเนินการผ่านแฮนเดิลรากที่เชื่อถือได้ แทนการตรวจสอบแบบเฉพาะกิจด้วย path.resolve(...).startsWith(...);
• ปฏิเสธรูปแบบ symlink และ hardlink บน API ที่กำหนดนโยบายนี้;
• เปิดไฟล์พร้อมการตรวจสอบอัตลักษณ์ในจุดที่ API ส่งคืนหรือรับเนื้อหาไฟล์;
• เขียนแบบอะตอมมิกผ่านไฟล์ชั่วคราวข้างเคียงสำหรับไฟล์สถานะ/คอนฟิก;
• จำกัดจำนวนไบต์สำหรับการอ่านและการแตกไฟล์เก็บถาวร;
• ใช้โหมดส่วนตัวสำหรับไฟล์ลับและไฟล์สถานะในจุดที่ API กำหนด

การป้องกันเหล่านี้ครอบคลุมโมเดลภัยคุกคามปกติของ OpenClaw: โค้ด Gateway ที่เชื่อถือได้จัดการอินพุตพาธจากโมเดล/Plugin/ช่องทางที่ไม่น่าเชื่อถือ ภายในขอบเขตผู้ปฏิบัติงานเดียวที่เชื่อถือได้

# สิ่งที่ Python เพิ่มเข้ามา

บน POSIX ตัวช่วยเสริมของ fs-safe จะคงกระบวนการ Python แบบถาวรไว้หนึ่งกระบวนการ และใช้การดำเนินการกับระบบไฟล์แบบอ้างอิงสัมพันธ์กับ fd สำหรับการกลายพันธุ์ของไดเรกทอรีแม่ เช่น rename, remove, mkdir, stat/list และพาธการเขียนบางส่วน

สิ่งนี้ลดช่วงเวลา race แบบ same-UID ที่กระบวนการอื่นสามารถสลับไดเรกทอรีแม่ระหว่างการตรวจสอบและการกลายพันธุ์ได้ เป็นการป้องกันเชิงลึกสำหรับโฮสต์ที่กระบวนการภายในเครื่องที่ไม่น่าเชื่อถือสามารถแก้ไขไดเรกทอรีเดียวกับที่ OpenClaw กำลังดำเนินการอยู่

หากการปรับใช้ของคุณมีความเสี่ยงนี้และรับประกันว่ามี Python อยู่ ให้ใช้:

OPENCLAW_FS_SAFE_PYTHON_MODE=require

ใช้ require แทน auto เมื่อตัวช่วยเป็นส่วนหนึ่งของจุดยืนด้านความปลอดภัยของคุณ; auto จะถอยกลับไปใช้พฤติกรรมเฉพาะ Node โดยเจตนาหากตัวช่วยไม่พร้อมใช้งาน

# คำแนะนำสำหรับ Plugin และแกนหลัก

• การเข้าถึงไฟล์ที่หันหน้าให้ Plugin ควรผ่านตัวช่วย openclaw/plugin-sdk/* ไม่ใช่ fs โดยตรง เมื่อพาธมาจากข้อความ, เอาต์พุตของโมเดล, คอนฟิก หรืออินพุตของ Plugin
• โค้ดแกนหลักควรใช้ wrapper fs-safe ภายในเครื่องภายใต้ src/infra/* เพื่อให้นโยบายกระบวนการของ OpenClaw ถูกนำไปใช้อย่างสม่ำเสมอ
• การแตกไฟล์เก็บถาวรควรใช้ตัวช่วยไฟล์เก็บถาวรของ fs-safe พร้อมขีดจำกัดด้านขนาด, จำนวนรายการ, ลิงก์ และปลายทางที่ระบุอย่างชัดเจน
• ความลับควรใช้ตัวช่วยความลับของ OpenClaw หรือตัวช่วยความลับ/สถานะส่วนตัวของ fs-safe; อย่าเขียนการตรวจสอบโหมดรอบ fs.writeFile เอง
• หากคุณต้องการการแยกผู้ใช้ภายในเครื่องที่เป็นศัตรู อย่าพึ่งพา fs-safe เพียงอย่างเดียว ให้รัน Gateway แยกกันภายใต้ผู้ใช้/โฮสต์ OS แยกกัน หรือใช้แซนด์บ็อกซ์

ที่เกี่ยวข้อง: ความปลอดภัย, แซนด์บ็อกซ์, การอนุมัติ Exec, ความลับ.