การสร้าง Plugin

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

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

openclaw plugins install clawhub:<package-name>

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

ข้อกำหนด

• ใช้ Node 22.19 หรือใหม่กว่า และตัวจัดการแพ็กเกจ เช่น npm หรือ pnpm
• คุ้นเคยกับโมดูล TypeScript ESM
• สำหรับงาน Plugin ที่ bundled อยู่ใน repo ให้ clone repository แล้วรัน pnpm install การพัฒนา Plugin จาก source checkout ใช้ได้เฉพาะ pnpm เท่านั้น เพราะ OpenClaw โหลด Plugin ที่ bundled จากแพ็กเกจ workspace ใน extensions/*

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

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

สร้าง Plugin เครื่องมือแบบน้อยที่สุดโดยลงทะเบียนเครื่องมือของเอเจนต์ที่จำเป็นหนึ่งรายการ นี่คือ รูปแบบ Plugin ที่สั้นที่สุดแต่ยังมีประโยชน์ และแสดงแพ็กเกจ, manifest, entry point และ หลักฐานในเครื่อง

{"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","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

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

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

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

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

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(...) ต้องประกาศใน manifest ของ Plugin ด้วย:

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

ผู้ใช้เลือกเปิดใช้ด้วย tools.allow:

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

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

ใช้เครื่องมือที่ไม่บังคับสำหรับ side effect, binary ที่ไม่ปกติ หรือความสามารถที่ ไม่ควรถูกเปิดเผยโดยค่าเริ่มต้น ชื่อเครื่องมือต้องไม่ชนกับเครื่องมือ core; รายการที่ชนกันจะถูกข้ามและรายงานใน diagnostics ของ Plugin การลงทะเบียนที่มีรูปแบบผิด รวมถึง descriptor ของเครื่องมือที่ไม่มี parameters จะถูกข้ามและ รายงานแบบเดียวกัน เครื่องมือที่ลงทะเบียนคือฟังก์ชันที่มี type ซึ่งโมเดลเรียกได้ หลังจากผ่านการตรวจสอบ policy และ allowlist แล้ว

factory ของเครื่องมือจะได้รับออบเจ็กต์ context ที่ runtime ส่งให้ ใช้ ctx.activeModel เมื่อเครื่องมือต้อง log, แสดงผล หรือปรับให้เข้ากับโมเดลที่ active สำหรับ turn ปัจจุบัน ออบเจ็กต์นี้อาจมี provider, modelId และ modelRef ให้ถือว่าเป็น metadata runtime เพื่อข้อมูลเท่านั้น ไม่ใช่ขอบเขตความปลอดภัยต่อ operator ในเครื่อง, โค้ด Plugin ที่ติดตั้งแล้ว หรือ runtime ของ OpenClaw ที่ถูกแก้ไข เครื่องมือในเครื่องที่อ่อนไหว ยังควรกำหนดให้ต้องมีการ opt-in จาก Plugin หรือ operator อย่างชัดเจน และ fail closed เมื่อ metadata ของ active-model ขาดหายหรือไม่เหมาะสม

manifest ประกาศความเป็นเจ้าของและการค้นพบ; การรันยังคงเรียก implementation ของเครื่องมือที่ลงทะเบียนแบบ live รักษา toolMetadata.<tool>.optional: true ให้สอดคล้องกับ api.registerTool(..., { optional: true }) เพื่อให้ OpenClaw หลีกเลี่ยง การโหลด runtime ของ Plugin นั้นจนกว่าเครื่องมือจะถูกเพิ่มเข้า allowlist อย่างชัดเจน

ข้อกำหนดการ import

Import จาก subpath ของ SDK ที่เจาะจง:

อย่า import จาก root barrel ที่ deprecated แล้ว:

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

เมธอด RPC ของ Gateway แบบกำหนดเองเป็น entry point ขั้นสูง เก็บไว้ภายใต้ คำนำหน้าเฉพาะ Plugin; namespace ของ core admin เช่น config.*, exec.approvals.*, operator.admin.*, wizard.* และ update.* ยังคงถูกสงวนไว้ และ resolve ไปยัง operator.admin bridge openclaw/plugin-sdk/gateway-method-runtime ถูกสงวนไว้สำหรับ route HTTP ของ Plugin ที่ประกาศ contracts.gatewayMethodDispatch: ["authenticated-request"]

สำหรับแผนที่ import ฉบับเต็ม ดู ภาพรวม Plugin SDK

Checklist ก่อนส่ง

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

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s มี manifest openclaw.plugin.json และถูกต้อง OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Entry point ใช้ defineChannelPluginEntry หรือ definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Import ทั้งหมดใช้ path แบบเจาะจง plugin-sdk/<subpath> OPENCLAW_DOCS_MARKER:calloutClose: