Plugin

Plugin ช่วยขยาย OpenClaw ด้วยช่องทาง ผู้ให้บริการโมเดล ระบบควบคุมเอเจนต์ เครื่องมือ Skills เสียง การถอดเสียงแบบเรียลไทม์ เสียงพูด การทำความเข้าใจสื่อ การสร้างเนื้อหา การดึงข้อมูลเว็บ การค้นหาเว็บ และความสามารถอื่น ๆ ของรันไทม์

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

ข้อกำหนด

• เช็กเอาต์หรือการติดตั้ง OpenClaw ที่พร้อมใช้งาน CLI openclaw
• การเข้าถึงเครือข่ายไปยังแหล่งที่เลือก (ClawHub, npm หรือโฮสต์ git)
• ข้อมูลรับรอง คีย์การกำหนดค่า หรือเครื่องมือระบบปฏิบัติการเฉพาะ Plugin ตามที่ระบุใน เอกสารการตั้งค่าของ Plugin นั้น
• สิทธิ์ในการโหลดซ้ำหรือรีสตาร์ต Gateway ที่ให้บริการช่องทางของคุณ

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

openclaw plugins search "calendar"

# From ClawHub.openclaw plugins install clawhub:<package> # From npm.openclaw plugins install npm:<package> # From git.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # From a local development checkout.openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

openclaw plugins enable <plugin-id>

openclaw gateway restart

openclaw plugins inspect <plugin-id> --runtime --json

การกำหนดค่า

เลือกแหล่งติดตั้ง

ข้อกำหนดแพ็กเกจแบบชื่อเปล่ามีพฤติกรรมความเข้ากันได้เป็นพิเศษ: ชื่อเปล่าที่ ตรงกับรหัส Plugin แบบรวมมากับระบบจะใช้แหล่งแบบรวมมากับระบบนั้น ชื่อเปล่าที่ตรงกับ รหัส Plugin ภายนอกอย่างเป็นทางการจะใช้แค็ตตาล็อกแพ็กเกจอย่างเป็นทางการ ส่วนข้อกำหนด แบบชื่อเปล่าอื่น ๆ จะติดตั้งผ่าน npm ในช่วงการเปลี่ยนผ่านเพื่อเปิดตัว ข้อกำหนด @openclaw/* แบบดิบที่ตรงกับ Plugin แบบรวมมากับระบบจะถูกแก้ไปยังสำเนาที่รวมมากับระบบก่อน การย้อนกลับไปใช้ npm ใช้ npm:@openclaw/<plugin>@<version> เพื่อตั้งใจติดตั้ง แพ็กเกจ npm ภายนอกแทนสำเนาที่รวมมากับระบบ ใช้ clawhub:, npm:, git: หรือ npm-pack: เพื่อเลือกแหล่งที่มาอย่างแน่นอน โปรดดู openclaw plugins สำหรับสัญญาคำสั่งฉบับเต็ม

สำหรับการติดตั้งจาก npm ข้อกำหนดที่ไม่ตรึงเวอร์ชันและ @latest จะเลือก แพ็กเกจเสถียรใหม่ล่าสุดที่ประกาศว่าเข้ากันได้กับบิลด์ OpenClaw นี้ หากรุ่นล่าสุด ปัจจุบันของ npm ประกาศ openclaw.compat.pluginApi หรือ openclaw.install.minHostVersion ที่ใหม่กว่าบิลด์นี้รองรับ OpenClaw จะสแกน เวอร์ชันเสถียรที่เก่ากว่าและติดตั้งเวอร์ชันใหม่ล่าสุดที่ใช้ได้ เวอร์ชันแบบเจาะจง และแท็กช่องทางแบบชัดเจน เช่น @beta จะยังคงตรึงอยู่กับแพ็กเกจที่เลือก และล้มเหลวเมื่อไม่เข้ากัน

นโยบายการติดตั้งของผู้ดำเนินการ

กำหนดค่า security.installPolicy เพื่อเรียกใช้คำสั่งนโยบายภายในเครื่องที่เชื่อถือได้ ก่อนดำเนินการติดตั้งหรืออัปเดต Plugin นโยบายจะได้รับข้อมูลเมตาพร้อม พาธของแหล่งที่มาที่จัดเตรียมไว้ และสามารถอนุญาตหรือบล็อกการติดตั้งได้ โดยครอบคลุมทั้งเส้นทาง การติดตั้งและอัปเดตผ่าน CLI และผ่าน Gateway ฮุก before_install ของ Plugin จะทำงาน ภายหลัง และทำงานเฉพาะในกระบวนการ OpenClaw ที่โหลดฮุกของ Plugin แล้วเท่านั้น ดังนั้นให้ใช้ security.installPolicy สำหรับการตัดสินใจติดตั้งที่ผู้ดำเนินการเป็นเจ้าของแทน แฟล็ก --dangerously-force-unsafe-install ที่เลิกใช้แล้วได้รับการยอมรับเพื่อ ความเข้ากันได้ แต่ไม่ทำสิ่งใด: แฟล็กนี้ไม่ข้ามนโยบายการติดตั้งหรือรายการปฏิเสธ การพึ่งพาของ Plugin ที่มีมาใน OpenClaw

โปรดดู การกำหนดค่า Skills สำหรับสคีมาการดำเนินการ security.installPolicy ที่ใช้ร่วมกันโดย Skills และ Plugin

กำหนดค่านโยบาย Plugin

รูปแบบการกำหนดค่า Plugin ทั่วไปคือ:

{  plugins: {    enabled: true,    allow: ["voice-call"],    deny: ["untrusted-plugin"],    load: { paths: ["~/Projects/oss/voice-call-plugin"] },    slots: { memory: "memory-core" },    entries: {      "voice-call": { enabled: true, config: { provider: "twilio" } },    },  },}

กฎสำคัญของนโยบาย:

• plugins.enabled: false ปิดใช้งาน Plugin ทั้งหมดและข้ามงานค้นหา/โหลด การอ้างอิง Plugin ที่ล้าสมัยจะไม่ทำงานขณะที่ค่านี้มีผล หากต้องการให้ลบรหัสที่ล้าสมัย ให้เปิดใช้งาน Plugin อีกครั้งก่อนเรียกใช้การล้างข้อมูลด้วย doctor
• plugins.deny มีสิทธิ์เหนือรายการอนุญาตและการเปิดใช้งานราย Plugin
• plugins.allow เป็นรายการอนุญาตแบบเฉพาะเจาะจง เครื่องมือที่ Plugin เป็นเจ้าของและอยู่นอก รายการอนุญาตจะยังใช้ไม่ได้ แม้ tools.allow จะมี "*"
• plugins.entries.<id>.enabled: false ปิดใช้งาน Plugin หนึ่งรายการโดยยังเก็บ การกำหนดค่าของ Plugin ไว้
• plugins.load.paths เพิ่มไฟล์หรือไดเรกทอรี Plugin ภายในเครื่องแบบชัดเจน พาธภายในเครื่องที่จัดการโดย plugins install ต้องเป็นไดเรกทอรีหรือ ไฟล์เก็บถาวรของ Plugin ใช้ plugins.load.paths สำหรับไฟล์ Plugin แบบเดี่ยว
• Plugin ที่มาจากเวิร์กสเปซจะถูกปิดใช้งานโดยค่าเริ่มต้น ให้เปิดใช้งานหรือ เพิ่มลงในรายการอนุญาตอย่างชัดเจนก่อนใช้โค้ดจากเวิร์กสเปซภายในเครื่อง
• Plugin แบบรวมมากับระบบจะทำตามข้อมูลเมตาค่าเริ่มต้นเปิด/ปิดที่มีมาในตัว เว้นแต่การกำหนดค่าจะเขียนทับอย่างชัดเจน
• plugins.slots.<slot> (memory หรือ contextEngine) เลือก Plugin หนึ่งรายการสำหรับ หมวดหมู่แบบเฉพาะ การเลือกสล็อตถือเป็นการเปิดใช้งานอย่างชัดเจนและ บังคับเปิด Plugin ที่เลือกสำหรับสล็อตนั้น แม้ตามปกติจะเป็นแบบเลือกรับ plugins.deny และ plugins.entries.<id>.enabled: false ยังคง บล็อก Plugin ได้
• Plugin แบบรวมมากับระบบชนิดเลือกรับสามารถเปิดใช้งานโดยอัตโนมัติเมื่อการกำหนดค่าระบุหนึ่งใน พื้นผิวที่ Plugin นั้นเป็นเจ้าของ เช่น การอ้างอิงผู้ให้บริการ/โมเดล การกำหนดค่าช่องทาง แบ็กเอนด์ CLI หรือรันไทม์ระบบควบคุมเอเจนต์
• การกำหนดเส้นทาง Codex ในตระกูล OpenAI แยกขอบเขตของ Plugin ผู้ให้บริการและรันไทม์ ออกจากกัน: การอ้างอิงโมเดล Codex แบบเดิมคือการกำหนดค่าแบบเดิมที่ doctor ซ่อมแซม ขณะที่ Plugin codex แบบรวมมากับระบบเป็นเจ้าของรันไทม์เซิร์ฟเวอร์แอป Codex สำหรับ การอ้างอิงเอเจนต์ openai/* แบบมาตรฐาน, agentRuntime.id: "codex" แบบชัดเจน และ การอ้างอิง codex/* แบบเดิม

เมื่อไม่ได้ตั้งค่า plugins.allow และระบบค้นพบ Plugin ที่ไม่ได้รวมมากับระบบโดยอัตโนมัติจาก เวิร์กสเปซหรือราก Plugin ส่วนกลาง บันทึกการเริ่มต้นจะแสดง plugins.allow is empty; discovered non-bundled plugins may auto-load: ... พร้อมรหัส Plugin ที่ค้นพบ และสำหรับรายการสั้น ๆ จะแสดงตัวอย่าง plugins.allow ขั้นต่ำ เรียกใช้ openclaw plugins list --enabled --verbose หรือ openclaw plugins inspect <id> กับรหัส Plugin ที่แสดง ก่อนคัดลอก Plugin ที่เชื่อถือได้ลงใน openclaw.json การตรึง ความเชื่อถือลักษณะเดียวกันนี้ใช้เมื่อการวินิจฉัยระบุว่า Plugin โหลด without install/load-path provenance: ตรวจสอบรหัส Plugin นั้น แล้วตรึงไว้ใน plugins.allow หรือติดตั้งใหม่จากแหล่งที่เชื่อถือได้ เพื่อให้ OpenClaw บันทึก แหล่งที่มาของการติดตั้ง

เรียกใช้ openclaw doctor หรือ openclaw doctor --fix เมื่อการตรวจสอบ การกำหนดค่ารายงานรหัส Plugin ที่ล้าสมัย ความไม่สอดคล้องระหว่างรายการอนุญาตกับเครื่องมือ หรือพาธ Plugin แบบรวมมากับระบบรุ่นเดิม

ทำความเข้าใจรูปแบบ Plugin

OpenClaw รองรับ Plugin สองรูปแบบ:

ทั้งสองรูปแบบปรากฏใน openclaw plugins list, openclaw plugins inspect, openclaw plugins enable และ openclaw plugins disable โปรดดู บันเดิล Plugin สำหรับขอบเขตความเข้ากันได้ของบันเดิล และ การสร้าง Plugin สำหรับการเขียน Plugin แบบเนทีฟ

ฮุกของ Plugin

Plugin สามารถลงทะเบียนฮุกระหว่างรันไทม์ผ่าน API สองแบบ:

• ฮุกแบบมีชนิด api.on(...) สำหรับเหตุการณ์วงจรชีวิตของรันไทม์ นี่คือ พื้นผิวที่แนะนำสำหรับมิดเดิลแวร์ นโยบาย การเขียนข้อความใหม่ การปรับรูปแบบพรอมป์ต์ และการควบคุมเครื่องมือ
• api.registerHook(...) สำหรับระบบฮุกภายในที่อธิบายไว้ใน ฮุก โดยหลักใช้สำหรับผลข้างเคียงระดับกว้างของคำสั่ง/วงจรชีวิต และความเข้ากันได้กับระบบอัตโนมัติรูปแบบ HOOK ที่มีอยู่

กฎอย่างย่อ: หากตัวจัดการต้องใช้ลำดับความสำคัญ ความหมายของการผสาน หรือ พฤติกรรมบล็อก/ยกเลิก ให้ใช้ฮุกแบบมีชนิด หากเพียงตอบสนองต่อ command:new, command:reset, message:sent หรือเหตุการณ์ระดับกว้างที่คล้ายกัน ก็ใช้ api.registerHook ได้

ฮุกภายในที่ Plugin จัดการจะแสดงใน openclaw hooks list พร้อม plugin:<id> คุณไม่สามารถเปิดหรือปิดฮุกเหล่านี้ผ่าน openclaw hooks; ให้เปิดหรือปิด Plugin แทน

ตรวจสอบ Gateway ที่ทำงานอยู่

openclaw plugins list และ openclaw plugins inspect แบบปกติจะอ่าน การกำหนดค่า แมนิเฟสต์ และสถานะรีจิสทรีแบบเย็น คำสั่งเหล่านี้ไม่ได้ยืนยันว่า Gateway ที่กำลังทำงานอยู่นำเข้าโค้ด Plugin ชุดเดียวกันแล้ว

เมื่อ Plugin แสดงว่าติดตั้งแล้ว แต่ทราฟฟิกแชตที่ทำงานอยู่ไม่ได้ใช้ Plugin:

openclaw gateway status --deep --require-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

Gateway ที่มีการจัดการจะรีสตาร์ตโดยอัตโนมัติหลังการติดตั้ง อัปเดต และ ถอนการติดตั้ง Plugin ที่ทำให้ซอร์สของ Plugin เปลี่ยนแปลง สำหรับการติดตั้งบน VPS หรือคอนเทนเนอร์ โปรดตรวจสอบให้แน่ใจว่าการรีสตาร์ตด้วยตนเองกำหนดเป้าหมายไปยังโพรเซสลูก openclaw gateway run จริง ที่ให้บริการช่องทางของคุณ ไม่ใช่เพียงแรปเปอร์หรือโปรแกรมควบคุมโพรเซส

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

เมื่อการกำหนดค่า Plugin ที่ล้าสมัยยังคงระบุชื่อ Plugin ช่องทางที่ไม่สามารถค้นพบได้อีกต่อไป การตรวจสอบความถูกต้องของการกำหนดค่าจะลดระดับคีย์ช่องทางนั้นเป็นคำเตือนแทนความล้มเหลวร้ายแรง เพื่อให้การเริ่มต้น Gateway ยังคงให้บริการช่องทางอื่นทั้งหมดได้ เรียกใช้ openclaw doctor --fix เพื่อลบรายการ Plugin และช่องทางที่ล้าสมัย คีย์ ช่องทางที่ไม่รู้จักและไม่มีหลักฐานว่าเกิดจาก Plugin ที่ล้าสมัยจะยังคงทำให้การตรวจสอบล้มเหลว เพื่อให้ ข้อผิดพลาดจากการพิมพ์ยังคงมองเห็นได้

สำหรับการแทนที่ช่องทางโดยเจตนา Plugin ที่ต้องการควรประกาศ channelConfigs.<channel-id>.preferOver พร้อมรหัส Plugin เดิมหรือที่มีลำดับความสำคัญต่ำกว่า หาก Plugin ทั้งสองถูกเปิดใช้งานอย่างชัดเจน OpenClaw จะคงคำขอนั้นไว้ และรายงานข้อความวินิจฉัยช่องทาง/เครื่องมือซ้ำ แทนที่จะเลือก เจ้าของหนึ่งรายโดยไม่แจ้งให้ทราบ

หากแพ็กเกจที่ติดตั้งรายงานว่า requires compiled runtime output for TypeScript entry ... แสดงว่าแพ็กเกจถูกเผยแพร่โดยไม่มีไฟล์ JavaScript ที่ OpenClaw ต้องใช้ขณะรันไทม์ ให้อัปเดตหรือติดตั้งใหม่หลังจากผู้เผยแพร่จัดส่ง JavaScript ที่คอมไพล์แล้ว หรือปิดใช้งาน/ถอนการติดตั้ง Plugin จนกว่าจะดำเนินการเสร็จ

ความเป็นเจ้าของพาธ Plugin ที่ถูกบล็อก

หากข้อความวินิจฉัยระบุว่า blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) และตามด้วยการตรวจสอบความถูกต้องที่ระบุว่า plugin present but blocked แสดงว่า OpenClaw พบ ไฟล์ Plugin ที่เป็นของผู้ใช้ Unix คนละรายกับโพรเซสที่โหลดไฟล์เหล่านั้น ให้คงการกำหนดค่า Plugin ไว้ และแก้ไขความเป็นเจ้าของระบบไฟล์ หรือเรียกใช้ OpenClaw ด้วยผู้ใช้รายเดียวกับที่เป็นเจ้าของไดเรกทอรีสถานะ

สำหรับการติดตั้ง Docker อิมเมจอย่างเป็นทางการทำงานเป็น node (uid 1000) ดังนั้น ไดเรกทอรีการกำหนดค่าและพื้นที่ทำงานของ OpenClaw ที่เมานต์แบบผูกจากโฮสต์ โดยปกติควร เป็นของ uid 1000:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

หากคุณตั้งใจเรียกใช้ OpenClaw เป็น root ให้แก้ไขรูทของ Plugin ที่มีการจัดการให้ เป็นของ root แทน:

sudo chown -R root:root /path/to/openclaw-config/npm

หลังจากแก้ไขความเป็นเจ้าของแล้ว ให้เรียกใช้ openclaw doctor --fix หรือ openclaw plugins registry --refresh อีกครั้ง เพื่อให้รีจิสทรี Plugin ที่จัดเก็บถาวร ตรงกับไฟล์ที่แก้ไขแล้ว

การตั้งค่าเครื่องมือ Plugin ทำงานช้า

หากรอบการทำงานของเอเจนต์ดูเหมือนหยุดค้างระหว่างเตรียมเครื่องมือ ให้เปิดใช้งานการบันทึกแบบติดตาม และตรวจสอบบรรทัดเวลาการทำงานของแฟกทอรีเครื่องมือ Plugin:

openclaw config set logging.level traceopenclaw logs --follow

มองหาข้อความต่อไปนี้:

[trace:plugin-tools] factory timings ...

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

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

หาก Plugin หนึ่งรายการใช้เวลาส่วนใหญ่ ให้ตรวจสอบการลงทะเบียนขณะรันไทม์ของ Plugin นั้น:

openclaw plugins inspect <plugin-id> --runtime --json

จากนั้นอัปเดต ติดตั้งใหม่ หรือปิดใช้งาน Plugin นั้น ผู้เขียน Plugin ควรย้าย การโหลดดีเพนเดนซีที่ใช้ทรัพยากรมากไปไว้หลังเส้นทางการทำงานของเครื่องมือ แทนการดำเนินการ ภายในแฟกทอรีเครื่องมือ

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

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

• จัดการ Plugin - ตัวอย่างคำสั่งสำหรับแสดงรายการ ติดตั้ง อัปเดต ถอนการติดตั้ง และเผยแพร่
• openclaw plugins - เอกสารอ้างอิง CLI ฉบับเต็ม
• รายการ Plugin - รายการ Plugin ที่รวมมาให้และภายนอกซึ่งสร้างขึ้นโดยอัตโนมัติ
• เอกสารอ้างอิง Plugin - หน้าเอกสารอ้างอิงราย Plugin ที่สร้างขึ้นโดยอัตโนมัติ
• Plugin จากชุมชน - การค้นหาผ่าน ClawHub และนโยบาย PR เอกสาร
• การแก้ไขดีเพนเดนซีของ Plugin - รูทการติดตั้ง ระเบียนรีจิสทรี และขอบเขตรันไทม์
• การสร้าง Plugin - คู่มือการเขียน Plugin แบบเนทีฟ
• ภาพรวม SDK ของ Plugin - การลงทะเบียนรันไทม์ ฮุก และฟิลด์ API
• ไฟล์ manifest ของ Plugin - ข้อมูลเมตาของไฟล์ manifest และแพ็กเกจ