การแก้ไขการขึ้นต่อกันของ Plugin

OpenClaw จัดการการขึ้นต่อกันของ Plugin เฉพาะในเวลาติดตั้ง/อัปเดตเท่านั้น การโหลดขณะรันไทม์จะไม่เรียกใช้ตัวจัดการแพ็กเกจ ไม่ซ่อมแซมโครงสร้างการขึ้นต่อกัน และไม่แก้ไขไดเรกทอรีแพ็กเกจของ OpenClaw

การแบ่งความรับผิดชอบ

แพ็กเกจ Plugin เป็นเจ้าของกราฟการขึ้นต่อกันของตนเอง:

• การขึ้นต่อกันขณะรันไทม์อยู่ใน dependencies หรือ optionalDependencies ของแพ็กเกจ Plugin
• การนำเข้าจาก SDK/แกนหลักเป็นการขึ้นต่อกันแบบ peer หรือเป็นการนำเข้าที่ OpenClaw จัดเตรียมให้
• Plugin สำหรับการพัฒนาในเครื่องต้องมีการติดตั้งการขึ้นต่อกันของตนเองไว้แล้ว
• Plugin จาก npm และ git จะติดตั้งลงในรากแพ็กเกจที่ OpenClaw เป็นเจ้าของ

OpenClaw เป็นเจ้าของเฉพาะวงจรชีวิตของ Plugin:

• ค้นหาแหล่งที่มาของ Plugin
• ติดตั้งหรืออัปเดตแพ็กเกจเมื่อมีการร้องขออย่างชัดเจน
• บันทึกข้อมูลเมตาการติดตั้ง
• โหลดจุดเริ่มต้นของ Plugin
• ล้มเหลวพร้อมข้อผิดพลาดที่ระบุวิธีแก้ไขได้เมื่อขาดการขึ้นต่อกัน

รากการติดตั้ง

OpenClaw ใช้รากที่คงที่แยกตามแหล่งที่มา:

• แพ็กเกจ npm ติดตั้งลงในโปรเจกต์แยกต่อ Plugin ภายใต้ ~/.openclaw/npm/projects/<encoded-package>
• แพ็กเกจ git ถูกโคลนไว้ภายใต้ ~/.openclaw/git
• การติดตั้งจากเครื่อง/พาธ/ไฟล์เก็บถาวรจะถูกคัดลอกหรืออ้างอิงโดยไม่มีการซ่อมแซม การขึ้นต่อกัน

การติดตั้ง npm ทำงานในรากโปรเจกต์แยกต่อ Plugin ดังกล่าวด้วย:

cd ~/.openclaw/npm/projects/<encoded-package>npm install --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts --no-audit --no-fund

openclaw plugins install npm-pack:<path.tgz> ใช้รากโปรเจกต์ npm แยกต่อ Plugin เดียวกันสำหรับไฟล์ tarball แบบ npm-pack ในเครื่อง: OpenClaw อ่านข้อมูลเมตา npm ของไฟล์ tarball เพิ่มไฟล์ดังกล่าวลงในโปรเจกต์ที่จัดการในฐานะการขึ้นต่อกันแบบ file: ที่คัดลอกมา เรียกใช้การติดตั้ง npm ตามปกติข้างต้น จากนั้นตรวจสอบข้อมูลเมตาของไฟล์ล็อก ที่ติดตั้งแล้วก่อนเชื่อถือ Plugin พาธนี้มีไว้สำหรับการพิสูจน์การยอมรับแพ็กเกจและ รุ่นผู้สมัครออกเผยแพร่ ซึ่งอาร์ติแฟกต์แพ็กในเครื่องควรทำงานเหมือนอาร์ติแฟกต์จาก รีจิสทรีที่อาร์ติแฟกต์นั้นจำลอง

ใช้ npm-pack: เมื่อทดสอบแพ็กเกจ Plugin อย่างเป็นทางการหรือภายนอกก่อน เผยแพร่ การติดตั้งจากไฟล์เก็บถาวรหรือพาธโดยตรงมีประโยชน์สำหรับการแก้ไขข้อบกพร่อง ในเครื่อง แต่ไม่ได้พิสูจน์พาธการขึ้นต่อกันแบบเดียวกับแพ็กเกจ npm หรือ ClawHub ที่ติดตั้งแล้ว npm-pack: พิสูจน์รูปแบบการติดตั้งแพ็กเกจที่จัดการ แต่โดยตัวมันเอง ไม่ได้พิสูจน์ว่า Plugin เป็นเนื้อหาอย่างเป็นทางการที่เชื่อมโยงกับแค็ตตาล็อก

