การสร้าง Plugin

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

คุณไม่จำเป็นต้องเพิ่ม Plugin ภายนอกลงในที่เก็บ OpenClaw ให้เผยแพร่ แพ็กเกจไปยัง ClawHub แล้วผู้ใช้ติดตั้งด้วย:

openclaw plugins install clawhub:<package-name>

ข้อกำหนดแพ็กเกจแบบไม่มีคำนำหน้ายังคงติดตั้งจาก npm ระหว่างช่วงเปลี่ยนผ่านการเปิดตัว ใช้คำนำหน้า clawhub: เมื่อต้องการให้แก้ไขแพ็กเกจผ่าน ClawHub

ข้อกำหนด

• Node 22.22.3+, Node 24.15+ หรือ Node 25.9+ และ npm หรือ pnpm
• โมดูล TypeScript ESM
• สำหรับงาน Plugin แบบรวมมากับที่เก็บ ให้โคลนที่เก็บและเรียกใช้ pnpm install การพัฒนา Plugin จากซอร์สที่เช็กเอาต์รองรับเฉพาะ pnpm เนื่องจาก OpenClaw ค้นพบ Plugin แบบรวมมาจากแพ็กเกจเวิร์กสเปซ extensions/*

เลือกรูปแบบ Plugin

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

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

{"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"openclaw": {"extensions": ["./index.ts"],"compat": {"pluginApi": ">=2026.3.24-beta.2","minGatewayVersion": "2026.3.24-beta.2"},"build": {"openclawVersion": "2026.3.24-beta.2","pluginSdkVersion": "2026.3.24-beta.2"}}}

{"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

import { Type } from "typebox";import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Echo one input value",      parameters: Type.Object({ input: Type.String() }),      outputSchema: Type.Object(        { input: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        const details = { input: params.input };        return {          content: [{ type: "text", text: `Got: ${params.input}` }],          details,        };      },    });  },});

openclaw plugins inspect my-plugin --runtime --json

pnpm test extensions/my-plugin/pnpm check

npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

openclaw plugins install clawhub:your-org/your-plugin

การลงทะเบียนเครื่องมือ

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

แฟกทอรีเครื่องมือจะได้รับบริบทรันไทม์ที่เชื่อถือได้ ซึ่งรวมถึง deliveryContext, nativeChannelId สำหรับการสนทนาบนแพลตฟอร์มที่ใช้งานอยู่เมื่อมีให้ใช้งาน และ requesterSenderId

register(api) {  api.registerTool(    {      name: "workflow_tool",      description: "Run a workflow",      parameters: Type.Object({ pipeline: Type.String() }),      outputSchema: Type.Object(        { pipeline: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        return {          content: [{ type: "text", text: params.pipeline }],          details: { pipeline: params.pipeline },        };      },    },    { optional: true },  );}

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

เครื่องมือทุกตัวที่ลงทะเบียนด้วย api.registerTool(...) ต้องประกาศไว้ใน ไฟล์กำกับ Plugin ด้วย:

{  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

ผู้ใช้เลือกเข้าร่วมด้วย tools.allow:

{  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin}

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

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

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

ไฟล์กำกับประกาศความเป็นเจ้าของและการค้นพบ ส่วนการดำเนินการยังคงเรียกใช้ การติดตั้งเครื่องมือที่ลงทะเบียนจริง รักษา toolMetadata.<tool>.optional: true ให้สอดคล้องกับ api.registerTool(..., { optional: true }) เพื่อให้ OpenClaw หลีกเลี่ยง การโหลดรันไทม์ของ Plugin นั้นจนกว่าเครื่องมือจะได้รับอนุญาตอย่างชัดเจน

รูปแบบการนำเข้า

นำเข้าจากเส้นทางย่อย SDK ที่เฉพาะเจาะจง:

ภายในแพ็กเกจ Plugin ของคุณ ให้ใช้ไฟล์บาร์เรลภายในเครื่อง เช่น api.ts และ runtime-api.ts สำหรับการนำเข้าภายใน อย่านำเข้า Plugin ของตนเองผ่าน เส้นทาง SDK ตัวช่วยเฉพาะผู้ให้บริการควรอยู่ในแพ็กเกจผู้ให้บริการ เว้นแต่ รอยต่อดังกล่าวจะเป็นแบบทั่วไปอย่างแท้จริง

เมธอด RPC ของ Gateway แบบกำหนดเองเป็นจุดเข้าใช้งานขั้นสูง ให้ใช้คำนำหน้า เฉพาะ Plugin กับเมธอดเหล่านี้ เนมสเปซผู้ดูแลแกนหลัก เช่น config.*, exec.approvals.*, operator.admin.*, wizard.* และ update.* ยังคงสงวนไว้ และจะแก้ไขเป็น operator.admin บริดจ์ openclaw/plugin-sdk/gateway-method-runtime สงวนไว้สำหรับเส้นทาง HTTP ของ Plugin ที่ประกาศ contracts.gatewayMethodDispatch: ["authenticated-request"]

ดูแผนผังการนำเข้าฉบับเต็มได้ที่ ภาพรวม Plugin SDK

รายการตรวจสอบก่อนส่ง

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json มีข้อมูลเมตา openclaw ที่ถูกต้อง OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s มีไฟล์กำกับ openclaw.plugin.json และถูกต้อง OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s จุดเข้าใช้งานใช้ defineChannelPluginEntry หรือ definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s การนำเข้าทั้งหมดใช้เส้นทาง plugin-sdk/<subpath> ที่เฉพาะเจาะจง OPENCLAW_DOCS_MARKER:calloutClose: