โครงสร้างภายในของ Plugin

นี่คือเอกสารอ้างอิงสถาปัตยกรรมเชิงลึกสำหรับระบบ Plugin ของ OpenClaw สำหรับคู่มือเชิงปฏิบัติ ให้เริ่มจากหน้าที่เน้นหัวข้อเฉพาะด้านล่าง

โมเดลความสามารถสาธารณะ

ความสามารถคือโมเดลPlugin แบบเนทีฟสาธารณะภายใน OpenClaw Plugin แบบเนทีฟของ OpenClaw แต่ละรายการลงทะเบียนกับประเภทความสามารถอย่างน้อยหนึ่งประเภท:

จุดยืนด้านความเข้ากันได้ภายนอก

โมเดลความสามารถได้รวมเข้ากับแกนหลักแล้วและใช้งานโดย Plugin ที่มาพร้อมระบบ/แบบเนทีฟในปัจจุบัน แต่ความเข้ากันได้ของ Plugin ภายนอกยังต้องใช้เกณฑ์ที่เข้มงวดกว่า "เมื่อ export แล้วจึงถือว่าตรึงไว้"

การลงทะเบียนความสามารถคือทิศทางที่ตั้งใจไว้ hook แบบเดิมยังคงเป็นเส้นทางที่ปลอดภัยที่สุดในการหลีกเลี่ยงความเสียหายสำหรับ Plugin ภายนอกระหว่างการเปลี่ยนผ่าน subpath ของตัวช่วยที่ export แล้วไม่ได้เท่าเทียมกันทั้งหมด — ควรเลือกใช้สัญญาที่มีขอบเขตแคบและจัดทำเอกสารไว้ แทน export ของตัวช่วยที่เกิดขึ้นโดยบังเอิญ

รูปแบบ Plugin

OpenClaw จำแนก Plugin ที่โหลดแต่ละรายการเป็นรูปแบบตามพฤติกรรมการลงทะเบียนจริง (ไม่ใช่เพียง metadata แบบคงที่):

ใช้ openclaw plugins inspect <id> เพื่อดูรูปแบบและรายละเอียดความสามารถของ Plugin ดูรายละเอียดที่เอกสารอ้างอิง CLI

สัญญาณความเข้ากันได้

openclaw doctor, openclaw plugins inspect <id>, openclaw status --all และ openclaw plugins doctor แสดงประกาศความเข้ากันได้เหล่านี้:

ปัจจุบันสัญญาณคำแนะนำ/คำเตือนเหล่านี้ไม่ทำให้ Plugin ของคุณหยุดทำงาน สัญญาณเหล่านี้ยังปรากฏใน openclaw status --all และ openclaw plugins doctor

ภาพรวมสถาปัตยกรรม

ระบบ Plugin ของ OpenClaw มีสี่ชั้น:

สำหรับ CLI ของ Plugin โดยเฉพาะ การค้นหาคำสั่ง root แบ่งเป็นสองระยะ:

• metadata ในเวลา parse มาจาก registerCli(..., { descriptors: [...] })
• โมดูล CLI จริงของ Plugin ยังคงโหลดแบบ lazy และลงทะเบียนเมื่อเรียกใช้ครั้งแรกได้

วิธีนี้ช่วยให้โค้ด CLI ที่ Plugin เป็นเจ้าของอยู่ภายใน Plugin ขณะที่ OpenClaw ยังคงจองชื่อคำสั่ง root ก่อนแยกวิเคราะห์ได้

ขอบเขตการออกแบบที่สำคัญ:

• การตรวจสอบ manifest/config ควรทำงานจาก metadata ของ manifest/schema โดยไม่เรียกใช้โค้ด Plugin
• การค้นหาความสามารถแบบเนทีฟอาจโหลดโค้ด entry ของ Plugin ที่เชื่อถือได้ เพื่อสร้าง snapshot ของ registry ที่ไม่เปิดใช้งาน
• พฤติกรรมรันไทม์แบบเนทีฟมาจาก path register(api) ของโมดูล Plugin พร้อม api.registrationMode === "full"

