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

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

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

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

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

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

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

รูปแบบ Plugin

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

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

ฮุกแบบเดิม

ฮุก before_agent_start ยังคงได้รับการรองรับในฐานะเส้นทางความเข้ากันได้สำหรับ Plugin ที่มีเฉพาะฮุก Plugin แบบเดิมที่ใช้งานจริงยังคงพึ่งพาฮุกนี้

ทิศทาง:

• รักษาให้ใช้งานได้
• ระบุในเอกสารว่าเป็นแบบเดิม
• ควรใช้ before_model_resolve สำหรับงานแทนที่โมเดล/ผู้ให้บริการ
• ควรใช้ before_prompt_build สำหรับงานแก้ไขพรอมต์
• นำออกต่อเมื่อการใช้งานจริงลดลงและความครอบคลุมของฟิกซ์เจอร์พิสูจน์ว่าการย้ายมีความปลอดภัยแล้วเท่านั้น

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

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

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

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

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

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

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

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

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

• การตรวจสอบ manifest/การกำหนดค่าควรทำงานได้จาก เมทาดาทา manifest/สคีมา โดยไม่เรียกใช้โค้ด Plugin
• การค้นหาความสามารถแบบเนทีฟอาจโหลดโค้ดจุดเข้าของ Plugin ที่เชื่อถือได้เพื่อสร้างสแนปช็อตรีจิสทรีที่ไม่เปิดใช้งาน
• พฤติกรรมขณะทำงานแบบเนทีฟมาจากพาธ register(api) ของโมดูล Plugin โดยมี api.registrationMode === "full"

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

สแนปช็อตเมทาดาทา Plugin และตารางค้นหา

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

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

หลังจากเริ่มต้น Gateway จะเก็บสแนปช็อตเมทาดาทาปัจจุบันไว้เป็นผลิตผลรันไทม์ที่แทนที่ได้ การค้นหาผู้ให้บริการขณะทำงานซ้ำ ๆ สามารถยืมสแนปช็อตนี้แทนการสร้างดัชนีที่ติดตั้งและรีจิสทรี manifest ใหม่สำหรับการตรวจแค็ตตาล็อกผู้ให้บริการแต่ละครั้ง สแนปช็อตจะถูกล้างหรือแทนที่เมื่อ Gateway ปิดตัว เมื่อการกำหนดค่า/รายการ Plugin เปลี่ยนแปลง และเมื่อมีการเขียนดัชนีที่ติดตั้ง ผู้เรียกจะย้อนกลับไปใช้พาธ manifest/ดัชนีแบบเย็นเมื่อไม่มีสแนปช็อตปัจจุบันที่เข้ากันได้ การตรวจสอบความเข้ากันได้ต้องรวมรากการค้นหา Plugin เช่น plugins.load.paths และเวิร์กสเปซเริ่มต้นของเอเจนต์ เพราะ Plugin ในเวิร์กสเปซเป็นส่วนหนึ่งของขอบเขตเมทาดาทา

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

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

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

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

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

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

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

ตัววางแผนยังคงเข้ากันได้กับพฤติกรรมปัจจุบันของแมนิเฟสต์:

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

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

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

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

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

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

เมื่อพารามิเตอร์เครื่องมือข้อความที่เฉพาะเจาะจงกับช่องทางมีแหล่งสื่อ เช่น พาธภายในเครื่องหรือ 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 ที่เฉพาะเจาะจงกับรหัส 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 มีสัญญาที่ใช้ร่วมกันสำหรับโมเดล เสียง การถอดเสียงแบบเรียลไทม์ เสียงแบบเรียลไทม์ การทำความเข้าใจสื่อ การสร้างรูปภาพ การสร้างวิดีโอ การดึงข้อมูลจากเว็บ และการค้นหาเว็บ ผู้ให้บริการสามารถเป็นเจ้าของพื้นผิวทั้งหมดของตนไว้ในที่เดียว:

    describeImageWithModel,  transcribeOpenAiCompatibleAudio,} from "openclaw/plugin-sdk/media-understanding"; const plugin: OpenClawPluginDefinition = {  id: "exampleai",  name: "ExampleAI",  register(api) {    api.registerProvider({      id: "exampleai",      // auth/model catalog/runtime hooks    });     api.registerSpeechProvider({      id: "exampleai",      // vendor speech config — implement the SpeechProviderPlugin interface directly    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      async describeImage(req) {        return describeImageWithModel({          ...req,          provider: "exampleai",        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          ...req,          provider: "exampleai",        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // credential + fetch logic      }),    );  },}; export default plugin;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

รูปแบบการดำเนินการ

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

บันเดิลที่เข้ากันได้มีความปลอดภัยกว่าโดยค่าเริ่มต้น เนื่องจากปัจจุบัน 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 และ plugin-sdk/plugin-config-runtime

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

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

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

• การสร้าง Plugin
• แมนิเฟสต์ Plugin
• การตั้งค่า SDK ของ Plugin