Chuyển đến nội dung chính

​
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, tạo hình ảnh, tìm kiếm web, công cụ agent, hoặc bất kỳ tổ hợp nào. Một plugin có thể đăng ký nhiều khả năng. OpenClaw khuyến khích phát triển plugin bên ngoài. Bạn không cần thêm plugin vào kho OpenClaw. Hãy xuất bản plugin của bạn trên npm, và người dùng có thể cài đặt nó với openclaw plugins install <npm-spec>. OpenClaw cũng duy trì một bộ plugin cốt lõi trong kho, nhưng hệ thống plugin được thiết kế để sở hữu và phân phối độc lập.

​
Yêu cầu trước

  • 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 OpenClaw và chạy pnpm install

​
Khả năng của Plugin

Một plugin có thể đăng ký một hoặc nhiều khả năng. Khả năng bạn đăng ký sẽ xác định plugin của bạn cung cấp gì cho OpenClaw:
Khả năngPhương thức đăng kýThêm gì vào
Suy luận văn bảnapi.registerProvider(...)Nhà cung cấp mô hình (LLM)
Kênh / nhắn tinapi.registerChannel(...)Kênh chat (ví dụ: Slack, IRC)
Giọng nóiapi.registerSpeechProvider(...)Chuyển văn bản thành giọng nói / STT
Hiểu phương tiệnapi.registerMediaUnderstandingProvider(...)Phân tích hình ảnh/âm thanh/video
Tạo hình ảnhapi.registerImageGenerationProvider(...)Tạo hình ảnh
Tìm kiếm webapi.registerWebSearchProvider(...)Nhà cung cấp tìm kiếm web
Công cụ agentapi.registerTool(...)Công cụ có thể gọi bởi agent
Một plugin không đăng ký khả năng nào nhưng cung cấp hooks hoặc dịch vụ là plugin chỉ có hook. Mẫu này vẫn được hỗ trợ.

​
Cấu trúc Plugin

Plugin tuân theo cấu trúc này (dù trong kho hay độc lập): 
my-plugin/
├── package.json          # Thông tin npm + cấu hình openclaw
├── openclaw.plugin.json  # Tệp manifest của plugin
├── index.ts              # Điểm vào
├── setup-entry.ts        # Trình hướng dẫn cài đặt (tùy chọn)
├── api.ts                # Xuất công khai (tùy chọn)
├── runtime-api.ts        # Xuất nội bộ (tùy chọn)
└── src/
    ├── provider.ts       # Triển khai khả năng
    ├── runtime.ts        # Kết nối runtime
    └── *.test.ts         # Kiểm thử đi kèm

​
Tạo một plugin

1

Tạo package

Tạo package.json với khối metadata openclaw. Cấu trúc phụ thuộc vào khả năng mà plugin của bạn cung cấp.Ví dụ plugin kênh:
{
  "name": "@myorg/openclaw-my-channel",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "my-channel",
      "label": "My Channel",
      "blurb": "Mô tả ngắn về kênh."
    }
  }
}
Ví dụ plugin nhà cung cấp:
{
  "name": "@myorg/openclaw-my-provider",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "providers": ["my-provider"]
  }
}
Trường openclaw cho hệ thống plugin biết plugin của bạn cung cấp gì. Một plugin có thể khai báo cả channel và providers nếu nó cung cấp nhiều khả năng.
2

Định nghĩa điểm vào

Điểm vào đăng ký khả năng của bạn với API plugin.Plugin kênh:
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Kết nối OpenClaw với My Channel",
  plugin: {
    // Triển khai adapter kênh
  },
});
Plugin nhà cung cấp:
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-provider",
  name: "My Provider",
  register(api) {
    api.registerProvider({
      // Triển khai nhà cung cấp
    });
  },
});
Plugin đa khả năng (nhà cung cấp + công cụ):
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  register(api) {
    api.registerProvider({ /* ... */ });
    api.registerTool({ /* ... */ });
    api.registerImageGenerationProvider({ /* ... */ });
  },
});
Sử dụng defineChannelPluginEntry từ plugin-sdk/core cho plugin kênh và definePluginEntry từ plugin-sdk/plugin-entry cho mọi thứ khác. Một plugin có thể đăng ký nhiều khả năng như cần thiết.Đối với các kênh kiểu chat, plugin-sdk/core cũng cung cấp createChatChannelPlugin(...) để bạn có thể kết hợp bảo mật DM thông thường, ghép nối văn bản, luồng trả lời, và gửi kết quả đính kèm mà không cần kết nối từng adapter riêng lẻ.
3

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

Luôn import từ các đường dẫn openclaw/plugin-sdk/\<subpath\> cụ thể. Việc import nguyên khối cũ đã bị loại bỏ (xem SDK Migration).Nếu mã plugin cũ vẫn import openclaw/extension-api, hãy coi đó là cầu nối tương thích tạm thời. Mã mới nên sử dụng các trợ giúp runtime được tiêm như api.runtime.agent.* thay vì import trực tiếp các trợ giúp agent phía host.
// Đúng: subpath tập trung
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { buildOauthProviderAuthResult } from "openclaw/plugin-sdk/provider-oauth";

// Sai: gốc nguyên khối (lint sẽ từ chối điều này)
import { ... } from "openclaw/plugin-sdk";