การแยกนี้ทำให้ OpenClaw ตรวจสอบ config อธิบาย Plugin ที่หายไป/ปิดใช้งาน และสร้างคำแนะนำ UI/schema ได้ก่อนที่รันไทม์เต็มรูปแบบจะทำงาน

snapshot metadata และตารางค้นหาของ Plugin

เมื่อ Gateway เริ่มทำงาน ระบบจะสร้าง PluginMetadataSnapshot หนึ่งรายการสำหรับ snapshot ของ config ปัจจุบัน snapshot นี้มีเฉพาะ metadata โดยจัดเก็บดัชนี Plugin ที่ติดตั้ง, registry ของ manifest, การวินิจฉัย manifest, แผนผังเจ้าของ, ตัวปรับ Plugin id ให้เป็นรูปแบบมาตรฐาน และ record ของ manifest แต่ไม่ได้เก็บโมดูล Plugin ที่โหลดแล้ว, SDK ของผู้ให้บริการ, เนื้อหาแพ็กเกจ หรือ export ของรันไทม์

การตรวจสอบ config ที่รับรู้ Plugin, การเปิดใช้งานอัตโนมัติเมื่อเริ่มระบบ และการเริ่มต้น Plugin ของ Gateway จะใช้ snapshot ดังกล่าว แทนการสร้าง metadata ของ manifest/index ใหม่แยกจากกัน PluginLookUpTable สร้างขึ้นจาก snapshot เดียวกันและเพิ่มแผน Plugin ตอนเริ่มระบบสำหรับ config รันไทม์ปัจจุบัน

หลังจากเริ่มระบบ Gateway จะเก็บ snapshot metadata ปัจจุบันไว้เป็นผลิตผลรันไทม์ที่เปลี่ยนแทนได้ การค้นหาผู้ให้บริการซ้ำระหว่างรันไทม์สามารถยืม snapshot นี้ แทนการสร้างดัชนีที่ติดตั้งและ registry ของ manifest ใหม่ในการประมวลผลแค็ตตาล็อกผู้ให้บริการแต่ละครั้ง snapshot จะถูกล้างหรือเปลี่ยนเมื่อ Gateway ปิดตัว, config/รายการ Plugin เปลี่ยนแปลง และมีการเขียนดัชนีที่ติดตั้ง โดยผู้เรียกจะ fallback ไปยัง path ของ manifest/index แบบ cold เมื่อไม่มี snapshot ปัจจุบันที่เข้ากันได้ การตรวจสอบความเข้ากันได้ต้องรวม root การค้นหา Plugin เช่น plugins.load.paths และ workspace เริ่มต้นของเอเจนต์ เนื่องจาก Plugin ใน workspace เป็นส่วนหนึ่งของขอบเขต metadata

snapshot และตารางค้นหาทำให้การตัดสินใจซ้ำเมื่อเริ่มระบบอยู่บนเส้นทางที่รวดเร็ว:

• ความเป็นเจ้าของช่องทาง
• การเริ่มต้นช่องทางแบบเลื่อนเวลา
• id ของ Plugin ตอนเริ่มระบบ
• ความเป็นเจ้าของผู้ให้บริการและแบ็กเอนด์ CLI
• ความเป็นเจ้าของผู้ให้บริการการตั้งค่า, นามแฝงคำสั่ง, ผู้ให้บริการแค็ตตาล็อกโมเดล และสัญญา manifest
• การตรวจสอบ schema config ของ Plugin และ schema config ของช่องทาง
• การตัดสินใจเปิดใช้งานอัตโนมัติเมื่อเริ่มระบบ

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

กฎแคชมีบันทึกไว้ในรายละเอียดภายในสถาปัตยกรรม Plugin: metadata ของ manifest และการค้นหาจะเป็นข้อมูลล่าสุด เว้นแต่ผู้เรียกจะถือ snapshot, ตารางค้นหา หรือ registry ของ manifest ที่ชัดเจนสำหรับโฟลว์ปัจจุบัน แคช metadata ที่ซ่อนอยู่และ TTL ตามเวลานาฬิกาไม่ใช่ส่วนหนึ่งของการโหลด Plugin มีเพียงแคชตัวโหลดรันไทม์ โมดูล และอาร์ติแฟกต์การขึ้นต่อกันเท่านั้นที่คงอยู่ได้ หลังจากโหลดโค้ดหรืออาร์ติแฟกต์ที่ติดตั้งจริงแล้ว

ผู้เรียกใน cold path บางส่วนยังสร้าง registry ของ manifest ใหม่โดยตรงจากดัชนี Plugin ที่ติดตั้งซึ่งคงอยู่ แทนการรับ PluginLookUpTable ของ Gateway ขณะนี้ path ดังกล่าวจะสร้าง registry ใหม่ตามต้องการ ควรส่งตารางค้นหาปัจจุบันหรือ registry ของ manifest ที่ชัดเจนผ่านโฟลว์รันไทม์เมื่อผู้เรียกมีข้อมูลดังกล่าวอยู่แล้ว

การวางแผนการเปิดใช้งาน

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

ตัววางแผนรักษาความเข้ากันได้กับพฤติกรรม manifest ปัจจุบัน:

• ฟิลด์ activation.* เป็นคำใบ้สำหรับตัววางแผนที่ระบุไว้อย่างชัดเจน
• providers, channels, commandAliases, setup.providers, contracts.tools และฮุกยังคงเป็นทางเลือกสำรองตามความเป็นเจ้าของของแมนิเฟสต์
• API ของตัววางแผนที่รับเฉพาะ ID ยังคงพร้อมใช้งานสำหรับผู้เรียกเดิม
• API แผนจะรายงานป้ายกำกับเหตุผล เพื่อให้การวินิจฉัยแยกแยะคำใบ้ที่ระบุไว้อย่างชัดเจนออกจากทางเลือกสำรองตามความเป็นเจ้าของได้

Plugin ช่องทางและเครื่องมือข้อความที่ใช้ร่วมกัน

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

ขอบเขตปัจจุบันคือ:

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

สำหรับ Plugin ช่องทาง พื้นผิว SDK คือ ChannelMessageActionAdapter.describeMessageTool(...) การเรียกค้นหาแบบรวมนี้ช่วยให้ Plugin ส่งคืนการดำเนินการที่มองเห็นได้ ความสามารถ และส่วนเสริมสคีมาพร้อมกัน เพื่อไม่ให้ส่วนเหล่านี้คลาดเคลื่อนจากกัน

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

เมื่อพารามิเตอร์เครื่องมือข้อความเฉพาะช่องทางมีแหล่งสื่อ เช่น พาธภายในเครื่องหรือ URL สื่อระยะไกล Plugin ควรส่งคืน mediaSourceParams จาก describeMessageTool(...) ด้วย แกนหลักใช้รายการที่ระบุไว้อย่างชัดเจนนี้เพื่อใช้การปรับพาธแซนด์บ็อกซ์ให้เป็นมาตรฐานและคำใบ้การเข้าถึงสื่อขาออก โดยไม่ฮาร์ดโค้ดชื่อพารามิเตอร์ที่ Plugin เป็นเจ้าของ ควรใช้แมปตามขอบเขตการดำเนินการในตำแหน่งนั้น ไม่ใช่รายการแบบแบนรายการเดียวสำหรับทั้งช่องทาง เพื่อไม่ให้พารามิเตอร์สื่อที่ใช้เฉพาะโปรไฟล์ถูกปรับให้เป็นมาตรฐานในการดำเนินการที่ไม่เกี่ยวข้อง เช่น send

แกนหลักส่งขอบเขตรันไทม์เข้าสู่ขั้นตอนการค้นหานั้น ฟิลด์สำคัญประกอบด้วย:

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• requesterSenderId ขาเข้าที่เชื่อถือได้

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

นี่คือเหตุผลที่การเปลี่ยนแปลงการกำหนดเส้นทางของรันเนอร์แบบฝังยังคงเป็นงานของ Plugin: รันเนอร์มีหน้าที่ส่งต่อตัวตนของแชต/เซสชันปัจจุบันไปยังขอบเขตการค้นหาของ Plugin เพื่อให้เครื่องมือ message ที่ใช้ร่วมกันแสดงพื้นผิวที่ช่องทางเป็นเจ้าของอย่างถูกต้องสำหรับรอบปัจจุบัน

สำหรับตัวช่วยการดำเนินการที่ช่องทางเป็นเจ้าของ Plugin ที่รวมมาให้ควรเก็บรันไทม์การดำเนินการไว้ภายในโมดูล Plugin ของตนเอง แกนหลักไม่ได้เป็นเจ้าของรันไทม์การดำเนินการกับข้อความของ Discord, Slack, Telegram หรือ WhatsApp ภายใต้ src/agents/tools อีกต่อไป เราไม่เผยแพร่พาธย่อย plugin-sdk/*-action-runtime แยกต่างหาก และ Plugin ที่รวมมาให้ควรนำเข้าโค้ดรันไทม์ภายในของตนโดยตรงจากโมดูลที่ Plugin เป็นเจ้าของ

ขอบเขตเดียวกันนี้ใช้กับรอยต่อ SDK ที่ตั้งชื่อตามผู้ให้บริการโดยทั่วไป: แกนหลักไม่ควรนำเข้าบาร์เรลอำนวยความสะดวกเฉพาะช่องทางสำหรับ Discord, Signal, Slack, WhatsApp หรือ Plugin ที่คล้ายกัน หากแกนหลักต้องการพฤติกรรมใด ให้ใช้บาร์เรล api.ts / runtime-api.ts ของ Plugin ที่รวมมาให้เอง หรือยกระดับความต้องการนั้นเป็นความสามารถทั่วไปแบบจำกัดขอบเขตใน SDK ที่ใช้ร่วมกัน

Plugin ที่รวมมาให้ปฏิบัติตามกฎเดียวกัน runtime-api.ts ของ Plugin ที่รวมมาให้ไม่ควรส่งออกฟาซาด openclaw/plugin-sdk/<plugin-id> ที่มีแบรนด์ของตนเองซ้ำ ฟาซาดที่มีแบรนด์เหล่านั้นยังคงเป็นชิมความเข้ากันได้สำหรับ Plugin ภายนอกและผู้ใช้รุ่นเก่า แต่ Plugin ที่รวมมาให้ควรใช้การส่งออกภายในร่วมกับพาธย่อย SDK ทั่วไปแบบจำกัดขอบเขต เช่น openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/runtime-store หรือ openclaw/plugin-sdk/webhook-ingress โค้ดใหม่ไม่ควรเพิ่มฟาซาด SDK เฉพาะ ID ของ Plugin เว้นแต่ขอบเขตความเข้ากันได้ของระบบนิเวศภายนอกที่มีอยู่กำหนดให้ต้องมี

สำหรับโพลโดยเฉพาะ มีเส้นทางการดำเนินการสองเส้นทาง:

• outbound.sendPoll เป็นเส้นฐานที่ใช้ร่วมกันสำหรับช่องทางที่สอดคล้องกับโมเดลโพลทั่วไป
• actions.handleAction("poll") เป็นเส้นทางที่แนะนำสำหรับความหมายของโพลเฉพาะช่องทางหรือพารามิเตอร์โพลเพิ่มเติม

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

ดูลำดับการเริ่มต้นทั้งหมดได้ที่ รายละเอียดภายในสถาปัตยกรรม Plugin

โมเดลความเป็นเจ้าของความสามารถ

OpenClaw ถือว่า Plugin แบบเนทีฟเป็นขอบเขตความเป็นเจ้าของสำหรับ บริษัท หรือ ฟีเจอร์ ไม่ใช่ที่รวมการผสานการทำงานที่ไม่เกี่ยวข้องกัน

ซึ่งหมายความว่า:

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

สถานะปลายทางที่ต้องการคือ:

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

นี่คือความแตกต่างสำคัญ:

• Plugin = ขอบเขตความเป็นเจ้าของ
• ความสามารถ = สัญญาของแกนหลักที่ Plugin หลายรายการสามารถนำไปใช้หรือเรียกใช้ได้

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

หากยังไม่มีความสามารถนั้น แนวทางที่ถูกต้องโดยทั่วไปคือ:

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

การแบ่งชั้นความสามารถ

ใช้โมเดลความคิดนี้เมื่อตัดสินใจว่าโค้ดควรอยู่ที่ใด:

ตัวอย่างเช่น TTS มีโครงสร้างดังนี้:

• แกนหลักเป็นเจ้าของนโยบาย TTS ขณะตอบกลับ ลำดับทางเลือกสำรอง ค่ากำหนด และการส่งมอบผ่านช่องทาง
• elevenlabs, google, microsoft และ openai เป็นเจ้าของการนำการสังเคราะห์ไปใช้
• voice-call ใช้ตัวช่วยรันไทม์ TTS สำหรับโทรศัพท์

ควรใช้รูปแบบเดียวกันนี้เป็นหลักสำหรับความสามารถในอนาคต

ตัวอย่าง Plugin บริษัทที่มีหลายความสามารถ

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

  export default definePluginEntry({  id: "exampleai",  name: "ExampleAI",  description: "โมเดลและความสามารถด้านสื่อของ ExampleAI",  register(api) {    api.registerProvider({      id: "exampleai",      // ฮุกการยืนยันตัวตน/แค็ตตาล็อกโมเดล/รันไทม์    });     api.registerSpeechProvider({      id: "exampleai",      // การกำหนดค่าเสียงของผู้จำหน่าย — นำอินเทอร์เฟซ SpeechProviderPlugin ไปใช้โดยตรง    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      describeImage: (req) => exampleAiMedia.describeImage(req),      transcribeAudio: (req) => exampleAiMedia.transcribeAudio(req),      describeVideo: (req) => exampleAiMedia.describeVideo(req),    });     api.registerWebSearchProvider({      id: "exampleai-search",      createTool() {        // ส่งคืนเครื่องมือค้นหาเว็บที่ผู้จำหน่ายเป็นเจ้าของ      },    });  },});

สิ่งสำคัญไม่ใช่ชื่อตัวช่วยที่แน่นอน แต่คือโครงสร้าง:

• Plugin เดียวเป็นเจ้าของพื้นผิวของผู้จำหน่าย
• แกนหลักยังคงเป็นเจ้าของสัญญาความสามารถ
• การแปลคำขอของผู้ให้บริการและตัวช่วย HTTP ยังคงอยู่ใน Plugin ของผู้จำหน่าย
• ช่องทางและ Plugin ฟีเจอร์ใช้ตัวช่วย api.runtime.* ไม่ใช่โค้ดของผู้จำหน่าย
• การทดสอบสัญญาสามารถยืนยันได้ว่า Plugin ลงทะเบียนความสามารถที่ประกาศว่าเป็นเจ้าของแล้ว

ตัวอย่างความสามารถ: การทำความเข้าใจวิดีโอ

OpenClaw ถือว่าการทำความเข้าใจรูปภาพ/เสียง/วิดีโอเป็นความสามารถที่ใช้ร่วมกันหนึ่งรายการอยู่แล้ว โมเดลความเป็นเจ้าของเดียวกันนี้ใช้กับกรณีดังกล่าว:

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

การสร้างวิดีโอใช้ลำดับเดียวกันนี้อยู่แล้ว: core เป็นเจ้าของสัญญาความสามารถแบบมีชนิดและตัวช่วยรันไทม์ ส่วน Plugin ของผู้จำหน่ายจะลงทะเบียนการใช้งาน api.registerVideoGenerationProvider(...) ตามสัญญานั้น

ต้องการรายการตรวจสอบการเปิดใช้งานที่เป็นรูปธรรมหรือไม่? ดู คู่มือความสามารถ

สัญญาและการบังคับใช้

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

เหตุผลที่เรื่องนี้สำคัญ:

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

การบังคับใช้มีสองระดับ:

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

สิ่งที่ควรอยู่ในสัญญา

เมื่อไม่แน่ใจ ให้ยกระดับความเป็นนามธรรม: กำหนดความสามารถก่อน แล้วจึงให้ Plugin เชื่อมต่อเข้ากับความสามารถนั้น

รูปแบบการทำงาน

Plugin แบบเนทีฟของ OpenClaw ทำงาน ภายในโปรเซสเดียวกัน กับ Gateway โดยไม่มีแซนด์บ็อกซ์ Plugin แบบเนทีฟที่โหลดแล้วมีขอบเขตความเชื่อถือระดับโปรเซสเดียวกับโค้ด core

บันเดิลที่เข้ากันได้มีความปลอดภัยกว่าโดยค่าเริ่มต้น เพราะปัจจุบัน OpenClaw ปฏิบัติต่อบันเดิลเหล่านั้นในฐานะแพ็กข้อมูลเมตา/เนื้อหา ในรุ่นปัจจุบัน ส่วนใหญ่หมายถึง Skills ที่รวมมาให้

ใช้รายการอนุญาตและเส้นทางติดตั้ง/โหลดที่ชัดเจนสำหรับ Plugin ที่ไม่ได้รวมมาให้ ปฏิบัติต่อ Plugin ในเวิร์กสเปซในฐานะโค้ดสำหรับช่วงการพัฒนา ไม่ใช่ค่าเริ่มต้นสำหรับการใช้งานจริง

สำหรับชื่อแพ็กเกจเวิร์กสเปซที่รวมมาให้ ให้ยึดรหัส Plugin ตามชื่อ npm: ใช้ @openclaw/<id> โดยค่าเริ่มต้น หรือใช้ส่วนต่อท้ายแบบมีชนิดที่ได้รับอนุมัติ เช่น -provider, -plugin, -speech, -sandbox หรือ -media-understanding เมื่อแพ็กเกจตั้งใจเปิดเผยบทบาท Plugin ที่จำกัดกว่า

ขอบเขตการส่งออก

OpenClaw ส่งออกความสามารถ ไม่ใช่สิ่งอำนวยความสะดวกในการใช้งาน

เปิดเผยการลงทะเบียนความสามารถต่อสาธารณะไว้ และตัดการส่งออกตัวช่วยที่ไม่อยู่ในสัญญาออก:

• พาธย่อยของตัวช่วยเฉพาะ Plugin ที่รวมมาให้
• พาธย่อยของระบบเชื่อมต่อรันไทม์ที่ไม่ได้มีไว้เป็น API สาธารณะ
• ตัวช่วยอำนวยความสะดวกเฉพาะผู้จำหน่าย
• ตัวช่วยการตั้งค่า/การเริ่มต้นใช้งานที่เป็นรายละเอียดการใช้งาน

พาธย่อยของตัวช่วย Plugin ที่รวมมาให้ซึ่งสงวนไว้ถูกยกเลิกจากแผนผังการส่งออก SDK ที่สร้างขึ้นแล้ว เก็บตัวช่วยเฉพาะเจ้าของไว้ภายในแพ็กเกจ Plugin ของเจ้าของนั้น และยกระดับเฉพาะพฤติกรรมโฮสต์ที่นำกลับมาใช้ได้ให้เป็นสัญญา SDK ทั่วไป เช่น plugin-sdk/gateway-runtime, plugin-sdk/security-runtime และความสามารถ API ของ Plugin ที่ฉีดเข้ามา

รายละเอียดภายในและข้อมูลอ้างอิง

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

เนื้อหาที่เกี่ยวข้อง

• การสร้าง Plugin
• ไฟล์ manifest ของ Plugin
• การตั้งค่า Plugin SDK