Plugin

Quản lý Plugin Gateway, gói hook và các bundle tương thích.

Lệnh

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --jsonopenclaw plugins search <query>openclaw plugins search <query> --limit 20openclaw plugins search <query> --jsonopenclaw plugins install <path-or-spec>openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --jsonopenclaw plugins inspect --allopenclaw plugins info <id>openclaw plugins enable <id>openclaw plugins disable <id>openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins uninstall <id>openclaw plugins doctoropenclaw plugins update <id-or-npm-spec>openclaw plugins update --allopenclaw plugins marketplace entriesopenclaw plugins marketplace entries --offlineopenclaw plugins marketplace entries --jsonopenclaw plugins marketplace list <marketplace>openclaw plugins marketplace list <marketplace> --jsonopenclaw plugins marketplace refreshopenclaw plugins marketplace refresh --feed-profile clawhub-public --jsonopenclaw plugins marketplace refresh --feed-url https://clawhub.ai/v1/feeds/plugins --expected-sha256 <sha256>openclaw plugins init my-tool --name "My Tool"openclaw plugins init my-provider --name "My Provider" --type provideropenclaw plugins init my-provider --name "My Provider" --type provider --directory ./my-provideropenclaw plugins build --entry ./dist/index.jsopenclaw plugins build --entry ./dist/index.js --checkopenclaw plugins validate --entry ./dist/index.js

Để điều tra cài đặt, kiểm tra, gỡ cài đặt hoặc làm mới registry bị chậm, hãy chạy lệnh với OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1. Trace ghi thời gian từng pha vào stderr và giữ cho đầu ra JSON vẫn có thể phân tích được. Xem Gỡ lỗi.

Tác giả

openclaw plugins init stock-quotes --name "Stock Quotes"cd stock-quotesnpm run plugin:buildnpm run plugin:validate

Theo mặc định, plugins init tạo một Plugin công cụ TypeScript tối thiểu. Đối số đầu tiên là id Plugin; truyền --name cho tên hiển thị. OpenClaw dùng id cho thư mục đầu ra mặc định và cách đặt tên package. Khung công cụ dùng defineToolPlugin. plugins build import entry đã build, đọc metadata công cụ tĩnh, ghi openclaw.plugin.json, và giữ cho package.json openclaw.extensions đồng bộ. plugins validate kiểm tra manifest đã tạo, metadata package và export entry hiện tại vẫn khớp nhau. Xem Plugin công cụ để biết toàn bộ quy trình biên soạn công cụ.

Khung mẫu ghi mã nguồn TypeScript nhưng tạo metadata từ entry ./dist/index.js đã build, nên quy trình này cũng hoạt động với CLI đã phát hành. Dùng --entry <path> khi entry không phải entry package mặc định. Dùng plugins build --check trong CI để thất bại khi metadata đã tạo bị cũ mà không ghi lại tệp.

Khung mẫu Provider

openclaw plugins init acme-models --name "Acme Models" --type providercd acme-modelsnpm installnpm run buildnpm testnpm run validate

Khung mẫu provider tạo một Plugin provider văn bản/mô hình chung với phần nối API key tương thích OpenAI, một script npm run validate tích hợp sẵn cho clawhub package validate, metadata package ClawHub và một workflow GitHub được kích hoạt thủ công để phát hành đáng tin cậy trong tương lai qua GitHub Actions OIDC. Khung mẫu provider không tạo Skills và không dùng openclaw plugins build hoặc openclaw plugins validate; các lệnh đó dành cho đường dẫn metadata đã tạo của khung công cụ.

Trước khi phát hành, hãy thay URL cơ sở API, catalog mô hình, tuyến docs, văn bản thông tin xác thực và nội dung README giữ chỗ bằng chi tiết provider thật. Dùng README đã tạo cho lần phát hành ClawHub đầu tiên và thiết lập nhà phát hành đáng tin cậy.

Cài đặt

openclaw plugins search "calendar"                   # search ClawHub pluginsopenclaw plugins install <package>                      # source auto-detectionopenclaw plugins install clawhub:<package>              # ClawHub onlyopenclaw plugins install npm:<package>                  # npm onlyopenclaw plugins install npm-pack:<path.tgz>            # local npm pack through npm install semanticsopenclaw plugins install git:github.com/<owner>/<repo>  # git repoopenclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <package> --force              # overwrite existing installopenclaw plugins install <package> --pin                # pin versionopenclaw plugins install clawhub:<package> --acknowledge-clawhub-riskopenclaw plugins install <package> --dangerously-force-unsafe-installopenclaw plugins install <path>                         # local pathopenclaw plugins install <plugin>@<marketplace>         # marketplaceopenclaw plugins install <plugin> --marketplace <name>  # marketplace (explicit)openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>

Maintainer kiểm thử cài đặt ở thời điểm thiết lập có thể ghi đè nguồn cài đặt Plugin tự động bằng các biến môi trường được bảo vệ. Xem Ghi đè cài đặt Plugin.

plugins search truy vấn ClawHub để tìm các package Plugin có thể cài đặt và in ra tên package sẵn sàng cài đặt. Lệnh này tìm các package code-plugin và bundle-plugin, không phải Skills. Dùng openclaw skills search cho Skills trên ClawHub.

Các lượt cài đặt ClawHub dùng locator clawhub:<package> rõ ràng:

openclaw plugins install clawhub:openclaw-codex-app-serveropenclaw plugins install clawhub:openclaw-codex-app-server@1.2.3

Thông số plugin trần an toàn với npm cài đặt từ npm theo mặc định trong giai đoạn chuyển đổi ra mắt, trừ khi chúng khớp với một id plugin chính thức:

openclaw plugins install openclaw-codex-app-server

Dùng npm: để làm rõ phân giải chỉ qua npm:

openclaw plugins install npm:openclaw-codex-app-serveropenclaw plugins install npm:@openclaw/discord@2026.5.20openclaw plugins install npm:@scope/plugin-name@1.0.1

OpenClaw kiểm tra API plugin / khả năng tương thích gateway tối thiểu được quảng bá trước khi cài đặt. Khi phiên bản ClawHub đã chọn phát hành artifact ClawPack, OpenClaw tải xuống npm-pack .tgz có phiên bản, xác minh header digest ClawHub và digest artifact, rồi cài đặt qua đường dẫn archive thông thường. Các phiên bản ClawHub cũ hơn không có metadata ClawPack vẫn cài đặt qua đường dẫn xác minh archive package legacy. Các lượt cài đặt được ghi lại giữ metadata nguồn ClawHub, loại artifact, integrity npm, shasum npm, tên tarball, và các dữ kiện digest ClawPack để cập nhật về sau. Các lượt cài đặt ClawHub không có phiên bản giữ thông số đã ghi không có phiên bản để openclaw plugins update có thể theo các bản phát hành ClawHub mới hơn; bộ chọn phiên bản hoặc tag rõ ràng như clawhub:pkg@1.2.3 và clawhub:pkg@beta vẫn được ghim vào bộ chọn đó.

Cú pháp rút gọn marketplace

Dùng cú pháp rút gọn plugin@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:

openclaw plugins marketplace list <marketplace-name>openclaw plugins install <plugin-name>@<marketplace-name>

Dùng --marketplace khi bạn muốn truyền nguồn marketplace rõ ràng:

openclaw plugins install <plugin-name> --marketplace <marketplace-name>openclaw plugins install <plugin-name> --marketplace <owner/repo>openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>openclaw plugins install <plugin-name> --marketplace ./my-marketplace

Với đường dẫn cục bộ và archive, OpenClaw tự động phát hiện:

• 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.json hoặc layout component Claude mặc định)
• bundle tương thích Cursor (.cursor-plugin/plugin.json)

Các lượt cài đặt cục bộ được quản lý phải là thư mục plugin hoặc archive. Các file plugin .js, .mjs, .cjs, và .ts độc lập không được sao chép vào root plugin được quản lý bởi plugins install; thay vào đó hãy liệt kê chúng rõ ràng trong plugins.load.paths.

Liệt kê

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --jsonopenclaw plugins search <query>openclaw plugins search <query> --limit 20openclaw plugins search <query> --json

