Plugin

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

# Lệnh

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json
openclaw plugins install <path-or-spec>
openclaw plugins inspect <id>
openclaw plugins inspect <id> --runtime
openclaw plugins inspect <id> --json
openclaw plugins inspect --all
openclaw plugins info <id>
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins uninstall <id>
openclaw plugins doctor
openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json

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

# Cài đặt

openclaw plugins search "calendar"                   # search ClawHub plugins
openclaw plugins install <package>                      # npm by default
openclaw plugins install clawhub:<package>              # ClawHub only
openclaw plugins install npm:<package>                  # npm only
openclaw plugins install npm-pack:<path.tgz>            # local npm pack through npm install semantics
openclaw plugins install git:github.com/<owner>/<repo>  # git repo
openclaw plugins install git:github.com/<owner>/<repo>@<ref>
openclaw plugins install <package> --force              # overwrite existing install
openclaw plugins install <package> --pin                # pin version
openclaw plugins install <package> --dangerously-force-unsafe-install
openclaw plugins install <path>                         # local path
openclaw plugins install <plugin>@<marketplace>         # marketplace
openclaw plugins install <plugin> --marketplace <name>  # marketplace (explicit)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>

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

Cài đặt ClawHub dùng locator rõ ràng clawhub:<package>:

openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:[email protected]

Spec plugin an toàn với npm dạng trần cài đặt từ npm theo mặc định trong giai đoạn chuyển đổi lúc ra mắt:

openclaw plugins install openclaw-codex-app-server

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

openclaw plugins install npm:openclaw-codex-app-server
openclaw plugins install npm:@scope/[email protected]

OpenClaw kiểm tra API Plugin được công bố / mức tương thích Gateway tối thiểu trước khi cài đặt. Khi phiên bản ClawHub được chọn phát hành artifact ClawPack, OpenClaw tải xuống .tgz npm-pack có phiên bản, xác minh header digest của ClawHub và digest của artifact, rồi cài đặt thông qua đường dẫn archive thông thường. Các phiên bản ClawHub cũ hơn không có siêu dữ liệu ClawPack vẫn cài đặt thông qua đường dẫn xác minh package archive cũ. Các bản cài đặt đã ghi lại giữ siêu dữ liệu nguồn ClawHub, loại artifact, npm integrity, npm shasum, tên tarball và các dữ kiện digest ClawPack để dùng cho các lần cập nhật sau. Các bản cài đặt ClawHub không có phiên bản giữ spec đã 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; các selector phiên bản hoặc tag tường minh như clawhub:[email protected] và clawhub:pkg@beta vẫn được ghim vào selector đó.

# 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 bộ nhớ đệm 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 một cách tường minh:

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

# Liệt kê

openclaw plugins list
openclaw plugins list --enabled
openclaw plugins list --verbose
openclaw plugins list --json
openclaw plugins search <query>
openclaw plugins search <query> --limit 20
openclaw plugins search <query> --json

--enabledboolean

Chỉ hiển thị các Plugin đã bật.

--verboseboolean

Chuyển từ chế độ xem bảng sang các dòng chi tiết theo từng Plugin với siêu dữ liệu source/origin/version/activation.

--jsonboolean

Inventory có thể đọc bằng máy cùng diagnostics registry và trạng thái cài đặt dependency package.

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

Đối với công việc Plugin đi kèm bên trong image Docker đã đóng gói, hãy bind-mount thư mục nguồn Plugin lên đúng đườ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 thuần túy vẫn không hoạt động, nên 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> --runtime --json hiển thị các 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 cũ hoặc khôi phục các Plugin có thể tải xuống bị thiếu nhưng được tham chiếu bởi config.
• openclaw gateway status --deep --require-rpc xác nhận Gateway có thể truy cập, gợi ý service/process, đường dẫn config và tình trạng RPC.
• Các hook hội thoại không đi kèm (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 một thư mục cục bộ (thêm vào plugins.load.paths):

openclaw plugins install -l ./my-plugin

# 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 config người dùng. Các lần cài đặt và cập nhật ghi nó vào plugins/installs.json dưới thư mục trạng thái OpenClaw đang hoạt động. Map installRecords cấp cao nhất của nó là nguồn bền vững của siêu dữ liệu cài đặt, bao gồm các bản ghi cho manifest Plugin bị hỏng hoặc thiếu. Mảng plugins là bộ nhớ đệm registry lạnh được dẫn xuất 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, uninstall, diagnostics và registry Plugin lạnh.

Khi OpenClaw thấy các bản ghi plugins.installs cũ đã ship trong config, 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 tường minh và openclaw doctor --fix di chuyển những bản ghi đó vào chỉ mục Plugin và xóa khóa config khi được phép ghi config; nếu một trong hai lượt ghi thất bại, các bản ghi config đượ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-run
openclaw plugins uninstall <id> --keep-files

uninstall xóa bản ghi Plugin khỏi plugins.entries, chỉ mục Plugin đã lưu, các mục danh sách allow/deny Plugin và các mục plugins.load.paths được liên kết khi áp dụng. Trừ khi đặt --keep-files, uninstall cũng xóa thư mục cài đặt được quản lý đang được theo dõi khi nó nằm trong thư mục gốc extensions Plugin của OpenClaw. Với Plugin active memory, slot memory đặt lại thành memory-core.

# Cập nhật

openclaw plugins update <id-or-npm-spec>
openclaw plugins update --all
openclaw plugins update <id-or-npm-spec> --dry-run
openclaw plugins update @openclaw/voice-call
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install

Các bản cập nhật áp dụng cho những 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> --runtime
openclaw plugins inspect <id> --json

Inspect hiển thị identity, trạng thái tải, source, khả năng manifest, cờ chính sách, diagnostics, siêu dữ liệu cài đặt, khả năng bundle và mọi hỗ trợ MCP hoặc LSP server được phát hiện mà mặc định không import runtime Plugin. Thêm --runtime để tải module Plugin và bao gồm các hook, tool, command, service, gateway method và HTTP route đã đăng ký. Kiểm tra runtime báo cáo trực tiếp các dependency Plugin bị thiếu; cài đặt và sửa chữa vẫn nằm trong openclaw plugins install, openclaw plugins update và openclaw doctor --fix.

Các lệnh CLI do Plugin sở hữu được cài đặt làm nhóm lệnh openclaw gốc. Sau khi inspect --runtime hiển thị một lệnh dưới cliCommands, hãy chạy nó dưới dạng openclaw <command> ...; 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ật sự đăng ký tại runtime:

• plain-capability — một loại khả năng (ví dụ: Plugin chỉ dành cho nhà cung cấp)
• hybrid-capability — nhiều loại khả năng (ví dụ: văn bản + giọng nói + hình ảnh)
• hook-only — chỉ có hook, không có khả năng hoặc bề mặt
• non-capability — công cụ/lệnh/dịch vụ nhưng không có khả năng

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

# Doctor

openclaw plugins doctor

doctor báo cáo lỗi tải Plugin, chẩn đoán manifest/phát hiện và thông báo tương thích. Khi mọi thứ sạch, nó in No plugin issues detected.

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 cáo là present but blocked. Sửa chẩn đoán Plugin bị chặn trước đó, chẳng hạn như 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 mô-đun như thiếu export register/activate, chạy lại với OPENCLAW_PLUGIN_LOAD_DEBUG=1 để đưa bản tóm tắt hình dạng export gọn vào đầu ra chẩn đoán.

# Registry

openclaw plugins registry
openclaw plugins registry --refresh
openclaw plugins registry --json

Registry Plugin cục bộ là mô hình đọc lạnh được lưu bền vững 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 nhà cung cấp, phân loại thiết lập kênh và kiểm kê Plugin có thể đọc nó mà không cần nhập các mô-đun runtime của Plugin.

Dùng plugins registry để kiểm tra registry đã lưu bền vững có tồn tại, hiện hành hay đã cũ không. Dùng --refresh để dựng lại nó từ chỉ mục Plugin đã lưu bền vững, 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 lệch managed npm liền kề registry: nếu một package @openclaw/* mồ côi hoặc được khôi phục dưới thư mục gốc managed plugin npm che khuất một Plugin đi kèm, doctor sẽ xóa package cũ đó và dựng lại registry để khởi động xác thực theo manifest đi kèm.

# Marketplace

openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json

Danh sách Marketplace chấp nhận đường dẫn marketplace cục bộ, đường dẫn marketplace.json, dạng viết tắt GitHub như owner/repo, URL repo GitHub hoặc URL git. --json in nhãn nguồn đã phân giải cùng manifest marketplace đã phân tích và các mục Plugin.

# Liên quan

• Xây dựng Plugin
• Tham chiếu CLI
• Plugin cộng đồng