Skip to main content

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.

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, ความลับ.