การสร้าง Plugin

Plugin ขยาย OpenClaw ได้โดยไม่ต้องเปลี่ยน core. Plugin สามารถเพิ่มช่องทางการส่งข้อความ, model provider, backend CLI ภายในเครื่อง, เครื่องมือของเอเจนต์, hook, media provider, หรือความสามารถอื่นที่ Plugin เป็นเจ้าของได้

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

openclaw plugins install clawhub:<package-name>

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

ข้อกำหนด

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

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

Quickstart

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

{"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

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

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

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    }  }}

ผู้ใช้ opt in ด้วย tools.allow:

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

เครื่องมือ optional ควบคุมว่าเครื่องมือจะถูกเปิดเผยต่อ model หรือไม่ ใช้ plugin permission requests เมื่อเครื่องมือ หรือ hook ควรขอการอนุมัติหลังจาก model เลือกแล้วและก่อนที่ action จะทำงาน

ใช้เครื่องมือ optional สำหรับ side effects, binary ที่ไม่ปกติ, หรือความสามารถที่ ไม่ควรถูกเปิดเผยเป็นค่าเริ่มต้น ชื่อเครื่องมือต้องไม่ชนกับเครื่องมือ core; รายการที่ชนจะถูกข้ามและรายงานใน diagnostics ของ Plugin การลงทะเบียนที่ malformed รวมถึง tool descriptors ที่ไม่มี parameters จะถูกข้ามและ รายงานในลักษณะเดียวกัน เครื่องมือที่ลงทะเบียนคือ typed functions ที่ model เรียกใช้ได้ หลังจาก policy และ allowlist checks ผ่านแล้ว

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

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

แบบแผนการ import

Import จาก SDK subpaths ที่เจาะจง:

อย่า import จาก root barrel ที่ deprecated:

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

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

สำหรับ import map ฉบับเต็ม ดู Plugin SDK overview

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 imports ทั้งหมดใช้ path แบบเจาะจง plugin-sdk/<subpath> OPENCLAW_DOCS_MARKER:calloutClose: