Quản lý các Plugin Gateway, hook pack và bundle tương thích.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.
Hệ thống Plugin
Hướng dẫn cho người dùng cuối về cài đặt, bật và khắc phục sự cố Plugin.
Bundle Plugin
Mô hình tương thích bundle.
Manifest Plugin
Các trường manifest và schema cấu hình.
Bảo mật
Gia cố bảo mật cho cài đặt Plugin.
Lệnh
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1. Trace ghi thời gian từng pha vào stderr và giữ cho đầu ra JSON có thể phân tích cú pháp. Xem Gỡ lỗi.
Các Plugin đi kèm được phát hành cùng OpenClaw. Một số được bật theo mặc định (ví dụ như nhà cung cấp mô hình đi kèm, nhà cung cấp giọng nói đi kèm và Plugin trình duyệt đi kèm); các Plugin khác yêu cầu
plugins enable.Plugin OpenClaw gốc phải phát hành openclaw.plugin.json với JSON Schema nội tuyến (configSchema, ngay cả khi rỗng). Bundle tương thích dùng manifest bundle riêng của chúng.plugins list hiển thị Format: openclaw hoặc Format: bundle. Đầu ra list/info chi tiết cũng hiển thị kiểu con của bundle (codex, claude, hoặc cursor) cùng với các khả năng bundle được phát hiện.Cài đặt
ClawHub là bề mặt phân phối và khám phá chính cho hầu hết Plugin. Npm vẫn là đường dẫn dự phòng và cài đặt trực tiếp được hỗ trợ. Trong quá trình di chuyển sang ClawHub, OpenClaw vẫn phát hành một số gói Plugin
@openclaw/* do OpenClaw sở hữu trên npm; các phiên bản gói đó có thể tụt lại so với mã nguồn đi kèm giữa các đợt phát hành Plugin. Nếu npm báo một gói Plugin do OpenClaw sở hữu là đã ngừng khuyến nghị sử dụng, phiên bản đã phát hành đó là một artifact bên ngoài cũ; hãy dùng Plugin đi kèm với OpenClaw hiện tại hoặc một checkout cục bộ cho đến khi gói npm mới hơn được phát hành.Include cấu hình và khôi phục cấu hình không hợp lệ
Include cấu hình và khôi phục cấu hình không hợp lệ
Nếu phần
plugins của bạn được hỗ trợ bởi một $include một tệp, plugins install/update/enable/disable/uninstall ghi xuyên qua tệp được include đó và giữ nguyên openclaw.json. Include gốc, mảng include và include có override cùng cấp sẽ thất bại đóng thay vì làm phẳng. Xem Include cấu hình để biết các dạng được hỗ trợ.Nếu cấu hình không hợp lệ trong khi cài đặt, plugins install thường thất bại đóng và yêu cầu bạn chạy openclaw doctor --fix trước. Trong quá trình khởi động Gateway, cấu hình không hợp lệ cho một Plugin được cô lập vào Plugin đó để các kênh và Plugin khác có thể tiếp tục chạy; openclaw doctor --fix có thể cách ly mục nhập Plugin không hợp lệ. Ngoại lệ duy nhất được tài liệu hóa tại thời điểm cài đặt là đường dẫn khôi phục hẹp cho Plugin đi kèm đối với các Plugin chọn rõ ràng openclaw.install.allowInvalidConfigRecovery.--force và cài đặt lại so với cập nhật
--force và cài đặt lại so với cập nhật
--force dùng lại đích cài đặt hiện có và ghi đè một Plugin hoặc hook pack đã cài đặt tại chỗ. Dùng tùy chọn này khi bạn cố ý cài đặt lại cùng một id từ một đường dẫn cục bộ, archive, gói ClawHub hoặc artifact npm mới. Với nâng cấp thường lệ của một Plugin npm đã được theo dõi, hãy ưu tiên openclaw plugins update <id-or-npm-spec>.Nếu bạn chạy plugins install cho một id Plugin đã được cài đặt, OpenClaw dừng lại và chỉ bạn đến plugins update <id-or-npm-spec> để nâng cấp thông thường, hoặc đến plugins install <package> --force khi bạn thật sự muốn ghi đè cài đặt hiện tại từ một nguồn khác.Phạm vi --pin
Phạm vi --pin
--pin chỉ áp dụng cho cài đặt npm. Tùy chọn này không được hỗ trợ với --marketplace, vì cài đặt marketplace lưu metadata nguồn marketplace thay vì một spec npm.--dangerously-force-unsafe-install
--dangerously-force-unsafe-install
--dangerously-force-unsafe-install là tùy chọn phá kính cho các kết quả dương tính giả trong bộ quét mã nguy hiểm tích hợp. Tùy chọn này cho phép cài đặt tiếp tục ngay cả khi bộ quét tích hợp báo phát hiện mức critical, nhưng không bỏ qua các chặn chính sách hook before_install của Plugin và không bỏ qua lỗi quét.Cờ CLI này áp dụng cho luồng cài đặt/cập nhật Plugin. Cài đặt phụ thuộc Skills do Gateway hỗ trợ dùng override yêu cầu tương ứng dangerouslyForceUnsafeInstall, trong khi openclaw skills install vẫn là một luồng tải xuống/cài đặt Skills ClawHub riêng.Nếu một Plugin bạn đã phát hành trên ClawHub bị chặn bởi quét registry, hãy dùng các bước dành cho nhà phát hành trong ClawHub.Hook pack và spec npm
Hook pack và spec npm
plugins install cũng là bề mặt cài đặt cho các hook pack phơi bày openclaw.hooks trong package.json. Dùng openclaw hooks để hiển thị hook có lọc và bật từng hook, không phải để cài đặt gói.Spec npm là chỉ registry (tên gói + phiên bản chính xác hoặc dist-tag tùy chọn). Spec Git/URL/file và dải semver bị từ chối. Cài đặt phụ thuộc chạy theo dự án cục bộ với --ignore-scripts để an toàn, ngay cả khi shell của bạn có thiết lập cài đặt npm toàn cục.Dùng npm:<package> khi bạn muốn bỏ qua tra cứu ClawHub và cài đặt trực tiếp từ npm. Spec gói trần vẫn ưu tiên ClawHub và chỉ rơi về npm khi ClawHub không có gói hoặc phiên bản đó.Spec trần và @latest vẫn ở kênh ổn định. Nếu npm phân giải một trong hai thành bản prerelease, OpenClaw dừng lại và yêu cầu bạn chọn tham gia rõ ràng bằng một thẻ prerelease như @beta/@rc hoặc một phiên bản prerelease chính xác như @1.2.3-beta.4.Nếu spec cài đặt trần khớp với id Plugin đi kèm (ví dụ diffs), OpenClaw cài đặt trực tiếp Plugin đi kèm. Để cài đặt một gói npm cùng tên, hãy dùng spec có scope rõ ràng (ví dụ @scope/diffs).Archive
Archive
Archive được hỗ trợ:
.zip, .tgz, .tar.gz, .tar. Archive Plugin OpenClaw gốc phải chứa openclaw.plugin.json hợp lệ ở gốc Plugin sau khi giải nén; archive chỉ chứa package.json bị từ chối trước khi OpenClaw ghi bản ghi cài đặt.Cài đặt marketplace Claude cũng được hỗ trợ.clawhub:<package> rõ ràng:
npm: để buộc chỉ phân giải npm, ví dụ khi không truy cập được ClawHub hoặc bạn biết gói chỉ tồn tại trên npm:
openclaw plugins update có thể theo các bản phát hành ClawHub mới hơn; selector phiên bản hoặc thẻ rõ ràng như clawhub:pkg@1.2.3 và clawhub:pkg@beta vẫn được ghim vào selector đó.
Viết tắt marketplace
Dùng viết tắtplugin@marketplace khi tên marketplace tồn tại trong cache registry cục bộ của Claude tại ~/.claude/plugins/known_marketplaces.json:
--marketplace khi bạn muốn truyền nguồn marketplace rõ ràng:
- Nguồn marketplace
- Quy tắc marketplace từ xa
- tên known-marketplace của Claude từ
~/.claude/plugins/known_marketplaces.json - gốc marketplace cục bộ hoặc đường dẫn
marketplace.json - viết tắt repo GitHub như
owner/repo - URL repo GitHub như
https://github.com/owner/repo - URL git
- Plugin OpenClaw gốc (
openclaw.plugin.json) - bundle tương thích Codex (
.codex-plugin/plugin.json) - bundle tương thích Claude (
.claude-plugin/plugin.jsonhoặc bố cục thành phần Claude mặc định) - bundle tương thích Cursor (
.cursor-plugin/plugin.json)
Bundle tương thích cài vào gốc Plugin thông thường và tham gia cùng luồng list/info/enable/disable. Hiện tại, bundle skills, command-skills của Claude, mặc định
settings.json của Claude, mặc định .lsp.json / lspServers được khai báo trong manifest của Claude, command-skills của Cursor và thư mục hook Codex tương thích được hỗ trợ; các khả năng bundle được phát hiện khác được hiển thị trong diagnostics/info nhưng chưa được nối vào thực thi runtime.Liệt kê
Chỉ hiển thị các Plugin đã bật.
Chuyển từ chế độ xem bảng sang các dòng chi tiết theo từng Plugin với metadata nguồn/xuất xứ/phiên bản/kích hoạt.
Inventory có thể đọc bằng máy cùng diagnostics registry.
plugins list đọc sổ đăng ký Plugin cục bộ đã lưu trước, với phương án dự phòng được suy ra chỉ từ manifest khi sổ đăng ký bị thiếu hoặc không hợp lệ. Lệnh này hữu ích để kiểm tra một Plugin có được cài đặt, bật và hiển thị cho kế hoạch khởi động nguội hay không, nhưng không phải là phép dò runtime trực tiếp của một tiến trình Gateway đang chạy. Sau khi thay đổi mã Plugin, trạng thái bật, chính sách hook hoặc plugins.load.paths, hãy khởi động lại Gateway phục vụ kênh trước khi kỳ vọng mã register(api) hoặc hook mới chạy. Với các triển khai từ xa/container, hãy xác minh bạn đang khởi động lại đúng tiến trình con openclaw gateway run, không chỉ một tiến trình wrapper./app/extensions/synology-chat. OpenClaw sẽ phát hiện overlay nguồn đã mount đó
trước /app/dist/extensions/synology-chat; một thư mục nguồn được sao chép thông thường
vẫn không có hiệu lực để các bản cài đặt đóng gói thông thường vẫn dùng dist đã biên dịch.
Để gỡ lỗi hook runtime:
openclaw plugins inspect <id> --jsonhiển thị các hook đã đăng ký và chẩn đoán từ một lượt kiểm tra đã tải module.openclaw gateway status --deep --require-rpcxác nhận Gateway có thể truy cập, gợi ý dịch vụ/tiến trình, đường dẫn cấu hình và tình trạng RPC.- Các hook hội thoại không đi kèm (
llm_input,llm_output,before_agent_finalize,agent_end) yêu cầuplugins.entries.<id>.hooks.allowConversationAccess=true.
--link để tránh sao chép một thư mục cục bộ (thêm vào plugins.load.paths):
--force không được hỗ trợ với --link vì các bản cài đặt liên kết dùng lại đường dẫn nguồn thay vì sao chép đè lên một đích cài đặt được quản lý.Dùng --pin trên các bản cài đặt npm để lưu spec chính xác đã phân giải (name@version) trong chỉ mục Plugin được quản lý, trong khi vẫn giữ hành vi mặc định là không ghim.Chỉ mục Plugin
Siêu dữ liệu cài đặt Plugin là trạng thái do máy quản lý, không phải cấu hình người dùng. Các thao tác cài đặt và cập nhật ghi nó vàoplugins/installs.json trong thư mục trạng thái OpenClaw đang hoạt động. Bản đồ installRecords cấp cao nhất của nó là nguồn bền vững cho siêu dữ liệu cài đặt, bao gồm các bản ghi cho manifest Plugin bị hỏng hoặc bị thiếu. Mảng plugins là bộ nhớ đệm sổ đăng ký nguội được suy ra từ manifest. Tệp này bao gồm cảnh báo không chỉnh sửa và được dùng bởi openclaw plugins update, gỡ cài đặt, chẩn đoán và sổ đăng ký Plugin nguội.
Khi OpenClaw thấy các bản ghi plugins.installs cũ được phát hành trong cấu hình, nó chuyển chúng vào chỉ mục Plugin và xóa khóa cấu hình; nếu một trong hai thao tác ghi thất bại, các bản ghi cấu hình sẽ được giữ lại để siêu dữ liệu cài đặt không bị mất.
Phụ thuộc runtime
plugins deps kiểm tra giai đoạn phụ thuộc runtime đã đóng gói cho các Plugin đi kèm do OpenClaw sở hữu. Đây không phải là đường dẫn cài đặt/cập nhật cho Plugin npm bên thứ ba hoặc ClawHub.
Dùng --repair khi một bản cài đặt đóng gói báo thiếu phụ thuộc runtime đi kèm trong lúc khởi động Gateway hoặc plugins doctor. Sửa chữa chỉ cài đặt các phụ thuộc Plugin đi kèm đang bật bị thiếu với lifecycle scripts bị tắt. Dùng --prune để xóa các gốc phụ thuộc runtime bên ngoài không xác định đã lỗi thời còn sót lại từ các bố cục đóng gói cũ hơn.
Gỡ cài đặt
uninstall xóa bản ghi Plugin khỏi plugins.entries, chỉ mục Plugin đã lưu, các mục trong danh sách cho phép/từ chối Plugin, và các mục plugins.load.paths đã liên kết khi áp dụng. Trừ khi đặt --keep-files, gỡ cài đặt cũng xóa thư mục cài đặt được quản lý đã theo dõi khi thư mục đó nằm trong gốc phần mở rộng Plugin của OpenClaw. Đối với các Plugin active memory, slot bộ nhớ đặt lại về memory-core.
--keep-config được hỗ trợ dưới dạng bí danh đã ngừng khuyến nghị cho --keep-files.Cập nhật
hooks.internal.installs.
Resolving plugin id vs npm spec
Resolving plugin id vs npm spec
Khi bạn truyền một id Plugin, OpenClaw dùng lại spec cài đặt đã ghi cho Plugin đó. Điều đó có nghĩa là các dist-tag đã lưu trước đó như
@beta và các phiên bản ghim chính xác tiếp tục được dùng trong các lần chạy update <id> sau này.Với các bản cài đặt npm, bạn cũng có thể truyền một spec gói npm rõ ràng với dist-tag hoặc phiên bản chính xác. OpenClaw phân giải tên gói đó trở lại bản ghi Plugin đã theo dõi, cập nhật Plugin đã cài đặt đó và ghi lại spec npm mới cho các lần cập nhật dựa trên id trong tương lai.Truyền tên gói npm mà không có phiên bản hoặc tag cũng phân giải trở lại bản ghi Plugin đã theo dõi. Dùng cách này khi một Plugin đã được ghim vào một phiên bản chính xác và bạn muốn chuyển nó trở lại dòng phát hành mặc định của registry.Version checks and integrity drift
Version checks and integrity drift
Trước một bản cập nhật npm trực tiếp, OpenClaw kiểm tra phiên bản gói đã cài đặt so với siêu dữ liệu registry npm. Nếu phiên bản đã cài đặt và danh tính artifact đã ghi đã khớp với đích đã phân giải, bản cập nhật sẽ bị bỏ qua mà không tải xuống, cài đặt lại hoặc ghi lại
openclaw.json.Khi có hash integrity đã lưu và hash artifact đã fetch thay đổi, OpenClaw xem đó là hiện tượng trôi artifact npm. Lệnh tương tác openclaw plugins update in ra các hash kỳ vọng và thực tế rồi yêu cầu xác nhận trước khi tiếp tục. Các helper cập nhật không tương tác sẽ thất bại đóng trừ khi caller cung cấp một chính sách tiếp tục rõ ràng.--dangerously-force-unsafe-install on update
--dangerously-force-unsafe-install on update
--dangerously-force-unsafe-install cũng có trên plugins update như một override khẩn cấp cho các false positive của quét mã nguy hiểm tích hợp trong lúc cập nhật Plugin. Nó vẫn không bỏ qua các chặn chính sách before_install của Plugin hoặc chặn do lỗi quét, và chỉ áp dụng cho cập nhật Plugin, không áp dụng cho cập nhật hook-pack.Kiểm tra
- plain-capability — một loại capability (ví dụ: Plugin chỉ dành cho provider)
- hybrid-capability — nhiều loại capability (ví dụ: văn bản + giọng nói + hình ảnh)
- hook-only — chỉ hook, không có capability hoặc bề mặt
- non-capability — công cụ/lệnh/dịch vụ nhưng không có capability
Cờ
--json xuất báo cáo máy đọc được, phù hợp cho script và kiểm toán. inspect --all hiển thị một bảng toàn hệ thống với các cột dạng, loại capability, thông báo tương thích, capability bundle và tóm tắt hook. info là bí danh của inspect.Doctor
doctor báo cáo lỗi tải Plugin, chẩn đoán manifest/discovery và thông báo tương thích. Khi mọi thứ sạch, nó in No plugin issues detected.
Đối với các lỗi dạng module như thiếu export register/activate, hãy chạy lại với OPENCLAW_PLUGIN_LOAD_DEBUG=1 để bao gồm bản tóm tắt dạng export ngắn gọn trong đầu ra chẩn đoán.
Registry
plugins registry để kiểm tra sổ đăng ký đã lưu có tồn tại, hiện hành hay lỗi thời hay không. Dùng --refresh để xây dựng lại nó từ chỉ mục Plugin đã lưu, chính sách cấu hình và siêu dữ liệu manifest/package. Đây là đường dẫn sửa chữa, không phải đường dẫn kích hoạt runtime.
Marketplace
marketplace.json, dạng viết tắt GitHub như owner/repo, một URL repo GitHub hoặc một URL git. --json in nhãn nguồn đã phân giải cùng với manifest marketplace đã phân tích cú pháp và các mục Plugin.