Tổng quan Plugin SDK

​

Quy ước import

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ý năng lực

​

Công cụ và lệnh

agentPromptGuidance: [
  "Global command hint.",
  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },
];

​

Hạ tầng

​

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

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

• Plugin bên ngoài có thể sở hữu phần mở rộng phiên, bộ mô tả UI, lệnh, siêu dữ liệu công cụ, phần chèn vào lượt tiếp theo 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à được host tin cậy. Chính sách đóng gói chạy trước; chính sách từ Plugin đã cài đặt cần được bật rõ ràng cùng với id cục bộ của chúng trong contracts.trustedToolPolicies, rồi chạy tiếp theo theo thứ tự tải Plugin. Id chính sách được giới hạn theo Plugin đăng ký.
• Quyền sở hữu lệnh dành riêng chỉ dành cho Plugin đóng gói. Plugin bên ngoài nên dùng tên lệnh hoặc alias riêng của mình.
• allowPromptInjection=false tắt 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ý khám phá 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() };
  },
});

​

Siêu dữ liệu đăng ký CLI

• commands: tên 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 dùng cho trợ giúp CLI, định tuyến và đăng ký CLI Plugin lười
• parentPath: đường dẫn lệnh cha tùy chọn cho nhóm lệnh lồng nhau, chẳng hạn ["nodes"]

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,
      },
    ],
  },
);

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "Capture or render canvas content from a paired node",
        hasSubcommands: true,
      },
    ],
  },
);

​

Đăng ký backend CLI

• Backend id trở thành tiền tố provider trong các tham chiếu mô hình như my-cli/gpt-5.
• Backend config dùng cùng hình dạng với agents.defaults.cliBackends.<id>.
• Cấu hình người dùng vẫn được ưu tiên. OpenClaw gộp 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 gộp (ví dụ chuẩn hóa các hình dạng cờ cũ).
• Dùng resolveExecutionArgs cho các viết lại argv theo phạm vi yêu cầu thuộc về phương ngữ CLI, chẳng hạn ánh xạ mức suy nghĩ của OpenClaw sang một cờ effort gốc. Hook nhận ctx.executionMode; dùng "side-question" để thêm các cờ cô lập gốc của backend cho các lệnh gọi /btw tạm thời. Nếu các cờ đó vô hiệu hóa đáng tin cậy các công cụ gốc cho một CLI vốn luôn bật, hãy khai báo thêm sideQuestionToolMode: "disabled".

​

Các khe độc quyền

​

Adapter nhúng bộ nhớ đã ngừng khuyến nghị

• registerMemoryCapability là API Plugin bộ nhớ độc quyền được ưu tiên.
• registerMemoryCapability cũng có thể cung cấp publicArtifacts.listArtifacts(...) để các Plugin đồng hành có thể tiêu thụ các tạo tác bộ nhớ đã xuất thông qua openclaw/plugin-sdk/memory-host-core thay vì truy cập vào bố cục 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 với di sản.
• MemoryFlushPlan.model có thể ghim lượt flush vào đúng tham chiếu provider/model, chẳng hạn ollama/qwen3:8b, mà không kế thừa chuỗi fallback đang hoạt động.
• registerMemoryEmbeddingProvider đã ngừng khuyến nghị. Các provider nhúng mới nên dùng api.registerEmbeddingProvider(...) và contracts.embeddingProviders.
• Các provider riêng cho bộ nhớ hiện có tiếp tục hoạt động trong cửa sổ di chuyển, nhưng báo cáo kiểm tra Plugin sẽ ghi nhận đây là nợ tương thích đối với các Plugin không được đóng gói sẵn.

​

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 giá trị này, các handler có độ ư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 giá trị này, các handler có độ ư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 có độ ưu tiên thấp hơn và đường dẫn dispatch mô hình 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 giá trị này, các handler có độ ư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ủ đề đầu vào. Giữ metadata cho các phần bổ sung riêng của kênh.
• message_sending: dùng các trường định tuyến có kiểu replyToId / threadId trước khi fallback về metadata riêng của 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ộ các bộ lập lịch đánh thức bên ngoài, và giữ OpenClaw làm nguồn sự thật cho các 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 api.ts / contract-api.ts công khai cho các trợ giúp stream beta-header Claude và service_tier.
• @openclaw/openai-provider: api.ts xuất các bộ dựng provider, trợ giúp mô hình mặc định, và bộ dựng provider realtime.
• @openclaw/openrouter-provider: api.ts xuất bộ dựng provider cùng các trợ giúp onboarding/cấu hình.

​

Liên quan