Nội bộ kiến trúc Plugin

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Quy trình tải

1. phát hiện các gốc Plugin ứng viên
2. đọc manifest bundle gốc hoặc tương thích và metadata package
3. từ chối các ứng viên không an toàn
4. chuẩn hóa cấu hình Plugin (plugins.enabled, allow, deny, entries, slots, load.paths)
5. quyết định trạng thái bật cho từng ứng viên
6. tải các module gốc đã bật: các module đóng gói sẵn được xây dựng dùng trình tải gốc; mã nguồn TypeScript cục bộ của bên thứ ba dùng phương án dự phòng khẩn cấp Jiti
7. gọi hook register(api) gốc và thu thập các đăng ký vào Plugin registry
8. hiển thị registry cho các lệnh/bề mặt runtime

​

Hành vi ưu tiên manifest

• nhận diện Plugin
• phát hiện các kênh/Skills/lược đồ cấu hình đã khai báo hoặc khả năng bundle
• kiểm thực plugins.entries.<id>.config
• bổ sung nhãn/placeholder cho Control UI
• hiển thị metadata cài đặt/catalog
• giữ lại descriptor kích hoạt và thiết lập rẻ mà không tải runtime Plugin

• việc tải CLI thu hẹp vào các Plugin sở hữu lệnh chính được yêu cầu
• phân giải thiết lập kênh/Plugin thu hẹp vào các Plugin sở hữu id kênh được yêu cầu
• phân giải thiết lập/runtime provider tường minh thu hẹp vào các Plugin sở hữu id provider được yêu cầu
• lập kế hoạch khởi động Gateway dùng activation.onStartup cho các import khởi động tường minh và các trường hợp chọn không tham gia khởi động; Plugin không có metadata khởi động chỉ tải thông qua các trigger kích hoạt hẹp hơn

​

Ranh giới cache Plugin

• PluginLoaderCacheState và runtime registry đang hoạt động tương thích
• cache jiti/module và cache trình tải bề mặt công khai dùng để tránh import cùng một bề mặt runtime nhiều lần
• cache hệ thống tệp cho artifact Plugin đã cài đặt
• map ngắn hạn theo từng lần gọi để chuẩn hóa đường dẫn hoặc phân giải trùng lặp

• kết quả khám phá
• registry manifest trực tiếp
• registry manifest được tái tạo từ chỉ mục Plugin đã cài đặt
• tra cứu chủ sở hữu provider, chặn model, chính sách provider hoặc metadata artifact công khai
• bất kỳ câu trả lời nào khác dẫn xuất từ manifest mà manifest, chỉ mục đã cài đặt hoặc đường dẫn tải đã thay đổi cần hiển thị ở lần đọc metadata tiếp theo

​

Mô hình registry

• bản ghi Plugin (danh tính, nguồn, origin, trạng thái, chẩn đoán)
• công cụ
• hook cũ và hook có kiểu
• kênh
• provider
• trình xử lý RPC Gateway
• route HTTP
• registrar CLI
• dịch vụ nền
• lệnh do Plugin sở hữu

• module Plugin -> đăng ký registry
• runtime lõi -> tiêu thụ registry

​

Callback ràng buộc hội thoại

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" hoặc "denied"
• decision: "allow-once", "allow-always" hoặc "deny"
• binding: binding đã phân giải cho các yêu cầu được phê duyệt
• request: tóm tắt yêu cầu ban đầu, gợi ý tách, id người gửi và metadata hội thoại

​

Hook runtime provider

• Metadata manifest cho tra cứu rẻ trước runtime: setup.providers[].envVars, tương thích đã ngừng khuyến nghị providerAuthEnvVars, providerAuthAliases, providerAuthChoices và channelEnvVars.
• Hook thời điểm cấu hình: catalog (discovery cũ) cộng với applyConfigDefaults.
• Hook runtime: hơn 40 hook tùy chọn bao phủ auth, phân giải model, bọc stream, cấp độ suy nghĩ, chính sách replay và endpoint sử dụng. Xem danh sách đầy đủ trong Thứ tự hook và cách sử dụng.

​

Thứ tự hook và cách sử dụng

​

Ví dụ nhà cung cấp

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

Ví dụ tích hợp sẵn

​

Helper runtime

const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeech trả về payload đầu ra TTS core thông thường cho các bề mặt file/voice-note.
• Sử dụng cấu hình messages.tts của core và lựa chọn nhà cung cấp.
• Trả về buffer âm thanh PCM + sample rate. Plugin phải resample/encode cho nhà cung cấp.
• listVoices là tùy chọn theo từng nhà cung cấp. Dùng nó cho bộ chọn giọng nói hoặc luồng thiết lập do vendor sở hữu.
• Danh sách giọng nói có thể bao gồm metadata phong phú hơn như locale, gender và thẻ personality cho các bộ chọn nhận biết nhà cung cấp.
• OpenAI và ElevenLabs hiện hỗ trợ telephony. Microsoft thì không.

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme Speech",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• Giữ chính sách TTS, fallback và chuyển phát phản hồi trong core.
• Dùng nhà cung cấp speech cho hành vi tổng hợp do vendor sở hữu.
• Đầu vào Microsoft edge kế thừa được chuẩn hóa thành id nhà cung cấp microsoft.
• Mô hình sở hữu được ưu tiên là theo công ty: một Plugin vendor có thể sở hữu nhà cung cấp text, speech, image và media trong tương lai khi OpenClaw thêm các hợp đồng capability đó.

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• Giữ orchestration, fallback, config và channel wiring trong core.
• Giữ hành vi vendor trong Plugin nhà cung cấp.
• Mở rộng bổ sung nên vẫn có kiểu: phương thức tùy chọn mới, trường kết quả tùy chọn mới, capability tùy chọn mới.
• Tạo video đã tuân theo cùng mẫu:
  • core sở hữu hợp đồng capability và helper runtime
  • Plugin vendor đăng ký api.registerVideoGenerationProvider(...)
  • Plugin tính năng/channel tiêu thụ api.runtime.videoGeneration.*

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.5",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Use the printed fields as the source of truth." },
  ],
  instructions: "Return entities and searchable tags.",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* là bề mặt dùng chung được ưu tiên cho hiểu image/audio/video.
• extractStructuredWithModel(...) là seam hướng tới Plugin cho trích xuất giới hạn, do nhà cung cấp sở hữu, ưu tiên image. Bao gồm ít nhất một đầu vào image; đầu vào text là ngữ cảnh bổ sung. Plugin sản phẩm sở hữu route và schema của chúng trong khi OpenClaw sở hữu ranh giới provider/runtime.
• Sử dụng cấu hình âm thanh media-understanding của core (tools.media.audio) và thứ tự fallback nhà cung cấp.
• Trả về { text: undefined } khi không tạo ra đầu ra phiên âm nào (ví dụ đầu vào bị bỏ qua/không hỗ trợ).
• api.runtime.stt.transcribeAudioFile(...) vẫn là alias tương thích.

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider và model là các override tùy chọn cho từng lần chạy, không phải thay đổi session bền vững.
• OpenClaw chỉ tôn trọng các trường override đó cho caller đáng tin cậy.
• Với các lần chạy fallback do Plugin sở hữu, operator phải bật bằng plugins.entries.<id>.subagent.allowModelOverride: true.
• Dùng plugins.entries.<id>.subagent.allowedModels để giới hạn Plugin đáng tin cậy vào các mục tiêu provider/model canonical cụ thể, hoặc "*" để cho phép rõ ràng bất kỳ mục tiêu nào.
• Các lần chạy subagent của Plugin không đáng tin cậy vẫn hoạt động, nhưng yêu cầu override bị từ chối thay vì âm thầm fallback.
• Các session subagent do Plugin tạo được gắn thẻ bằng id Plugin tạo ra chúng. Fallback api.runtime.subagent.deleteSession(...) chỉ có thể xóa các session được sở hữu đó; xóa session tùy ý vẫn cần yêu cầu Gateway có phạm vi admin.

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw plugin runtime helpers",
    count: 5,
  },
});

• Giữ lựa chọn nhà cung cấp, phân giải credential và ngữ nghĩa yêu cầu dùng chung trong core.
• Dùng nhà cung cấp web-search cho transport tìm kiếm riêng theo vendor.
• api.runtime.webSearch.* là bề mặt dùng chung được ưu tiên cho Plugin tính năng/channel cần hành vi tìm kiếm mà không phụ thuộc vào agent tool wrapper.

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): tạo image bằng chuỗi nhà cung cấp image-generation đã cấu hình.
• listProviders(...): liệt kê các nhà cung cấp image-generation có sẵn và capability của họ.

​

Route HTTP Gateway

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: đường dẫn route dưới máy chủ HTTP gateway.
• auth: bắt buộc. Dùng "gateway" để yêu cầu auth Gateway thông thường, hoặc "plugin" cho xác minh auth/webhook do Plugin quản lý.
• match: tùy chọn. "exact" (mặc định) hoặc "prefix".
• replaceExisting: tùy chọn. Cho phép cùng một Plugin thay thế đăng ký route hiện có của chính nó.
• handler: trả về true khi route đã xử lý yêu cầu.

• api.registerHttpHandler(...) đã bị gỡ bỏ và sẽ gây lỗi tải Plugin. Thay vào đó hãy dùng api.registerHttpRoute(...).
• Các tuyến Plugin phải khai báo auth một cách tường minh.
• Các xung đột chính xác path + match bị từ chối trừ khi có replaceExisting: true, và một Plugin không thể thay thế tuyến của Plugin khác.
• Các tuyến chồng lấn với các mức auth khác nhau bị từ chối. Chỉ giữ các chuỗi chuyển tiếp exact/prefix trên cùng một mức auth.
• Các tuyến auth: "plugin" không tự động nhận phạm vi runtime của operator. Chúng dành cho Webhook do Plugin quản lý/xác minh chữ ký, không phải các lệnh gọi trợ giúp Gateway có đặc quyền.
• Các tuyến auth: "gateway" chạy bên trong phạm vi runtime yêu cầu Gateway, nhưng phạm vi đó được cố ý giữ thận trọng:
  • xác thực bearer bằng shared-secret (gateway.auth.mode = "token" / "password") giữ phạm vi runtime của tuyến Plugin cố định ở operator.write, ngay cả khi bên gọi gửi x-openclaw-scopes
  • các chế độ HTTP mang danh tính đáng tin cậy (ví dụ trusted-proxy hoặc gateway.auth.mode = "none" trên ingress riêng tư) chỉ tôn trọng x-openclaw-scopes khi header được hiện diện tường minh
  • nếu thiếu x-openclaw-scopes trên các yêu cầu tuyến Plugin mang danh tính đó, phạm vi runtime quay về operator.write
• Quy tắc thực tế: đừng giả định một tuyến Plugin được xác thực bằng gateway là bề mặt quản trị ngầm định. Nếu tuyến của bạn cần hành vi chỉ dành cho quản trị viên, hãy yêu cầu chế độ auth mang danh tính và ghi rõ hợp đồng header x-openclaw-scopes tường minh trong tài liệu.

​

Đường dẫn import Plugin SDK

• index.js — điểm nhập Plugin được đóng gói kèm
• api.js — barrel trợ giúp/kiểu
• runtime-api.js — barrel chỉ dành cho runtime
• setup-entry.js — điểm nhập Plugin thiết lập

​

Lược đồ công cụ tin nhắn

• presentation cho các block trình bày ngữ nghĩa (text, context, divider, buttons, select)
• delivery-pin cho các yêu cầu ghim gửi

​

Phân giải mục tiêu kênh

• messaging.inferTargetChatType({ to }) quyết định liệu mục tiêu đã chuẩn hóa nên được xử lý là direct, group, hay channel trước khi tra cứu thư mục.
• messaging.targetResolver.looksLikeId(raw, normalized) cho core biết liệu một đầu vào có nên bỏ qua để đi thẳng đến phân giải dạng id thay vì tìm kiếm thư mục.
• messaging.targetResolver.resolveTarget(...) là fallback của Plugin khi core cần phân giải cuối cùng do nhà cung cấp sở hữu sau khi chuẩn hóa hoặc sau một lần trượt thư mục.
• messaging.resolveOutboundSessionRoute(...) sở hữu việc xây dựng tuyến phiên riêng theo nhà cung cấp sau khi mục tiêu được phân giải.

• Dùng inferTargetChatType cho các quyết định phân loại nên xảy ra trước khi tìm kiếm peer/nhóm.
• Dùng looksLikeId cho các kiểm tra “xử lý đây là id mục tiêu tường minh/gốc”.
• Dùng resolveTarget cho fallback chuẩn hóa riêng theo nhà cung cấp, không phải cho tìm kiếm thư mục rộng.
• Giữ các id gốc của nhà cung cấp như id chat, id thread, JID, handle, và id phòng bên trong giá trị target hoặc tham số riêng theo nhà cung cấp, không đặt trong các trường SDK tổng quát.

​

Thư mục dựa trên cấu hình

• peer DM dựa trên allowlist
• bản đồ kênh/nhóm đã cấu hình
• fallback thư mục tĩnh theo phạm vi tài khoản

• lọc truy vấn
• áp dụng giới hạn
• trợ giúp khử trùng lặp/chuẩn hóa
• xây dựng ChannelDirectoryEntry[]

​

Catalog nhà cung cấp

• { provider } cho một mục nhập nhà cung cấp
• { providers } cho nhiều mục nhập nhà cung cấp

• simple: nhà cung cấp dùng API key đơn giản hoặc điều khiển bằng env
• profile: nhà cung cấp xuất hiện khi có hồ sơ auth
• paired: nhà cung cấp tổng hợp nhiều mục nhập nhà cung cấp có liên quan
• late: lượt cuối, sau các nhà cung cấp ngầm định khác

• discovery vẫn hoạt động như alias cũ, nhưng phát cảnh báo không còn được khuyến nghị
• nếu cả catalog và discovery đều được đăng ký, OpenClaw dùng catalog
• augmentModelCatalog không còn được khuyến nghị; các nhà cung cấp được đóng gói kèm nên công bố hàng bổ sung thông qua registerModelCatalogProvider

​

Kiểm tra kênh chỉ đọc

• resolveAccount(...) là đường dẫn runtime. Nó được phép giả định thông tin xác thực đã được hiện thực hóa đầy đủ và có thể fail fast khi thiếu secret bắt buộc.
• Các đường dẫn lệnh chỉ đọc như openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, và các luồng sửa doctor/cấu hình không nên phải hiện thực hóa thông tin xác thực runtime chỉ để mô tả cấu hình.

• Chỉ trả về trạng thái tài khoản mang tính mô tả.
• Giữ nguyên enabled và configured.
• Bao gồm các trường nguồn/trạng thái thông tin xác thực khi liên quan, như:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• Bạn không cần trả về giá trị token thô chỉ để báo cáo khả dụng chỉ đọc. Trả về tokenStatus: "available" (và trường nguồn tương ứng) là đủ cho các lệnh kiểu trạng thái.
• Dùng configured_unavailable khi một thông tin xác thực được cấu hình qua SecretRef nhưng không khả dụng trong đường dẫn lệnh hiện tại.

​

Gói package

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• bản thân việc đăng ký kênh
• mọi tuyến HTTP phải sẵn sàng trước khi Gateway bắt đầu lắng nghe
• mọi phương thức, công cụ hoặc dịch vụ Gateway phải tồn tại trong cùng khoảng thời gian đó

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

Siêu dữ liệu danh mục kênh

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: nhãn phụ cho các bề mặt danh mục/trạng thái phong phú hơn
• docsLabel: ghi đè văn bản liên kết cho liên kết tài liệu
• preferOver: các id Plugin/kênh có độ ưu tiên thấp hơn mà entry danh mục này nên xếp trên
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: các điều khiển nội dung cho bề mặt chọn lựa
• markdownCapable: đánh dấu kênh là có khả năng markdown cho các quyết định định dạng gửi ra
• exposure.configured: ẩn kênh khỏi các bề mặt liệt kê kênh đã cấu hình khi đặt thành false
• exposure.setup: ẩn kênh khỏi các bộ chọn thiết lập/cấu hình tương tác khi đặt thành false
• exposure.docs: đánh dấu kênh là nội bộ/riêng tư cho các bề mặt điều hướng tài liệu
• showConfigured / showInSetup: các bí danh cũ vẫn được chấp nhận để tương thích; ưu tiên exposure
• quickstartAllowFrom: đưa kênh vào luồng quickstart allowFrom tiêu chuẩn
• forceAccountBinding: yêu cầu liên kết tài khoản rõ ràng ngay cả khi chỉ tồn tại một tài khoản
• preferSessionLookupForAnnounceTarget: ưu tiên tra cứu phiên khi phân giải đích thông báo

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

Plugin công cụ ngữ cảnh

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", (ctx) => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Thêm capability mới

1. định nghĩa hợp đồng lõi Quyết định hành vi dùng chung nào lõi nên sở hữu: chính sách, fallback, hợp nhất cấu hình, vòng đời, ngữ nghĩa hướng tới kênh, và hình dạng helper runtime.
2. thêm các bề mặt đăng ký/runtime Plugin có kiểu Mở rộng OpenClawPluginApi và/hoặc api.runtime với bề mặt capability có kiểu nhỏ nhất nhưng hữu ích.
3. nối lõi + consumer kênh/tính năng Các kênh và Plugin tính năng nên tiêu thụ capability mới thông qua lõi, không phải bằng cách import trực tiếp một implementation của vendor.
4. đăng ký implementation của vendor Sau đó Plugin vendor đăng ký backend của chúng với capability.
5. thêm độ phủ hợp đồng Thêm test để quyền sở hữu và hình dạng đăng ký luôn rõ ràng theo thời gian.

​

Checklist capability

• kiểu hợp đồng lõi trong src/<capability>/types.ts
• runner/helper runtime lõi trong src/<capability>/runtime.ts
• bề mặt đăng ký API Plugin trong src/plugins/types.ts
• nối dây registry Plugin trong src/plugins/registry.ts
• phơi bày runtime Plugin trong src/plugins/runtime/* khi Plugin tính năng/kênh cần tiêu thụ nó
• helper capture/test trong src/test-utils/plugin-registration.ts
• assertion quyền sở hữu/hợp đồng trong src/plugins/contracts/registry.ts
• tài liệu operator/Plugin trong docs/

​

Mẫu capability

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• lõi sở hữu hợp đồng capability + điều phối
• Plugin vendor sở hữu implementation của vendor
• Plugin tính năng/kênh tiêu thụ helper runtime
• test hợp đồng giữ quyền sở hữu rõ ràng

​

Liên quan

• Kiến trúc Plugin — mô hình và hình dạng capability công khai
• Đường dẫn con Plugin SDK
• Thiết lập Plugin SDK
• Xây dựng Plugin