Nếu log khởi động ghi plugins.allow is empty; discovered non-bundled plugins may auto-load: ..., hãy chạy openclaw plugins list --enabled --verbose hoặc openclaw plugins inspect <id> với một id plugin được liệt kê để xác nhận các id plugin và sao chép các id đáng tin cậy vào plugins.allow trong openclaw.json. Khi cảnh báo có thể liệt kê mọi plugin được phát hiện, nó in một đoạn plugins.allow sẵn sàng dán đã bao gồm các id đó. Nếu một plugin tải mà không có provenance install/load-path, hãy inspect id plugin đó, rồi ghim id đáng tin cậy trong plugins.allow hoặc cài đặt lại plugin từ một nguồn đáng tin cậy để OpenClaw ghi provenance cài đặt.

plugins search là tra cứu catalog ClawHub từ xa. Nó không kiểm tra trạng thái cục bộ, không thay đổi config, không cài đặt package, và không tải mã runtime plugin. Kết quả tìm kiếm bao gồm tên package ClawHub, family, channel, phiên bản, tóm tắt, và gợi ý cài đặt như openclaw plugins install clawhub:<package>.

Với công việc plugin được đóng gói sẵn bên trong image Docker đã đóng gói, hãy bind-mount thư mục nguồn plugin đè lên đường dẫn nguồn đã đóng gói tương ứng, chẳng hạn /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 vẫn không hoạt động nên các lượt cài đặt đã đóng gói thông thường vẫn dùng dist đã biên dịch.

Để debug hook runtime:

• openclaw plugins inspect <id> --runtime --json hiển thị hook đã đăng ký và diagnostics từ một lượt kiểm tra đã tải module. Kiểm tra runtime không bao giờ cài đặt dependency; dùng openclaw doctor --fix để dọn trạng thái dependency legacy hoặc khôi phục plugin có thể tải xuống bị thiếu đang được config tham chiếu.
• openclaw gateway status --deep --require-rpc xác nhận URL/profile Gateway có thể truy cập, gợi ý service/process, đường dẫn config, và sức khỏe RPC.
• Hook hội thoại không đóng gói sẵn (llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize, agent_end) yêu cầu plugins.entries.<id>.hooks.allowConversationAccess=true.

Dùng --link để tránh sao chép thư mục plugin cục bộ (thêm vào plugins.load.paths):

openclaw plugins install -l ./my-plugin

File plugin độc lập phải được liệt kê trong plugins.load.paths thay vì được cài đặt bằng plugins install hoặc đặt trực tiếp trong ~/.openclaw/extensions hoặc <workspace>/.openclaw/extensions. Các root được tự động phát hiện đó tải thư mục package hoặc bundle plugin, còn file script cấp cao nhất được xem là helper cục bộ và bị bỏ qua.

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 lượt cài đặt và cập nhật ghi dữ liệu này vào cơ sở dữ liệu trạng thái SQLite dùng chung trong thư mục trạng thái OpenClaw đang hoạt động. Hàng installed_plugin_index lưu siêu dữ liệu installRecords bền vững, bao gồm bản ghi cho các manifest Plugin bị lỗi hoặc bị thiếu, cùng bộ nhớ đệm cold registry được suy ra từ manifest dùng bởi openclaw plugins update, gỡ cài đặt, chẩn đoán và cold plugin registry.

Khi OpenClaw thấy các bản ghi plugins.installs kế thừa đã phát hành trong cấu hình, các lượt đọc runtime xem chúng là đầu vào tương thích mà không ghi lại openclaw.json. Các lượt ghi Plugin rõ ràng và openclaw doctor --fix chuyển những bản ghi đó vào chỉ mục Plugin và xóa khóa cấu hình khi được phép ghi cấu hình; nếu một trong hai lượt ghi thất bại, các bản ghi cấu hình được giữ lại để siêu dữ liệu cài đặt không bị mất.

Gỡ cài đặt

openclaw plugins uninstall <id>openclaw plugins uninstall <id> --dry-runopenclaw plugins uninstall <id> --keep-files