เมื่อพฤติกรรมขึ้นอยู่กับสถานะ Plugin ที่รวมมาในชุดหรือ Plugin อย่างเป็นทางการ ที่เชื่อถือได้ ให้ใช้การพิสูจน์แพ็กเกจในเครื่องร่วมกับการติดตั้งอย่างเป็นทางการ ที่อ้างอิงแค็ตตาล็อก หรือพาธแพ็กเกจที่เผยแพร่แล้วซึ่งบันทึกความเชื่อถืออย่างเป็นทางการ ควรตรวจสอบสิทธิ์เข้าถึงตัวช่วยพิเศษและการจัดการขอบเขตที่เชื่อถือได้อย่างเป็นทางการ บนพาธการติดตั้งที่เชื่อถือได้นั้น ไม่ใช่อนุมานจากการติดตั้งไฟล์ tarball ในเครื่อง

หาก Plugin ล้มเหลวขณะรันไทม์เนื่องจากขาดการนำเข้า ให้แก้ไขไฟล์ manifest ของแพ็กเกจแทนการซ่อมแซมโปรเจกต์ที่จัดการด้วยตนเอง การนำเข้าขณะรันไทม์ต้องอยู่ใน dependencies หรือ optionalDependencies ของแพ็กเกจ Plugin โดย devDependencies จะไม่ถูกติดตั้งสำหรับโปรเจกต์รันไทม์ที่จัดการ การเรียก npm install ในเครื่องภายใน ~/.openclaw/npm/projects/<encoded-package> อาจช่วยให้การวินิจฉัยชั่วคราว ดำเนินต่อได้ แต่ไม่ใช่หลักฐานการยอมรับแพ็กเกจ เนื่องจากการติดตั้งหรืออัปเดตครั้งถัดไป จะสร้างโปรเจกต์ใหม่จากข้อมูลเมตาของแพ็กเกจ

npm อาจยกระดับการขึ้นต่อกันทางอ้อมไปยัง node_modules ของโปรเจกต์แยกต่อ Plugin ซึ่งอยู่ข้างแพ็กเกจ Plugin OpenClaw สแกนรากโปรเจกต์ที่จัดการก่อนเชื่อถือการติดตั้ง และลบโปรเจกต์นั้นเมื่อถอนการติดตั้ง ดังนั้นการขึ้นต่อกันขณะรันไทม์ที่ถูกยกระดับ จึงยังคงอยู่ภายในขอบเขตการล้างข้อมูลของ Plugin นั้น

แพ็กเกจ Plugin ที่เผยแพร่บน npm สามารถจัดส่ง npm-shrinkwrap.json ได้ โดย npm จะใช้ไฟล์ล็อกที่เผยแพร่ได้นั้นระหว่างการติดตั้ง และรากโปรเจกต์ npm ที่ OpenClaw จัดการรองรับไฟล์ดังกล่าวผ่านพาธการติดตั้งตามปกติ แพ็กเกจ Plugin ที่เผยแพร่ได้ และ OpenClaw เป็นเจ้าของต้องมี shrinkwrap ภายในแพ็กเกจ ซึ่งสร้างจากกราฟ การขึ้นต่อกันที่เผยแพร่ของแพ็กเกจนั้น:

pnpm deps:shrinkwrap:generatepnpm deps:shrinkwrap:check

ตัวสร้างจะตัด devDependencies ของ Plugin ออก ใช้นโยบายการแทนที่ของเวิร์กสเปซ และเขียน extensions/<id>/npm-shrinkwrap.json สำหรับแต่ละ Plugin ที่มี openclaw.release.publishToNpm: true แพ็กเกจ Plugin ของบุคคลที่สามก็สามารถ จัดส่ง shrinkwrap ได้เช่นกัน OpenClaw ไม่กำหนดให้แพ็กเกจจากชุมชนต้องมีไฟล์นี้ แต่ npm จะปฏิบัติตามเมื่อมีไฟล์ดังกล่าว

ก่อนถือว่าแพ็กเกจในเครื่องเป็นหลักฐานสำหรับรุ่นผู้สมัครออกเผยแพร่ ให้ตรวจสอบ ไฟล์ tarball ที่จะติดตั้ง:

npm pack --pack-destination /tmptar -xOf /tmp/<plugin-package>.tgz package/package.jsontar -tf /tmp/<plugin-package>.tgz | grep '^package/dist/'

สำหรับการเปลี่ยนแปลงการขึ้นต่อกัน ให้ตรวจสอบด้วยว่าการติดตั้งสำหรับการใช้งานจริง สามารถค้นหาแพ็กเกจรันไทม์ได้โดยไม่มีการขึ้นต่อกันสำหรับการพัฒนา:

tmpdir=$(mktemp -d)(  cd "$tmpdir"  npm init -y >/dev/null  npm install --package-lock-only --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts /tmp/<plugin-package>.tgz)rm -rf "$tmpdir"

แพ็กเกจ Plugin บน npm ที่ OpenClaw เป็นเจ้าของสามารถเผยแพร่พร้อม bundledDependencies ที่ระบุอย่างชัดเจนได้เช่นกัน พาธการเผยแพร่ npm จะซ้อนทับ รายการชื่อการขึ้นต่อกันขณะรันไทม์ ตัดข้อมูลเมตาเวิร์กสเปซที่ใช้เฉพาะการพัฒนา ออกจากไฟล์ manifest ที่เผยแพร่ เรียกใช้การติดตั้ง npm แบบไม่เรียกสคริปต์ สำหรับการขึ้นต่อกันขณะรันไทม์ภายในแพ็กเกจ จากนั้นแพ็กหรือเผยแพร่ไฟล์ tarball ของ Plugin โดยรวมไฟล์การขึ้นต่อกันเหล่านั้นไว้ด้วย แพ็กเกจที่ใช้ส่วนประกอบเนทีฟ จำนวนมาก (Codex, ACPX, Copilot, llama.cpp, memory-lancedb, Tlon) จะเลือกไม่ใช้ด้วย openclaw.release.bundleRuntimeDependencies: false แพ็กเกจเหล่านี้ยังคงจัดส่ง shrinkwrap แต่ npm จะค้นหาและติดตั้งการขึ้นต่อกัน ขณะรันไทม์ระหว่างการติดตั้ง แทนการฝังไบนารีของทุกแพลตฟอร์มไว้ในไฟล์ tarball ของ Plugin แพ็กเกจราก openclaw จะไม่รวมโครงสร้างการขึ้นต่อกันทั้งหมดของตน

