Xây dựng Plugin

Các 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ụ tác tử, hook, nhà cung cấp phương tiện hoặc một khả năng 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, sau đó người dùng cài đặt bằng:

openclaw plugins install clawhub:<package-name>

Các đặc tả gói không có tiền tố vẫn được cài đặt từ npm trong giai đoạn chuyển đổi khi ra mắt. Sử dụng tiền tố clawhub: khi bạn muốn phân giải qua ClawHub.

Yêu cầu

• Node 22.22.3+, Node 24.15+ hoặc Node 25.9+, cùng với npm hoặc pnpm.
• Các mô-đun TypeScript ESM.
• Đối với công việc trên plugin đi kèm trong kho lưu trữ, hãy sao chép kho lưu trữ và chạy pnpm install. Việc phát triển plugin từ bản mã nguồn chỉ hỗ trợ pnpm vì OpenClaw phát hiện các plugin đi kèm từ những gói workspace extensions/*.

Chọn dạng plugin

Bắt đầu 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ụ tác tử bắt buộc. Đây là dạng plugin hữu ích ngắn gọn nhất và bao quát gói, tệp kê khai, điểm vào và bước kiểm 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() }),      outputSchema: Type.Object(        { input: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        const details = { input: params.input };        return {          content: [{ type: "text", text: `Got: ${params.input}` }],          details,        };      },    });  },});

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 cần người dùng chủ động chọn dùng trước khi OpenClaw nạp thời gian chạy của plugin sở hữu.

Các hàm tạo công cụ nhận ngữ cảnh thời gian chạy đáng tin cậy, bao gồm deliveryContext, nativeChannelId cho cuộc hội thoại đang hoạt động trên nền tảng khi có sẵn, và requesterSenderId.

register(api) {  api.registerTool(    {      name: "workflow_tool",      description: "Run a workflow",      parameters: Type.Object({ pipeline: Type.String() }),      outputSchema: Type.Object(        { pipeline: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        return {          content: [{ type: "text", text: params.pipeline }],          details: { pipeline: params.pipeline },        };      },    },    { optional: true },  );}

outputSchema là tùy chọn. Nó mô tả giá trị details có cấu trúc được Chế độ mã và Tìm kiếm công cụ sử dụng. Các lệnh gọi danh mục từ chối lược đồ không hợp lệ trước khi thực thi và xác thực giá trị cuối cùng sau các hook công cụ. Bỏ qua trường này đối với công cụ không có kết quả JSON ổn định. Xem Plugin công cụ để biết đầy đủ hợp đồng.

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

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

Người dùng chủ động chọn dùng qua tools.allow:

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

Công cụ tùy chọn kiểm soát việc một công cụ có được cung cấp cho mô hình hay không. Sử dụng yêu cầu quyền plugin khi một công cụ hoặc hook cầ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.

Sử dụng công cụ tùy chọn cho các hiệu ứng phụ, tệp nhị phân ít dùng hoặc khả năng không nên được cung cấp theo mặc định. Tên công cụ không được xung đột với tên 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 lượt đăng ký không đúng định dạng cũng bị bỏ qua và báo cáo theo cùng cách: thiếu name không rỗng, execute không phải hàm hoặc bộ mô tả công cụ không có đối tượng parameters.

Các hàm tạo công cụ nhận một đối tượng ngữ cảnh do thời gian chạy cung cấp. Sử dụng ctx.activeModel khi công cụ cần ghi nhật ký, hiển thị hoặc điều chỉnh theo mô hình đang hoạt động cho lượt hiện tại; đối tượng này có thể bao gồm provider, modelId và modelRef. Hãy xem đây là siêu dữ liệu thời gian chạy mang tính thông tin, không phải ranh giới bảo mật chống lại người vận hành cục bộ, mã plugin đã cài đặt hoặc thời gian chạy OpenClaw đã sửa đổi. Các công cụ cục bộ nhạy cảm vẫn nên yêu cầu plugin hoặc người vận hành chủ động cho phép một cách rõ ràng và từ chối theo hướng an toàn khi siêu dữ liệu mô hình đang hoạt động bị thiếu hoặc không phù hợp.

Tệp kê khai khai báo quyền sở hữu và khả năng phát hiện; việc thực thi vẫn gọi phần triển khai công cụ đang đượ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 nạp thời gian chạy của plugin đó cho đến khi công cụ được đưa rõ ràng vào danh sách cho phép.

Quy ước nhập

Nhập từ các đường dẫn con SDK chuyên biệt:

Trong gói plugin của bạn, sử dụng các tệp barrel cục bộ như api.ts và runtime-api.ts cho các mục nhập nội bộ. Không nhập chính plugin của bạn thông qua đường dẫn SDK. Các trình trợ giúp dành riêng cho nhà cung cấp nên nằm trong gói nhà cung cấp trừ khi ranh giới đó thực sự dùng chung.

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 trong tiền tố dành riêng cho plugin; các không gian tên 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 thành operator.admin. Cầu nối openclaw/plugin-sdk/gateway-method-runtime được dành riêng cho các tuyến HTTP của plugin khai báo contracts.gatewayMethodDispatch: ["authenticated-request"].

Để biết bản đồ nhập đầy đủ, hãy xem Tổng quan SDK Plugin.

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

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json có siêu dữ liệu openclaw chính xác OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Tệp kê khai openclaw.plugin.json hiện diện và hợp lệ OPENCLAW_DOCS_MARKER:calloutClose:

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

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Mọi mục nhập đều sử dụng các đường dẫn plugin-sdk/<subpath> chuyên biệt OPENCLAW_DOCS_MARKER:calloutClose: