Điểm vào Plugin

{
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"],
    "setupEntry": "./src/setup-entry.ts",
    "runtimeSetupEntry": "./dist/setup-entry.js"
  }
}

​

defineToolPlugin

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

export default defineToolPlugin({
  id: "stock-quotes",
  name: "Stock Quotes",
  description: "Fetch stock quotes.",
  configSchema: Type.Object({
    apiKey: Type.Optional(Type.String({ description: "API key." })),
  }),
  tools: (tool) => [
    tool({
      name: "quote",
      label: "Quote",
      description: "Fetch a quote.",
      parameters: Type.Object({
        symbol: Type.String({ description: "Ticker symbol." }),
      }),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

• configSchema là tùy chọn. Khi bỏ qua, OpenClaw dùng một schema đối tượng rỗng nghiêm ngặt và manifest được tạo vẫn bao gồm configSchema.
• execute trả về một chuỗi thuần hoặc giá trị có thể tuần tự hóa thành JSON. Helper bọc nó thành kết quả công cụ dạng văn bản với details.
• Tên công cụ là tĩnh. openclaw plugins build suy ra contracts.tools từ các công cụ đã khai báo, nên tác giả không cần tự nhân đôi tên.
• Việc tải runtime vẫn nghiêm ngặt. Các Plugin đã cài đặt vẫn cần openclaw.plugin.json và package.json openclaw.extensions; OpenClaw không thực thi mã Plugin để suy luận dữ liệu manifest bị thiếu.

​

definePluginEntry

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

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
  },
});

• id phải khớp với manifest openclaw.plugin.json của bạn.
• kind dành cho các vị trí độc quyền: "memory" hoặc "context-engine".
• configSchema có thể là một hàm để đánh giá lười.
• OpenClaw phân giải và ghi nhớ schema đó trong lần truy cập đầu tiên, nên các trình tạo schema tốn kém chỉ chạy một lần.

​

defineChannelPluginEntry

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

• setRuntime được gọi trong quá trình đăng ký để bạn có thể lưu tham chiếu runtime (thường qua createPluginRuntimeStore). Nó được bỏ qua trong quá trình thu thập metadata CLI.
• registerCliMetadata chạy trong api.registrationMode === "cli-metadata", api.registrationMode === "discovery", và api.registrationMode === "full". Dùng nó làm nơi chính thức cho các descriptor CLI do kênh sở hữu để trợ giúp gốc không kích hoạt Plugin, snapshot khám phá bao gồm metadata lệnh tĩnh, và việc đăng ký lệnh CLI thông thường vẫn tương thích với tải Plugin đầy đủ.
• Đăng ký khám phá là không kích hoạt, không phải không import. OpenClaw có thể đánh giá mục nhập Plugin đáng tin cậy và module Plugin kênh để xây dựng snapshot, vì vậy hãy giữ các import cấp cao nhất không có hiệu ứng phụ và đặt socket, client, worker, và service phía sau các đường dẫn chỉ dành cho "full".
• registerFull chỉ chạy khi api.registrationMode === "full". Nó được bỏ qua trong quá trình tải chỉ dành cho thiết lập.
• Giống definePluginEntry, configSchema có thể là một factory lười và OpenClaw ghi nhớ schema đã phân giải trong lần truy cập đầu tiên.
• Đối với các lệnh CLI gốc do Plugin sở hữu, ưu tiên api.registerCli(..., { descriptors: [...] }) khi bạn muốn lệnh vẫn được tải lười mà không biến mất khỏi cây phân tích CLI gốc. Đối với các lệnh tính năng nút theo cặp, ưu tiên api.registerNodeCliFeature(...) để lệnh nằm dưới openclaw nodes. Đối với các lệnh Plugin lồng khác, thêm parentPath và đăng ký lệnh trên đối tượng program được truyền cho registrar; OpenClaw phân giải nó tới lệnh cha trước khi gọi Plugin. Đối với Plugin kênh, ưu tiên đăng ký các descriptor đó từ registerCliMetadata(...) và giữ registerFull(...) tập trung vào công việc chỉ dành cho runtime.
• Nếu registerFull(...) cũng đăng ký các phương thức RPC Gateway, hãy giữ chúng trên tiền tố riêng của Plugin. Các namespace quản trị lõi được dành riêng (config.*, exec.approvals.*, wizard.*, update.*) luôn bị ép về operator.admin.

​

defineSetupPluginEntry

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);

• openclaw/plugin-sdk/setup-runtime dành cho các helper thiết lập an toàn với runtime như createSetupTranslator, adapter vá thiết lập an toàn để import, đầu ra ghi chú tra cứu, promptResolvedAllowFrom, splitSetupEntries, và proxy thiết lập được ủy quyền
• openclaw/plugin-sdk/channel-setup dành cho các bề mặt thiết lập cài đặt tùy chọn
• openclaw/plugin-sdk/setup-tools dành cho các helper CLI/kho lưu trữ/tài liệu về thiết lập/cài đặt

import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

export default defineBundledChannelSetupEntry({
  importMetaUrl: import.meta.url,
  plugin: {
    specifier: "./channel-plugin-api.js",
    exportName: "myChannelPlugin",
  },
  runtime: {
    specifier: "./runtime-api.js",
    exportName: "setMyChannelRuntime",
  },
  registerSetupRuntime(api) {
    api.registerHttpRoute({
      path: "/my-channel/events",
      auth: "plugin",
      handler: async (req, res) => {
        /* setup-safe route */
      },
    });
  },
});

​

Chế độ đăng ký

register(api) {
  if (
    api.registrationMode === "cli-metadata" ||
    api.registrationMode === "discovery" ||
    api.registrationMode === "full"
  ) {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Heavy runtime-only registrations
  api.registerService(/* ... */);
}

• dùng descriptors khi trình đăng ký sở hữu một hoặc nhiều lệnh gốc và bạn muốn OpenClaw tải lười mô-đun CLI thật ở lần gọi đầu tiên
• bảo đảm các mô tả đó bao phủ mọi gốc lệnh cấp cao nhất do trình đăng ký cung cấp
• giữ tên lệnh trong mô tả chỉ gồm chữ cái, chữ số, dấu gạch nối và dấu gạch dưới, bắt đầu bằng chữ cái hoặc chữ số; OpenClaw từ chối tên mô tả nằm ngoài dạng đó và loại bỏ các chuỗi điều khiển terminal khỏi phần mô tả trước khi hiển thị trợ giúp
• chỉ dùng riêng commands cho các đường dẫn tương thích eager

​

Hình dạng Plugin

​

Liên quan

• Tổng quan SDK - API đăng ký và tham chiếu subpath
• Trình trợ giúp runtime - api.runtime và createPluginRuntimeStore
• Thiết lập và cấu hình - manifest, entry thiết lập, tải trì hoãn
• Plugin kênh - xây dựng đối tượng ChannelPlugin
• Plugin nhà cung cấp - đăng ký nhà cung cấp và hook