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

Tài liệu tham chiếu cho đó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": "My Channel",      "blurb": "Short description of the channel."    }  }}

{  "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"    }  }}

Các trường openclaw

openclaw.channel

openclaw.channel là metadata gói nhẹ cho việc khám phá kênh và các bề mặt thiết lập trước khi runtime tải.

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 bề mặt liệt kê 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 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/[email protected]",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

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

Plugin kênh có thể chọn tải trì hoãn với:

{  "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 lắng nghe, ngay cả với các kênh đã được cấu hình. Điểm vào đầy đủ sẽ 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 Gateway, hãy đặt chúng dưới tiền tố dành riêng cho Plugin. Các namespace quản trị lõi dành riêng (config.*, exec.approvals.*, wizard.*, update.*) vẫn thuộc sở hữu của lõi và luôn phân giải thành operator.admin.

Manifest Plugin

Mọi Plugin native phải cung cấp openclaw.plugin.json trong gốc gói. OpenClaw 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": "My Plugin",  "description": "Adds My Plugin capabilities to OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook verification secret"      }    }  }}

Với Plugin kênh, hãy thêm kind và channels:

{  "id": "my-channel",  "kind": "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 schema. Schema rỗng là hợp lệ:

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

Xem Manifest Plugin để biết tài liệu tham chiếu schema đầy đủ.

Phát hành ClawHub

Với các gói Plugin, dùng lệnh ClawHub 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

Tệp setup-entry.ts là một lựa chọn thay thế nhẹ cho index.ts mà OpenClaw tải khi chỉ cần các bề mặt thiết lập (onboarding, sửa cấu hình, kiểm tra kênh bị tắt).

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

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

Các kênh workspace được đóng gói giữ các export an toàn cho thiết lập trong module phụ có thể dùng defineBundledChannelSetupEntry(...) từ openclaw/plugin-sdk/channel-entry-contract thay cho defineSetupPluginEntry(...). Hợp đồng được đóng gói đó cũng hỗ trợ export runtime tùy chọn để wiring runtime lúc thiết lập có thể luôn nhẹ và rõ ràng.

Import helper thiết lập hẹp

Đối với các đường dẫn nóng chỉ dành cho thiết lập, ưu tiên các seam helper thiết lập hẹp thay vì umbrella plugin-sdk/setup rộng hơn khi bạn chỉ cần một phần của bề mặt thiết lập:

Dùng seam plugin-sdk/setup rộng hơn khi bạn muốn toàn bộ hộp công cụ thiết lập dùng chung, bao gồm các helper vá cấu hình như moveSingleAccountChannelSectionToDefaultAccount(...).

Các adapter vá thiết lập vẫn an toàn trên đường dẫn nóng khi import. Tra cứu bề mặt hợp đồng thăng cấp một tài khoản được đóng gói của chúng là lazy, nên việc import plugin-sdk/setup-runtime không tải háo hức việc khám phá bề mặt hợp đồng được đóng gói trước khi adapter thật sự được dùng.

Thăng cấp một tài khoả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 một tài khoản sang channels.<id>.accounts.*, hành vi dùng chung mặc định là di chuyển các giá trị phạm vi tài khoản được thăng cấp vào accounts.default.

Các kênh được đóng gói có thể thu hẹp hoặc ghi đè việc thăng cấp đó 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 nên được di 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ỉ các khóa này được di 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 ở gốc kênh
• resolveSingleAccountPromotionTarget(...): chọn tài khoản hiện có nào nhận các giá trị được thăng cấp

Schema cấu hình

Cấu hình Plugin được xác thực với JSON Schema trong manifest của bạn. Người dùng cấu hình plugin 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 khi đă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

Dùng buildChannelConfigSchema để chuyển đổi schema Zod thành wrapper ChannelConfigSchema được dùng bởi các artifact 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 helper trực tiếp để OpenClaw có thể bỏ qua chuyển đổi Zod sang JSON Schema trên các đường dẫn metadata:

  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 lạnh vẫn là manifest plugin: phản chiếu JSON Schema đã tạo vào openclaw.plugin.json#channelConfigs để schema cấu hình, thiết lập và các bề mặt UI có thể kiểm tra channels.<id> mà không cần tải mã runtime.

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à đố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),        };      },    },  ],};

Kiểu ChannelSetupWizard hỗ trợ credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize và nhiều hơn nữa. Xem các gói plugin được đóng gói (ví dụ Plugin Discord src/channel.setup.ts) để có ví dụ đầ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, rồi 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 repo: đặt dưới cây workspace Plugin đi kèm và chúng sẽ tự động được phát hiện trong quá trình build.

Người dùng có thể cài đặt:

openclaw plugins install <package-name>

Siêu dữ liệu package đi kèm là tường minh, không được suy luận từ JavaScript đã build khi Gateway khởi động. Các phụ thuộc runtime thuộc về package 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 phản chiếu các 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
• Manifest Plugin — tài liệu tham khảo đầy đủ về schema manifest
• Điểm vào SDK — definePluginEntry và defineChannelPluginEntry