Plugin SDK 概览

概述

Plugin SDK 是插件与 OpenClaw 核心之间的类型化契约层。通过 openclaw/plugin-sdk/* 子路径导入，每个子路径是独立的小模块，避免循环依赖并加快启动速度。

注意：本页面针对插件作者（内部插件开发）。外部应用（CI、IDE 扩展等）应使用 @openclaw/sdk 包。

核心 API

导入约定

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

能力注册方法（OpenClawPluginApi）

提供商类

• api.registerProvider(...) — 文本推理（LLM）
• api.registerAgentHarness(...) — 实验性低级 Agent 执行器
• api.registerCliBackend(...) — 本地 CLI 推理后端
• api.registerChannel(...) — 消息渠道
• api.registerSpeechProvider(...) — TTS/STT
• api.registerRealtimeTranscriptionProvider(...) — 流式实时转录
• api.registerRealtimeVoiceProvider(...) — 双工实时语音
• api.registerMediaUnderstandingProvider(...) — 图像/音频/视频分析
• api.registerImageGenerationProvider(...) — 图像生成
• api.registerMusicGenerationProvider(...) — 音乐生成
• api.registerVideoGenerationProvider(...) — 视频生成
• api.registerWebFetchProvider(...) — Web 抓取
• api.registerWebSearchProvider(...) — Web 搜索

工具与命令

• api.registerTool(tool, opts?) — Agent 工具
• api.registerCommand(def) — 自定义命令（绕过 LLM）

基础设施

• api.registerHook(events, handler, opts?) — 事件钩子
• api.registerHttpRoute(params) — Gateway HTTP 端点
• api.registerGatewayMethod(name, handler) — Gateway RPC 方法
• api.registerService(service) — 后台服务
• api.registerCli(registrar, opts?) — CLI 子命令

独占插槽

• api.registerContextEngine(id, factory) — 上下文引擎（同时只有一个激活）
• api.registerMemoryCapability(capability) — 统一记忆能力
• api.registerMemoryEmbeddingProvider(adapter) — 记忆嵌入适配器

工作流宿主钩子

• api.session.state.registerSessionExtension(...) — 会话状态扩展
• api.session.workflow.enqueueNextTurnInjection(...) — 下一轮上下文注入
• api.lifecycle.registerRuntimeLifecycle(...) — 运行时生命周期清理
• api.agent.events.registerAgentEventSubscription(...) — Agent 事件订阅

API 对象字段

字段	类型	说明
api.id	string	插件 ID
api.config	OpenClawConfig	当前配置快照
api.pluginConfig	Record<string, unknown>	插件专属配置
api.runtime	PluginRuntime	运行时辅助工具
api.logger	PluginLogger	作用域日志
api.registrationMode	PluginRegistrationMode	当前加载模式

使用示例

// Gateway 发现服务注册
api.registerGatewayDiscoveryService({
  id: "my-discovery",
  async advertise(ctx) {
    const handle = await startMyAdvertiser({
      gatewayPort: ctx.gatewayPort,
      tls: ctx.gatewayTlsEnabled,
    });
    return { stop: () => handle.stop() };
  },
});
 
// CLI 注册（带懒加载描述符）
api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [{ name: "matrix", description: "Manage Matrix accounts", hasSubcommands: true }],
  },
);

相关页面

• concepts/plugin-sdk-entrypoints — definePluginEntry 和 defineChannelPluginEntry 选项
• concepts/plugin-sdk-runtime — api.runtime 命名空间完整参考
• concepts/plugin-sdk-setup — 打包、清单和配置 Schema
• concepts/plugin-sdk-subpaths — 子路径目录
• concepts/plugin-architecture — 插件架构与能力模型
• concepts/plugin-hooks — 钩子系统