Chuyển đến nội dung chính

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Tài liệu tham khảo cho việc đó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.
Bạn đang tìm hướng dẫn từng bước? Các hướng dẫn cách làm trình bày việc đóng gói theo ngữ cảnh: Plugin kênhPlugin nhà cung cấp.

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 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."
    }
  }
}
Nếu bạn phát hành Plugin bên ngoài trên ClawHub, các trường compatbuild đó là bắt buộc. Các đoạn lệnh phát hành chuẩn nằm trong docs/snippets/plugin-publish/.

Các trường openclaw

extensions
string[]
Các tệp điểm vào (tương đối với thư mục gốc của gói).
setupEntry
string
Mục chỉ dành cho thiết lập, nhẹ (tùy chọn).
channel
object
Siêu dữ liệu danh mục kênh cho các bề mặt thiết lập, bộ chọn, khởi động nhanh và trạng thái.
providers
string[]
Các id nhà cung cấp được Plugin này đăng ký.
install
object
Gợi ý cài đặt: npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.
startup
object
Các cờ hành vi khởi động.

openclaw.channel

openclaw.channel là siêu dữ liệu 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.
TrườngKiểuÝ nghĩa
idstringId kênh chuẩn.
labelstringNhãn kênh chính.
selectionLabelstringNhãn bộ chọn/thiết lập khi cần khác với label.
detailLabelstringNhãn chi tiết phụ cho danh mục kênh và bề mặt trạng thái phong phú hơn.
docsPathstringĐường dẫn tài liệu cho các liên kết thiết lập và lựa chọn.
docsLabelstringGhi đè nhãn dùng cho liên kết tài liệu khi cần khác với id kênh.
blurbstringMô tả ngắn cho onboarding/danh mục.
ordernumberThứ tự sắp xếp trong danh mục kênh.
aliasesstring[]Bí danh tra cứu bổ sung cho lựa chọn kênh.
preferOverstring[]Các id Plugin/kênh có mức ưu tiên thấp hơn mà kênh này nên xếp trên.
systemImagestringTên biểu tượng/hình ảnh hệ thống tùy chọn cho danh mục giao diện kênh.
selectionDocsPrefixstringVăn bản tiền tố trước liên kết tài liệu trong các bề mặt lựa chọn.
selectionDocsOmitLabelbooleanHiển thị trực tiếp đường dẫn tài liệu thay vì liên kết tài liệu có nhãn trong nội dung lựa chọn.
selectionExtrasstring[]Các chuỗi ngắn bổ sung được nối vào nội dung lựa chọn.
markdownCapablebooleanĐánh dấu kênh là hỗ trợ markdown cho các quyết định định dạng gửi đi.
exposureobjectĐiều khiển khả năng hiển thị kênh cho thiết lập, danh sách đã cấu hình và bề mặt tài liệu.
quickstartAllowFrombooleanCho phép kênh này tham gia luồng thiết lập khởi động nhanh allowFrom tiêu chuẩn.
forceAccountBindingbooleanYêu cầu liên kết tài khoản rõ ràng ngay cả khi chỉ có một tài khoản.
preferSessionLookupForAnnounceTargetbooleanƯu tiên tra cứu phiên khi phân giải mục tiêu thông báo cho kênh nà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: bao gồm kênh trong các bề mặt liệt kê kiểu đã cấu hình/trạng thái
  • setup: bao gồm kênh trong 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
showConfiguredshowInSetup vẫn được hỗ trợ dưới dạng bí danh cũ. Nên dùng exposure.

openclaw.install

openclaw.install là siêu dữ liệu gói, không phải siêu dữ liệu manifest.
TrườngKiểuÝ nghĩa
npmSpecstringĐặc tả npm chuẩn cho các luồng cài đặt/cập nhật.
localPathstringĐường dẫn phát triển cục bộ hoặc cài đặt đi kèm.
defaultChoice"npm" | "local"Nguồn cài đặt ưu tiên khi cả hai đều có sẵn.
minHostVersionstringPhiên bản OpenClaw tối thiểu được hỗ trợ theo dạng >=x.y.z.
expectedIntegritystringChuỗi toàn vẹn npm dist dự kiến, thường là sha512-..., cho cài đặt được ghim.
allowInvalidConfigRecoverybooleanCho phép các luồng cài đặt lại Plugin đi kèm khôi phục từ các lỗi cấu hình cũ cụ thể.
Onboarding tương tác cũng dùng openclaw.install cho các bề mặt cài đặt theo nhu cầu. Nếu Plugin của bạn hiển thị lựa chọn xác thực nhà cung cấp hoặc siêu dữ liệu thiết lập/danh mục kênh trước khi runtime tải, onboarding có thể hiển thị lựa chọn đó, nhắc chọn cài đặt npm hay cục bộ, cài đặt hoặc bật Plugin, rồi tiếp tục luồng đã chọn. Các lựa chọn onboarding npm yêu cầu siêu dữ liệu danh mục đáng tin cậy với npmSpec trong registry; phiên bản chính xác và expectedIntegrity là các ghim tùy chọn. Nếu có expectedIntegrity, các luồng cài đặt/cập nhật sẽ thực thi nó. Giữ siêu dữ liệu “hiển thị gì” trong openclaw.plugin.json và siêu dữ liệu “cài đặt nó như thế nào” trong package.json.
Nếu đặt minHostVersion, cả cài đặt và tải registry manifest đều thực thi nó. Các host cũ hơn sẽ bỏ qua Plugin; chuỗi phiên bản không hợp lệ sẽ bị từ chối.
Với cài đặt npm được ghim, hãy giữ phiên bản chính xác trong npmSpec và thêm toàn vẹn artifact dự kiến:
{
  "openclaw": {
    "install": {
      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",
      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",
      "defaultChoice": "npm"
    }
  }
}
allowInvalidConfigRecovery không phải cơ chế bỏ qua chung cho cấu hình hỏng. Nó chỉ dành cho khôi phục Plugin đi kèm trong phạm vi hẹp, để cài đặt lại/thiết lập có thể sửa các phần còn sót sau nâng cấp đã biết như thiếu đường dẫn Plugin đi kèm hoặc mục channels.<id> cũ cho chính Plugin đó. Nếu cấu hình hỏng vì lý do không liên quan, cài đặt vẫn thất bại đóng và yêu cầu người vận hành chạy openclaw doctor --fix.

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, kể 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.
Chỉ bật tải trì hoãn khi setupEntry của bạn đăng ký mọi thứ Gateway cần trước khi bắt đầu lắng nghe (đăng ký kênh, route HTTP, phương thức Gateway). Nếu mục đầy đủ sở hữu các năng lực khởi động bắt buộc, hãy giữ hành vi mặc định.
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 đặt chúng dưới tiền tố dành riêng cho Plugin. Các namespace quản trị lõi được dành riêng (config.*, exec.approvals.*, wizard.*, update.*) vẫn do lõi sở hữu và luôn phân giải thành operator.admin.

Manifest Plugin

Mọi Plugin native phải đi kèm một openclaw.plugin.json trong thư mục gốc của 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 kindchannels:
{
  "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 đi kèm một 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 khảo schema đầy đủ.

Phát hành ClawHub

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
Bí danh phát hành cũ chỉ dành cho skill là dành cho Skills. Các gói Plugin phải luôn dùng clawhub package publish.

Mục thiết lập

Tệp setup-entry.ts là 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 đã tắt).
// setup-entry.ts
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { myChannelPlugin } from "./src/channel.js";

export default defineSetupPluginEntry(myChannelPlugin);
Điều này tránh tải mã runtime nặng (thư viện crypto, đăng ký CLI, dịch vụ nền) trong các luồng thiết lập. Các kênh workspace được gói kèm giữ các export an toàn cho thiết lập trong module sidecar có thể dùng defineBundledChannelSetupEntry(...) từ openclaw/plugin-sdk/channel-entry-contract thay cho defineSetupPluginEntry(...). Contract được gói kèm đó cũng hỗ trợ export runtime tùy chọn để phần nối runtime tại thời điểm thiết lập có thể vẫn gọn nhẹ và rõ ràng.
  • Kênh bị tắt nhưng cần các bề mặt thiết lập/onboarding.
  • Kênh đã bật nhưng chưa được cấu hình.
  • Tải trì hoãn được bật (deferConfiguredChannelFullLoadUntilAfterListen).
  • Đối tượng Plugin kênh (qua defineSetupPluginEntry).
  • Mọi tuyến HTTP cần thiết trước khi Gateway lắng nghe.
  • Mọi phương thức Gateway cần trong lúc khởi động.
Những phương thức Gateway lúc khởi động đó vẫn nên tránh các namespace quản trị lõi dành riêng như config.* hoặc update.*.
  • Đăng ký CLI.
  • Dịch vụ nền.
  • Import runtime nặng (crypto, SDK).
  • Phương thức Gateway chỉ cần sau khi khởi động.

