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

​

Quy trình tải

1. phát hiện các root Plugin ứng viên
2. đọc bản kê khai gói native hoặc tương thích và siêu dữ liệu 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 bật hay không cho từng ứng viên
6. tải các mô-đun native đã bật: mô-đun bundled đã build dùng bộ tải native; mã nguồn TypeScript cục bộ của bên thứ ba dùng fallback Jiti khẩn cấp
7. gọi các hook native register(api) và thu thập đăng ký vào registry Plugin
8. hiển thị registry cho các bề mặt lệnh/môi trường chạy

​

Hành vi ưu tiên bản kê khai

• nhận diện Plugin
• phát hiện kênh/skills/schema cấu hình hoặc năng lực gói đã khai báo
• xác thực plugins.entries.<id>.config
• bổ sung nhãn/placeholder cho Control UI
• hiển thị siêu dữ liệu cài đặt/catalog
• giữ các mô tả kích hoạt và thiết lập rẻ mà không cần tải môi trường chạy của 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/môi trường chạy nhà cung cấp tường minh thu hẹp vào các Plugin sở hữu id nhà cung cấp đượ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 lựa chọn không tham gia khởi động; Plugin không có siêu dữ liệu khởi động chỉ tải qua các trigger kích hoạt hẹp hơn

​

Ranh giới bộ nhớ đệm Plugin

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

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

​

Mô hình registry

• bản ghi Plugin (danh tính, nguồn, xuất xứ, trạng thái, chẩn đoán)
• công cụ
• hook cũ và hook có kiểu
• kênh
• nhà cung cấp
• handler RPC Gateway
• tuyến HTTP
• registrar CLI
• dịch vụ nền
• lệnh do Plugin sở hữu

• mô-đun Plugin -> đăng ký registry
• môi trường chạy lõi -> tiêu thụ registry

​

Callback liên kết 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: liên kết đã giải quyết cho 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à siêu dữ liệu hội thoại

​

Hook môi trường chạy nhà cung cấp

• Siêu dữ liệu bản kê khai cho tra cứu rẻ trước môi trường chạy: setup.providers[].envVars, tương thích đã ngừng khuyến nghị providerAuthEnvVars, providerAuthAliases, providerAuthChoices, và channelEnvVars.
• Hook lúc cấu hình: catalog (discovery cũ) cộng với applyConfigDefaults.
• Hook môi trường chạy: hơn 40 hook tùy chọn bao phủ xác thực, phân giải mô hình, bọc stream, mức thinking, chính sách replay, và endpoint sử dụng. Xem danh sách đầy đủ trong Thứ tự và cách dùng hook.

​

Thứ tự và cách dùng hook

​

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 lõi bình thường cho các bề mặt tệp/ghi chú thoại.
• Dùng cấu hình lõi messages.tts và lựa chọn nhà cung cấp.
• Trả về bộ đệm âm thanh PCM + tần số mẫu. 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 nhà cung cấp sở hữu.
• Danh sách giọng nói có thể bao gồm metadata phong phú hơn như locale, giới tính và thẻ tính cách cho 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à gửi phản hồi trong lõi.
• Dùng nhà cung cấp speech cho hành vi tổng hợp do nhà cung cấp sở hữu.
• Đầu vào Microsoft legacy edge được chuẩn hóa thành mã định danh nhà cung cấp microsoft.
• Mô hình sở hữu ưu tiên là theo công ty: một plugin nhà cung cấp có thể sở hữu nhà cung cấp văn bản, speech, hình ảnh và media tương lai khi OpenClaw bổ sung các hợp đồng năng lực đó.

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

• Giữ orchestration, fallback, cấu hình và nối dây kênh trong lõi.
• Giữ hành vi nhà cung cấp trong plugin nhà cung cấp.
• Mở rộng cộng thêm nên duy trì có kiểu: phương thức tùy chọn mới, trường kết quả tùy chọn mới, năng lực tùy chọn mới.
• Tạo video đã đi theo cùng mẫu:
  • lõi sở hữu hợp đồng năng lực và helper runtime
  • plugin nhà cung cấp đăng ký api.registerVideoGenerationProvider(...)
  • plugin tính năng/kênh 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 ưu tiên cho hiểu hình ảnh/âm thanh/video.
