Nội bộ 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.

​

Mô hình năng lực công khai

​

Lập trường tương thích bên ngoài

​

Hình dạng Plugin

​

Hook kiểu cũ

• giữ cho nó hoạt động
• ghi tài liệu rằng nó là kiểu cũ
• ưu tiên before_model_resolve cho công việc ghi đè mô hình/nhà cung cấp
• ưu tiên before_prompt_build cho công việc chỉnh sửa prompt
• chỉ gỡ bỏ sau khi mức sử dụng thực tế giảm và phạm vi fixture chứng minh việc di chuyển là an toàn

​

Tín hiệu tương thích

​

Tổng quan kiến trúc

• metadata tại thời điểm phân tích cú pháp đến từ registerCli(..., { descriptors: [...] })
• module CLI thật của Plugin có thể vẫn lazy và đăng ký ở lần gọi đầu tiên

• xác thực manifest/cấu hình nên hoạt động từ metadata manifest/schema mà không thực thi mã Plugin
• khám phá năng lực gốc có thể tải mã entry Plugin đáng tin cậy để xây dựng snapshot registry không kích hoạt
• hành vi runtime gốc đến từ đường dẫn register(api) của module Plugin với api.registrationMode === "full"

​

Snapshot metadata Plugin và bảng tra cứu

• quyền sở hữu kênh
• khởi động kênh trì hoãn
• id Plugin khởi động
• quyền sở hữu nhà cung cấp và backend CLI
• quyền sở hữu nhà cung cấp thiết lập, bí danh lệnh, nhà cung cấp catalog mô hình và hợp đồng manifest
• xác thực schema cấu hình Plugin và schema cấu hình kênh
• quyết định tự động bật khi khởi động

​

Lập kế hoạch kích hoạt

• các trường activation.* là gợi ý lập kế hoạch rõ ràng
• providers, channels, commandAliases, setup.providers, contracts.tools và hook vẫn là phương án dự phòng quyền sở hữu manifest
• API trình lập kế hoạch chỉ có id vẫn có sẵn cho các bên gọi hiện có
• API kế hoạch báo nhãn lý do để chẩn đoán có thể phân biệt gợi ý rõ ràng với phương án dự phòng quyền sở hữu

​

Plugin kênh và công cụ tin nhắn dùng chung

• lõi sở hữu máy chủ công cụ message dùng chung, nối dây prompt, ghi sổ phiên/luồng, và điều phối thực thi
• Plugin kênh sở hữu khám phá hành động theo phạm vi, khám phá năng lực, và mọi mảnh schema đặc thù theo kênh
• Plugin kênh sở hữu ngữ pháp hội thoại phiên theo nhà cung cấp, chẳng hạn cách id hội thoại mã hóa id luồng hoặc kế thừa từ hội thoại cha
• Plugin kênh thực thi hành động cuối cùng thông qua bộ chuyển đổi hành động của chúng

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• requesterSenderId đầu vào đáng tin cậy

• outbound.sendPoll là baseline dùng chung cho các kênh phù hợp với mô hình bình chọn chung
• actions.handleAction("poll") là đường được ưu tiên cho ngữ nghĩa bình chọn đặc thù theo kênh hoặc các tham số bình chọn bổ sung

​

Mô hình sở hữu năng lực

• một Plugin công ty thường nên sở hữu toàn bộ các bề mặt hướng tới OpenClaw của công ty đó
• một Plugin tính năng thường nên sở hữu toàn bộ bề mặt tính năng mà nó giới thiệu
• các kênh nên dùng các năng lực lõi dùng chung thay vì triển khai lại hành vi nhà cung cấp theo kiểu tùy biến

• OpenAI nằm trong một Plugin ngay cả khi nó bao phủ mô hình văn bản, giọng nói, hình ảnh, và video trong tương lai
• một nhà cung cấp khác có thể làm tương tự cho phạm vi bề mặt của chính họ
• các kênh không quan tâm Plugin nhà cung cấp nào sở hữu provider; chúng dùng hợp đồng năng lực dùng chung do lõi hiển thị

• Plugin = ranh giới sở hữu
• năng lực = hợp đồng lõi mà nhiều Plugin có thể triển khai hoặc dùng

​

Phân lớp năng lực

• lõi sở hữu chính sách TTS tại thời điểm trả lời, thứ tự fallback, tùy chọn, và phân phối qua kênh
• openai, elevenlabs, và microsoft sở hữu các triển khai tổng hợp
• voice-call dùng helper runtime TTS điện thoại

​

Ví dụ Plugin công ty đa năng lực

import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
import {
  describeImageWithModel,
  transcribeOpenAiCompatibleAudio,
} from "openclaw/plugin-sdk/media-understanding";

const plugin: OpenClawPluginDefinition = {
  id: "exampleai",
  name: "ExampleAI",
  register(api) {
    api.registerProvider({
      id: "exampleai",
      // auth/model catalog/runtime hooks
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // vendor speech config — implement the SpeechProviderPlugin interface directly
    });

    api.registerMediaUnderstandingProvider({
      id: "exampleai",
      capabilities: ["image", "audio", "video"],
      async describeImage(req) {
        return describeImageWithModel({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
      async transcribeAudio(req) {
        return transcribeOpenAiCompatibleAudio({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
    });

    api.registerWebSearchProvider(
      createPluginBackedWebSearchProvider({
        id: "exampleai-search",
        // credential + fetch logic
      }),
    );
  },
};

export default plugin;

• một Plugin sở hữu bề mặt nhà cung cấp
• lõi vẫn sở hữu các hợp đồng năng lực
• các kênh và Plugin tính năng dùng helper api.runtime.*, không dùng mã nhà cung cấp
• kiểm thử hợp đồng có thể xác nhận rằng Plugin đã đăng ký các năng lực mà nó tuyên bố sở hữu

​

Ví dụ năng lực: hiểu video

​

Hợp đồng và thực thi

• tác giả Plugin có một chuẩn nội bộ ổn định duy nhất
• lõi có thể từ chối quyền sở hữu trùng lặp như hai Plugin đăng ký cùng một id provider
• khởi động có thể hiển thị chẩn đoán có thể hành động cho đăng ký sai định dạng
• kiểm thử hợp đồng có thể thực thi quyền sở hữu Plugin đi kèm và ngăn trôi lệch âm thầm

​

Nội dung thuộc về một hợp đồng

​

Mô hình thực thi

​

Ranh giới xuất

• đường dẫn con trợ giúp dành riêng cho plugin đi kèm
• đường dẫn con hệ thống thời gian chạy không được chủ định làm API công khai
• trợ giúp tiện ích dành riêng cho nhà cung cấp
• trợ giúp thiết lập/onboarding là chi tiết triển khai

​

Nội bộ và tham khảo

​

Liên quan

• Xây dựng plugin
• Manifest Plugin
• Thiết lập SDK Plugin