Plugin ที่นำเข้า openclaw/plugin-sdk/* จะประกาศ openclaw เป็นการขึ้นต่อกัน แบบ peer OpenClaw ไม่อนุญาตให้ npm ติดตั้งสำเนาแพ็กเกจโฮสต์อีกชุดจากรีจิสทรี ลงในโปรเจกต์ที่จัดการ เพราะแพ็กเกจโฮสต์ที่ล้าสมัยอาจส่งผลต่อการแก้ไขการขึ้นต่อกัน แบบ peer ของ npm ภายใน Plugin นั้น การติดตั้ง npm ที่จัดการจะข้ามการแก้ไข/ สร้างการขึ้นต่อกันแบบ peer ของ npm และ OpenClaw จะยืนยันลิงก์ node_modules/openclaw ภายใน Plugin อีกครั้งสำหรับแพ็กเกจที่ติดตั้งซึ่งประกาศ โฮสต์แบบ peer หลังการติดตั้งหรืออัปเดต

การติดตั้งจาก git จะโคลนหรือรีเฟรชที่เก็บ แล้วเรียกใช้:

npm install --omit=dev --ignore-scripts --no-audit --no-fund

จากนั้น Plugin ที่ติดตั้งจะโหลดจากไดเรกทอรีแพ็กเกจนั้น ทำให้การค้นหาจาก node_modules ภายในแพ็กเกจและระดับแม่ทำงานในลักษณะเดียวกับแพ็กเกจ Node ปกติ

Plugin ในเครื่อง

Plugin ในเครื่องคือไดเรกทอรีที่ผู้พัฒนาควบคุม OpenClaw จะไม่เรียกใช้ npm install, pnpm install หรือซ่อมแซมการขึ้นต่อกันให้ Plugin เหล่านี้ หาก Plugin ในเครื่องมีการขึ้นต่อกัน ให้ติดตั้งภายใน Plugin นั้นก่อนโหลด

Plugin TypeScript ของบุคคลที่สามในเครื่องจะโหลดผ่าน Jiti เป็นพาธฉุกเฉิน ส่วน Plugin JavaScript ที่จัดเป็นแพ็กเกจและ Plugin ภายในที่รวมมาในชุด จะโหลดผ่าน import/require แบบเนทีฟแทน

การเริ่มทำงานและการโหลดซ้ำ

การเริ่มทำงานของ Gateway และการโหลดการกำหนดค่าใหม่จะไม่ติดตั้งการขึ้นต่อกัน ของ Plugin โดยจะอ่านบันทึกการติดตั้ง Plugin คำนวณจุดเริ่มต้น และโหลดจุดดังกล่าว

การขาดการขึ้นต่อกันขณะรันไทม์จะทำให้การโหลด Plugin ล้มเหลว พร้อมข้อผิดพลาด ที่ชี้ให้ผู้ดูแลระบบดำเนินการแก้ไขอย่างชัดเจน:

openclaw plugins update <id>openclaw plugins install <source>openclaw doctor --fix

doctor --fix จะล้างสถานะการขึ้นต่อกันแบบเดิมที่ OpenClaw สร้างขึ้น และสามารถ กู้คืน Plugin ที่ดาวน์โหลดได้ซึ่งหายไปจากบันทึกการติดตั้งในเครื่อง เมื่อการกำหนดค่า ยังคงอ้างอิง Plugin เหล่านั้น Doctor จะไม่ซ่อมแซมการขึ้นต่อกันของ Plugin ในเครื่อง ที่ติดตั้งอยู่แล้ว

Plugin ที่รวมมาในชุด

Plugin ที่มีขนาดเล็กและสำคัญต่อแกนหลักจะจัดส่งเป็นส่วนหนึ่งของ OpenClaw Plugin เหล่านี้ควรไม่มีโครงสร้างการขึ้นต่อกันขณะรันไทม์ขนาดใหญ่ หรือย้ายออกไป เป็นแพ็กเกจที่ดาวน์โหลดได้บน ClawHub/npm

สำหรับรายการที่สร้างขึ้นในปัจจุบันของ Plugin ที่จัดส่งในแพ็กเกจแกนหลัก ติดตั้งจากภายนอก หรือคงไว้เฉพาะซอร์ส โปรดดู รายการ Plugin

ไฟล์ manifest ของ Plugin ที่รวมมาในชุดต้องไม่ร้องขอการจัดเตรียมการขึ้นต่อกัน ความสามารถของ Plugin ที่มีขนาดใหญ่หรือเป็นทางเลือกควรถูกจัดเป็น Plugin ปกติ และติดตั้งผ่านพาธ npm/git/ClawHub เดียวกับ Plugin ของบุคคลที่สาม

ในเช็กเอาต์ซอร์ส OpenClaw จะถือว่าที่เก็บเป็น pnpm monorepo หลังจาก pnpm install Plugin ที่รวมมาในชุดจะโหลดจาก extensions/<id> เพื่อให้ การขึ้นต่อกันของเวิร์กสเปซภายในแพ็กเกจพร้อมใช้งาน และการแก้ไขถูกนำมาใช้โดยตรง การพัฒนาจากเช็กเอาต์ซอร์สรองรับเฉพาะ pnpm เท่านั้น การเรียก npm install โดยตรงที่รากของที่เก็บจะไม่เตรียมการขึ้นต่อกันของ Plugin ที่รวมมาในชุด

การล้างข้อมูลแบบเดิม

OpenClaw รุ่นเก่าสร้างรากการขึ้นต่อกันของ Plugin ที่รวมมาในชุดเมื่อเริ่มทำงาน หรือระหว่างการซ่อมแซมโดย Doctor การล้างข้อมูลของ Doctor ในปัจจุบันจะลบ ไดเรกทอรีและ symlink ที่ล้าสมัยเหล่านั้นด้วย --fix รวมถึงราก plugin-runtime-deps แบบเก่า, symlink แพ็กเกจในคำนำหน้าส่วนกลางของ Node ที่ชี้ไปยังเป้าหมาย plugin-runtime-deps ซึ่งถูกตัดออก, ไฟล์ manifest .openclaw-runtime-deps*, node_modules ของ Plugin ที่สร้างขึ้น, ไดเรกทอรีขั้นตอนการติดตั้ง และที่เก็บ pnpm ภายในแพ็กเกจ ขั้นตอนหลังการติดตั้งของแพ็กเกจจะลบ symlink ส่วนกลางเหล่านั้นก่อนตัดรากเป้าหมาย แบบเดิมออกด้วย เพื่อให้การอัปเกรดไม่ทิ้งการนำเข้าแพ็กเกจ ESM ที่ชี้ไปยัง เป้าหมายซึ่งไม่มีอยู่

การติดตั้ง npm รุ่นเก่ายังใช้ราก ~/.openclaw/npm/node_modules ร่วมกัน ขั้นตอนติดตั้ง อัปเดต ถอนการติดตั้ง และ Doctor ในปัจจุบันยังคงรู้จักรากแบบแบน เดิมนี้เพื่อการกู้คืนและล้างข้อมูลเท่านั้น การติดตั้ง npm ใหม่จะสร้างรากโปรเจกต์ แยกต่อ Plugin แทน