• extractStructuredWithModel(...) là seam hướng plugin cho trích xuất có giới hạn, do nhà cung cấp sở hữu, ưu tiên hình ảnh. Bao gồm ít nhất một đầu vào hình ảnh; đầu vào văn bản 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.
• Dùng cấu hình âm thanh media-understanding lõi (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 được 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à override theo từng lượt chạy tùy chọn, không phải thay đổi phiên bền vững.
• OpenClaw chỉ tôn trọng các trường override đó cho bên gọi đáng tin cậy.
• Với lượt 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.
• Lượt 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.
• Phiên subagent do plugin tạo được gắn thẻ bằng mã định danh plugin đã tạo. Fallback api.runtime.subagent.deleteSession(...) chỉ có thể xóa các phiên được sở hữu đó; xóa phiên tùy ý vẫn yêu cầu một yêu cầu Gateway 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 thông tin xác thực và ngữ nghĩa yêu cầu dùng chung trong lõi.
• Dùng nhà cung cấp tìm kiếm web cho transport tìm kiếm riêng theo nhà cung cấp.
• api.runtime.webSearch.* là bề mặt dùng chung ưu tiên cho plugin tính năng/kênh cần hành vi tìm kiếm mà không phụ thuộc vào wrapper công cụ agent.

​

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 một hình ảnh bằng chuỗi nhà cung cấp tạo hình ảnh đã cấu hình.
• listProviders(...): liệt kê các nhà cung cấp tạo hình ảnh hiện có và năng lực 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 của Gateway.
• auth: bắt buộc. Dùng "gateway" để yêu cầu xác thực Gateway thông thường, hoặc "plugin" cho xác thực/xác minh 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ị xóa và sẽ gây lỗi tải plugin. Thay vào đó, hãy dùng api.registerHttpRoute(...).
• Các route của plugin phải khai báo auth rõ ràng.
• Xung đột path + match chính xác sẽ bị từ chối trừ khi replaceExisting: true, và một plugin không thể thay thế route của plugin khác.
• Các route chồng lấn với các mức auth khác nhau sẽ bị từ chối. Chỉ giữ các chuỗi chuyển tiếp exact/prefix trên cùng một mức xác thực.
• Các route auth: "plugin" không tự động nhận phạm vi runtime của operator. Chúng dành cho webhook/xác minh chữ ký do plugin quản lý, không phải các lệnh gọi trợ giúp Gateway đặc quyền.
• Các route 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 route plugin cố định ở operator.write, ngay cả khi caller gửi x-openclaw-scopes
  • các chế độ HTTP có 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 trình bày rõ ràng
  • nếu x-openclaw-scopes vắng mặt trên các yêu cầu route plugin có danh tính đó, phạm vi runtime quay về operator.write
• Quy tắc thực tế: đừng giả định route plugin xác thực qua gateway là một bề mặt quản trị ngầm định. Nếu route 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ế độ xác thực có danh tính và ghi tài liệu hợp đồng header x-openclaw-scopes rõ ràng.

​

Đường dẫn import SDK của plugin

• index.js — entry 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 — entry plugin thiết lập

​

Schema công cụ tin nhắn

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

​

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

• messaging.inferTargetChatType({ to }) quyết định một mục tiêu đã chuẩn hóa nên được coi là direct, group, hay channel trước khi tra cứu thư mục.
• messaging.targetResolver.looksLikeId(raw, normalized) cho lõi biết liệu một input có nên đi thẳng tới phân giải kiểu id thay vì tìm kiếm thư mục hay không.
• messaging.targetResolver.reservedLiterals liệt kê các từ trần là tham chiếu kênh/phiên cho nhà cung cấp đó. Phân giải giữ nguyên các mục thư mục đã cấu hình trước khi từ chối literal dành riêng, rồi fail closed khi không tìm thấy trong thư mục.
• messaging.targetResolver.resolveTarget(...) là fallback của plugin khi lõi cần một phân giải cuối cùng thuộc sở hữu nhà cung cấp sau khi chuẩn hóa hoặc sau khi không tìm thấy trong thư mục.
• messaging.resolveOutboundSessionRoute(...) sở hữu việc xây dựng route phiên 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 danh mục cần xảy ra trước khi tìm kiếm peer/group.
• Dùng looksLikeId cho các kiểm tra “coi đây là id mục tiêu rõ ràng/gốc”.
• Dùng resolveTarget cho fallback chuẩn hóa 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ư chat id, thread id, JID, handle, và room id bên trong giá trị target hoặc tham số 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 theo allowlist
• ánh xạ kênh/group đã 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à cung cấp
• { providers } cho nhiều mục nhà cung cấp

• simple: nhà cung cấp dùng khóa API thuần hoặc điều khiển bằng env
• profile: nhà cung cấp xuất hiện khi có hồ sơ xác thực
• paired: nhà cung cấp tổng hợp nhiều mục nhà cung cấp 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 ngừng khuyến nghị
• nếu cả catalog và discovery đều được đăng ký, OpenClaw dùng catalog
• augmentModelCatalog đã ngừng khuyến nghị; các nhà cung cấp đóng gói kèm nên phát hành 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 materialize đầ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 doctor/sửa chữa cấu hình không nên cần materialize 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, chẳng hạn:
  • 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 tính sẵn có 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 thông tin xác thực được cấu hình qua SecretRef nhưng không sẵn có 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"
  }
}

• chính việc đăng ký channel
• mọi route HTTP phải có sẵn 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 channel

{
  "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/channel có ưu tiên thấp hơn mà mục danh mục này nên vượt lên
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: điều khiển nội dung bề mặt chọn
• markdownCapable: đánh dấu channel là có khả năng markdown cho các quyết định định dạng gửi đi
• exposure.configured: ẩn channel khỏi các bề mặt liệt kê channel đã cấu hình khi đặt thành false
• exposure.setup: ẩn channel khỏi 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 channel 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 alias legacy vẫn được chấp nhận để tương thích; ưu tiên exposure
• quickstartAllowFrom: chọn channel vào luồng quickstart allowFrom chuẩn
• forceAccountBinding: yêu cầu ràng buộc tài khoản tường minh ngay cả khi chỉ có một tài khoản tồn tại
• preferSessionLookupForAnnounceTarget: ưu tiên tra cứu phiên khi phân giải mục tiêu thông báo

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

​

Plugin engine 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 một năng lực mới

1. định nghĩa hợp đồng core Quyết định hành vi chia sẻ nào core nên sở hữu: policy, fallback, hợp nhất cấu hình, vòng đời, ngữ nghĩa hướng channel, 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 năng lực có kiểu nhỏ nhất hữu ích.
3. nối dây core + các consumer channel/tính năng Channel và feature plugin nên tiêu thụ năng lực mới thông qua core, không phải bằng cách import trực tiếp một triển khai vendor.
4. đăng ký các triển khai vendor Sau đó các plugin vendor đăng ký backend của chúng với năng lực.
5. thêm phạm vi kiểm thử hợp đồng Thêm kiểm thử để hình dạng sở hữu và đăng ký luôn tường minh theo thời gian.

​

Checklist năng lực

• kiểu hợp đồng core trong src/<capability>/types.ts
• helper runner/runtime core 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 feature/channel plugin cần tiêu thụ nó
• helper capture/kiểm thử trong src/test-utils/plugin-registration.ts
• assertion sở hữu/hợp đồng trong src/plugins/contracts/registry.ts
• tài liệu operator/plugin trong docs/

​

Mẫu năng lực

// 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"]);

• core sở hữu hợp đồng năng lực + điều phối
• các Plugin nhà cung cấp sở hữu phần triển khai của nhà cung cấp
• các Plugin tính năng/kênh dùng các helper runtime
• kiểm thử 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 năng lực công khai
• Đường dẫn con Plugin SDK
• Thiết lập Plugin SDK
• Xây dựng Plugin