Tài liệu tham khảo cho việc đóng gói Plugin (siêu dữ liệuDocumentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
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 một trường openclaw để cho hệ thống Plugin biết Plugin của bạn cung cấp gì:
- Plugin kênh
- Plugin nhà cung cấp / đường cơ sở ClawHub
Nếu bạn phát hành Plugin bên ngoài trên ClawHub, các trường
compat và build đó 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
Các tệp điểm vào (tương đối với thư mục gốc của gói).
Mục chỉ dành cho thiết lập, nhẹ (tùy chọn).
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.
Các id nhà cung cấp được Plugin này đăng ký.
Gợi ý cài đặt:
npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.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ường | Kiểu | Ý nghĩa |
|---|---|---|
id | string | Id kênh chuẩn. |
label | string | Nhãn kênh chính. |
selectionLabel | string | Nhãn bộ chọn/thiết lập khi cần khác với label. |
detailLabel | string | Nhãn chi tiết phụ cho danh mục kênh và bề mặt trạng thái phong phú hơn. |
docsPath | string | Đường dẫn tài liệu cho các liên kết thiết lập và lựa chọn. |
docsLabel | string | Ghi đè nhãn dùng cho liên kết tài liệu khi cần khác với id kênh. |
blurb | string | Mô tả ngắn cho onboarding/danh mục. |
order | number | Thứ tự sắp xếp trong danh mục kênh. |
aliases | string[] | Bí danh tra cứu bổ sung cho lựa chọn kênh. |
preferOver | string[] | 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. |
systemImage | string | Tên biểu tượng/hình ảnh hệ thống tùy chọn cho danh mục giao diện kênh. |
selectionDocsPrefix | string | Vă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. |
selectionDocsOmitLabel | boolean | Hiể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. |
selectionExtras | string[] | Các chuỗi ngắn bổ sung được nối vào nội dung lựa chọn. |
markdownCapable | boolean | Đánh dấu kênh là hỗ trợ markdown cho các quyết định định dạng gửi đi. |
exposure | object | Đ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. |
quickstartAllowFrom | boolean | Cho phép kênh này tham gia luồng thiết lập khởi động nhanh allowFrom tiêu chuẩn. |
forceAccountBinding | boolean | Yê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. |
preferSessionLookupForAnnounceTarget | boolean | Ư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. |
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áisetup: bao gồm kênh trong các bộ chọn thiết lập/cấu hình tương tácdocs: đánh dấu kênh là công khai trong các bề mặt tài liệu/điều hướng
showConfigured và showInSetup 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ường | Kiểu | Ý nghĩa |
|---|---|---|
npmSpec | string | Đặc tả npm chuẩn cho các luồng cài đặt/cập nhật. |
localPath | string | Đườ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. |
minHostVersion | string | Phiên bản OpenClaw tối thiểu được hỗ trợ theo dạng >=x.y.z. |
expectedIntegrity | string | Chuỗi toàn vẹn npm dist dự kiến, thường là sha512-..., cho cài đặt được ghim. |
allowInvalidConfigRecovery | boolean | Cho 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ể. |
Hành vi onboarding
Hành vi onboarding
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.Thực thi minHostVersion
Thực thi minHostVersion
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.Cài đặt npm được ghim
Cài đặt npm được ghim
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:Phạm vi allowInvalidConfigRecovery
Phạm vi allowInvalidConfigRecovery
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: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.
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ộtopenclaw.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.
kind và channels:
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: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ệpsetup-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).
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.
When OpenClaw uses setupEntry instead of the full entry
When OpenClaw uses setupEntry instead of the full entry
- 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).
What setupEntry must register
What setupEntry must register
- Đố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.
config.* hoặc update.*.What setupEntry should NOT include
What setupEntry should NOT include
- Đă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 umbrellaplugin-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 import | Dùng cho | Export chính |
|---|---|---|
plugin-sdk/setup-runtime | helper 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ãn | createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy |
plugin-sdk/setup-adapter-runtime | adapter thiết lập tài khoản nhận biết môi trường | createEnvPatchedAccountSetupAdapter |
plugin-sdk/setup-tools | helper thiết lập/cài đặt CLI/lưu trữ/tài liệu | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
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 sangchannels.<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ấpnamedAccountPromotionKeys: 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ênhresolveSingleAccountPromotionTarget(...): 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: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 đó:
Xây dựng schema cấu hình kênh
DùngbuildChannelConfigSchema để 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:
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 choopenclaw onboard. Trình hướng dẫn là đối tượng ChannelSetupWizard trên ChannelPlugin:
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 đủ.
Shared allowFrom prompts
Shared allowFrom prompts
Standard channel setup status
Standard channel setup status
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.Optional channel setup surface
Optional channel setup surface
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:plugin-sdk/channel-setup cũng cung cấp các builder cấp thấp hơn createOptionalChannelSetupAdapter(...) và 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, applyAccountConfig và finalize, đồng thời thêm liên kết tài liệu khi docsPath được đặt.Binary-backed setup helpers
Binary-backed setup helpers
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 binarycreateCliPathTextInput(...)cho input văn bản dựa trên đường dẫncreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)vàcreateDelegatedResolveConfigured(...)khisetupEntrycần chuyển tiếp lazy tới một trình hướng dẫn đầy đủ nặng hơncreateDelegatedTextInputShouldPrompt(...)khisetupEntrychỉ cần ủy quyền quyết địnhtextInputs[*].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:- Auto (ClawHub then npm)
- ClawHub only
- npm package spec
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.openclaw.bundle.mirroredRootRuntimeDependencies trong manifest gói gốc.
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ề lược đồ manifest
- Điểm vào SDK —
definePluginEntryvàdefineChannelPluginEntry