Xây dựng các Plugin

Plugins mở rộng OpenClaw bằng 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 đa phương tiện, tạo hình ảnh, tạo video, tìm nạp web, tìm kiếm web, công cụ agent, 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 khi 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 repo: đã clone kho lưu trữ và chạy xong pnpm install. Phát triển plugin từ bản checkout mã nguồn chỉ dùng pnpm vì OpenClaw tải các plugin được đóng gói sẵn từ các gói workspace extensions/*.

# Loại plugin nào?

Đối với plugin kênh không được bảo đảm đã cài đặt khi chạy onboarding/thiết lập, hãy dùng createOptionalChannelSetupSurface(...) từ openclaw/plugin-sdk/channel-setup. Nó tạo 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ụ 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.

{
"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.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}` }] };
      },
    });
  },
});

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

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

# Khả năng của Plugin

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

Để xem đầy đủ API đăng ký, hãy xem Tổng quan SDK.

Plugin đi kèm có thể dùng api.registerAgentToolResultMiddleware(...) khi chúng cần viết lại bất đồng bộ kết quả công cụ trước khi mô hình nhìn 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 đường nối đáng tin cậy cho Plugin đi kèm; plugin bên ngoài nên ưu tiên các hook Plugin OpenClaw thông thường, trừ khi OpenClaw phát triển 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 cho 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à điểm kết thúc và dừng các handler 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 tác nhân và nhắc người dùng phê duyệt thông 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à điểm kết thúc và dừng các handler 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à điểm kết thúc và dừng các handler 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ủ đề đi vào. Giữ metadata cho các 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 vì 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 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ì khớp thủ công các chuỗi hết hạn phê duyệt.

Xem Hook của Plugin để biết ví dụ và 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 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 },
  );
}

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

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

OpenClaw ghi nhận và lưu vào bộ nhớ đệm bộ mô tả đã được xác thực từ công cụ đã đăng ký, vì vậy plugin không sao chép description hoặc dữ liệu schema trong manifest. Hợp đồng manifest chỉ khai báo quyền sở hữu và khả năng khám phá; quá trình thực thi vẫn gọi triển khai công cụ đã đăng ký trực tiếp. Đặ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 đưa rõ ràng vào allowlist.

Người dùng bật 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ý 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 lượt chạy tác tử
• Dùng optional: true cho công cụ có tác dụng phụ hoặc yêu cầu thêm tệp nhị phân
• 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 phải 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 --json
openclaw 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 tệp barrel cục bộ (api.ts, runtime-api.ts) cho

Đố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 tổng quát. Các ví dụ đóng gói hiện tại:

• Anthropic: wrapper stream Claude và helper service_tier / beta
• OpenAI: bộ dựng nhà cung cấp, helper mô hình mặc định, nhà cung cấp realtime
• OpenRouter: bộ dựng 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 gói nhà cung cấp đóng gói, hãy giữ helper đó trên seam gốc gói thay vì đưa nó vào openclaw/plugin-sdk/*.

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

# Danh sách kiểm tra 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 Điểm vào dùng defineChannelPluginEntry hoặc definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Tất cả import dùng các đường dẫn plugin-sdk/<subpath> tập trung OPENCLAW_DOCS_MARKER:calloutClose: