Các gói Plugin

OpenClaw có thể cài đặt các plugin từ ba hệ sinh thái bên ngoài: Codex, Claude và Cursor. Chúng được gọi là gói — các gói nội dung và siêu dữ liệu mà OpenClaw ánh xạ thành các tính năng gốc như Skills, hook và công cụ MCP.

Lý do tồn tại của gói

Nhiều plugin hữu ích được phát hành theo định dạng Codex, Claude hoặc Cursor. Thay vì yêu cầu tác giả viết lại chúng thành plugin OpenClaw gốc, OpenClaw phát hiện các định dạng này và ánh xạ nội dung được hỗ trợ của chúng vào tập hợp tính năng gốc. Bạn có thể cài đặt một gói lệnh Claude hoặc một gói Skills Codex và sử dụng ngay lập tức.

Cài đặt gói

# Thư mục cục bộopenclaw plugins install ./my-bundle # Tệp lưu trữopenclaw plugins install ./my-bundle.tgz # Marketplace Claudeopenclaw plugins marketplace list <source>openclaw plugins install <plugin> --marketplace <source>

openclaw plugins listopenclaw plugins inspect <id>

openclaw gateway restart

Nội dung OpenClaw ánh xạ từ các gói

Hiện tại không phải mọi tính năng của gói đều chạy trong OpenClaw. Dưới đây là những gì hoạt động và những gì được phát hiện nhưng chưa được kết nối.

Hiện được hỗ trợ

Nội dung Skills

• Các thư mục gốc Skills của gói được tải như các thư mục gốc Skills OpenClaw thông thường.
• Các thư mục gốc commands/ của Claude được xử lý như thư mục gốc Skills bổ sung.
• Các thư mục gốc .cursor/commands/ của Cursor được xử lý như thư mục gốc Skills bổ sung.

Các tệp lệnh markdown của Claude và markdown lệnh của Cursor đều hoạt động thông qua trình tải Skills OpenClaw thông thường.

Gói hook

Các thư mục gốc hook của gói chỉ hoạt động khi sử dụng bố cục gói hook OpenClaw thông thường: HOOK.md cùng với handler.ts hoặc handler.js. Hiện tại, trường hợp này chủ yếu tương thích với Codex.

MCP cho OpenClaw nhúng

• Các gói đã bật có thể cung cấp cấu hình máy chủ MCP.
• OpenClaw hợp nhất cấu hình MCP của gói vào cài đặt OpenClaw nhúng có hiệu lực dưới dạng mcpServers.
• OpenClaw cung cấp các công cụ MCP được hỗ trợ của gói trong lượt tác tử OpenClaw nhúng bằng cách khởi chạy máy chủ stdio hoặc kết nối với máy chủ HTTP.
• Các hồ sơ công cụ coding và messaging mặc định bao gồm công cụ MCP của gói; dùng tools.deny: ["bundle-mcp"] để vô hiệu hóa đối với một tác tử hoặc Gateway.
• Cài đặt tác tử nhúng cục bộ theo dự án vẫn được áp dụng sau các giá trị mặc định của gói, vì vậy cài đặt không gian làm việc có thể ghi đè các mục MCP của gói khi cần.
• Danh mục công cụ MCP của gói được sắp xếp theo cách xác định trước khi đăng ký, để các thay đổi thứ tự listTools() ở thượng nguồn không làm xáo trộn các khối công cụ trong bộ nhớ đệm lời nhắc.

Phương thức truyền tải

Máy chủ MCP có thể sử dụng phương thức truyền tải stdio hoặc HTTP.

Stdio khởi chạy một tiến trình con:

{  "mcp": {    "servers": {      "my-server": {        "command": "node",        "args": ["server.js"],        "env": { "PORT": "3000" }      }    }  }}

HTTP kết nối với một máy chủ MCP đang chạy, mặc định dùng sse trừ khi yêu cầu streamable-http:

{  "mcp": {    "servers": {      "my-server": {        "url": "http://localhost:3100/mcp",        "transport": "streamable-http",        "headers": {          "Authorization": "Bearer ${MY_SECRET_TOKEN}"        },        "connectionTimeoutMs": 30000      }    }  }}

• transport chấp nhận "streamable-http" hoặc "sse"; nếu bỏ qua thì mặc định là sse.
• type: "http" là cấu trúc hạ nguồn gốc CLI; dùng transport: "streamable-http" trong cấu hình OpenClaw. openclaw mcp set và openclaw doctor --fix chuẩn hóa bí danh phổ biến này.
• Chỉ cho phép lược đồ URL http: và https:.
• Các giá trị headers hỗ trợ nội suy ${ENV_VAR}.
• Mục máy chủ có cả command và url sẽ bị từ chối.
• Thông tin xác thực trong URL (thông tin người dùng và tham số truy vấn) được che khỏi mô tả công cụ và nhật ký.
• connectionTimeoutMs ghi đè thời gian chờ kết nối mặc định 30 giây cho cả phương thức truyền tải stdio và HTTP. Thời gian chờ yêu cầu mặc định là 60 giây và có thể được ghi đè bằng requestTimeoutMs.

Đặt tên công cụ

OpenClaw đăng ký các công cụ MCP của gói bằng tên an toàn cho nhà cung cấp theo dạng serverName__toolName. Ví dụ: một máy chủ có khóa "vigil-harbor" cung cấp công cụ memory_search sẽ được đăng ký thành vigil-harbor__memory_search.

• Các ký tự ngoài A-Za-z0-9_- được thay bằng -.
• Các phân đoạn bắt đầu bằng ký tự không phải chữ cái sẽ được thêm tiền tố chữ cái, vì vậy các khóa máy chủ dạng số như 12306 trở thành tiền tố công cụ an toàn cho nhà cung cấp.
• Tiền tố máy chủ được giới hạn ở 30 ký tự.
• Tên công cụ đầy đủ được giới hạn ở 64 ký tự.
• Tên máy chủ trống sẽ dùng giá trị dự phòng mcp.
• Các tên đã làm sạch bị trùng được phân biệt bằng hậu tố số.
• Thứ tự công cụ được cung cấp cuối cùng được xác định theo tên an toàn, giúp các lượt tác tử nhúng lặp lại giữ ổn định bộ nhớ đệm.
• Bộ lọc hồ sơ coi mọi công cụ từ một máy chủ MCP của gói là thuộc sở hữu của plugin bundle-mcp, vì vậy danh sách cho phép/từ chối của hồ sơ có thể tham chiếu tên từng công cụ được cung cấp hoặc khóa plugin bundle-mcp.

Cài đặt OpenClaw nhúng

settings.json của Claude được nhập làm cài đặt OpenClaw nhúng mặc định khi gói được bật. OpenClaw làm sạch các khóa ghi đè shell trước khi áp dụng:

• shellPath
• shellCommandPrefix

LSP OpenClaw nhúng

• Các gói Claude đã bật có thể cung cấp cấu hình máy chủ LSP.
• OpenClaw tải .lsp.json cùng với mọi đường dẫn lspServers được khai báo trong tệp kê khai.
• Cấu hình LSP của gói được hợp nhất vào các giá trị mặc định LSP OpenClaw nhúng có hiệu lực.
• Hiện chỉ các máy chủ LSP dựa trên stdio được hỗ trợ mới có thể chạy; các phương thức truyền tải không được hỗ trợ vẫn xuất hiện trong openclaw plugins inspect <id>.

Được phát hiện nhưng không thực thi

Các thành phần sau được nhận dạng và hiển thị trong chẩn đoán, nhưng OpenClaw không chạy chúng:

• Tính năng tự động hóa agents, hooks/hooks.json, outputStyles của Claude
• .cursor/agents, .cursor/hooks.json, .cursor/rules của Cursor
• Siêu dữ liệu .app.json của Codex ngoài báo cáo khả năng

Định dạng gói

Thứ tự ưu tiên phát hiện

OpenClaw kiểm tra định dạng plugin gốc trước:

1. openclaw.plugin.json hoặc package.json hợp lệ có openclaw.extensions — được xử lý như plugin gốc
2. Dấu hiệu nhận biết gói (.codex-plugin/, .claude-plugin/ hoặc bố cục Claude/Cursor mặc định) — được xử lý như gói

Nếu một thư mục chứa cả hai, OpenClaw sử dụng đường dẫn gốc. Điều này ngăn các gói có hai định dạng bị cài đặt một phần dưới dạng gói.

Phụ thuộc thời gian chạy và dọn dẹp

• Các gói tương thích của bên thứ ba không được sửa chữa bằng npm install khi khởi động. Chúng nên được cài đặt thông qua openclaw plugins install và cung cấp mọi thứ cần thiết trong thư mục plugin đã cài đặt.
• Các plugin đi kèm do OpenClaw sở hữu hoặc được cung cấp ở dạng gọn nhẹ trong lõi hoặc có thể tải xuống thông qua trình cài đặt plugin. Khi khởi động, Gateway không bao giờ chạy trình quản lý gói cho chúng.
• openclaw doctor --fix xóa các bản ghi cài đặt plugin đi kèm cục bộ đã lỗi thời và có thể khôi phục các plugin có thể tải xuống bị thiếu trong chỉ mục plugin cục bộ khi cấu hình vẫn tham chiếu đến chúng.

Bảo mật

Gói có ranh giới tin cậy hẹp hơn plugin gốc:

• OpenClaw không tải các mô-đun thời gian chạy tùy ý của gói trong cùng tiến trình.
• Đường dẫn Skills và gói hook phải nằm bên trong thư mục gốc plugin (được kiểm tra ranh giới).
• Các tệp cài đặt được đọc với cùng cơ chế kiểm tra ranh giới.
• Các máy chủ MCP stdio được hỗ trợ có thể được khởi chạy dưới dạng tiến trình con.

Điều này giúp các gói an toàn hơn theo mặc định, nhưng bạn vẫn nên coi các gói bên thứ ba là nội dung đáng tin cậy đối với những tính năng mà chúng cung cấp.

Khắc phục sự cố

Liên quan

• Cài đặt và cấu hình plugin
• Xây dựng plugin — tạo plugin gốc
• Tệp kê khai plugin — lược đồ tệp kê khai gốc