Xây dựng các Plugin

Plugin mở rộng OpenClaw mà không thay đổi phần lõi. Một Plugin có thể thêm kênh nhắn tin, nhà cung cấp mô hình, backend CLI cục bộ, công cụ agent, hook, nhà cung cấp phương tiện, hoặc một năng lực khác do Plugin sở hữu.

Bạn không cần thêm Plugin bên ngoài vào kho lưu trữ OpenClaw. Hãy phát hành gói lên ClawHub và người dùng cài đặt bằng:

openclaw plugins install clawhub:<package-name>

Thông số gói trần vẫn cài đặt từ npm trong giai đoạn chuyển đổi ra mắt. Dùng tiền tố clawhub: khi bạn muốn phân giải qua ClawHub.

Yêu cầu

• Dùng Node 22.19+, Node 23.11+, hoặc Node 24+ và một trình quản lý gói như npm hoặc pnpm.
• Quen thuộc với các mô-đun TypeScript ESM.
• Với công việc trên Plugin đóng gói sẵn trong repo, hãy clone kho lưu trữ và chạy pnpm install. Phát triển Plugin từ source checkout chỉ dùng pnpm vì OpenClaw tải các Plugin đóng gói sẵn từ các gói workspace extensions/*.

Chọn hình dạng Plugin

Khởi động nhanh

Xây dựng một Plugin công cụ tối thiểu bằng cách đăng ký một công cụ agent bắt buộc. Đây là hình dạng Plugin hữu ích ngắn nhất và thể hiện gói, manifest, điểm vào, và bằng chứng cục bộ.

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

Đăng ký công cụ

Công cụ có thể là bắt buộc hoặc tùy chọn. Công cụ bắt buộc luôn khả dụng khi Plugin được bật. Công cụ tùy chọn yêu cầu người dùng chọn tham gia.

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 },  );}

Mọi công cụ được đăng ký bằng api.registerTool(...) cũng phải được khai báo trong manifest Plugin:

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

Người dùng chọn tham gia bằng tools.allow:

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

Công cụ tùy chọn kiểm soát việc một công cụ có được hiển thị cho mô hình hay không. Dùng yêu cầu quyền Plugin khi một công cụ hoặc hook nên yêu cầu phê duyệt sau khi mô hình chọn nó và trước khi hành động chạy.

Dùng công cụ tùy chọn cho tác dụng phụ, binary ít phổ biến, hoặc năng lực không nên được hiển thị theo mặc định. Tên công cụ không được xung đột với công cụ lõi; xung đột sẽ bị bỏ qua và được báo cáo trong chẩn đoán Plugin. Các đăng ký không đúng định dạng, bao gồm bộ mô tả công cụ không có parameters, sẽ bị bỏ qua và được báo cáo theo cùng cách. Công cụ đã đăng ký là các hàm có kiểu mà mô hình có thể gọi sau khi vượt qua kiểm tra chính sách và allowlist.

Factory công cụ nhận một đối tượng ngữ cảnh do runtime cung cấp. Dùng ctx.activeModel khi một công cụ cần ghi log, hiển thị, hoặc thích ứng với mô hình đang hoạt động cho lượt hiện tại. Đối tượng có thể bao gồm provider, modelId, và modelRef. Hãy xem nó là metadata runtime mang tính thông tin, không phải ranh giới bảo mật chống lại operator cục bộ, mã Plugin đã cài đặt, hoặc runtime OpenClaw đã sửa đổi. Công cụ cục bộ nhạy cảm vẫn nên yêu cầu chọn tham gia rõ ràng từ Plugin hoặc operator và fail closed khi metadata active-model bị thiếu hoặc không phù hợp.

Manifest khai báo quyền sở hữu và phát hiện; khi thực thi vẫn gọi phần triển khai công cụ đã đăng ký trực tiếp. Giữ toolMetadata.<tool>.optional: true đồng bộ với api.registerTool(..., { optional: true }) để OpenClaw có thể tránh tải runtime Plugin đó cho đến khi công cụ được đưa vào allowlist rõ ràng.

Quy ước import

Import từ các subpath SDK tập trung:

Không import từ root barrel đã ngừng khuyến nghị:

Trong gói Plugin của bạn, dùng các tệp barrel cục bộ như api.ts và runtime-api.ts cho import nội bộ. Không import chính Plugin của bạn thông qua đường dẫn SDK. Helper chuyên biệt cho nhà cung cấp nên ở lại trong gói nhà cung cấp trừ khi đường nối thực sự có tính tổng quát.

Các phương thức RPC Gateway tùy chỉnh là một điểm vào nâng cao. Giữ chúng trên một tiền tố riêng cho Plugin; các namespace quản trị lõi như config.*, exec.approvals.*, operator.admin.*, wizard.*, và update.* vẫn được dành riêng và phân giải tới operator.admin. Cầu nối openclaw/plugin-sdk/gateway-method-runtime được dành riêng cho các route HTTP của Plugin khai báo contracts.gatewayMethodDispatch: ["authenticated-request"].

Để xem đầy đủ bản đồ import, xem tổng quan Plugin SDK.

Danh sách kiểm tra trước khi gửi

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json có metadata openclaw chính xác OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Manifest openclaw.plugin.json hiện diện và hợp lệ OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Điểm vào dùng defineChannelPluginEntry hoặc definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Mọi import dùng đường dẫn plugin-sdk/<subpath> tập trung OPENCLAW_DOCS_MARKER:calloutClose: