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

Tham chiếu cho đóng gói plugin (siêu dữ liệu package.json), manifest (openclaw.plugin.json), mục thiết lập và schema 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ẹ cho việc phát hiện kênh và các bề mặt thiết lập trước khi thời gian chạy 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à hướng ra công chúng trong bề mặt 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 manifest.

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

Tải đầy đủ trì hoãn

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

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

Khi 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. Mục đầy đủ sẽ tải sau khi gateway bắt đầu lắng nghe.

Nếu mục thiết lập/đầy đủ của bạn đăng ký các phương thức RPC gateway, hãy giữ chúng trên 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 sở hữu lõi và luôn phân giải thành operator.admin.

Manifest plugin

Mọi plugin native phải kèm theo 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, thêm kind và channels:

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

Ngay cả các Plugin không có cấu hình cũng phải phát hành kèm schema. Schema rỗng là hợp lệ:

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

Xem manifest Plugin để biết tham chiếu schema đầy đủ.

Xuất bản lên ClawHub

Đối với các gói Plugin, hãy 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à lựa chọn thay thế nhẹ hơn 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 sẵn giữ export an toàn cho thiết lập trong các module sidecar có thể dùng defineBundledChannelSetupEntry(...) từ openclaw/plugin-sdk/channel-entry-contract thay vì defineSetupPluginEntry(...). Contract được đóng gói đó cũng hỗ trợ export runtime tùy chọn để wiring runtime ở thời điểm thiết lập có thể vẫn nhẹ và tường minh.

Import helper 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 helper thiết lập phạm vi hẹp hơn 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 điểm nối plugin-sdk/setup rộng hơn khi bạn muốn bộ công cụ thiết lập dùng chung đầy đủ, bao gồm các helper vá cấu hình như moveSingleAccountChannelSectionToDefaultAccount(...).

Dùng createSetupTranslator(...) cho nội dung wizard thiết lập cố định. Nó tuân theo locale của wizard CLI (OPENCLAW_LOCALE, rồi đến các biến locale hệ thống) và fallback về 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 khóa catalog 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 Plugin đóng gói chính thức.

Các adapter vá thiết lập vẫn an toàn cho đường dẫn nóng khi import. Việc tra cứu bề mặt contract thăng cấp tài khoản đơn được đóng gói của chúng là lazy, nên import plugin-sdk/setup-runtime không tải háo hức quá trình khám phá bề mặt contract được đóng gói trước khi adapter thực sự được 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 một tài khoản sang channels.<id>.accounts.*, hành vi dùng chung mặc định là 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 đó thông qua bề mặt contract thiết lập của chúng:

• singleAccountKeysToMove: các khóa cấp cao nhất bổ sung nê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ỉ các khóa này được chuyển vào tài khoản được thăng cấp; các khóa policy/delivery dùng chung vẫn ở root của 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 dựa trên 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 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

Dùng buildChannelConfigSchema để chuyển 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 contract 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, contract đườ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à bề mặt UI có thể kiểm tra channels.<id> mà không tải mã runtime.

Wizard thiết lập

Plugin kênh có thể cung cấp wizard thiết lập tương tác cho openclaw onboard. Wizard 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),        };      },    },  ],};

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 sẵn (ví dụ Plugin Discord src/channel.setup.ts) để biết 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 }

Xuất bản và cài đặt

Plugin bên ngoài: xuất bản 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 được đóng gó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 gói đóng 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ề 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 phản chiếu 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ề schema tệp kê khai
• Điểm vào SDK — definePluginEntry và defineChannelPluginEntry