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

Tài liệu tham khảo về đóng gói plugin (siêu dữ liệu package.json), manifest (openclaw.plugin.json), mục 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 một 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à siêu dữ liệu gói nhẹ dành cho phát hiện 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 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à siêu dữ liệu gói, không phải siêu dữ liệu manifest.

{
  "openclaw": {
    "install": {
      "npmSpec": "@wecom/[email protected]",
      "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. Điểm vào đầ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ý phương thức RPC gateway, hãy giữ 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 gốc phải cung cấp một openclaw.plugin.json ở 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"
      }
    }
  }
}

Đối 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ả 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 Manifest plugin để biết tham chiếu lược đồ đầy đủ.

# Phát hành 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-run
clawhub package publish your-org/your-plugin

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

Tệp setup-entry.ts là một phương á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 vì defineSetupPluginEntry(...). Hợp đồng đóng gói đó cũng hỗ trợ export runtime tùy chọn để phần nối dây runtime lúc thiết lập có thể luôn nhẹ và tường minh.

# 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ộ bộ 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 cho đường dẫn nóng khi import. Phần tra cứu bề mặt hợp đồng thăng cấp tài khoản đơn được đóng gói của chúng là lazy, nên việc import plugin-sdk/setup-runtime không tải sớm phần phát hiện bề mặt hợp đồng đóng gói trước khi adapter thật 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 tài khoản đơn lên channels.<id>.accounts.*, hành vi dùng chung mặc định là chuyển các giá trị theo 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 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 chuyển vào tài khoản được thăng cấp
• namedAccountPromotionKeys: khi tài khoản được đặt tên đã tồn tại, chỉ các khóa này 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 theo 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 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à bề mặt UI có thể kiểm tra channels.<id> mà không 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à 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 (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 }

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

Plugin bên ngoài: xuất bản 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 repo: đặt dưới cây workspace Plugin đi kèm và chúng sẽ được tự động phát hiện trong quá trình build.

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

openclaw plugins install <package-name>

Metadata của package đi kèm là tường minh, không được suy luận từ JavaScript đã build khi khởi động Gateway. 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 sao chép 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 — tham chiếu schema manifest đầy đủ
• Điểm vào SDK — definePluginEntry và defineChannelPluginEntry