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ể bổ sung kênh nhắn tin, nhà cung cấp mô hình, phần phụ trợ CLI cục bộ, công cụ tác nhân, 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.19+, Node 23.11+ hoặc Node 24+, 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 đã lấy về chỉ hỗ trợ pnpm vì OpenClaw phát hiện các Plugin đi kèm từ những gói không gian làm việc extensions/*.

Chọn kiểu Plugin

Bắt đầu nhanh

Xây dựng một Plugin công cụ tối giản bằng cách đăng ký một công cụ tác nhân bắt buộc. Đây là kiểu Plugin hữu ích ngắn gọn nhất và bao quát gói, tệp kê khai, điểm vào cũng như 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() }),      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 cần người dùng chủ động đồng ý rõ ràng trước khi OpenClaw tải thời gian chạy của Plugin sở hữu công cụ đó.

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() }),      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 tệp kê khai Plugin:

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

Người dùng chủ động bật bằng tools.allow:

{  tools: { allow: ["workflow_tool"] }, // hoặc ["my-plugin"] cho mọi công cụ từ một 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. Sử dụng yêu cầu quyền của 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 những khả năng không nên được hiển thị theo mặc định. Tên công cụ không được xung đột với tên công cụ lõi; các xung đột sẽ bị bỏ qua và được báo cáo trong chẩn đoán Plugin. Các đăng ký không hợp lệ 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 thích ứng với 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 coi đâ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 đã bị sửa đổi. Các công cụ cục bộ nhạy cảm vẫn phải yêu cầu Plugin hoặc người vận hành chủ động bật rõ ràng và phải từ chối 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ụ đã đăng ký đang hoạt động. Giữ toolMetadata.<tool>.optional: true nhất quán với api.registerTool(..., { optional: true }) để OpenClaw có thể tránh tải 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:

Không nhập từ tệp tổng hợp gốc đã lỗi thời:

Trong gói Plugin của bạn, hãy sử dụng các tệp tổng hợp cục bộ như api.ts và runtime-api.ts cho các phần 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 hàm hỗ trợ dành riêng cho nhà cung cấp nên nằm trong gói nhà cung cấp, trừ khi điểm nối thực sự mang tính tổng quát.

Các phương thức RPC tùy chỉnh của Gateway là một điểm vào nâng cao. Giữ chúng dưới 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"].

Để xem bản đồ nhập đầy đủ, hãy xem Tổng quan về 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 phần nhập đều sử dụng đường dẫn chuyên biệt plugin-sdk/<subpath> OPENCLAW_DOCS_MARKER:calloutClose: