Tổng quan về SDK Plugin

Documentation Index

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

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

​

Quy ước nhập

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

​

Tham chiếu subpath

​

API đăng ký

​

Đăng ký capability

​

Công cụ và lệnh

​

Hạ tầng

​

Hook host cho Plugin quy trình làm việc

• Plugin bên ngoài có thể sở hữu phần mở rộng phiên, descriptor UI, lệnh, metadata công cụ, tiêm lượt kế tiếp và hook thông thường.
• Chính sách công cụ tin cậy chạy trước các hook before_tool_call thông thường và chỉ dành cho bản đóng gói vì chúng tham gia vào chính sách an toàn của host.
• Quyền sở hữu lệnh dành riêng chỉ dành cho bản đóng gói. Plugin bên ngoài nên dùng tên lệnh hoặc alias của riêng chúng.
• allowPromptInjection=false vô hiệu hóa các hook làm thay đổi prompt, bao gồm agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, các trường prompt từ before_agent_start cũ, và enqueueNextTurnInjection.

​

Đăng ký phát hiện Gateway

api.registerGatewayDiscoveryService({
  id: "my-discovery",
  async advertise(ctx) {
    const handle = await startMyAdvertiser({
      gatewayPort: ctx.gatewayPort,
      tls: ctx.gatewayTlsEnabled,
      displayName: ctx.machineDisplayName,
    });
    return { stop: () => handle.stop() };
  },
});

​

Metadata đăng ký CLI

• commands: gốc lệnh rõ ràng thuộc sở hữu của registrar
• descriptors: bộ mô tả lệnh tại thời điểm phân tích cú pháp, dùng cho trợ giúp CLI gốc, định tuyến và đăng ký CLI plugin theo kiểu lazy

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Manage Matrix accounts, verification, devices, and profile state",
        hasSubcommands: true,
      },
    ],
  },
);

​

Đăng ký backend CLI

• id của backend trở thành tiền tố provider trong tham chiếu model như codex-cli/gpt-5.
• config của backend dùng cùng cấu trúc với agents.defaults.cliBackends.<id>.
• Cấu hình người dùng vẫn thắng. OpenClaw hợp nhất agents.defaults.cliBackends.<id> lên trên mặc định của plugin trước khi chạy CLI.
• Dùng normalizeConfig khi một backend cần viết lại tương thích sau khi hợp nhất (ví dụ chuẩn hóa các dạng flag cũ).

​

Slot độc quyền

​

Adapter embedding bộ nhớ

• registerMemoryCapability là API plugin bộ nhớ độc quyền được ưu tiên.
• registerMemoryCapability cũng có thể phơi bày publicArtifacts.listArtifacts(...) để các plugin đồng hành có thể dùng artifact bộ nhớ đã xuất thông qua openclaw/plugin-sdk/memory-host-core thay vì truy cập vào layout riêng của một plugin bộ nhớ cụ thể.
• registerMemoryPromptSection, registerMemoryFlushPlan và registerMemoryRuntime là các API plugin bộ nhớ độc quyền tương thích legacy.
• MemoryFlushPlan.model có thể ghim lượt flush vào một tham chiếu provider/model chính xác, chẳng hạn ollama/qwen3:8b, mà không kế thừa chuỗi fallback đang hoạt động.
• registerMemoryEmbeddingProvider cho phép plugin bộ nhớ đang hoạt động đăng ký một hoặc nhiều id adapter embedding (ví dụ openai, gemini hoặc một id tùy chỉnh do plugin định nghĩa).
• Cấu hình người dùng như agents.defaults.memorySearch.provider và agents.defaults.memorySearch.fallback được phân giải theo các id adapter đã đăng ký đó.

​

Sự kiện và vòng đời

​

Ngữ nghĩa quyết định của hook

• before_tool_call: trả về { block: true } là kết thúc. Khi bất kỳ handler nào đặt nó, các handler ưu tiên thấp hơn sẽ bị bỏ qua.
• before_tool_call: trả về { block: false } được xem là không có quyết định (giống như bỏ qua block), không phải là ghi đè.
• before_install: trả về { block: true } là kết thúc. Khi bất kỳ handler nào đặt nó, các handler ưu tiên thấp hơn sẽ bị bỏ qua.
• before_install: trả về { block: false } được xem là không có quyết định (giống như bỏ qua block), không phải là ghi đè.
• reply_dispatch: trả về { handled: true, ... } là kết thúc. Khi bất kỳ handler nào nhận xử lý dispatch, các handler ưu tiên thấp hơn và đường dẫn dispatch model mặc định sẽ bị bỏ qua.
• message_sending: trả về { cancel: true } là kết thúc. Khi bất kỳ handler nào đặt nó, các handler ưu tiên thấp hơn sẽ bị bỏ qua.
• message_sending: trả về { cancel: false } được xem là không có quyết định (giống như bỏ qua cancel), không phải là ghi đè.
• message_received: dùng trường có kiểu threadId khi bạn cần định tuyến thread/chủ đề đến. Giữ metadata cho phần bổ sung riêng theo kênh.
• message_sending: dùng các trường định tuyến có kiểu replyToId / threadId trước khi fallback sang metadata riêng theo kênh.
• gateway_start: dùng ctx.config, ctx.workspaceDir và ctx.getCron?.() cho trạng thái khởi động do Gateway sở hữu thay vì dựa vào các hook nội bộ gateway:startup.
• cron_changed: quan sát các thay đổi vòng đời Cron do Gateway sở hữu. Dùng event.job?.state?.nextRunAtMs và ctx.getCron?.() khi đồng bộ bộ lập lịch đánh thức bên ngoài, và giữ OpenClaw là nguồn sự thật cho kiểm tra đến hạn và thực thi.

​

Các trường đối tượng API

​

Quy ước module nội bộ

my-plugin/
  api.ts            # Public exports for external consumers
  runtime-api.ts    # Internal-only runtime exports
  index.ts          # Plugin entry point
  setup-entry.ts    # Lightweight setup-only entry (optional)

• Anthropic: seam public api.ts / contract-api.ts cho các helper Claude beta-header và luồng service_tier.
• @openclaw/openai-provider: api.ts xuất các provider builder, helper model mặc định và realtime provider builder.
• @openclaw/openrouter-provider: api.ts xuất provider builder cùng helper onboarding/cấu hình.

​

Liên quan