Xây dựng Plugin

Plugins mở rộng OpenClaw với các năng lực mới: kênh, nhà cung cấp mô hình, giọng nói, phiên âm thời gian thực, thoại thời gian thực, hiểu nội dung phương tiện, tạo hình ảnh, tạo video, truy xuất web, tìm kiếm web, công cụ tác nhân, hoặc bất kỳ sự kết hợp nào.

Bạn không cần thêm Plugin của mình vào kho lưu trữ OpenClaw. Hãy phát hành lên ClawHub và người dùng cài đặt bằng openclaw plugins install clawhub:<package-name>. Các đặc tả gói trần vẫn cài đặt từ npm trong giai đoạn chuyển đổi ra mắt.

Điều kiện tiên quyết

• Node >= 22 và một trình quản lý gói (npm hoặc pnpm)
• Quen thuộc với TypeScript (ESM)
• Đối với Plugin trong kho: đã clone kho lưu trữ và chạy xong pnpm install. Phát triển Plugin từ checkout mã nguồn chỉ dùng pnpm vì OpenClaw tải các Plugin được đóng gói từ các gói workspace extensions/*.

Loại Plugin nào?

Đối với một Plugin kênh không được bảo đảm là đã cài đặt khi chạy onboarding/thiết lập, hãy dùng createOptionalChannelSetupSurface(...) từ openclaw/plugin-sdk/channel-setup. Hàm này tạo ra một cặp adapter thiết lập + wizard thông báo yêu cầu cài đặt và đóng an toàn khi ghi cấu hình thật cho đến khi Plugin được cài đặt.

Bắt đầu nhanh: Plugin công cụ

Hướng dẫn này tạo một Plugin tối thiểu để đăng ký một công cụ tác nhân. Plugin kênh và Plugin nhà cung cấp có các hướng dẫn riêng được liên kết ở trên.

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

// index.tsimport { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";import { Type } from "@sinclair/typebox"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Do a thing",      parameters: Type.Object({ input: Type.String() }),      async execute(_id, params) {        return { content: [{ type: "text", text: `Got: ${params.input}` }] };      },    });  },});

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-pluginopenclaw plugins install clawhub:@myorg/openclaw-my-plugin

pnpm test -- <bundled-plugin-root>/my-plugin/

Năng lực của Plugin

Một Plugin duy nhất có thể đăng ký bất kỳ số lượng năng lực nào thông qua đối tượng api:

Để biết API đăng ký đầy đủ, xem Tổng quan SDK.

Plugin được đóng gói có thể dùng api.registerAgentToolResultMiddleware(...) khi chúng cần ghi lại kết quả công cụ bất đồng bộ trước khi mô hình nhìn thấy đầu ra. Khai báo các runtime mục tiêu trong contracts.agentToolResultMiddleware, ví dụ ["pi", "codex"]. Đây là một seam đáng tin cậy dành cho Plugin được đóng gói; các Plugin bên ngoài nên ưu tiên hook Plugin OpenClaw thông thường trừ khi OpenClaw có thêm chính sách tin cậy rõ ràng cho năng lực này.

Nếu Plugin của bạn đăng ký các phương thức RPC Gateway tùy chỉnh, hãy giữ chúng trên một tiền tố riêng của Plugin. Các namespace quản trị lõi (config.*, exec.approvals.*, wizard.*, update.*) vẫn được dành riêng và luôn phân giải thành operator.admin, ngay cả khi một Plugin yêu cầu phạm vi hẹp hơn.

Các ngữ nghĩa bảo vệ hook cần ghi nhớ:

• before_tool_call: { block: true } là kết thúc và dừng các handler có độ ưu tiên thấp hơn.
• before_tool_call: { block: false } được xử lý như không có quyết định.
• before_tool_call: { requireApproval: true } tạm dừng thực thi tác nhân và nhắc người dùng phê duyệt thông qua lớp phủ phê duyệt exec, nút Telegram, tương tác Discord, hoặc lệnh /approve trên bất kỳ kênh nào.
• before_install: { block: true } là kết thúc và dừng các handler có độ ưu tiên thấp hơn.
• before_install: { block: false } được xử lý như không có quyết định.
• message_sending: { cancel: true } là kết thúc và dừng các handler có độ ưu tiên thấp hơn.
• message_sending: { cancel: false } được xử lý như không có quyết định.
• message_received: ưu tiên trường có kiểu threadId khi bạn cần định tuyến luồng/chủ đề đi vào. Giữ metadata cho các thông tin bổ sung riêng theo kênh.
• message_sending: ưu tiên các trường định tuyến có kiểu replyToId / threadId thay vì các khóa metadata riêng theo kênh.

Lệnh /approve xử lý cả phê duyệt exec và phê duyệt Plugin với dự phòng có giới hạn: khi không tìm thấy id phê duyệt exec, OpenClaw thử lại cùng id đó qua phê duyệt Plugin. Chuyển tiếp phê duyệt Plugin có thể được cấu hình độc lập thông qua approvals.plugin trong cấu hình.

Nếu hệ thống phê duyệt tùy chỉnh cần phát hiện cùng trường hợp dự phòng có giới hạn đó, hãy ưu tiên isApprovalNotFoundError từ openclaw/plugin-sdk/error-runtime thay vì tự khớp chuỗi hết hạn phê duyệt thủ công.

Xem Hook Plugin để biết ví dụ và tài liệu tham chiếu hook.

Đăng ký công cụ tác nhân

Công cụ là các hàm có kiểu mà LLM có thể gọi. Chúng có thể là bắt buộc (luôn có sẵn) hoặc tùy chọn (người dùng chọn tham gia):

register(api) {  // Required tool - always available  api.registerTool({    name: "my_tool",    description: "Do a thing",    parameters: Type.Object({ input: Type.String() }),    async execute(_id, params) {      return { content: [{ type: "text", text: params.input }] };    },  });   // Optional tool - user must add to allowlist  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 },  );}

Các 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 này 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 là ranh giới bảo mật chống lại toán tử cục bộ, mã plugin đã cài đặt, hoặc runtime OpenClaw đã bị sửa đổi. Với các công cụ cục bộ nhạy cảm, hãy giữ cơ chế plugin hoặc toán tử chọn tham gia rõ ràng và đóng an toàn khi metadata mô hình đang hoạt động bị thiếu hoặc không phù hợp.

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": ["my_tool", "workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

OpenClaw ghi nhận và lưu vào bộ nhớ đệm descriptor đã xác thực từ công cụ đã đăng ký, nên plugin không lặp lại dữ liệu description hoặc schema trong manifest. Hợp đồng manifest chỉ khai báo quyền sở hữu và khả năng khám phá; khi thực thi vẫn gọi implementation công cụ đã đăng ký đang chạy. Đặt toolMetadata.<tool>.optional: true cho các công cụ được đăng ký bằng api.registerTool(..., { optional: true }) để OpenClaw có thể tránh tải runtime plugin đó cho đến khi công cụ được allowlist rõ ràng.

Người dùng bật các công cụ tùy chọn trong cấu hình:

{  tools: { allow: ["workflow_tool"] },}

• Tên công cụ không được xung đột với công cụ lõi (các xung đột sẽ bị bỏ qua)
• Công cụ có đối tượng đăng ký sai định dạng, bao gồm thiếu parameters, sẽ bị bỏ qua và được báo cáo trong chẩn đoán plugin thay vì làm hỏng các lần chạy agent
• Dùng optional: true cho các công cụ có hiệu ứng phụ hoặc yêu cầu binary bổ sung
• Người dùng có thể bật tất cả công cụ từ một plugin bằng cách thêm id plugin vào tools.allow

Đăng ký lệnh CLI

Plugin có thể thêm các nhóm lệnh gốc openclaw bằng api.registerCli. Cung cấp descriptors cho mọi gốc lệnh cấp cao nhất để OpenClaw có thể hiển thị và định tuyến lệnh mà không cần tải sẵn mọi runtime plugin.

register(api) {  api.registerCli(    ({ program }) => {      const demo = program        .command("demo-plugin")        .description("Run demo plugin commands");       demo        .command("ping")        .description("Check that the plugin CLI is executable")        .action(() => {          console.log("demo-plugin:pong");        });    },    {      descriptors: [        {          name: "demo-plugin",          description: "Run demo plugin commands",          hasSubcommands: true,        },      ],    },  );}

Sau khi cài đặt, hãy xác minh đăng ký runtime và thực thi lệnh:

openclaw plugins inspect demo-plugin --runtime --jsonopenclaw demo-plugin ping

Quy ước import

Luôn import từ các đường dẫn openclaw/plugin-sdk/<subpath> tập trung:

  // Wrong: monolithic root (deprecated, will be removed) 

Để xem tham chiếu subpath đầy đủ, xem Tổng quan SDK.

Trong plugin của bạn, dùng các file barrel cục bộ (api.ts, runtime-api.ts) cho import nội bộ - không bao giờ import chính plugin của bạn qua đường dẫn SDK của nó.

Đối với plugin nhà cung cấp, hãy giữ các helper riêng cho nhà cung cấp trong các barrel gốc package đó trừ khi seam thật sự mang tính chung. Các ví dụ được bundled hiện tại:

• Anthropic: wrapper stream Claude và helper service_tier / beta
• OpenAI: builder nhà cung cấp, helper mô hình mặc định, nhà cung cấp realtime
• OpenRouter: builder nhà cung cấp cùng helper onboarding/cấu hình

Nếu một helper chỉ hữu ích bên trong một package nhà cung cấp bundled, hãy giữ nó trên seam gốc package đó thay vì đưa nó vào openclaw/plugin-sdk/*.

Một số seam helper openclaw/plugin-sdk/<bundled-id> được tạo tự động vẫn tồn tại để bảo trì bundled-plugin khi chúng theo dõi usage của owner. Hãy xem chúng là các bề mặt được dành riêng, không phải mẫu mặc định cho plugin bên thứ ba mới.

Checklist 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 Entry point 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: