Tệp kê khai Plugin

Trang này trình bày tệp kê khai plugin OpenClaw gốc, openclaw.plugin.json. Để biết các bố cục gói tương thích (Codex, Claude, Cursor), hãy xem Gói Plugin.

Các định dạng gói tương thích sử dụng tệp kê khai riêng:

• Gói Codex: .codex-plugin/plugin.json
• Gói Claude: .claude-plugin/plugin.json, hoặc bố cục thành phần Claude mặc định không có tệp kê khai
• Gói Cursor: .cursor-plugin/plugin.json

OpenClaw tự động phát hiện các bố cục đó nhưng không xác thực chúng theo lược đồ openclaw.plugin.json bên dưới. Đối với một gói tương thích, OpenClaw đọc siêu dữ liệu gói, các thư mục gốc Skills đã khai báo, các thư mục gốc lệnh Claude, giá trị mặc định trong settings.json của Claude, giá trị mặc định LSP của Claude và các gói hook được hỗ trợ khi bố cục đáp ứng kỳ vọng thời gian chạy của OpenClaw.

Mọi Plugin OpenClaw gốc phải cung cấp openclaw.plugin.json trong thư mục gốc của Plugin. OpenClaw đọc tệp này để xác thực cấu hình mà không thực thi mã Plugin. Tệp kê khai bị thiếu hoặc không hợp lệ sẽ chặn quá trình xác thực cấu hình và được coi là lỗi Plugin.

Xem Plugin để biết hướng dẫn đầy đủ về hệ thống Plugin và Mô hình khả năng để biết mô hình khả năng gốc cùng hướng dẫn hiện tại về khả năng tương thích bên ngoài.

Tệp này có tác dụng gì

openclaw.plugin.json là siêu dữ liệu mà OpenClaw đọc trước khi tải mã Plugin của bạn. Mọi nội dung trong đó phải đủ nhẹ để kiểm tra mà không cần khởi động môi trường thời gian chạy của Plugin.

Sử dụng tệp này cho:

• danh tính Plugin, xác thực cấu hình và gợi ý giao diện người dùng cấu hình
• siêu dữ liệu xác thực, hướng dẫn thiết lập ban đầu và thiết lập (bí danh, tự động bật, biến môi trường của nhà cung cấp, lựa chọn xác thực)
• gợi ý kích hoạt cho các bề mặt của mặt phẳng điều khiển
• quyền sở hữu họ mô hình dạng viết tắt
• ảnh chụp tĩnh về quyền sở hữu khả năng (contracts)
• siêu dữ liệu trình chạy QA mà máy chủ openclaw qa dùng chung có thể kiểm tra
• siêu dữ liệu cấu hình dành riêng cho kênh được hợp nhất vào danh mục và các bề mặt xác thực

Không sử dụng tệp này để: đăng ký hành vi thời gian chạy, khai báo điểm vào mã hoặc siêu dữ liệu cài đặt npm. Những nội dung đó thuộc về mã Plugin và package.json của bạn.

Ví dụ tối thiểu

{  "id": "voice-call",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

Ví dụ đầy đủ

{  "id": "openrouter",  "name": "OpenRouter",  "description": "OpenRouter provider plugin",  "version": "1.0.0",  "providers": ["openrouter"],  "modelSupport": {    "modelPrefixes": ["router-"]  },  "modelIdNormalization": {    "providers": {      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  },  "providerEndpoints": [    {      "endpointClass": "openrouter",      "hostSuffixes": ["openrouter.ai"]    }  ],  "providerRequest": {    "providers": {      "openrouter": {        "family": "openrouter"      }    }  },  "cliBackends": ["openrouter-cli"],  "syntheticAuthRefs": ["openrouter-cli"],  "setup": {    "providers": [      {        "id": "openrouter",        "envVars": ["OPENROUTER_API_KEY"]      }    ]  },  "providerAuthAliases": {    "openrouter-coding": "openrouter"  },  "channelEnvVars": {    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "OpenRouter API key",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "OpenRouter API key",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "API key",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

Tham chiếu các trường cấp cao nhất

tham chiếu catalog

catalog cung cấp các gợi ý hiển thị tùy chọn cho trình duyệt Plugin. Máy chủ có thể bỏ qua các gợi ý này. Chúng không bao giờ cài đặt hoặc bật Plugin, cũng không thay đổi hành vi khi chạy hay mức độ tin cậy của Plugin.

{  "catalog": {    "featured": true,    "order": 10  }}

tham chiếu siêu dữ liệu nhà cung cấp tạo nội dung

Các trường siêu dữ liệu nhà cung cấp tạo nội dung mô tả những tín hiệu xác thực tĩnh cho các nhà cung cấp được khai báo trong danh sách contracts.*GenerationProviders tương ứng. OpenClaw đọc các trường này trước khi môi trường chạy của nhà cung cấp được tải, để các công cụ lõi có thể xác định một nhà cung cấp tạo nội dung có khả dụng hay không mà không cần nhập mọi Plugin nhà cung cấp.

Chỉ sử dụng các trường này cho những thông tin khai báo đơn giản, ít tốn tài nguyên. Cơ chế truyền tải, biến đổi yêu cầu, làm mới token, xác thực thông tin xác thực và hành vi tạo nội dung thực tế vẫn thuộc môi trường chạy của Plugin.

{  "contracts": {    "imageGenerationProviders": ["example-image"]  },  "imageGenerationProviderMetadata": {    "example-image": {      "aliases": ["example-image-oauth"],      "authProviders": ["example-image"],      "configSignals": [        {          "rootPath": "plugins.entries.example-image.config",          "overlayPath": "image",          "mode": {            "path": "mode",            "default": "local",            "allowed": ["local"]          },          "requiredAny": ["workflow", "workflowPath"],          "required": ["promptNodeId"]        }      ],      "authSignals": [        {          "provider": "example-image"        },        {          "provider": "example-image-oauth",          "providerBaseUrl": {            "provider": "example-image",            "defaultBaseUrl": "https://api.example.com/v1",            "allowedBaseUrls": ["https://api.example.com/v1"]          }        }      ]    }  }}

Mỗi mục siêu dữ liệu hỗ trợ:

Mỗi mục configSignals hỗ trợ:

Mỗi điều kiện bảo vệ mode hỗ trợ:

Mỗi mục authSignals hỗ trợ:

Mỗi điều kiện bảo vệ providerBaseUrl hỗ trợ:

tham chiếu siêu dữ liệu công cụ

toolMetadata sử dụng cùng cấu trúc configSignals và authSignals như siêu dữ liệu nhà cung cấp tạo nội dung, với khóa là tên công cụ. contracts.tools khai báo quyền sở hữu. toolMetadata khai báo bằng chứng khả dụng đơn giản, ít tốn tài nguyên, để OpenClaw có thể tránh nhập môi trường chạy của Plugin chỉ để hàm tạo công cụ trả về null.

{  "setup": {    "providers": [      {        "id": "example",        "envVars": ["EXAMPLE_API_KEY"]      }    ]  },  "contracts": {    "tools": ["example_search"]  },  "toolMetadata": {    "example_search": {      "authSignals": [        {          "provider": "example"        }      ],      "configSignals": [        {          "rootPath": "plugins.entries.example.config",          "overlayPath": "search",          "required": ["apiKey"]        }      ]    }  }}

Ngoài các trường configSignals/authSignals dùng chung ở trên, các mục toolMetadata còn chấp nhận optional (đánh dấu công cụ là không bắt buộc để kích hoạt Plugin) và replaySafe (đánh dấu việc thực thi công cụ là an toàn để lặp lại sau một lượt mô hình chưa hoàn tất).

Nếu một công cụ không có toolMetadata, OpenClaw giữ nguyên hành vi hiện có và tải Plugin sở hữu khi hợp đồng công cụ phù hợp với chính sách. Đối với các công cụ trên đường dẫn nóng có hàm tạo phụ thuộc vào xác thực/cấu hình, tác giả Plugin nên khai báo toolMetadata thay vì khiến lõi nhập môi trường chạy để truy vấn.

tham chiếu providerAuthChoices

Mỗi mục providerAuthChoices mô tả một lựa chọn trong quá trình thiết lập ban đầu hoặc xác thực. OpenClaw đọc mục này trước khi môi trường chạy của nhà cung cấp được tải. Danh sách thiết lập nhà cung cấp sử dụng các lựa chọn trong tệp kê khai này, các lựa chọn thiết lập được suy ra từ bộ mô tả và siêu dữ liệu catalog cài đặt mà không cần tải môi trường chạy của nhà cung cấp.

Tham chiếu commandAliases

Dùng commandAliases khi một plugin sở hữu tên lệnh thời gian chạy mà người dùng có thể nhầm lẫn đưa vào plugins.allow hoặc cố chạy dưới dạng lệnh CLI gốc. OpenClaw dùng siêu dữ liệu này cho mục đích chẩn đoán mà không cần nhập mã thời gian chạy của plugin.

{  "commandAliases": [    {      "name": "dreaming",      "kind": "runtime-slash",      "cliCommand": "memory"    }  ]}

Tham chiếu activation

Dùng activation khi plugin có thể khai báo với chi phí thấp những sự kiện thuộc mặt phẳng điều khiển nào cần đưa plugin đó vào kế hoạch kích hoạt/tải.

Khối này là siêu dữ liệu cho bộ lập kế hoạch, không phải API vòng đời. Nó không đăng ký hành vi thời gian chạy, không thay thế register(...) và không đảm bảo rằng mã plugin đã được thực thi. Bộ lập kế hoạch kích hoạt dùng các trường này để thu hẹp danh sách plugin ứng viên trước khi quay về dùng siêu dữ liệu quyền sở hữu hiện có trong manifest như providers, channels, commandAliases, setup.providers, contracts.tools và các hook.

Ưu tiên siêu dữ liệu hẹp nhất đã mô tả quyền sở hữu. Dùng providers, channels, commandAliases, các bộ mô tả thiết lập hoặc contracts khi những trường đó biểu đạt được mối quan hệ. Dùng activation cho các gợi ý bổ sung dành cho bộ lập kế hoạch mà những trường quyền sở hữu đó không thể biểu diễn. Dùng cliBackends cấp cao nhất cho các bí danh thời gian chạy CLI như claude-cli, my-cli hoặc google-gemini-cli; activation.onAgentHarnesses chỉ dành cho các ID khung chạy tác tử nhúng chưa có trường quyền sở hữu tương ứng.

Mỗi plugin nên chủ động đặt activation.onStartup. Chỉ đặt thành true khi plugin phải chạy trong quá trình khởi động Gateway. Đặt thành false khi plugin không hoạt động lúc khởi động và chỉ nên tải từ các điều kiện kích hoạt hẹp hơn. Việc bỏ qua onStartup không còn khiến plugin được tải ngầm khi khởi động; hãy dùng siêu dữ liệu kích hoạt tường minh cho các điều kiện kích hoạt khi khởi động, theo kênh, theo cấu hình, theo khung chạy tác tử, theo bộ nhớ hoặc các điều kiện hẹp hơn khác.

{  "activation": {    "onStartup": false,    "onProviders": ["openai"],    "onCommands": ["models"],    "onChannels": ["web"],    "onRoutes": ["gateway-webhook"],    "onConfigPaths": ["browser"],    "onCapabilities": ["provider", "tool"]  }}

Các thành phần đang sử dụng trực tiếp:

• Việc lập kế hoạch khởi động Gateway dùng activation.onStartup để nhập tường minh khi khởi động.
• Việc lập kế hoạch CLI được kích hoạt bởi lệnh sẽ quay về dùng commandAliases[].cliCommand hoặc commandAliases[].name cũ.
• Việc lập kế hoạch khởi động thời gian chạy tác tử dùng activation.onAgentHarnesses cho các khung chạy nhúng và cliBackends[] cấp cao nhất cho các bí danh thời gian chạy CLI.
• Việc lập kế hoạch thiết lập/kênh được kích hoạt bởi kênh sẽ quay về dùng quyền sở hữu channels[] cũ khi thiếu siêu dữ liệu kích hoạt kênh tường minh.
• Việc lập kế hoạch plugin khi khởi động dùng activation.onConfigPaths cho các bề mặt cấu hình gốc không thuộc kênh, chẳng hạn như khối browser của plugin trình duyệt đi kèm.
• Việc lập kế hoạch thiết lập/thời gian chạy được kích hoạt bởi nhà cung cấp sẽ quay về dùng quyền sở hữu providers[] cũ và cliBackends[] cấp cao nhất khi thiếu siêu dữ liệu kích hoạt nhà cung cấp tường minh.

Chẩn đoán của bộ lập kế hoạch có thể phân biệt các gợi ý kích hoạt tường minh với phương án dự phòng dựa trên quyền sở hữu trong manifest. Ví dụ, activation-command-hint nghĩa là activation.onCommands đã khớp, còn manifest-command-alias nghĩa là bộ lập kế hoạch đã dùng quyền sở hữu commandAliases. Các nhãn lý do này dành cho hoạt động chẩn đoán của máy chủ và kiểm thử; tác giả plugin nên tiếp tục khai báo siêu dữ liệu mô tả quyền sở hữu chính xác nhất.

Tham chiếu qaRunners

Dùng qaRunners khi một plugin đóng góp một hoặc nhiều trình chạy phương thức truyền tải bên dưới lệnh gốc openclaw qa dùng chung. Giữ siêu dữ liệu này gọn nhẹ và tĩnh; thời gian chạy của plugin vẫn sở hữu việc đăng ký CLI thực tế thông qua bề mặt runtime-api.ts gọn nhẹ, xuất các qaRunnerCliRegistrations tương ứng. Một adapterFactory tùy chọn cung cấp phương thức truyền tải cho các kịch bản QA dùng chung mà không thay đổi trình chạy của lệnh đã đăng ký.

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"    }  ]}

Id adapterFactory phải khớp với commandName. Không xuất các đăng ký cho những lệnh không có trong manifest.

tham chiếu setup

Sử dụng setup khi các bề mặt thiết lập và hướng dẫn ban đầu cần siêu dữ liệu chi phí thấp do plugin sở hữu trước khi runtime tải.

{  "setup": {    "providers": [      {        "id": "openai",        "authMethods": ["api-key"],        "envVars": ["OPENAI_API_KEY"],        "authEvidence": [          {            "type": "local-file-with-env",            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",            "requiresAllEnv": ["OPENAI_PROJECT"],            "credentialMarker": "openai-local-credentials",            "source": "openai local credentials"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

cliBackends cấp cao nhất vẫn hợp lệ và tiếp tục mô tả các backend suy luận CLI. setup.cliBackends là bề mặt bộ mô tả dành riêng cho thiết lập đối với các luồng mặt phẳng điều khiển/thiết lập chỉ nên sử dụng siêu dữ liệu.

Khi có mặt, setup.providers và setup.cliBackends là bề mặt tra cứu ưu tiên theo hướng bộ mô tả cho việc khám phá thiết lập. Nếu bộ mô tả chỉ thu hẹp plugin ứng viên và quá trình thiết lập vẫn cần các hook runtime phong phú hơn tại thời điểm thiết lập, hãy đặt requiresRuntime: true và giữ setup-api làm đường dẫn thực thi dự phòng.

OpenClaw cũng đưa setup.providers[].envVars vào các phép tra cứu biến môi trường và xác thực nhà cung cấp dùng chung. providerAuthEnvVars vẫn được hỗ trợ thông qua bộ điều hợp tương thích trong thời gian ngừng hỗ trợ dần, nhưng các plugin không được đóng gói vẫn sử dụng nó sẽ nhận được chẩn đoán manifest. Các plugin mới nên đặt siêu dữ liệu biến môi trường cho thiết lập/trạng thái tại setup.providers[].envVars.

Sử dụng providerUsageAuthEnvVars khi thông tin xác thực ở cấp thanh toán hoặc tổ chức phải kích hoạt resolveUsageAuth mà không trở thành thông tin xác thực suy luận. Những tên này được đưa vào cơ chế chặn dotenv của workspace, loại bỏ khỏi tiến trình con ACP, lọc bí mật trong sandbox và làm sạch bí mật trên diện rộng. Runtime của nhà cung cấp vẫn đọc và phân loại giá trị bên trong resolveUsageAuth.

OpenClaw cũng có thể suy ra các lựa chọn thiết lập đơn giản từ setup.providers[].authMethods khi không có mục nhập thiết lập, hoặc khi setup.requiresRuntime: false khai báo rằng runtime thiết lập là không cần thiết. Các mục nhập providerAuthChoices tường minh vẫn được ưu tiên cho nhãn tùy chỉnh, cờ CLI, phạm vi hướng dẫn ban đầu và siêu dữ liệu trợ lý.

Chỉ đặt requiresRuntime: false khi các bộ mô tả đó đủ cho bề mặt thiết lập. OpenClaw coi giá trị false tường minh là hợp đồng chỉ dùng bộ mô tả và sẽ không thực thi setup-api hoặc openclaw.setupEntry để tra cứu thiết lập. Nếu một plugin chỉ dùng bộ mô tả vẫn phân phối một trong các mục nhập runtime thiết lập đó, OpenClaw sẽ báo chẩn đoán bổ sung và tiếp tục bỏ qua mục nhập. Việc bỏ qua requiresRuntime duy trì hành vi dự phòng cũ để các plugin hiện có đã thêm bộ mô tả mà không có cờ này không bị hỏng.

Vì việc tra cứu thiết lập có thể thực thi mã setup-api do plugin sở hữu, các giá trị setup.providers[].id và setup.cliBackends[] đã chuẩn hóa phải duy nhất trong tất cả plugin được phát hiện. Quyền sở hữu không rõ ràng sẽ đóng khi lỗi thay vì chọn một bên thắng dựa trên thứ tự phát hiện.

Khi runtime thiết lập được thực thi, chẩn đoán sổ đăng ký thiết lập sẽ báo độ lệch bộ mô tả nếu setup-api đăng ký một nhà cung cấp hoặc backend CLI mà bộ mô tả manifest không khai báo, hoặc nếu một bộ mô tả không có đăng ký runtime tương ứng. Các chẩn đoán này mang tính bổ sung và không từ chối plugin cũ.

tham chiếu setup.providers

authEvidence dành cho các dấu hiệu thông tin xác thực cục bộ do nhà cung cấp sở hữu, có thể được xác minh mà không cần tải mã runtime. Những phép kiểm tra này phải có chi phí thấp và chỉ thực hiện cục bộ: không gọi mạng, không đọc chuỗi khóa hoặc trình quản lý bí mật, không chạy lệnh shell và không thăm dò API nhà cung cấp.

Các mục bằng chứng được hỗ trợ:

các trường setup

tham chiếu uiHints

uiHints là ánh xạ từ tên trường cấu hình đến các gợi ý kết xuất nhỏ. Khóa có thể dùng dấu chấm cho các trường cấu hình lồng nhau, nhưng không đoạn đường dẫn nào được là __proto__, constructor hoặc prototype; quá trình thiết lập sẽ từ chối các tên đó.

{  "uiHints": {    "apiKey": {      "label": "API key",      "help": "Used for OpenRouter requests",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

Mỗi gợi ý trường có thể bao gồm:

tham chiếu contracts

Chỉ sử dụng contracts cho siêu dữ liệu quyền sở hữu khả năng tĩnh mà OpenClaw có thể đọc mà không cần nhập runtime của plugin.

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"],    "trustedToolPolicies": ["workflow-budget"],    "externalAuthProviders": ["acme-ai"],    "embeddingProviders": ["openai-compatible"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "musicGenerationProviders": ["stability-audio"],    "documentExtractors": ["example-docs"],    "webContentExtractors": ["firecrawl"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "workerProviders": ["example-worker"],    "usageProviders": ["acme-ai"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

Mỗi danh sách đều là tùy chọn:

contracts.embeddedExtensionFactories được giữ lại cho các factory tiện ích mở rộng chỉ dành cho app-server Codex đi kèm. Thay vào đó, các phép biến đổi kết quả công cụ đi kèm nên khai báo contracts.agentToolResultMiddleware và đăng ký bằng api.registerAgentToolResultMiddleware(...). Các Plugin đã cài đặt chỉ có thể sử dụng cùng điểm nối middleware này khi được bật rõ ràng và chỉ cho các runtime mà chúng khai báo trong contracts.agentToolResultMiddleware.

Các Plugin đã cài đặt cần tầng chính sách tin cậy của máy chủ trước khi chạy công cụ phải khai báo từng mã định danh cục bộ đã đăng ký trong contracts.trustedToolPolicies và được bật rõ ràng. Các Plugin đi kèm tiếp tục sử dụng đường dẫn chính sách tin cậy hiện có, nhưng những Plugin đã cài đặt có mã định danh chính sách chưa khai báo sẽ bị từ chối trước khi đăng ký. Mã định danh chính sách có phạm vi theo Plugin đăng ký, vì vậy hai Plugin đều có thể khai báo và đăng ký workflow-budget; một Plugin không thể đăng ký cùng một mã định danh cục bộ hai lần.

Các đăng ký api.registerTool(...) trong runtime phải khớp với contracts.tools. Quá trình khám phá công cụ sử dụng danh sách này để chỉ tải các runtime Plugin có thể sở hữu những công cụ được yêu cầu.

Các Plugin nhà cung cấp triển khai resolveExternalAuthProfiles nên khai báo contracts.externalAuthProviders; các hook xác thực bên ngoài chưa khai báo sẽ bị bỏ qua.

Các Plugin nhà cung cấp triển khai cả resolveUsageAuth và fetchUsageSnapshot nên khai báo từng mã định danh nhà cung cấp được tự động phát hiện trong contracts.usageProviders. Quá trình khám phá mức sử dụng đọc hợp đồng này trước khi tải mã runtime, sau đó xác minh cả hai hook sau khi chỉ tải các chủ sở hữu đã khai báo.

Các nhà cung cấp embedding chung nên khai báo contracts.embeddingProviders cho từng bộ chuyển đổi được đăng ký bằng api.registerEmbeddingProvider(...). Sử dụng hợp đồng chung cho việc tạo vectơ có thể tái sử dụng, bao gồm các nhà cung cấp được tìm kiếm bộ nhớ sử dụng. contracts.memoryEmbeddingProviders là khả năng tương thích dành riêng cho embedding bộ nhớ đã lỗi thời và chỉ được duy trì trong khi các nhà cung cấp hiện có chuyển sang điểm nối nhà cung cấp embedding chung.

Các nhà cung cấp worker phải khai báo từng mã định danh api.registerWorkerProvider(...) trong contracts.workerProviders. Lõi lưu ý định bền vững trước khi gọi provision; các nhà cung cấp xác thực cài đặt của họ trước khi cấp phát bên ngoài, và các lệnh gọi lặp lại với cùng mã định danh thao tác phải tiếp nhận cùng một hợp đồng thuê. Lõi cũng lưu ảnh chụp cài đặt đã xác thực đó và truyền nó cùng leaseId đến inspect({ leaseId, profile }) và destroy({ leaseId, profile }), kể cả sau khi hồ sơ có tên được thay đổi hoặc xóa. Việc hủy có tính lũy đẳng, thao tác kiểm tra trả về hợp đóng gồm các trạng thái active / destroyed / unknown, và vật liệu khóa riêng SSH chỉ được tham chiếu thông qua SecretRef. Các điểm cuối SSH được cấp phát cũng phải bao gồm một hostKey công khai từ đầu ra cấp phát đáng tin cậy, có định dạng chính xác là algorithm base64, không có tên máy chủ hoặc chú thích, để lõi có thể ghim máy chủ trước khi kết nối. Các nhà cung cấp tạo tham chiếu danh tính động có thể triển khai resolveSshIdentity({ leaseId, profile, keyRef }) có thẩm quyền; các nhà cung cấp không triển khai phương thức này sẽ sử dụng bộ phân giải bí mật chung của lõi. Kết quả unknown có thẩm quyền sẽ khiến một bản ghi cục bộ đang hoạt động trở thành mồ côi; sau một yêu cầu hủy đã được lưu, kết quả này xác nhận quá trình tháo dỡ.

contracts.gatewayMethodDispatch hiện chấp nhận "authenticated-request". Đây là cổng kiểm soát vệ sinh API cho các tuyến HTTP Plugin gốc cố ý điều phối các phương thức mặt phẳng điều khiển Gateway trong cùng tiến trình, không phải môi trường cách ly chống lại Plugin gốc độc hại. Chỉ sử dụng nó cho các bề mặt đi kèm/dành cho người vận hành đã được xem xét chặt chẽ và vốn đã yêu cầu xác thực HTTP của Gateway. Một tuyến có quyền vẫn có thể truy cập được khi việc tiếp nhận công việc gốc của Gateway bị đóng chỉ khi tuyến đó cũng khai báo auth: "gateway" và gatewayRuntimeScopeSurface: "trusted-operator" dành riêng cho tuyến; các tuyến cùng cấp thông thường của cùng Plugin vẫn nằm sau ranh giới tiếp nhận. Điều này giúp trạng thái tạm ngưng và chức năng tiếp tục vẫn có thể truy cập mà không cấp quyền bỏ qua tiếp nhận cho toàn bộ Plugin. Giữ việc phân tích cú pháp và định hình phản hồi ở phạm vi giới hạn bên ngoài quá trình điều phối; công việc quan trọng hoặc có thay đổi trạng thái phải đi qua cơ chế điều phối phương thức Gateway, nơi sở hữu việc thực thi quy tắc tiếp nhận và phạm vi.

Tham chiếu configContracts

Sử dụng configContracts cho hành vi cấu hình do manifest sở hữu mà các trình trợ giúp lõi chung cần dùng nhưng không phải nhập runtime Plugin: phát hiện cờ nguy hiểm, đích di chuyển SecretRef và thu hẹp đường dẫn cấu hình cũ.

{  "configContracts": {    "compatibilityMigrationPaths": ["legacyProvider"],    "compatibilityRuntimePaths": ["legacyProvider.webhook"],    "dangerousFlags": [      {        "path": "accounts.*.allowUnverifiedSenders",        "equals": true      }    ],    "secretInputs": {      "bundledDefaultEnabled": false,      "paths": [        {          "path": "apiKey",          "expected": "string"        }      ]    }  }}

Mỗi mục dangerousFlags hỗ trợ:

secretInputs hỗ trợ:

Tham chiếu mediaUnderstandingProviderMetadata

Sử dụng mediaUnderstandingProviderMetadata khi một nhà cung cấp khả năng hiểu phương tiện có các mô hình mặc định, mức ưu tiên dự phòng xác thực tự động hoặc khả năng hỗ trợ tài liệu gốc mà các trình trợ giúp lõi dùng chung cần trước khi thời gian chạy được tải. Các khóa cũng phải được khai báo trong contracts.mediaUnderstandingProviders.

{  "contracts": {    "mediaUnderstandingProviders": ["example"]  },  "mediaUnderstandingProviderMetadata": {    "example": {      "capabilities": ["image", "audio"],      "defaultModels": {        "image": "example-vision-latest",        "audio": "example-transcribe-latest"      },      "autoPriority": {        "image": 40      },      "nativeDocumentInputs": ["pdf"],      "documentModels": {        "pdf": {          "textExtraction": "example-doc-text-latest",          "image": "example-doc-vision-latest"        }      }    }  }}

Mỗi mục nhà cung cấp có thể bao gồm:

Tham chiếu channelConfigs

Sử dụng channelConfigs khi Plugin kênh cần siêu dữ liệu cấu hình nhẹ trước khi thời gian chạy được tải. Việc khám phá thiết lập/trạng thái kênh ở chế độ chỉ đọc có thể sử dụng trực tiếp siêu dữ liệu này cho các kênh bên ngoài đã cấu hình khi không có mục thiết lập, hoặc khi setup.requiresRuntime: false khai báo rằng thời gian chạy thiết lập là không cần thiết.

channelConfigs là siêu dữ liệu trong manifest của Plugin, không phải một phần cấu hình cấp cao nhất mới dành cho người dùng. Người dùng vẫn cấu hình các phiên bản kênh trong channels.<channel-id>. OpenClaw đọc siêu dữ liệu manifest để xác định Plugin nào sở hữu kênh đã cấu hình đó trước khi mã thời gian chạy của Plugin thực thi.

Đối với Plugin kênh, configSchema và channelConfigs mô tả các đường dẫn khác nhau:

• configSchema xác thực plugins.entries.<plugin-id>.config
• channelConfigs.<channel-id>.schema xác thực channels.<channel-id>

Các Plugin không đi kèm khai báo channels[] cũng nên khai báo các mục channelConfigs tương ứng. Nếu không có chúng, OpenClaw vẫn có thể tải Plugin, nhưng lược đồ cấu hình trên đường dẫn nguội, bề mặt thiết lập và Control UI không thể biết hình dạng tùy chọn thuộc sở hữu của kênh cho đến khi thời gian chạy của Plugin thực thi.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled và nativeSkillsAutoEnabled có thể khai báo các giá trị mặc định auto tĩnh cho những lần kiểm tra cấu hình lệnh chạy trước khi thời gian chạy của kênh được tải. Các kênh đi kèm cũng có thể công bố cùng các giá trị mặc định thông qua package.json#openclaw.channel.commands cùng với siêu dữ liệu danh mục kênh khác do gói sở hữu.

{  "channelConfigs": {    "matrix": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "homeserverUrl": { "type": "string" }        }      },      "uiHints": {        "homeserverUrl": {          "label": "Homeserver URL",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "Matrix homeserver connection",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

Mỗi mục kênh có thể bao gồm:

Thay thế một Plugin kênh khác

Sử dụng preferOver khi Plugin của bạn là chủ sở hữu được ưu tiên cho một mã định danh kênh mà Plugin khác cũng có thể cung cấp. Các trường hợp phổ biến gồm mã định danh Plugin đã được đổi tên, một Plugin độc lập thay thế Plugin đi kèm, hoặc một bản phân nhánh được duy trì vẫn giữ nguyên mã định danh kênh để tương thích cấu hình.

{  "id": "acme-chat",  "channels": ["chat"],  "channelConfigs": {    "chat": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "webhookUrl": { "type": "string" }        }      },      "preferOver": ["chat"]    }  }}

Khi channels.chat được cấu hình, OpenClaw xem xét cả mã định danh kênh và mã định danh Plugin được ưu tiên. Nếu Plugin có mức ưu tiên thấp hơn chỉ được chọn vì nó được đi kèm hoặc được bật theo mặc định, OpenClaw sẽ tắt Plugin đó trong cấu hình thời gian chạy hiệu lực để một Plugin duy nhất sở hữu kênh và các công cụ của kênh. Lựa chọn rõ ràng của người dùng vẫn được ưu tiên: nếu người dùng bật rõ ràng cả hai Plugin (thông qua plugins.allow hoặc một cấu hình plugins.entries có nội dung thực), OpenClaw giữ nguyên lựa chọn đó và báo cáo chẩn đoán kênh/công cụ trùng lặp thay vì âm thầm thay đổi tập hợp Plugin được yêu cầu.

Chỉ dùng preferOver cho các mã định danh Plugin thực sự có thể cung cấp cùng một kênh. Đây không phải là trường ưu tiên chung và không đổi tên các khóa cấu hình của người dùng.

Tham chiếu modelSupport

Sử dụng modelSupport khi OpenClaw cần suy luận Plugin nhà cung cấp của bạn từ các mã định danh mô hình dạng rút gọn như gpt-5.6-sol hoặc claude-sonnet-4.6 trước khi thời gian chạy của Plugin được tải.

{  "modelSupport": {    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],    "modelPatterns": ["^computer-use-preview"]  }}

OpenClaw áp dụng thứ tự ưu tiên sau:

• các tham chiếu provider/model rõ ràng sử dụng siêu dữ liệu manifest providers của chủ sở hữu
• modelPatterns được ưu tiên hơn modelPrefixes
• nếu một Plugin không đi kèm và một Plugin đi kèm đều khớp, Plugin không đi kèm được ưu tiên
• sự mơ hồ còn lại được bỏ qua cho đến khi người dùng hoặc cấu hình chỉ định một nhà cung cấp

Các trường:

Các mục modelPatterns được biên dịch thông qua compileSafeRegex, hàm này từ chối những mẫu chứa phép lặp lồng nhau (ví dụ (a+)+$). Các mẫu không vượt qua kiểm tra an toàn sẽ bị âm thầm bỏ qua, tương tự biểu thức chính quy không hợp lệ về cú pháp. Hãy giữ các mẫu đơn giản và tránh các bộ định lượng lồng nhau.

Tham chiếu modelCatalog

Sử dụng modelCatalog khi OpenClaw cần biết siêu dữ liệu mô hình của nhà cung cấp trước khi tải thời gian chạy của Plugin. Đây là nguồn do manifest sở hữu cho các hàng danh mục cố định, bí danh nhà cung cấp, quy tắc ẩn và chế độ khám phá. Việc làm mới khi chạy vẫn thuộc về mã thời gian chạy của nhà cung cấp, nhưng manifest cho lõi biết khi nào cần thời gian chạy.

{  "providers": ["openai"],  "modelCatalog": {    "providers": {      "openai": {        "baseUrl": "https://api.openai.com/v1",        "api": "openai-responses",        "models": [          {            "id": "gpt-5.4",            "name": "GPT-5.4",            "input": ["text", "image"],            "reasoning": true,            "contextWindow": 256000,            "maxTokens": 128000,            "cost": {              "input": 1.25,              "output": 10,              "cacheRead": 0.125            },            "status": "available",            "tags": ["default"]          }        ]      }    },    "aliases": {      "azure-openai-responses": {        "provider": "openai",        "api": "azure-openai-responses"      }    },    "suppressions": [      {        "provider": "azure-openai-responses",        "model": "gpt-5.3-codex-spark",        "reason": "not available on Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

Các trường cấp cao nhất:

aliases tham gia vào việc tra cứu quyền sở hữu nhà cung cấp để lập kế hoạch danh mục mô hình. Đích của bí danh phải là nhà cung cấp cấp cao nhất do cùng một plugin sở hữu. Khi danh sách được lọc theo nhà cung cấp sử dụng bí danh, OpenClaw có thể đọc manifest sở hữu và áp dụng các giá trị ghi đè API/URL cơ sở của bí danh mà không cần tải runtime của nhà cung cấp. Bí danh không mở rộng các danh sách danh mục chưa lọc; danh sách tổng quát chỉ xuất các hàng của nhà cung cấp chuẩn sở hữu.

suppressions thay thế hook suppressBuiltInModel cũ trong runtime của nhà cung cấp. Các mục loại trừ chỉ được áp dụng khi nhà cung cấp thuộc sở hữu của plugin hoặc được khai báo là một khóa modelCatalog.aliases trỏ đến nhà cung cấp thuộc sở hữu. Các hook loại trừ trong runtime không còn được gọi trong quá trình phân giải mô hình.

Các trường của nhà cung cấp:

Các trường của mô hình:

Các trường loại trừ:

Không đưa dữ liệu chỉ có trong runtime vào modelCatalog. Chỉ sử dụng static khi các hàng manifest đủ hoàn chỉnh để danh sách được lọc theo nhà cung cấp và các bề mặt bộ chọn có thể bỏ qua việc khám phá registry/runtime. Sử dụng refreshable khi các hàng manifest là dữ liệu khởi tạo có thể liệt kê hoặc phần bổ sung hữu ích, nhưng quá trình làm mới/bộ nhớ đệm có thể thêm nhiều hàng hơn sau đó; bản thân các hàng có thể làm mới không phải là nguồn có thẩm quyền. Sử dụng runtime khi OpenClaw phải tải runtime của nhà cung cấp để biết danh sách.

Tham chiếu modelIdNormalization

Sử dụng modelIdNormalization để dọn dẹp mã định danh mô hình ít tốn tài nguyên, thuộc quyền sở hữu của nhà cung cấp và phải diễn ra trước khi runtime của nhà cung cấp được tải. Điều này giữ các bí danh như tên mô hình ngắn, mã định danh cũ cục bộ của nhà cung cấp và quy tắc tiền tố proxy trong manifest của plugin sở hữu thay vì trong các bảng lựa chọn mô hình cốt lõi.

{  "providers": ["anthropic", "openrouter"],  "modelIdNormalization": {    "providers": {      "anthropic": {        "aliases": {          "sonnet-4.6": "claude-sonnet-4-6"        }      },      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  }}

Các trường của nhà cung cấp:

Tham chiếu providerEndpoints

Sử dụng providerEndpoints để phân loại điểm cuối mà chính sách yêu cầu chung phải biết trước khi runtime của nhà cung cấp được tải. Phần cốt lõi vẫn sở hữu ý nghĩa của từng endpointClass; manifest của plugin sở hữu siêu dữ liệu máy chủ và URL cơ sở.

Các plugin nhà cung cấp được chính thức đưa ra bên ngoài bị loại khỏi bản phân phối cốt lõi, vì vậy manifest của chúng không hiển thị cho đến khi được cài đặt. providerEndpoints của chúng cũng phải được phản chiếu trong scripts/lib/official-external-provider-catalog.json để việc phân loại điểm cuối tiếp tục hoạt động khi không có plugin; một kiểm thử hợp đồng thực thi yêu cầu phản chiếu này.

Các trường điểm cuối:

Tham chiếu providerRequest

Dùng providerRequest cho siêu dữ liệu tương thích yêu cầu có chi phí thấp mà chính sách yêu cầu chung cần dùng nhưng không phải tải môi trường chạy của nhà cung cấp. Giữ việc viết lại tải trọng theo hành vi cụ thể trong các hook môi trường chạy của nhà cung cấp hoặc các trình trợ giúp dùng chung cho họ nhà cung cấp.

{  "providerRequest": {    "providers": {      "vllm": {        "family": "vllm",        "openAICompletions": {          "supportsStreamingUsage": true        }      }    }  }}

Các trường của nhà cung cấp:

Tham chiếu secretProviderIntegrations

Dùng secretProviderIntegrations khi một plugin có thể công bố cấu hình đặt trước của nhà cung cấp thực thi SecretRef có thể tái sử dụng. OpenClaw đọc siêu dữ liệu này trước khi môi trường chạy của plugin được tải, lưu quyền sở hữu plugin trong secrets.providers.<alias>.pluginIntegration và để việc phân giải bí mật thực tế cho môi trường chạy SecretRef. Cấu hình đặt trước chỉ được cung cấp cho các plugin đi kèm và các plugin đã cài đặt được phát hiện từ các thư mục gốc cài đặt plugin được quản lý, chẳng hạn như bản cài đặt từ git và ClawHub.

{  "secretProviderIntegrations": {    "secret-store": {      "providerAlias": "team-secrets",      "displayName": "Team secrets",      "source": "exec",      "command": "${node}",      "args": ["./bin/resolve-secrets.mjs"]    }  }}

Khóa của ánh xạ là mã định danh tích hợp. Nếu bỏ qua providerAlias, OpenClaw dùng mã định danh tích hợp làm bí danh nhà cung cấp SecretRef. Bí danh nhà cung cấp phải khớp mẫu bí danh nhà cung cấp SecretRef thông thường, ví dụ team-secrets hoặc onepassword-work.

Khi người vận hành chọn cấu hình đặt trước, OpenClaw ghi một tham chiếu nhà cung cấp như sau:

{  "secrets": {    "providers": {      "team-secrets": {        "source": "exec",        "pluginIntegration": {          "pluginId": "acme-secrets",          "integrationId": "secret-store"        }      }    }  }}

Khi khởi động/tải lại, OpenClaw phân giải nhà cung cấp đó bằng cách tải siêu dữ liệu manifest plugin hiện tại, kiểm tra plugin sở hữu đã được cài đặt và đang hoạt động, rồi hiện thực hóa lệnh thực thi từ manifest. Việc vô hiệu hóa hoặc xóa plugin sẽ thu hồi nhà cung cấp đối với các SecretRef đang hoạt động. Người vận hành muốn cấu hình thực thi độc lập vẫn có thể ghi trực tiếp các nhà cung cấp command/args thủ công.

Hiện chỉ hỗ trợ các cấu hình đặt trước source: "exec". command phải là ${node} và args[0] phải là tập lệnh phân giải bắt đầu bằng ./, có đường dẫn tương đối so với thư mục gốc plugin. Khi khởi động/tải lại, OpenClaw hiện thực hóa nó thành tệp thực thi Node hiện tại và đường dẫn tuyệt đối của tập lệnh bên trong plugin. Các tùy chọn Node như --require, --import, --loader, --env-file, --eval và --print không thuộc hợp đồng cấu hình đặt trước của manifest. Người vận hành cần lệnh không phải Node có thể trực tiếp cấu hình các nhà cung cấp thực thi thủ công độc lập.

OpenClaw suy ra trustedDirs cho các cấu hình đặt trước trong manifest từ thư mục gốc plugin và, đối với cấu hình đặt trước ${node}, từ thư mục chứa tệp thực thi Node hiện tại. Các trustedDirs được khai báo trong manifest sẽ bị bỏ qua. Các tùy chọn khác của nhà cung cấp thực thi như timeoutMs, noOutputTimeoutMs, maxOutputBytes, jsonOnly, env, passEnv và allowInsecurePath được chuyển tiếp tới cấu hình nhà cung cấp thực thi SecretRef thông thường.

Tham chiếu modelPricing

Dùng modelPricing khi một nhà cung cấp cần hành vi định giá ở mặt phẳng điều khiển trước khi môi trường chạy được tải. Bộ nhớ đệm định giá của Gateway đọc siêu dữ liệu này mà không nhập mã môi trường chạy của nhà cung cấp.

{  "providers": ["ollama", "openrouter"],  "modelPricing": {    "providers": {      "ollama": {        "external": false      },      "openrouter": {        "openRouter": {          "passthroughProviderModel": true        },        "liteLLM": false      }    }  }}

Các trường của nhà cung cấp:

Các trường nguồn:

Chỉ mục nhà cung cấp OpenClaw

Chỉ mục nhà cung cấp OpenClaw là siêu dữ liệu xem trước do OpenClaw sở hữu dành cho các nhà cung cấp có plugin có thể chưa được cài đặt. Nó không thuộc manifest plugin. Manifest plugin vẫn là nguồn có thẩm quyền đối với plugin đã cài đặt. Chỉ mục nhà cung cấp là hợp đồng dự phòng nội bộ mà các giao diện chọn mô hình trước khi cài đặt và nhà cung cấp có thể cài đặt trong tương lai sẽ sử dụng khi plugin của nhà cung cấp chưa được cài đặt.

Thứ tự thẩm quyền của danh mục:

1. Cấu hình người dùng.
2. modelCatalog trong manifest plugin đã cài đặt.
3. Bộ nhớ đệm danh mục mô hình từ lần làm mới tường minh.
4. Các hàng xem trước trong Chỉ mục nhà cung cấp OpenClaw.

Chỉ mục nhà cung cấp không được chứa bí mật, trạng thái kích hoạt, hook môi trường chạy hoặc dữ liệu mô hình trực tiếp dành riêng cho tài khoản. Các danh mục xem trước của nó dùng cùng cấu trúc hàng nhà cung cấp modelCatalog như manifest plugin, nhưng chỉ nên giới hạn ở siêu dữ liệu hiển thị ổn định, trừ khi các trường bộ điều hợp môi trường chạy như api, baseUrl, giá hoặc cờ tương thích được chủ ý giữ đồng bộ với manifest plugin đã cài đặt. Các nhà cung cấp có cơ chế khám phá /models trực tiếp nên ghi các hàng đã làm mới qua đường dẫn bộ nhớ đệm danh mục mô hình tường minh thay vì để thao tác liệt kê hoặc hướng dẫn thiết lập thông thường gọi API của nhà cung cấp.

Các mục trong Chỉ mục nhà cung cấp cũng có thể chứa siêu dữ liệu plugin có thể cài đặt cho các nhà cung cấp có plugin đã được chuyển ra khỏi lõi hoặc chưa được cài đặt vì lý do khác. Siêu dữ liệu này phản ánh mẫu danh mục kênh: tên gói, đặc tả cài đặt npm, tính toàn vẹn dự kiến và các nhãn lựa chọn xác thực có chi phí thấp là đủ để hiển thị một tùy chọn thiết lập có thể cài đặt. Sau khi plugin được cài đặt, manifest của nó được ưu tiên và mục Chỉ mục nhà cung cấp của nhà cung cấp đó bị bỏ qua.

openclaw doctor --fix di chuyển một tập hợp nhỏ, khép kín các khóa khả năng manifest cấp cao nhất cũ vào contracts.*: speechProviders, mediaUnderstandingProviders, imageGenerationProviders và tools. Không khóa nào trong số này — hoặc bất kỳ danh sách khả năng nào khác — còn được đọc dưới dạng trường manifest cấp cao nhất; quá trình tải manifest thông thường chỉ nhận diện chúng bên dưới contracts.

Manifest so với package.json

Hai tệp phục vụ các mục đích khác nhau:

Nếu bạn không chắc một phần siêu dữ liệu thuộc về đâu, hãy dùng quy tắc sau:

• nếu OpenClaw phải biết nó trước khi tải mã plugin, hãy đặt nó trong openclaw.plugin.json
• nếu nó liên quan đến đóng gói, tệp điểm vào hoặc hành vi cài đặt npm, hãy đặt nó trong package.json

Các trường package.json ảnh hưởng đến việc khám phá

Một số siêu dữ liệu plugin trước môi trường chạy được chủ ý đặt trong package.json bên dưới khối openclaw thay vì trong openclaw.plugin.json. openclaw.bundle và openclaw.bundle.json không phải là hợp đồng plugin OpenClaw; plugin gốc phải dùng openclaw.plugin.json cùng với các trường package.json#openclaw được hỗ trợ bên dưới.

Các ví dụ quan trọng:

Siêu dữ liệu manifest quyết định các lựa chọn nhà cung cấp/kênh/thiết lập nào xuất hiện trong quá trình hướng dẫn ban đầu trước khi runtime tải. package.json#openclaw.install cho quá trình hướng dẫn ban đầu biết cách tải về hoặc bật Plugin đó khi người dùng chọn một trong các lựa chọn này. Không chuyển các gợi ý cài đặt sang openclaw.plugin.json.

openclaw.install.minHostVersion được thực thi trong quá trình cài đặt và tải sổ đăng ký manifest đối với các nguồn Plugin không đi kèm. Giá trị không hợp lệ sẽ bị từ chối; giá trị hợp lệ nhưng mới hơn sẽ khiến các Plugin bên ngoài bị bỏ qua trên các máy chủ cũ hơn. Các Plugin nguồn đi kèm được giả định là có cùng phiên bản với bản checkout của máy chủ.

openclaw.install.requiredPlatformPackages dành cho các gói npm cung cấp tệp nhị phân gốc bắt buộc thông qua các bí danh tùy chọn dành riêng cho từng nền tảng. Liệt kê tên gói npm thuần cho mọi bí danh nền tảng được hỗ trợ. Trong quá trình cài đặt npm, OpenClaw chỉ xác minh bí danh đã khai báo có ràng buộc trong lockfile khớp với máy chủ hiện tại. Nếu npm báo thành công nhưng bỏ sót bí danh đó, OpenClaw thử lại một lần với bộ nhớ đệm mới và hoàn tác cài đặt nếu bí danh vẫn còn thiếu.

openclaw.compat.pluginApi được thực thi trong quá trình cài đặt gói đối với các nguồn Plugin không đi kèm. Sử dụng trường này cho ngưỡng API SDK/runtime Plugin OpenClaw mà gói được dựng dựa trên. Trường này có thể nghiêm ngặt hơn minHostVersion khi một gói Plugin cần API mới hơn nhưng vẫn giữ gợi ý cài đặt thấp hơn cho các luồng khác. Theo mặc định, quy trình đồng bộ bản phát hành chính thức của OpenClaw nâng các ngưỡng API Plugin chính thức hiện có lên phiên bản phát hành OpenClaw, nhưng các bản phát hành chỉ dành cho Plugin có thể giữ ngưỡng thấp hơn khi gói chủ ý hỗ trợ các máy chủ cũ hơn. Không chỉ sử dụng phiên bản gói làm hợp đồng tương thích. peerDependencies.openclaw vẫn là siêu dữ liệu gói npm; OpenClaw sử dụng hợp đồng openclaw.compat.pluginApi để đưa ra quyết định về khả năng tương thích khi cài đặt.

Siêu dữ liệu cài đặt theo nhu cầu chính thức nên sử dụng clawhubSpec khi Plugin được phát hành trên ClawHub; quá trình hướng dẫn ban đầu coi đó là nguồn từ xa ưu tiên và ghi lại thông tin hiện vật ClawHub sau khi cài đặt. npmSpec vẫn là phương án dự phòng tương thích cho các gói chưa chuyển sang ClawHub.

Việc ghim phiên bản npm chính xác đã nằm trong npmSpec, ví dụ "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Các mục danh mục bên ngoài chính thức nên ghép thông số chính xác với expectedIntegrity để luồng cập nhật đóng an toàn nếu hiện vật npm đã tải về không còn khớp với bản phát hành được ghim. Quá trình hướng dẫn ban đầu tương tác vẫn cung cấp các thông số npm từ sổ đăng ký đáng tin cậy, bao gồm tên gói thuần và dist-tag, nhằm bảo đảm khả năng tương thích. Chẩn đoán danh mục có thể phân biệt các nguồn chính xác, thả nổi, được ghim tính toàn vẹn, thiếu tính toàn vẹn, không khớp tên gói và lựa chọn mặc định không hợp lệ. Chẩn đoán cũng cảnh báo khi có expectedIntegrity nhưng không có nguồn npm hợp lệ để ghim. Khi có expectedIntegrity, luồng cài đặt/cập nhật sẽ thực thi trường này; khi bị bỏ qua, kết quả phân giải sổ đăng ký được ghi lại mà không ghim tính toàn vẹn.

Các Plugin kênh nên cung cấp openclaw.setupEntry khi việc quét trạng thái, danh sách kênh hoặc SecretRef cần xác định các tài khoản đã cấu hình mà không tải toàn bộ runtime. Điểm vào thiết lập nên cung cấp siêu dữ liệu kênh cùng các bộ điều hợp cấu hình, trạng thái và bí mật an toàn cho thiết lập; giữ các máy khách mạng, trình lắng nghe Gateway và runtime truyền tải trong điểm vào tiện ích mở rộng chính.

Các trường điểm vào runtime không ghi đè kiểm tra ranh giới gói đối với các trường điểm vào nguồn. Ví dụ, openclaw.runtimeExtensions không thể khiến một đường dẫn openclaw.extensions thoát ra ngoài ranh giới trở nên có thể tải được.

openclaw.install.allowInvalidConfigRecovery có phạm vi hẹp theo chủ ý. Trường này không làm cho mọi cấu hình hỏng tùy ý đều có thể cài đặt. Hiện tại, nó chỉ cho phép các luồng cài đặt khôi phục từ một số lỗi nâng cấp Plugin đi kèm đã lỗi thời cụ thể, chẳng hạn như thiếu đường dẫn Plugin đi kèm hoặc mục channels.<id> đã lỗi thời cho chính Plugin đi kèm đó. Các lỗi cấu hình không liên quan vẫn chặn cài đặt và hướng người vận hành đến openclaw doctor --fix.

openclaw.channel.persistedAuthState là siêu dữ liệu gói dành cho một mô-đun kiểm tra rất nhỏ:

{  "openclaw": {    "channel": {      "id": "whatsapp",      "persistedAuthState": {        "specifier": "./auth-presence",        "exportName": "hasAnyWhatsAppAuth"      }    }  }}

Sử dụng trường này khi các luồng thiết lập, doctor, trạng thái hoặc kiểm tra hiện diện chỉ đọc cần một phép thăm dò xác thực có/không ít tốn tài nguyên trước khi toàn bộ Plugin kênh tải. Trạng thái xác thực đã lưu không phải là trạng thái kênh đã cấu hình: không sử dụng siêu dữ liệu này để tự động bật Plugin, sửa chữa các phần phụ thuộc runtime hoặc quyết định liệu runtime của kênh có nên tải hay không. Giá trị export đích nên là một hàm nhỏ chỉ đọc trạng thái đã lưu; không định tuyến hàm này qua barrel của toàn bộ runtime kênh.

openclaw.channel.configuredState tuân theo cùng cấu trúc cho các phép kiểm tra trạng thái đã cấu hình chỉ qua biến môi trường với chi phí thấp:

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "specifier": "./configured-state",        "exportName": "hasTelegramConfiguredState"      }    }  }}

Sử dụng trường này khi một kênh có thể xác định trạng thái đã cấu hình từ biến môi trường hoặc các đầu vào nhỏ khác không thuộc runtime. Nếu phép kiểm tra cần phân giải toàn bộ cấu hình hoặc runtime kênh thực, hãy giữ logic đó trong hook config.hasConfiguredState của Plugin.

Thứ tự ưu tiên khám phá (id Plugin trùng lặp)

OpenClaw khám phá Plugin từ ba thư mục gốc, được kiểm tra theo thứ tự sau: các Plugin đi kèm OpenClaw, thư mục gốc cài đặt toàn cục (~/.openclaw/extensions) và thư mục gốc của không gian làm việc hiện tại (<workspace>/.openclaw/extensions), cùng với mọi mục plugins.load.paths được chỉ định rõ ràng.

Nếu hai kết quả khám phá có cùng id, chỉ manifest có mức ưu tiên cao nhất được giữ lại; các bản trùng lặp có mức ưu tiên thấp hơn bị loại bỏ thay vì được tải song song. Thứ tự ưu tiên, từ cao nhất đến thấp nhất:

1. Được chọn bằng cấu hình — một đường dẫn được ghim rõ ràng trong plugins.entries.<id>
2. Bản cài đặt toàn cục khớp với bản ghi cài đặt được theo dõi — một Plugin được cài đặt qua openclaw plugin install/openclaw plugin update mà cơ chế theo dõi cài đặt của OpenClaw nhận diện cho cùng id đó, ngay cả khi id này cũng thuộc về một Plugin đi kèm
3. Đi kèm — các Plugin được phân phối cùng OpenClaw
4. Không gian làm việc — các Plugin được khám phá tương đối với không gian làm việc hiện tại
5. Mọi ứng viên được khám phá khác

Hệ quả:

• Một bản fork hoặc bản sao lỗi thời của Plugin đi kèm nằm ngoài theo dõi trong không gian làm việc hoặc thư mục gốc toàn cục sẽ không che khuất bản dựng đi kèm.
• Để ghi đè một Plugin đi kèm, hãy chạy openclaw plugin install cho id đó để bản cài đặt toàn cục được theo dõi có mức ưu tiên cao hơn bản đi kèm, hoặc ghim một đường dẫn cụ thể qua plugins.entries.<id> để đường dẫn đó thắng nhờ mức ưu tiên được chọn bằng cấu hình.
• Việc loại bỏ bản trùng lặp được ghi nhật ký để Doctor và chẩn đoán khởi động có thể chỉ ra bản sao đã bị loại bỏ.
• Các trường hợp ghi đè bản trùng lặp được chọn bằng cấu hình được mô tả là ghi đè rõ ràng trong chẩn đoán, nhưng vẫn hiển thị cảnh báo để các bản fork lỗi thời và trường hợp che khuất ngoài ý muốn tiếp tục được nhận biết.

Yêu cầu về JSON Schema

• Mỗi plugin phải cung cấp một JSON Schema, ngay cả khi không chấp nhận cấu hình nào.
• Có thể sử dụng schema rỗng (ví dụ: { "type": "object", "additionalProperties": false }).
• Schema được xác thực khi đọc/ghi cấu hình, không phải trong thời gian chạy.
• Khi mở rộng hoặc phân nhánh một plugin đi kèm bằng các khóa cấu hình mới, hãy đồng thời cập nhật configSchema trong openclaw.plugin.json của plugin đó. Schema của plugin đi kèm được kiểm tra nghiêm ngặt, vì vậy việc thêm plugins.entries.<id>.config.myNewKey vào cấu hình người dùng mà không thêm myNewKey vào configSchema.properties sẽ bị từ chối trước khi môi trường chạy của plugin được tải.

Ví dụ về phần mở rộng schema:

{  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "myNewKey": {        "type": "string"      }    }  }}

Hành vi xác thực

• Các khóa channels.* không xác định là lỗi, trừ khi mã định danh kênh được khai báo trong tệp kê khai của plugin. Nếu cùng mã định danh đó cũng xuất hiện trong plugins.allow, plugins.entries hoặc plugins.installs (một plugin được tham chiếu nhưng hiện không thể được phát hiện), OpenClaw sẽ hạ mức này xuống thành cảnh báo.
• plugins.entries.<id>, plugins.allow và plugins.deny tham chiếu đến mã định danh plugin không xác định sẽ tạo cảnh báo ("mục cấu hình lỗi thời bị bỏ qua"), không phải lỗi, để quá trình nâng cấp và các plugin đã bị xóa/đổi tên không ngăn Gateway khởi động.
• plugins.slots.memory tham chiếu đến mã định danh plugin không xác định là lỗi, ngoại trừ plugin bên ngoài chính thức memory-lancedb đã biết, trường hợp này chỉ tạo cảnh báo.
• Nếu một plugin đã được cài đặt nhưng có tệp kê khai hoặc schema bị hỏng hay bị thiếu, quá trình xác thực sẽ thất bại và Doctor sẽ báo cáo lỗi plugin.
• Nếu cấu hình plugin tồn tại nhưng plugin bị vô hiệu hóa, cấu hình vẫn được giữ lại và một cảnh báo sẽ xuất hiện trong Doctor và nhật ký.

Xem Tài liệu tham khảo cấu hình để biết toàn bộ schema plugins.*.

Lưu ý

• Tệp kê khai là bắt buộc đối với các plugin OpenClaw gốc, bao gồm cả các plugin được tải từ hệ thống tệp cục bộ. Môi trường chạy vẫn tải riêng mô-đun plugin; tệp kê khai chỉ phục vụ việc phát hiện và xác thực.
• Tệp kê khai gốc được phân tích bằng JSON5, vì vậy chấp nhận chú thích, dấu phẩy cuối và khóa không đặt trong dấu ngoặc kép, miễn là giá trị cuối cùng vẫn là một đối tượng.
• Trình tải tệp kê khai chỉ đọc các trường tệp kê khai đã được lập tài liệu. Tránh sử dụng các khóa cấp cao nhất tùy chỉnh.
• Có thể bỏ qua channels, providers, cliBackends và skills nếu plugin không cần đến chúng.
• providerCatalogEntry phải luôn gọn nhẹ và không nên nhập mã môi trường chạy có phạm vi rộng; hãy dùng trường này cho siêu dữ liệu danh mục nhà cung cấp tĩnh hoặc các bộ mô tả phát hiện có phạm vi hẹp, không dùng để thực thi trong thời gian xử lý yêu cầu.
• Các loại plugin độc quyền được chọn thông qua plugins.slots.*: kind: "memory" qua plugins.slots.memory (mặc định là memory-core), kind: "context-engine" qua plugins.slots.contextEngine (mặc định là legacy).
• Khai báo loại plugin độc quyền trong tệp kê khai này. OpenClawPluginDefinition.kind tại điểm vào môi trường chạy đã bị ngừng khuyến nghị và chỉ còn được giữ làm cơ chế dự phòng tương thích cho các plugin cũ.
• Siêu dữ liệu biến môi trường (setup.providers[].envVars, providerAuthEnvVars đã bị ngừng khuyến nghị và channelEnvVars) chỉ mang tính khai báo. Các bề mặt chỉ đọc như trạng thái, kiểm tra, xác thực phân phối cron và những bề mặt khác vẫn áp dụng chính sách tin cậy và kích hoạt hiệu lực của plugin trước khi coi một biến môi trường là đã được cấu hình.
• Đối với siêu dữ liệu trình hướng dẫn trong thời gian chạy cần mã nhà cung cấp, hãy xem Hook môi trường chạy của nhà cung cấp.
• Nếu plugin của bạn phụ thuộc vào các mô-đun gốc, hãy lập tài liệu về các bước xây dựng và mọi yêu cầu đối với danh sách cho phép của trình quản lý gói (ví dụ: allow-build-scripts của pnpm + pnpm rebuild <package>).

Nội dung liên quan