uninstall xóa các bản ghi Plugin khỏi plugins.entries, chỉ mục Plugin đã lưu, các mục danh sách cho phép/từ chối Plugin và các mục plugins.load.paths được 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ý đang được theo dõi khi thư mục đó nằm trong thư mục gốc extensions Plugin của OpenClaw. Với các Plugin active memory, slot bộ nhớ được đặt lại thành memory-core.

Cập nhật

openclaw plugins update <id-or-npm-spec>openclaw plugins update --allopenclaw plugins update <id-or-npm-spec> --dry-runopenclaw plugins update @openclaw/voice-callopenclaw plugins update openclaw-codex-app-server --acknowledge-clawhub-riskopenclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install

Các lượt cập nhật áp dụng cho các bản cài đặt Plugin được theo dõi trong chỉ mục Plugin được quản lý và các bản cài đặt hook-pack được theo dõi trong hooks.internal.installs.

Kiểm tra

openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --json

Inspect hiển thị danh tính, trạng thái tải, nguồn, capability trong manifest, cờ chính sách, chẩn đoán, siêu dữ liệu cài đặt, capability bundle và mọi hỗ trợ máy chủ MCP hoặc LSP được phát hiện mà mặc định không nhập runtime Plugin. Đầu ra JSON bao gồm các hợp đồng manifest Plugin, chẳng hạn contracts.agentToolResultMiddleware và contracts.trustedToolPolicies, để operator có thể kiểm toán các khai báo bề mặt tin cậy trước khi bật hoặc khởi động lại một Plugin. Thêm --runtime để tải module Plugin và bao gồm các hook, công cụ, lệnh, dịch vụ, phương thức Gateway và route HTTP đã đăng ký. Kiểm tra runtime báo trực tiếp các phụ thuộc Plugin bị thiếu; cài đặt và sửa chữa nằm trong openclaw plugins install, openclaw plugins update và openclaw doctor --fix.

Các lệnh CLI do Plugin sở hữu thường được cài đặt làm nhóm lệnh gốc openclaw, nhưng Plugin cũng có thể đăng ký các lệnh lồng dưới một parent lõi như openclaw nodes. Sau khi inspect --runtime hiển thị một lệnh dưới cliCommands, hãy chạy lệnh đó tại đường dẫn được liệt kê; ví dụ một Plugin đăng ký demo-git có thể được xác minh bằng openclaw demo-git ping.

Mỗi Plugin được phân loại theo những gì nó thực sự đăng ký ở runtime:

• plain-capability — một loại capability (ví dụ: Plugin chỉ 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

Xem Hình dạng Plugin để biết thêm về mô hình capability.

Doctor

openclaw plugins doctor

doctor báo lỗi tải Plugin, chẩn đoán manifest/discovery, thông báo tương thích và các tham chiếu cấu hình Plugin đã cũ như slot Plugin bị thiếu. Khi cây cài đặt và cấu hình Plugin sạch, nó in No plugin issues detected. Nếu cấu hình cũ vẫn còn nhưng cây cài đặt ngoài ra vẫn khỏe, phần tóm tắt sẽ nói như vậy thay vì ngụ ý sức khỏe Plugin đầy đủ.

Nếu một Plugin đã cấu hình có trên đĩa nhưng bị chặn bởi các kiểm tra an toàn đường dẫn của loader, xác thực cấu hình giữ lại mục Plugin và báo nó là present but blocked. Hãy sửa chẩn đoán Plugin bị chặn đứng trước, chẳng hạn quyền sở hữu đường dẫn hoặc quyền world-writable, thay vì xóa cấu hình plugins.entries.<id> hoặc plugins.allow.

Với các lỗi hình 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 phần tóm tắt hình dạng export gọn trong đầu ra chẩn đoán.

Registry

openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins registry --json

Registry Plugin cục bộ là mô hình đọc lạnh đã lưu của OpenClaw cho danh tính Plugin đã cài đặt, trạng thái bật, siêu dữ liệu nguồn và quyền sở hữu đóng góp. Khởi động thông thường, tra cứu chủ sở hữu provider, phân loại thiết lập kênh và kiểm kê Plugin có thể đọc nó mà không nhập các module runtime Plugin.

Dùng plugins registry để kiểm tra registry đã lưu có hiện diện, hiện hành hay đã cũ. Dùng --refresh để 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 sửa chữa, không phải đường kích hoạt runtime.

openclaw doctor --fix cũng sửa npm drift được quản lý liền kề registry: nếu một gói @openclaw/* mồ côi hoặc được khôi phục dưới một dự án npm Plugin được quản lý hoặc thư mục gốc npm được quản lý phẳng kế thừa che khuất một Plugin được bundle, doctor xóa gói cũ đó và dựng lại registry để startup xác thực theo manifest được bundle. Doctor cũng liên kết lại gói host openclaw vào các Plugin npm được quản lý khai báo peerDependencies.openclaw, để các import runtime cục bộ theo gói như openclaw/plugin-sdk/* phân giải sau cập nhật hoặc sửa chữa npm.

Marketplace

openclaw plugins marketplace entriesopenclaw plugins marketplace entries --offlineopenclaw plugins marketplace entries --jsonopenclaw plugins marketplace entries --feed-profile <name>openclaw plugins marketplace entries --feed-url <url>openclaw plugins marketplace list <source>openclaw plugins marketplace list <source> --jsonopenclaw plugins marketplace refreshopenclaw plugins marketplace refresh --feed-profile <name>openclaw plugins marketplace refresh --feed-url <url>openclaw plugins marketplace refresh --expected-sha256 <sha256> --json

plugins marketplace entries liệt kê các mục từ nguồn cấp marketplace OpenClaw đã cấu hình. Theo mặc định, lệnh này thử dùng nguồn cấp được lưu trữ và chuyển dự phòng sang ảnh chụp nhanh mới nhất đã được chấp nhận hoặc dữ liệu đi kèm. Dùng --feed-profile <name> để đọc một hồ sơ đã cấu hình cụ thể, --feed-url <url> để đọc một URL nguồn cấp được lưu trữ rõ ràng, và --offline để đọc ảnh chụp nhanh mới nhất đã được chấp nhận mà không lấy nguồn cấp.

plugins marketplace refresh làm mới ảnh chụp nhanh nguồn cấp được lưu trữ đã cấu hình và báo cáo OpenClaw đã chấp nhận dữ liệu được lưu trữ, ảnh chụp nhanh được lưu trữ, hay dữ liệu dự phòng đi kèm. Dùng --expected-sha256 khi bên gọi cần lệnh thất bại trừ khi một payload mới từ nguồn được lưu trữ khớp với checksum đã ghim.

list của chợ ứng dụng chấp nhận đường dẫn chợ ứng dụng cục bộ, đường dẫn marketplace.json, dạng viết tắt GitHub như owner/repo, URL kho GitHub, hoặc URL git. --json in nhãn nguồn đã phân giải cùng với tệp kê khai chợ ứng dụng đã phân tích và các mục plugin.

Làm mới chợ ứng dụng sẽ tải nguồn cấp chợ ứng dụng OpenClaw được lưu trữ và lưu phản hồi đã xác thực dưới dạng ảnh chụp nhanh nguồn cấp được lưu trữ cục bộ. Khi không có tùy chọn, lệnh dùng hồ sơ nguồn cấp mặc định đã cấu hình. Dùng --feed-profile <name> để làm mới một hồ sơ đã cấu hình cụ thể, --feed-url <url> để làm mới một URL nguồn cấp được lưu trữ rõ ràng, --expected-sha256 <sha256> để yêu cầu tổng kiểm payload khớp (sha256:<hex> hoặc mã băm hex 64 ký tự thuần), và --json cho đầu ra máy đọc được. Các URL nguồn cấp được lưu trữ rõ ràng không được chứa thông tin xác thực, chuỗi truy vấn, hoặc phân đoạn. Các lần làm mới không ghim có thể báo cáo kết quả ảnh chụp nhanh được lưu trữ hoặc kết quả dự phòng đi kèm mà không làm lệnh thất bại. Các lần làm mới đã ghim sẽ thất bại trừ khi chúng chấp nhận một payload được lưu trữ mới, và các lần làm mới được lưu trữ thành công sẽ thất bại nếu OpenClaw không thể lưu ảnh chụp nhanh đã xác thực.

Liên quan

• Xây dựng plugin
• Tham chiếu CLI
• ClawHub