Thiết lập và cấu hình Plugin

Tham chiếu về cách đóng gói plugin (siêu dữ liệu package.json), tệp kê khai (openclaw.plugin.json), các điểm vào thiết lập và lược đồ cấu hình.

Siêu dữ liệu gói

package.json của bạn cần có trường openclaw để cho hệ thống plugin biết plugin của bạn cung cấp những gì:

{  "name": "@myorg/openclaw-my-channel",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "channel": {      "id": "my-channel",      "label": "My Channel",      "blurb": "Short description of the channel."    }  }}

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "dependencies": {    "typebox": "1.1.39"  },  "peerDependencies": {    "openclaw": ">=2026.3.24-beta.2"  },  "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"    }  }}

Các trường openclaw

openclaw.channel

openclaw.channel là siêu dữ liệu gói nhẹ dùng cho việc khám phá kênh và các giao diện thiết lập trước khi tải thời gian chạy.

Ví dụ:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "My Channel",      "selectionLabel": "My Channel (self-hosted)",      "detailLabel": "My Channel Bot",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook-based self-hosted chat integration.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Guide:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure hỗ trợ:

• configured: đưa kênh vào các giao diện danh sách kiểu đã cấu hình/trạng thái
• setup: đưa kênh vào các bộ chọn thiết lập/cấu hình tương tác
• docs: đánh dấu kênh là công khai trong các giao diện tài liệu/điều hướng

openclaw.install

openclaw.install là siêu dữ liệu gói, không phải siêu dữ liệu tệp kê khai.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

Trì hoãn tải đầy đủ

Plugin kênh có thể chọn trì hoãn việc tải bằng cấu hình:

{  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "startup": {      "deferConfiguredChannelFullLoadUntilAfterListen": true    }  }}

Khi được bật, OpenClaw chỉ tải setupEntry trong giai đoạn khởi động trước khi bắt đầu lắng nghe, kể cả đối với các kênh đã được cấu hình. Điểm vào đầy đủ được tải sau khi Gateway bắt đầu lắng nghe.

Nếu điểm vào thiết lập/đầy đủ của bạn đăng ký các phương thức RPC của Gateway, hãy đặt chúng dưới một tiền tố riêng cho plugin. Các không gian tên quản trị lõi dành riêng (config.*, exec.approvals.*, wizard.*, update.*) vẫn thuộc quyền sở hữu của lõi và luôn được chuẩn hóa thành operator.admin.

Tệp kê khai plugin

Mọi plugin gốc đều phải cung cấp tệp openclaw.plugin.json tại thư mục gốc của gói. OpenClaw sử dụng tệp này để xác thực cấu hình mà không thực thi mã của plugin.

{  "id": "my-plugin",  "name": "My Plugin",  "description": "Adds My Plugin capabilities to OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook verification secret"      }    }  }}

Đối với plugin kênh, hãy thêm channels (và plugin nhà cung cấp thêm providers):