// Đã loại bỏ: cầu nối host cũ
import { runEmbeddedPiAgent } from "openclaw/extension-api";
SubpathMục đích
plugin-sdk/plugin-entryTrợ giúp definePluginEntry chuẩn + loại nhập nhà cung cấp/plugin
plugin-sdk/coreTrợ giúp điểm vào kênh, trình tạo kênh, và loại cơ sở chia sẻ
plugin-sdk/channel-setupBộ điều hợp trình hướng dẫn cài đặt
plugin-sdk/channel-pairingNguyên thủy ghép nối DM
plugin-sdk/channel-reply-pipelineDây nối tiền tố trả lời + gõ
plugin-sdk/channel-config-schemaTrình tạo lược đồ cấu hình
plugin-sdk/channel-policyTrợ giúp chính sách nhóm/DM
plugin-sdk/secret-inputPhân tích/trợ giúp nhập bí mật
plugin-sdk/webhook-ingressTrợ giúp yêu cầu/đích webhook
plugin-sdk/runtime-storeLưu trữ plugin lâu dài
plugin-sdk/allow-fromGiải quyết danh sách cho phép
plugin-sdk/reply-payloadLoại trả lời tin nhắn
plugin-sdk/provider-oauthĐăng nhập OAuth + trợ giúp PKCE
plugin-sdk/provider-onboardBản vá cấu hình onboarding nhà cung cấp
plugin-sdk/testingTiện ích kiểm thử
Sử dụng subpath hẹp nhất phù hợp với công việc.
4

Sử dụng module cục bộ cho import nội bộ

Trong plugin của bạn, tạo các tệp module cục bộ để chia sẻ mã nội bộ thay vì import lại thông qua SDK plugin:
// api.ts — xuất công khai cho plugin này
export { MyConfig } from "./src/config.js";
export { MyRuntime } from "./src/runtime.js";

// runtime-api.ts — xuất chỉ nội bộ
export { internalHelper } from "./src/helpers.js";
Không bao giờ import plugin của bạn trở lại thông qua đường dẫn SDK đã xuất bản từ các tệp sản xuất. Hướng các import nội bộ qua các tệp cục bộ như ./api.ts hoặc ./runtime-api.ts. Đường dẫn SDK chỉ dành cho người tiêu dùng bên ngoài.
5

Thêm một manifest plugin

Tạo openclaw.plugin.json trong thư mục gốc của plugin:
{
  "id": "my-plugin",
  "kind": "provider",
  "name": "My Plugin",
  "description": "Thêm My Provider vào OpenClaw"
}
Đối với plugin kênh, đặt "kind": "channel" và thêm "channels": ["my-channel"].Xem Plugin Manifest để biết lược đồ đầy đủ.
6

Kiểm thử plugin của bạn

Plugin bên ngoài: chạy bộ kiểm thử của riêng bạn với các hợp đồng SDK plugin.Plugin trong kho: OpenClaw chạy kiểm thử hợp đồng với tất cả các plugin đã đăng ký:
pnpm test:contracts:channels   # plugin kênh
pnpm test:contracts:plugins    # plugin nhà cung cấp
Đối với kiểm thử đơn vị, import các trợ giúp kiểm thử từ bề mặt kiểm thử:
import { createTestRuntime } from "openclaw/plugin-sdk/testing";
7

Xuất bản và cài đặt

Plugin bên ngoài: xuất bản lên npm, sau đó cài đặt:
npm publish
openclaw plugins install @myorg/openclaw-my-plugin
Plugin trong kho: đặt plugin dưới extensions/ và nó sẽ được tự động phát hiện trong quá trình build.Người dùng có thể duyệt và cài đặt plugin cộng đồng với:
openclaw plugins search <query>
openclaw plugins install <npm-spec>

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

Plugin có thể đăng ký công cụ agent — các hàm có kiểu mà LLM có thể gọi. Công cụ 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 qua danh sách cho phép). 
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  register(api) {
    // Công cụ bắt buộc (luôn có sẵn)
    api.registerTool({
      name: "my_tool",
      description: "Thực hiện một việc",
      parameters: Type.Object({ input: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.input }] };
      },
    });

    // Công cụ tùy chọn (người dùng phải thêm vào danh sách cho phép)
    api.registerTool(
      {
        name: "workflow_tool",
        description: "Chạy một quy trình",
        parameters: Type.Object({ pipeline: Type.String() }),
        async execute(_id, params) {
          return { content: [{ type: "text", text: params.pipeline }] };
        },
      },
      { optional: true },
    );
  },
});
Kích hoạt công cụ tùy chọn trong cấu hình: 
{
  tools: { allow: ["workflow_tool"] },
}
Mẹo:
  • Tên công cụ không được trùng với tên công cụ cốt lõi (xung đột sẽ bị bỏ qua)
  • Sử dụng optional: true cho các công cụ kích hoạt hiệu ứng phụ hoặc yêu cầu thêm các tệp nhị phân
  • Người dùng có thể kích hoạt tất cả các công cụ từ một plugin bằng cách thêm id plugin vào tools.allow

​
Kiểm tra lint (plugin trong kho)

Ba script kiểm tra ranh giới SDK cho các plugin trong kho OpenClaw:
  1. Không import gốc nguyên khối — gốc openclaw/plugin-sdk bị từ chối
  2. Không import trực tiếp từ src/ — plugin không thể import trực tiếp ../../src/
  3. Không tự import — plugin không thể import subpath plugin-sdk/\<name\> của chính nó
Chạy pnpm check để kiểm tra tất cả các ranh giới trước khi commit. Plugin bên ngoài không bị ràng buộc bởi các quy tắc lint này, nhưng việc tuân theo các mẫu tương tự được khuyến khích mạnh mẽ.

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

package.json có metadata openclaw chính xác
Điểm vào sử dụng defineChannelPluginEntry hoặc definePluginEntry
Tất cả các import sử dụng đường dẫn plugin-sdk/\<subpath\> tập trung
Import nội bộ sử dụng module cục bộ, không phải tự import SDK
Manifest openclaw.plugin.json có mặt và hợp lệ
Kiểm thử thành công
pnpm check thành công (plugin trong kho)

​
Liên quan

Last modified on March 22, 2026