Tổng quan về Plugin SDK

SDK plugin là hợp đồng có kiểu giữa plugin và lõi. Trang này là tài liệu tham chiếu về những gì cần import và những gì bạn có thể đăng ký.

Quy ước import

Luôn import từ một đường dẫn con cụ thể:

Mỗi đường dẫn con là một mô-đun nhỏ, tự chứa. Điều này giữ cho quá trình khởi động nhanh và ngăn các vấn đề phụ thuộc vòng. Với helper entry/build dành riêng cho kênh, ưu tiên openclaw/plugin-sdk/channel-core; giữ openclaw/plugin-sdk/core cho bề mặt bao quát rộng hơn và các helper dùng chung như buildChannelConfigSchema.

Với cấu hình kênh, hãy xuất bản JSON Schema do kênh sở hữu thông qua openclaw.plugin.json#channelConfigs. Đường dẫn con plugin-sdk/channel-config-schema dành cho các primitive schema dùng chung và builder tổng quát. Các plugin đóng gói sẵn của OpenClaw dùng plugin-sdk/bundled-channel-config-schema cho các schema kênh đóng gói sẵn được giữ lại. Các export tương thích đã lỗi thời vẫn còn trên plugin-sdk/channel-config-schema-legacy; cả hai đường dẫn con schema đóng gói sẵn đều không phải là mẫu cho plugin mới.

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

SDK plugin được cung cấp dưới dạng một tập các đường dẫn con hẹp được nhóm theo lĩnh vực (entry plugin, kênh, nhà cung cấp, xác thực, runtime, capability, bộ nhớ và các helper plugin đóng gói sẵn được dự trữ). Để xem danh mục đầy đủ — được nhóm và liên kết — hãy xem Đường dẫn con SDK Plugin.

Kho entrypoint của trình biên dịch nằm trong scripts/lib/plugin-sdk-entrypoints.json; package export được tạo từ tập con công khai sau khi trừ các đường dẫn con kiểm thử/nội bộ cục bộ của repo được liệt kê trong scripts/lib/plugin-sdk-private-local-only-subpaths.json. Chạy pnpm plugin-sdk:surface để kiểm tra số lượng export công khai. Các đường dẫn con công khai đã lỗi thời đủ cũ và không được mã production của phần mở rộng đóng gói sẵn dùng được theo dõi trong scripts/lib/plugin-sdk-deprecated-public-subpaths.json; các barrel re-export đã lỗi thời phạm vi rộng được theo dõi trong scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

API đăng ký

Callback register(api) nhận một đối tượng OpenClawPluginApi với các phương thức sau:

Đăng ký capability

Công cụ và lệnh

Lệnh plugin có thể đặt agentPromptGuidance khi agent cần một gợi ý định tuyến ngắn do lệnh sở hữu. Giữ văn bản đó xoay quanh chính lệnh; không thêm chính sách riêng cho nhà cung cấp hoặc plugin vào trình xây dựng prompt lõi.

Hạ tầng

Hook host cho plugin workflow

Hook host là các điểm nối SDK cho plugin cần tham gia vào vòng đời host thay vì chỉ thêm một nhà cung cấp, kênh hoặc công cụ. Chúng là hợp đồng tổng quát; Plan Mode có thể dùng chúng, nhưng workflow phê duyệt, cổng chính sách workspace, trình giám sát nền, trình hướng dẫn thiết lập và plugin đồng hành UI cũng có thể dùng.

Dùng các namespace được nhóm cho mã plugin mới:

• 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(...)

Các phương thức phẳng tương đương vẫn có sẵn dưới dạng alias tương thích đã lỗi thời cho plugin hiện có. Không thêm mã plugin mới gọi trực tiếp api.registerSessionExtension, api.enqueueNextTurnInjection, api.registerControlUiDescriptor, api.registerRuntimeLifecycle, api.registerAgentEventSubscription, api.emitAgentEvent, api.setRunContext, api.getRunContext, api.clearRunContext, api.registerSessionSchedulerJob, api.registerSessionAction, api.sendSessionAttachment, api.scheduleSessionTurn, hoặc api.unscheduleSessionTurnsByTag.

scheduleSessionTurn(...) là tiện ích theo phạm vi phiên nằm trên trình lập lịch Cron của Gateway. Cron sở hữu việc định thời và tạo bản ghi tác vụ nền khi lượt chạy; Plugin SDK chỉ ràng buộc phiên đích, cách đặt tên do plugin sở hữu, và dọn dẹp. Dùng api.runtime.tasks.managedFlows bên trong lượt đã lên lịch khi chính công việc cần trạng thái TaskFlow nhiều bước bền vững.

Các hợp đồng cố ý tách quyền hạn:

• 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.

Ví dụ về các bên tiêu thụ không thuộc Plan:

Đăng ký khám phá Gateway

api.registerGatewayDiscoveryService(...) cho phép một plugin quảng bá Gateway đang hoạt động trên một phương thức truyền tải khám phá cục bộ như mDNS/Bonjour. OpenClaw gọi dịch vụ trong quá trình khởi động Gateway khi khám phá cục bộ được bật, truyền các cổng Gateway hiện tại và dữ liệu gợi ý TXT không bí mật, rồi gọi handler stop được trả về trong quá trình tắt 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() };  },});

Plugin khám phá Gateway không được xem các giá trị TXT được quảng bá là bí mật hoặc xác thực. Khám phá là gợi ý định tuyến; xác thực Gateway và ghim TLS vẫn sở hữu niềm tin.

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

api.registerCli(registrar, opts?) chấp nhận hai loại siêu dữ liệu lệnh:

• 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"]

Đối với các tính năng node ghép cặp, ưu tiên api.registerNodeCliFeature(registrar, opts?). Đây là wrapper nhỏ quanh api.registerCli(..., { parentPath: ["nodes"] }) và làm cho các lệnh như openclaw nodes canvas trở thành các tính năng node do plugin sở hữu một cách rõ ràng.

Nếu bạn muốn một lệnh plugin vẫn được tải lười trong đường dẫn CLI root thông thường, hãy cung cấp descriptors bao phủ mọi root lệnh cấp cao nhất do registrar đó phơi bày.

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

Các lệnh lồng nhau nhận lệnh cha đã phân giải dưới dạng program:

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

Chỉ dùng riêng commands khi bạn không cần đăng ký CLI root tải lười. Đường dẫn tương thích tải ngay đó vẫn được hỗ trợ, nhưng nó không cài đặt placeholder dựa trên descriptor cho việc tải lười tại thời điểm phân tích cú pháp.

Đăng ký backend CLI

api.registerCliBackend(...) cho phép một plugin sở hữu cấu hình mặc định cho một backend CLI AI cục bộ như codex-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.

Để xem hướng dẫn soạn thảo đầu-cuối, xem Plugin backend CLI.

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

Xem Plugin hooks để biết ví dụ, tên hook phổ biến, và ngữ nghĩa guard.

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ộ

Trong Plugin của bạn, hãy dùng các tệp barrel cục bộ cho các import 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)

Các bề mặt công khai của Plugin đóng gói được tải qua facade (api.ts, runtime-api.ts, index.ts, setup-entry.ts, và các tệp entry công khai tương tự) ưu tiên ảnh chụp nhanh cấu hình runtime đang hoạt động khi OpenClaw đã chạy. Nếu chưa có ảnh chụp nhanh runtime, chúng sẽ fallback về tệp cấu hình đã phân giải trên đĩa. Các facade Plugin đóng gói đã được package nên được tải thông qua các bộ tải facade Plugin của OpenClaw; import trực tiếp từ dist/extensions/... sẽ bỏ qua manifest và các kiểm tra sidecar runtime mà các bản cài đặt đã package dùng cho mã do Plugin sở hữu.

Provider Plugin có thể phơi bày một barrel hợp đồng cục bộ hẹp của Plugin khi một trình trợ giúp được chủ ý thiết kế riêng cho provider và chưa thuộc về một subpath SDK chung. Ví dụ đóng gói:

• 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