{  "id": "my-channel",  "channels": ["my-channel"],  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

Ngay cả plugin không có cấu hình cũng phải cung cấp một lược đồ. Lược đồ trống là hợp lệ:

{  "id": "my-plugin",  "configSchema": {    "type": "object",    "additionalProperties": false  }}

Xem tệp kê khai Plugin để biết tài liệu tham khảo đầy đủ về lược đồ.

Phát hành trên ClawHub

Các gói Skills và plugin sử dụng những lệnh phát hành ClawHub riêng biệt. Đối với gói plugin, hãy sử dụng lệnh dành riêng cho gói:

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

Điểm vào thiết lập

setup-entry.ts là một lựa chọn thay thế gọn nhẹ cho index.ts mà OpenClaw tải khi chỉ cần các bề mặt thiết lập (hướng dẫn ban đầu, sửa cấu hình, kiểm tra kênh bị vô hiệu hóa):

// setup-entry.ts  export default defineSetupPluginEntry(myChannelPlugin);

Điều này tránh tải mã thời gian chạy nặng (thư viện mật mã, đăng ký CLI, dịch vụ nền) trong các luồng thiết lập.

Các kênh không gian làm việc đi kèm lưu các phần xuất an toàn cho thiết lập trong mô-đun phụ có thể sử dụng defineBundledChannelSetupEntry(...) từ openclaw/plugin-sdk/channel-entry-contract thay cho defineSetupPluginEntry(...). Hợp đồng đi kèm đó cũng hỗ trợ phần xuất runtime tùy chọn để việc kết nối thời gian chạy trong lúc thiết lập luôn gọn nhẹ và tường minh.

Phần nhập trình trợ giúp thiết lập phạm vi hẹp

Đối với các đường dẫn nóng chỉ dành cho thiết lập, hãy ưu tiên các điểm nối trình trợ giúp thiết lập phạm vi hẹp thay vì điểm nối bao quát plugin-sdk/setup khi bạn chỉ cần một phần của bề mặt thiết lập:

Sử dụng điểm nối rộng hơn plugin-sdk/setup khi bạn muốn toàn bộ bộ công cụ thiết lập dùng chung, bao gồm các trình trợ giúp vá cấu hình như moveSingleAccountChannelSectionToDefaultAccount(...).

Sử dụng createSetupTranslator(...) cho nội dung cố định của trình hướng dẫn thiết lập. Hàm này tuân theo ngôn ngữ của trình hướng dẫn CLI (OPENCLAW_LOCALE, sau đó là các biến ngôn ngữ hệ thống) và dùng tiếng Anh làm phương án dự phòng. Giữ văn bản thiết lập dành riêng cho plugin trong mã do plugin sở hữu và chỉ dùng các khóa danh mục dùng chung cho nhãn thiết lập phổ biến, văn bản trạng thái và nội dung thiết lập của plugin chính thức đi kèm.

Các bộ điều hợp vá thiết lập vẫn an toàn cho đường dẫn nóng khi nhập. Việc tra cứu bề mặt hợp đồng thăng cấp tài khoản đơn đi kèm của chúng được thực hiện trì hoãn, vì vậy việc nhập plugin-sdk/setup-runtime không tải ngay quá trình khám phá bề mặt hợp đồng đi kèm trước khi bộ điều hợp thực sự được sử dụng.

Thăng cấp tài khoản đơn do kênh sở hữu

Khi một kênh nâng cấp từ cấu hình cấp cao nhất dành cho một tài khoản sang channels.<id>.accounts.*, hành vi dùng chung mặc định sẽ chuyển các giá trị trong phạm vi tài khoản được thăng cấp vào accounts.default.

Các kênh đi kèm có thể thu hẹp hoặc ghi đè quá trình thăng cấp đó thông qua bề mặt hợp đồng thiết lập của mình:

• singleAccountKeysToMove: các khóa cấp cao nhất bổ sung cần được chuyển vào tài khoản được thăng cấp
• namedAccountPromotionKeys: khi các tài khoản có tên đã tồn tại, chỉ những khóa này được chuyển vào tài khoản được thăng cấp; các khóa chính sách/phân phối dùng chung vẫn nằm ở thư mục gốc của kênh
• resolveSingleAccountPromotionTarget(...): chọn tài khoản hiện có sẽ nhận các giá trị được thăng cấp

Lược đồ cấu hình

Cấu hình plugin được xác thực dựa trên JSON Schema trong tệp kê khai của bạn. Người dùng cấu hình plugin thông qua:

{  plugins: {    entries: {      "my-plugin": {        config: {          webhookSecret: "abc123",        },      },    },  },}

Plugin của bạn nhận cấu hình này dưới dạng api.pluginConfig trong quá trình đăng ký.

Đối với cấu hình dành riêng cho kênh, hãy sử dụng phần cấu hình kênh:

{  channels: {    "my-channel": {      token: "bot-token",      allowFrom: ["user1", "user2"],    },  },}

Xây dựng lược đồ cấu hình kênh

Sử dụng buildChannelConfigSchema để chuyển đổi lược đồ Zod thành trình bao ChannelConfigSchema được dùng bởi các cấu phần cấu hình do plugin sở hữu:

  const accountSchema = z.object({  token: z.string().optional(),  allowFrom: z.array(z.string()).optional(),  accounts: z.object({}).catchall(z.any()).optional(),  defaultAccount: z.string().optional(),}); const configSchema = buildChannelConfigSchema(accountSchema);

Nếu bạn đã viết hợp đồng dưới dạng JSON Schema hoặc TypeBox, hãy dùng trình trợ giúp trực tiếp để OpenClaw có thể bỏ qua việc chuyển đổi Zod sang JSON Schema trên các đường dẫn siêu dữ liệu:

  const configSchema = buildJsonChannelConfigSchema(  Type.Object({    token: Type.Optional(Type.String()),    allowFrom: Type.Optional(Type.Array(Type.String())),  }),);

Đối với plugin của bên thứ ba, hợp đồng đường dẫn lạnh vẫn là tệp kê khai plugin: phản chiếu JSON Schema đã tạo vào openclaw.plugin.json#channelConfigs để các bề mặt lược đồ cấu hình, thiết lập và giao diện người dùng có thể kiểm tra channels.<id> mà không cần tải mã thời gian chạy.

Trình hướng dẫn thiết lập

Plugin kênh có thể cung cấp trình hướng dẫn thiết lập tương tác cho openclaw onboard. Trình hướng dẫn là một đối tượng ChannelSetupWizard trên ChannelPlugin:

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "Connected",    unconfiguredLabel: "Not configured",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "Bot token",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",      keepPrompt: "Keep current token?",      inputPrompt: "Enter your bot token:",      inspect: ({ cfg, accountId }) => {        const token = (cfg.channels as any)?.["my-channel"]?.token;        return {          accountConfigured: Boolean(token),          hasConfiguredValue: Boolean(token),        };      },    },  ],};

ChannelSetupWizard cũng hỗ trợ textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize và nhiều mục khác. Xem src/setup-core.ts của plugin Discord để tham khảo ví dụ đi kèm đầy đủ.

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; const setupSurface = createOptionalChannelSetupSurface({  channel: "my-channel",  label: "My Channel",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Returns { setupAdapter, setupWizard }

Phát hành và cài đặt

Plugin bên ngoài: phát hành lên ClawHub, sau đó cài đặt:

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

Plugin trong kho mã: đặt trong cây không gian làm việc Plugin tích hợp sẵn; chúng được tự động phát hiện trong quá trình dựng.

Siêu dữ liệu gói tích hợp sẵn được khai báo tường minh, không được suy luận từ JavaScript đã dựng khi Gateway khởi động. Các phần phụ thuộc thời gian chạy thuộc về gói Plugin sở hữu chúng; quá trình khởi động OpenClaw đã đóng gói không bao giờ sửa chữa hoặc sao chép phần phụ thuộc của Plugin.

Liên quan

• Xây dựng Plugin — hướng dẫn bắt đầu từng bước
• Tệp kê khai Plugin — tài liệu tham chiếu đầy đủ về lược đồ tệp kê khai
• Các điểm vào SDK — definePluginEntry và defineChannelPluginEntry