Xây dựng Plugin

Plugin mở rộng OpenClaw với các khả năng 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 media, tạo ảnh, tạo video, tìm nạp web, tìm kiếm web, công cụ agent, hoặc bất 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. Xuất bản lên ClawHub và người dùng cài đặt bằng openclaw plugins install <package-name>. OpenClaw thử ClawHub trước và tự động chuyển về npm cho các gói vẫn dùng phân phối qua npm.

Đ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)
Với Plugin trong repo: đã clone kho lưu trữ và chạy xong pnpm install

Loại Plugin nào?

Plugin kênh

Kết nối OpenClaw với một nền tảng nhắn tin (Discord, IRC, v.v.)

Plugin nhà cung cấp

Thêm một nhà cung cấp mô hình (LLM, proxy, hoặc endpoint tùy chỉnh)

Plugin công cụ / hook

Đăng ký công cụ agent, hook sự kiện, hoặc dịch vụ — tiếp tục bên dưới

Với một Plugin kênh không được bảo đảm đã cài đặt khi quá trình onboarding/thiết lập chạy, hãy dùng createOptionalChannelSetupSurface(...) từ openclaw/plugin-sdk/channel-setup. Hàm này tạo một cặp adapter thiết lập + wizard thông báo yêu cầu cài đặt và từ chối an toàn các thao tác 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ụ agent. 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.

Tạo gói và manifest

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

Mỗi Plugin cần một manifest, ngay cả khi không có cấu hình, và mỗi Plugin nên khai báo activation.onStartup một cách có chủ đích. Các công cụ đăng ký lúc runtime cần import khi khởi động, nên ví dụ này đặt giá trị đó là true. Xem Manifest để biết schema đầy đủ. Các đoạn mẫu xuất bản ClawHub chính tắc nằm trong docs/snippets/plugin-publish/.

Viết điểm vào

// index.ts
import { 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}` }] };
      },
    });
  },
});

definePluginEntry dành cho các Plugin không phải kênh. Với kênh, dùng defineChannelPluginEntry — xem Plugin kênh. Để biết đầy đủ tùy chọn điểm vào, xem Điểm vào.

Kiểm thử và xuất bản

Plugin bên ngoài: xác thực và xuất bản bằng ClawHub, rồi cài đặt:

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

OpenClaw cũng kiểm tra ClawHub trước npm cho các đặc tả gói dạng trần như @myorg/openclaw-my-plugin; npm vẫn là phương án dự phòng cho các gói chưa di chuyển sang ClawHub.Plugin trong repo: đặt dưới cây workspace Plugin được đóng gói — sẽ được tự động phát hiện.

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

Khả năng của Plugin

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

Khả năng	Phương thức đăng ký	Hướng dẫn chi tiết
Suy luận văn bản (LLM)	`api.registerProvider(...)`	Plugin nhà cung cấp
Backend suy luận CLI	`api.registerCliBackend(...)`	Backend CLI
Kênh / nhắn tin	`api.registerChannel(...)`	Plugin kênh
Giọng nói (TTS/STT)	`api.registerSpeechProvider(...)`	Plugin nhà cung cấp
Phiên âm thời gian thực	`api.registerRealtimeTranscriptionProvider(...)`	Plugin nhà cung cấp
Thoại thời gian thực	`api.registerRealtimeVoiceProvider(...)`	Plugin nhà cung cấp
Hiểu nội dung media	`api.registerMediaUnderstandingProvider(...)`	Plugin nhà cung cấp
Tạo ảnh	`api.registerImageGenerationProvider(...)`	Plugin nhà cung cấp
Tạo nhạc	`api.registerMusicGenerationProvider(...)`	Plugin nhà cung cấp
Tạo video	`api.registerVideoGenerationProvider(...)`	Plugin nhà cung cấp
Tìm nạp web	`api.registerWebFetchProvider(...)`	Plugin nhà cung cấp
Tìm kiếm web	`api.registerWebSearchProvider(...)`	Plugin nhà cung cấp
Middleware kết quả công cụ	`api.registerAgentToolResultMiddleware(...)`	Tổng quan SDK
Công cụ agent	`api.registerTool(...)`	Bên dưới
Lệnh tùy chỉnh	`api.registerCommand(...)`	Điểm vào
Hook Plugin	`api.on(...)`	Hook Plugin
Hook sự kiện nội bộ	`api.registerHook(...)`	Điểm vào
Tuyến HTTP	`api.registerHttpRoute(...)`	Nội bộ
Lệnh con CLI	`api.registerCli(...)`	Điểm vào

Để biết đầy đủ registration API, 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 thấy đầu ra. Khai báo các runtime được nhắm tới trong contracts.agentToolResultMiddleware, ví dụ ["pi", "codex"]. Đây là một điểm nối đáng tin cậy dành cho Plugin được đóng gói; Plugin bên ngoài nên ưu tiên các hook Plugin OpenClaw thông thường trừ khi OpenClaw có thêm một chính sách tin cậy rõ ràng cho khả năng 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. 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ó mức ưu tiên thấp hơn.
before_tool_call: { block: false } được xem là không có quyết định.
before_tool_call: { requireApproval: true } tạm dừng thực thi agent và nhắc người dùng phê duyệt qua lớp phủ phê duyệt exec, các 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ó mức ưu tiên thấp hơn.
before_install: { block: false } được xem là không có quyết định.
message_sending: { cancel: true } là kết thúc và dừng các handler có mức ưu tiên thấp hơn.
message_sending: { cancel: false } được xem là 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 thread/chủ đề gửi đến. Giữ metadata cho phần 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 cho 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 cơ chế 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. Việc chuyển tiếp phê duyệt Plugin có thể được cấu hình độc lập qua approvals.plugin trong cấu hình. Nếu phần kết nối 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à tham chiếu hook.

Đăng ký công cụ agent

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 khả dụng) 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 },
  );
}

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 (xung đột sẽ bị bỏ qua)
Các công cụ có đối tượng đăng ký không đúng đị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ó tác dụng phụ hoặc yêu cầu thêm binary
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

Quy ước import

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

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

// Wrong: monolithic root (deprecated, will be removed)
import { ... } from "openclaw/plugin-sdk";

Để xem tham chiếu đầy đủ về đường dẫn con, hãy xem Tổng quan SDK. Trong Plugin của bạn, hãy dùng các tệp barrel cục bộ (api.ts, runtime-api.ts) cho các lệnh nhập nội bộ — tuyệt đối không nhập chính Plugin của bạn thông qua đường dẫn SDK của nó. Đối với Plugin nhà cung cấp, hãy giữ các helper dành riêng cho nhà cung cấp trong các barrel ở gốc gói đó, trừ khi seam thật sự mang tính chung. Các ví dụ tích hợp hiện tại:

Anthropic: các wrapper luồng Claude và helper service_tier / beta
OpenAI: builder nhà cung cấp, helper mô hình mặc định, nhà cung cấp thời gian thực
OpenRouter: builder nhà cung cấp cùng helper hướng dẫn ban đầu/cấu hình

Nếu một helper chỉ hữu ích bên trong một gói nhà cung cấp tích hợp, hãy giữ nó trên seam ở gốc gói đó thay vì đưa nó lên openclaw/plugin-sdk/*. Một số seam helper openclaw/plugin-sdk/<bundled-id> được tạo vẫn còn tồn tại để bảo trì Plugin tích hợp khi chúng có mức sử dụng của chủ sở hữu đã được theo dõi. Hãy xem chúng là bề mặt dành riêng, không phải mẫu mặc định cho các Plugin bên thứ ba mới.

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

package.json có metadata openclaw chính xác

Manifest openclaw.plugin.json tồn tại và hợp lệ

Điểm vào dùng defineChannelPluginEntry hoặc definePluginEntry

Tất cả lệnh nhập dùng đường dẫn plugin-sdk/<subpath> tập trung

Lệnh nhập nội bộ dùng module cục bộ, không tự nhập qua SDK

Kiểm thử chạy thành công (pnpm test -- <bundled-plugin-root>/my-plugin/)

pnpm check chạy thành công (Plugin trong repo)

Kiểm thử bản phát hành beta

Theo dõi các thẻ phát hành GitHub trên openclaw/openclaw và đăng ký qua Watch > Releases. Thẻ beta có dạng v2026.3.N-beta.1. Bạn cũng có thể bật thông báo cho tài khoản X chính thức của OpenClaw @openclaw để nhận thông báo phát hành.
Kiểm thử Plugin của bạn với thẻ beta ngay khi thẻ xuất hiện. Khoảng thời gian trước bản ổn định thường chỉ kéo dài vài giờ.
Đăng trong luồng của Plugin của bạn ở kênh Discord plugin-forum sau khi kiểm thử, với nội dung all good hoặc phần bị hỏng. Nếu bạn chưa có luồng, hãy tạo một luồng.
Nếu có gì đó hỏng, hãy mở hoặc cập nhật một issue có tiêu đề Beta blocker: <plugin-name> - <summary> và áp dụng nhãn beta-blocker. Đặt liên kết issue trong luồng của bạn.
Mở một PR tới main với tiêu đề fix(<plugin-id>): beta blocker - <summary> và liên kết issue trong cả PR lẫn luồng Discord của bạn. Cộng tác viên không thể gắn nhãn PR, vì vậy tiêu đề là tín hiệu phía PR cho maintainer và tự động hóa. Các blocker có PR sẽ được hợp nhất; blocker không có PR vẫn có thể được phát hành. Maintainer theo dõi các luồng này trong quá trình kiểm thử beta.
Im lặng nghĩa là xanh. Nếu bạn bỏ lỡ khoảng thời gian này, bản sửa của bạn nhiều khả năng sẽ vào chu kỳ tiếp theo.

Bước tiếp theo

Plugin kênh

Xây dựng Plugin kênh nhắn tin

Plugin nhà cung cấp

Xây dựng Plugin nhà cung cấp mô hình

Tổng quan SDK

Tham chiếu bản đồ nhập và API đăng ký

Helper runtime

TTS, tìm kiếm, subagent qua api.runtime

Kiểm thử

Tiện ích và mẫu kiểm thử

Manifest Plugin

Tham chiếu đầy đủ về schema manifest

Liên quan

Kiến trúc Plugin — phân tích sâu kiến trúc nội bộ
Tổng quan SDK — tham chiếu SDK Plugin
Manifest — định dạng manifest Plugin
Plugin kênh — xây dựng Plugin kênh
Plugin nhà cung cấp — xây dựng Plugin nhà cung cấp

Overview

Plugins

Skills

Automation and tasks

Tools

Agent coordination

Xây dựng Plugin

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

Loại Plugin nào?

Plugin kênh

Plugin nhà cung cấp

Plugin công cụ / hook

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

Khả năng của Plugin

Đăng ký công cụ agent

Quy ước import

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

Kiểm thử bản phát hành beta

Bước tiếp theo

Plugin kênh

Plugin nhà cung cấp

Tổng quan SDK

Helper runtime

Kiểm thử

Manifest Plugin

Liên quan

Overview

Plugins

Skills

Automation and tasks

Tools

Agent coordination

Documentation Index

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

​Loại Plugin nào?

Plugin kênh

Plugin nhà cung cấp

Plugin công cụ / hook

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

​Khả năng của Plugin

​Đăng ký công cụ agent

​Quy ước import

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

​Kiểm thử bản phát hành beta

​Bước tiếp theo

Plugin kênh

Plugin nhà cung cấp

Tổng quan SDK

Helper runtime

Kiểm thử

Manifest Plugin

​Liên quan

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

Loại Plugin nào?

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

Khả năng của Plugin

Đăng ký công cụ agent

Quy ước import

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

Kiểm thử bản phát hành beta

Bước tiếp theo

Liên quan