การสร้าง Plugin

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

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

openclaw plugins install clawhub:<package-name>

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

ข้อกำหนด

• Node 22.19+, Node 23.11+ หรือ Node 24+ และ 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() }),      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"] }, // 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"]

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

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

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: