Plugin

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

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

ข้อกำหนด

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

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

openclaw plugins search "calendar"

# จาก ClawHubopenclaw plugins install clawhub:<package> # จาก npmopenclaw plugins install npm:<package> # จาก gitopenclaw plugins install git:github.com/<owner>/<repo>@<ref> # จากเช็กเอาต์สำหรับการพัฒนาในเครื่อง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

การกำหนดค่า

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

ข้อกำหนดแพ็กเกจแบบเปล่ามีพฤติกรรมความเข้ากันได้เป็นพิเศษ: ชื่อแบบเปล่าที่ ตรงกับ id ของ Plugin แบบบันเดิลจะใช้แหล่งแบบบันเดิลนั้น ชื่อแบบเปล่าที่ตรงกับ id ของ Plugin ภายนอกอย่างเป็นทางการจะใช้แค็ตตาล็อกแพ็กเกจอย่างเป็นทางการ ส่วน ข้อกำหนดแบบเปล่าอื่นๆ จะติดตั้งผ่าน npm ระหว่างช่วงเปลี่ยนผ่านการเปิดตัว ข้อกำหนด @openclaw/* แบบดิบที่ตรงกับ Plugins แบบบันเดิลจะถูกแก้เป็นสำเนาแบบบันเดิลก่อน ย้อนกลับไปใช้ 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 สำหรับสคีมา exec ของ security.installPolicy ที่ใช้ร่วมกันโดยทั้ง Skills และ Plugins

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

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

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

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

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

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

ฮุกของ Plugin

Plugins สามารถลงทะเบียนฮุกที่รันไทม์ผ่าน 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 แบบธรรมดาจะอ่านการกำหนดค่า สถานะไฟล์ manifest และรีจิสทรีแบบ cold แต่ไม่ได้พิสูจน์ว่า Gateway ที่กำลังทำงานได้นำเข้าโค้ด Plugin เดียวกันแล้ว

เมื่อ Plugin แสดงว่าติดตั้งแล้ว แต่การรับส่งข้อมูลแชตสดไม่ได้ใช้งาน:

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

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

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

เมื่อ Plugin ที่มีการจัดการและเปิดใช้งานอยู่ตรวจสอบเพย์โหลดไม่ผ่านระหว่างการเริ่มต้น Gateway OpenClaw จะกักกันรูทของ Plugin ที่ติดตั้งรายการนั้นโดยเฉพาะสำหรับการบูตครั้งนั้น และให้บริการ Plugin อื่นต่อไป openclaw status --all, openclaw health และ openclaw doctor จะรายงานเป็น configured-unavailable แก้ไขหรือติดตั้ง Plugin ใหม่ แล้วรีสตาร์ต Gateway การแทนที่ plugins.load.paths ที่ระบุอย่างชัดเจนและทำงานปกติซึ่งมีรหัส Plugin เดียวกันจะไม่ถูกกักกันเพราะการติดตั้งเก่าที่เสียหาย

เมื่อการกำหนดค่า 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 ที่ bind mount จากโฮสต์ควรเป็นของ 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 ที่ช้า

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

openclaw config set logging.level traceopenclaw logs --follow

มองหา:

[trace:plugin-tools] เวลาของแฟกทอรี ...

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

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

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

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

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

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

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

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