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

Tham chiếu về đóng gói plugin (metadata package.json), manifest (openclaw.plugin.json), mục thiết lập và schema cấu hình.

Metadata 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": "Kênh của tôi",      "blurb": "Mô tả ngắn về kênh."    }  }}

{  "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à metadata gói nhẹ dùng cho việc khám phá kênh và các bề mặt thiết lập trước khi runtime được tải.

Ví dụ:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "Kênh của tôi",      "selectionLabel": "Kênh của tôi (tự lưu trữ)",      "detailLabel": "Bot kênh của tôi",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Tích hợp trò chuyện tự lưu trữ dựa trên Webhook.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Hướng dẫn:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure hỗ trợ:

• configured: đưa kênh vào các bề mặt 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à hướng đến công chúng trên các bề mặt tài liệu/điều hướng

openclaw.install

openclaw.install là metadata gói, không phải metadata manifest.

{  "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 tải bằng:

{  "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, ngay cả đối với các kênh đã được cấu hình. Mục đầy đủ được tải sau khi Gateway bắt đầu lắng nghe.

Nếu mục nhập 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ố dành riêng cho plugin. Các không gian tên quản trị lõi được 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.

Manifest plugin

Mọi plugin gốc phải cung cấp một openclaw.plugin.json ở 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ã plugin.

{  "id": "my-plugin",  "name": "Plugin của tôi",  "description": "Bổ sung các khả năng của Plugin của tôi vào OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Bí mật xác minh Webhook"      }    }  }}

Đố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 schema. Schema trống là hợp lệ:

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

Xem Manifest plugin để tham khảo schema đầy đủ.

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 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

Mục nhập thiết lập

setup-entry.ts là một phương án nhẹ hơn cho index.ts, được 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 giữ các phần xuất an toàn cho thiết lập trong mô-đun phụ có thể dùng defineBundledChannelSetupEntry(...) từ openclaw/plugin-sdk/channel-entry-contract thay cho defineSetupPluginEntry(...). Hợp đồng đi kèm đó cũng hỗ trợ một 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 vẫn nhẹ và tường minh.

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

Đối với đường dẫn nóng chỉ dùng để 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 cho đ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:

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

Hãy dùng createSetupTranslator(...) cho nội dung cố định của trình hướng dẫn thiết lập. Nó dùng giá trị không trống đầu tiên từ OPENCLAW_LOCALE, LC_ALL, LC_MESSAGES và LANG, theo thứ tự đó, rồi dự phòng sang tiếng Anh. Đặt OPENCLAW_LOCALE=en để ghi đè rõ ràng bằng tiếng Anh. 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 chung, 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 nâng cấp tài khoản đơn đi kèm của chúng được thực hiện lười, vì vậy việc nhập plugin-sdk/setup-runtime không tải sớm cơ chế 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.

Nâ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ị theo phạm vi tài khoản được nâng cấp vào accounts.default.

Các kênh đi kèm có thể thu hẹp hoặc ghi đè việc nâng cấp đó thông qua bề mặt hợp đồng thiết lập của chúng:

• singleAccountKeysToMove: các khóa cấp cao nhất bổ sung cần được chuyển vào tài khoản được nâng cấp
• namedAccountPromotionKeys: khi đã tồn tại các tài khoản được đặt tên, chỉ những khóa này được chuyển vào tài khoản được nâ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 nâng cấp

Schema cấu hình

Cấu hình plugin được xác thực theo JSON Schema trong manifest 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 dùng phần cấu hình kênh thay thế:

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

Xây dựng schema cấu hình kênh

Hãy dùng buildChannelConfigSchema để chuyển đổi một schema Zod thành trình bao ChannelConfigSchema được dùng bởi các tạo tác 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 đã soạn 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 từ 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 bên thứ ba, hợp đồng đường dẫn nguội vẫn là manifest plugin: phản chiếu JSON Schema đã tạo vào openclaw.plugin.json#channelConfigs để các bề mặt schema 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 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: "Đã kết nối",    unconfiguredLabel: "Chưa cấu hình",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "Token bot",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "Sử dụng MY_CHANNEL_BOT_TOKEN từ môi trường?",      keepPrompt: "Giữ token hiện tại?",      inputPrompt: "Nhập token bot của bạn:",      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 để biết một ví dụ đi kèm đầy đủ.

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; const setupSurface = createOptionalChannelSetupSurface({  channel: "my-channel",  label: "Kênh của tôi",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Trả về { 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 của Plugin đi kèm; chúng được tự động phát hiện trong quá trình dựng.

Siêu dữ liệu của gói đi kèm được khai báo rõ ràng, 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 khảo đầy đủ về lược đồ tệp kê khai
• Các điểm vào SDK — definePluginEntry và defineChannelPluginEntry