Tổng quan về Plugin SDK

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 ước import

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

​

Tài liệu tham chiếu đường dẫn con

​

API đăng ký

​

Đăng ký capability

​

Công cụ và lệnh

​

Hạ tầng

​

Hook host cho plugin workflow

• 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ụ, chèn lượt kế tiếp, và các hook thông thường.
• Chính sách công cụ đáng tin cậy chạy trước các hook before_tool_call thông thường và chỉ dành cho bundled vì chúng tham gia vào chính sách an toàn của máy chủ.
• Quyền sở hữu lệnh dành riêng chỉ dành cho bundled. Plugin bên ngoài nên dùng tên lệnh hoặc bí danh riêng của chúng.
• 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 do registrar sở hữu
• 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, định tuyến, và đăng ký CLI plugin tải lười
• parentPath: đường dẫn lệnh cha tùy chọn cho các 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

• id của backend trở thành tiền tố provider trong model ref như codex-cli/gpt-5.
• config của backend dùng cùng hình dạng 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 ghi lại tương thích sau khi hợp nhất (ví dụ chuẩn hóa các hình dạng flag cũ).
• Dùng resolveExecutionArgs cho các lần ghi lại argv theo phạm vi yêu cầu thuộc về dialect CLI, chẳng hạn ánh xạ mức suy nghĩ của OpenClaw sang flag effort gố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ể tiêu thụ artifact bộ nhớ đã xuất thông qua openclaw/plugin-sdk/memory-host-core thay vì đi vào bố cục riêng tư 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 cũ.
• 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 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 giá trị đó, 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ị đó, 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 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ị đó, 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/topic đến. Giữ metadata cho các 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 gateway:startup nội bộ.
• 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 trình lập lịch đánh thức bên ngoài, và giữ OpenClaw làm nguồn chân lý cho kiểm tra đến hạn và thực thi.

​

Trường đối tượng API

​

Quy ước mô-đun 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 công khai api.ts / contract-api.ts cho các trình trợ giúp stream beta-header Claude và service_tier.
• @openclaw/openai-provider: api.ts xuất các builder provider, trình trợ giúp model mặc định, và builder provider realtime.
• @openclaw/openrouter-provider: api.ts xuất builder provider cùng các trình trợ giúp onboarding/cấu hình.

​

Liên quan