Import helper thiết lập hẹp

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 hơn 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:
Đường dẫn importDùng choExport chính
plugin-sdk/setup-runtimehelper runtime tại thời điểm thiết lập vẫn khả dụng trong setupEntry / khởi động kênh trì hoãncreatePatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy
plugin-sdk/setup-adapter-runtimeadapter thiết lập tài khoản nhận biết môi trườngcreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolshelper thiết lập/cài đặt CLI/lưu trữ/tài liệuformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
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 cho đường dẫn nóng khi import. Việc tra cứu bề mặt contract thăng cấp một tài khoản được gói kèm của chúng là lazy, nên import plugin-sdk/setup-runtime không tải ngay việc khám phá bề mặt contract được gói kèm trước khi adapter thực 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à chuyển các giá trị theo phạm vi tài khoản đã thăng cấp vào accounts.default. Các kênh được gói kèm 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 đã 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 đã 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ị đã thăng cấp
Matrix là ví dụ được gói kèm hiện tại. Nếu đúng một tài khoản Matrix có tên đã tồn tại, hoặc nếu defaultAccount trỏ tới một khóa không chuẩn hiện có như Ops, việc thăng cấp giữ nguyên tài khoản đó thay vì tạo mục accounts.default mới.

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ý. 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 vào đó:
{
  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 một schema Zod thành wrapper ChannelConfigSchema được dùng bởi các artifact cấu hình do Plugin sở hữu:
import { z } from "zod";
import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";

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);
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à 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:
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";

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 gói kèm (ví dụ Plugin Discord src/channel.setup.ts) để có ví dụ đầy đủ.
Với lời nhắc danh sách cho phép DM chỉ cần luồng note -> prompt -> parse -> merge -> patch tiêu chuẩn, ưu tiên các helper thiết lập dùng chung từ openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...)createNestedChannelParsedAllowFromPrompt(...).
Với các khối trạng thái thiết lập kênh chỉ khác nhau theo nhãn, điểm số và các dòng bổ sung tùy chọn, ưu tiên createStandardChannelSetupStatus(...) từ openclaw/plugin-sdk/setup thay vì tự viết cùng một đối tượng status trong từng Plugin.
Với các bề mặt thiết lập tùy chọn chỉ nên xuất hiện trong một số ngữ cảnh nhất định, dùng createOptionalChannelSetupSurface từ openclaw/plugin-sdk/channel-setup:
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 }
plugin-sdk/channel-setup cũng cung cấp các builder cấp thấp hơn createOptionalChannelSetupAdapter(...)createOptionalChannelSetupWizard(...) khi bạn chỉ cần một nửa của bề mặt cài đặt tùy chọn đó.Adapter/trình hướng dẫn tùy chọn được tạo sẽ fail closed trên các lần ghi cấu hình thật. Chúng dùng lại một thông báo yêu cầu cài đặt duy nhất trên validateInput, applyAccountConfigfinalize, đồng thời thêm liên kết tài liệu khi docsPath được đặt.
Với UI thiết lập dựa trên binary, ưu tiên các helper ủy quyền dùng chung thay vì sao chép cùng phần nối binary/trạng thái vào mọi kênh:
  • createDetectedBinaryStatus(...) cho các khối trạng thái chỉ khác nhau theo nhãn, gợi ý, điểm số và phát hiện binary
  • createCliPathTextInput(...) cho input văn bản dựa trên đường dẫn
  • createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...)createDelegatedResolveConfigured(...) khi setupEntry cần chuyển tiếp lazy tới một trình hướng dẫn đầy đủ nặng hơn
  • createDelegatedTextInputShouldPrompt(...) khi setupEntry chỉ cần ủy quyền quyết định textInputs[*].shouldPrompt

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 thử ClawHub trước và tự động fallback sang npm.
Plugin trong repo: đặt dưới cây workspace Plugin được 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>
Với các cài đặt lấy từ npm, openclaw plugins install chạy npm install --ignore-scripts cục bộ theo dự án (không có script vòng đời), bỏ qua các thiết lập cài đặt npm toàn cục được kế thừa. Giữ cây phụ thuộc Plugin thuần JS/TS và tránh các gói yêu cầu build postinstall.
Các Plugin do OpenClaw sở hữu được đóng gói là ngoại lệ duy nhất cho việc sửa chữa khi khởi động: khi một bản cài đặt đóng gói thấy một Plugin được bật bởi cấu hình Plugin, cấu hình kênh cũ, hoặc manifest mặc định-bật được đóng gói của Plugin đó, quá trình khởi động sẽ cài đặt các phụ thuộc thời gian chạy còn thiếu của Plugin đó trước khi nhập. Người vận hành có thể kiểm tra hoặc sửa chữa giai đoạn đó bằng openclaw plugins deps. Plugin bên thứ ba không nên dựa vào cài đặt khi khởi động; hãy tiếp tục dùng trình cài đặt Plugin tường minh.
Các phụ thuộc thời gian chạy ở cấp gói được đóng gói là siêu dữ liệu tường minh, không được suy luận từ JavaScript đã được xây dựng khi Gateway khởi động. Nếu một phụ thuộc gốc OpenClaw dùng chung phải có sẵn bên trong bản sao môi trường chạy của Plugin được đóng gói bên ngoài, hãy khai báo phụ thuộc đó trong openclaw.bundle.mirroredRootRuntimeDependencies trong manifest gói gốc.

Liên quan