การสร้าง 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": "เพิ่มเครื่องมือแบบกำหนดเองให้ 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() }),      async execute(_id, params) {        return {          content: [{ type: "text", text: `Got: ${params.input}` }],        };      },    });  },});

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() }),      async execute(_id, params) {        return { content: [{ type: "text", text: params.pipeline }] };      },    },    { optional: true },  );}

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

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

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

{  tools: { allow: ["workflow_tool"] }, // หรือ ["my-plugin"] สำหรับเครื่องมือทั้งหมดจาก 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 ตัวช่วยเฉพาะผู้ให้บริการควรอยู่ในแพ็กเกจผู้ให้บริการ เว้นแต่ รอยต่อดังกล่าวจะเป็นแบบทั่วไปอย่างแท้จริง

เมธอด Gateway RPC แบบกำหนดเองเป็นจุดเข้าใช้งานขั้นสูง ให้ใช้คำนำหน้า เฉพาะ 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: