本页是 OpenClaw Plugin SDK 的完整参考索引。涵盖导入约定（始终用 openclaw/plugin-sdk/<subpath> 子路径）、按用途分组的子路径速查表（渠道/Provider/认证安全/Runtime 存储/能力测试/内存），以及 OpenClawPluginApi 上所有注册方法的完整清单（能力/工具/命令/基础设施/独占槽位）和 hook 决策语义。养龙虾不可不看的 SDK 手册。

OpenClaw Plugin SDK 概览

Plugin SDK 是插件与 core 之间的类型化合约。本页是导入路径和注册方法的完整参考。

需要实操指导？
第一个插件？从插件开发入门开始
渠道插件？参考渠道插件开发
Provider 插件？参考 Provider 插件开发

导入约定

始终从特定子路径导入：

typescript

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

每个子路径是一个小型、自包含的模块，这样可以保持启动速度快、避免循环依赖。渠道特定的入口/构建 helper 优先用 openclaw/plugin-sdk/channel-core；openclaw/plugin-sdk/core 保留给更宽泛的伞形接口和共享 helper（如 buildChannelConfigSchema）。

不要依赖 Provider 名称的便利接缝（如 openclaw/plugin-sdk/slack、openclaw/plugin-sdk/discord 等）——这些只是内置插件维护用的兼容接缝，不是外部插件的稳定合约。

子路径速查表

插件入口

子路径	关键导出
`plugin-sdk/plugin-entry`	`definePluginEntry`
`plugin-sdk/core`	`defineChannelPluginEntry`、`createChatChannelPlugin`、`createChannelPluginBase`、`defineSetupPluginEntry`、`buildChannelConfigSchema`
`plugin-sdk/config-schema`	`OpenClawSchema`
`plugin-sdk/provider-entry`	`defineSingleProviderPluginEntry`

渠道子路径

子路径	关键导出
`plugin-sdk/channel-core`	`defineChannelPluginEntry`、`defineSetupPluginEntry`、`createChatChannelPlugin`、`createChannelPluginBase`
`plugin-sdk/channel-setup`	`createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、`createOptionalChannelSetupWizard`、`DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries`
`plugin-sdk/setup`	共享 setup 向导 helper、白名单提示、setup 状态构建器
`plugin-sdk/setup-runtime`	`createPatchedAccountSetupAdapter`、`createEnvPatchedAccountSetupAdapter`、`createSetupInputPresenceValidator`、`noteChannelLookupFailure`、`noteChannelLookupSummary`、`promptResolvedAllowFrom`、`splitSetupEntries`、`createAllowlistSetupWizardProxy`、`createDelegatedSetupWizardProxy`
`plugin-sdk/setup-adapter-runtime`	`createEnvPatchedAccountSetupAdapter`
`plugin-sdk/setup-tools`	`formatCliCommand`、`detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、`CONFIG_DIR`
`plugin-sdk/account-core`	多账号配置/动作门控 helper、default 账号回退 helper
`plugin-sdk/account-id`	`DEFAULT_ACCOUNT_ID`、账号 id 规范化 helper
`plugin-sdk/account-resolution`	账号查找 + default 回退 helper
`plugin-sdk/account-helpers`	窄型账号列表/账号动作 helper
`plugin-sdk/channel-pairing`	`createChannelPairingController`
`plugin-sdk/channel-reply-pipeline`	`createChannelReplyPipeline`
`plugin-sdk/channel-config-helpers`	`createHybridChannelConfigAdapter`
`plugin-sdk/channel-lifecycle`	`createAccountStatusSink`
`plugin-sdk/inbound-envelope`	共享入站路由 + 信封构建器 helper
`plugin-sdk/inbound-reply-dispatch`	共享入站记录和调度 helper
`plugin-sdk/messaging-targets`	目标解析/匹配 helper
`plugin-sdk/outbound-media`	共享出站媒体加载 helper
`plugin-sdk/outbound-runtime`	出站身份/发送委托 helper
`plugin-sdk/thread-bindings-runtime`	线程绑定生命周期和适配器 helper
`plugin-sdk/approval-runtime`	exec/插件审批 helper、审批能力/配置文件构建器、原生路由/runtime helper

Provider 子路径

子路径	关键导出
`plugin-sdk/provider-entry`	`defineSingleProviderPluginEntry`
`plugin-sdk/provider-auth`	`createProviderApiKeyAuthMethod`、`ensureApiKeyFromOptionEnvOrPrompt`、`upsertAuthProfile`
`plugin-sdk/provider-model-shared`	`ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享回放策略构建器
`plugin-sdk/provider-catalog-shared`	`findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat`
`plugin-sdk/provider-http`	通用 Provider HTTP/端点能力 helper
`plugin-sdk/provider-stream`	`ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流式包装器类型
`plugin-sdk/provider-tools`	`ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理和诊断、xAI 兼容 helper
`plugin-sdk/provider-usage`	`fetchClaudeUsage` 及类似 helper
`plugin-sdk/provider-web-fetch`	网页抓取 Provider 注册/缓存 helper
`plugin-sdk/provider-web-search`	网页搜索 Provider 注册/缓存/配置 helper
`plugin-sdk/provider-onboard`	引导配置 patch helper

认证与安全子路径

子路径	关键导出
`plugin-sdk/command-auth`	`resolveControlCommandGate`、命令注册表 helper、发送者授权 helper
`plugin-sdk/approval-auth-runtime`	审批者解析和同聊天动作认证 helper
`plugin-sdk/approval-client-runtime`	原生 exec 审批配置文件/过滤器 helper
`plugin-sdk/approval-delivery-runtime`	原生审批能力/交付适配器
`plugin-sdk/approval-native-runtime`	原生审批目标 + 账号绑定 helper
`plugin-sdk/security-runtime`	共享信任/DM 门控/外部内容/密钥收集 helper
`plugin-sdk/ssrf-policy`	主机白名单和私有网络 SSRF 策略 helper
`plugin-sdk/ssrf-runtime`	固定调度器、SSRF 保护的 fetch、SSRF 策略 helper
`plugin-sdk/webhook-ingress`	Webhook 请求/目标 helper

Runtime 与存储子路径

子路径	关键导出
`plugin-sdk/runtime-store`	`createPluginRuntimeStore`
`plugin-sdk/runtime`	宽泛 runtime/日志/备份/插件安装 helper
`plugin-sdk/runtime-env`	窄型 runtime 环境/日志/超时/重试/退避 helper
`plugin-sdk/lazy-runtime`	`createLazyRuntimeModule`、`createLazyRuntimeMethod`、`createLazyRuntimeSurface`
`plugin-sdk/process-runtime`	进程 exec helper
`plugin-sdk/config-runtime`	配置加载/写入 helper
`plugin-sdk/gateway-runtime`	网关客户端和渠道状态 patch helper
`plugin-sdk/reply-runtime`	共享入站/回复 runtime helper、分块、调度、心跳
`plugin-sdk/reply-history`	共享短窗口回复历史 helper
`plugin-sdk/state-paths`	状态/OAuth 目录路径 helper
`plugin-sdk/routing`	路由/session-key/账号绑定 helper
`plugin-sdk/status-helpers`	共享渠道/账号状态摘要 helper

能力与测试子路径

子路径	关键导出
`plugin-sdk/media-runtime`	共享媒体加载/变换/存储 helper
`plugin-sdk/media-understanding`	媒体理解 Provider 类型及 Provider 端图像/音频 helper
`plugin-sdk/speech`	语音 Provider 类型及指令/注册表/验证 helper
`plugin-sdk/image-generation-core`	图像生成类型、失败转移、认证和注册表 helper
`plugin-sdk/video-generation-core`	视频生成类型、失败转移 helper、Provider 查找
`plugin-sdk/text-runtime`	共享文本/markdown/日志 helper
`plugin-sdk/zod`	为 SDK 消费者重新导出的 `zod`
`plugin-sdk/testing`	`installCommonResolveTargetErrorCases`、`shouldAckReaction`

内存子路径

子路径	关键导出
`plugin-sdk/memory-core`	内置 memory-core helper（管理器/配置/文件/CLI）
`plugin-sdk/memory-core-engine-runtime`	内存索引/搜索 runtime 门面
`plugin-sdk/memory-host-core`	内存宿主 core runtime helper（厂商中立别名）
`plugin-sdk/memory-host-search`	主动内存搜索管理器 runtime 门面
`plugin-sdk/memory-lancedb`	内置 memory-lancedb helper

注册 API

register(api) 回调接收 OpenClawPluginApi 对象，包含以下方法：

能力注册

方法	注册内容
`api.registerProvider(...)`	文本推理（LLM）
`api.registerChannel(...)`	消息渠道
`api.registerSpeechProvider(...)`	TTS / STT 合成
`api.registerRealtimeTranscriptionProvider(...)`	流式实时转录
`api.registerRealtimeVoiceProvider(...)`	双工实时语音会话
`api.registerMediaUnderstandingProvider(...)`	图像/音频/视频分析
`api.registerImageGenerationProvider(...)`	图像生成
`api.registerMusicGenerationProvider(...)`	音乐生成
`api.registerVideoGenerationProvider(...)`	视频生成
`api.registerWebFetchProvider(...)`	网页抓取/爬取 Provider
`api.registerWebSearchProvider(...)`	网页搜索

工具和命令

方法	注册内容
`api.registerTool(tool, opts?)`	Agent 工具（必选或 `{ optional: true }`）
`api.registerCommand(def)`	自定义命令（绕过 LLM）

基础设施

方法	注册内容
`api.registerHook(events, handler, opts?)`	事件 hook
`api.registerHttpRoute(params)`	网关 HTTP 端点
`api.registerGatewayMethod(name, handler)`	网关 RPC 方法
`api.registerCli(registrar, opts?)`	CLI 子命令
`api.registerService(service)`	后台服务
`api.registerInteractiveHandler(registration)`	交互式处理器
`api.registerMemoryPromptSupplement(builder)`	附加的内存相邻 prompt 节
`api.registerMemoryCorpusSupplement(adapter)`	附加的内存搜索/读取语料库

独占槽位

方法	注册内容
`api.registerContextEngine(id, factory)`	上下文引擎（同时只能激活一个）
`api.registerMemoryPromptSection(builder)`	内存 prompt 节构建器（memory 插件独占）
`api.registerMemoryFlushPlan(resolver)`	内存刷写计划解析器（memory 插件独占）
`api.registerMemoryRuntime(runtime)`	内存 runtime 适配器（memory 插件独占）
`api.registerMemoryEmbeddingProvider(adapter)`	内存嵌入适配器

registerMemoryEmbeddingProvider 允许激活的 memory 插件注册一个或多个嵌入适配器 id（如 openai、gemini 或自定义 id）。用户配置中的 agents.defaults.memorySearch.provider 和 agents.defaults.memorySearch.fallback 会解析至这些已注册的适配器 id。

事件与生命周期

方法	作用
`api.on(hookName, handler, opts?)`	类型化生命周期 hook
`api.onConversationBindingResolved(handler)`	会话绑定回调

Hook 决策语义

before_tool_call：返回 { block: true } 是终止决策，后续低优先级处理器会被跳过；{ block: false } 视为无决策（不覆盖）
before_install：{ block: true } 终止，{ block: false } 无决策
reply_dispatch：{ handled: true, ... } 终止，后续处理器和默认模型调度路径被跳过
message_sending：{ cancel: true } 终止，{ cancel: false } 无决策

API 对象字段

字段	类型	说明
`api.id`	`string`	插件 id
`api.name`	`string`	显示名称
`api.version`	`string?`	插件版本（可选）
`api.description`	`string?`	插件描述（可选）
`api.source`	`string`	插件源路径
`api.rootDir`	`string?`	插件根目录（可选）
`api.config`	`OpenClawConfig`	当前配置快照
`api.pluginConfig`	`Record<string, unknown>`	插件特定配置（来自 `plugins.entries.<id>.config`）
`api.runtime`	`PluginRuntime`	运行时辅助工具
`api.logger`	`PluginLogger`	作用域日志器（`debug`/`info`/`warn`/`error`）
`api.registrationMode`	`PluginRegistrationMode`	当前加载模式
`api.resolvePath(input)`	`(string) => string`	解析相对于插件根的路径

插件内部模块约定

在插件内部，用本地 barrel 文件管理内部导入：

my-plugin/
  api.ts            # 给外部消费者的公开导出
  runtime-api.ts    # 仅内部使用的 runtime 导出
  index.ts          # 插件入口点
  setup-entry.ts    # 轻量 setup 专用入口（可选）

警告： 永远不要在生产代码中通过 openclaw/plugin-sdk/<your-plugin> 导入自己的插件。内部导入通过 ./api.ts 或 ./runtime-api.ts 路由，SDK 路径是给外部的合约。

常见问题

Q: plugin-sdk/core 和 plugin-sdk/channel-core 有什么区别？

A: plugin-sdk/channel-core 是聚焦版本，包含 defineChannelPluginEntry、defineSetupPluginEntry、createChatChannelPlugin 和 createChannelPluginBase。plugin-sdk/core 是更宽泛的伞形接口，包含上述所有内容以及 buildChannelConfigSchema 等共享 helper。新代码优先用 channel-core，需要 buildChannelConfigSchema 才用 core。

Q: 注册工具时什么情况下用 optional: true？

A: 有副作用（发消息、执行命令）、依赖外部二进制、或功能较窄的工具用 optional: true。必选工具始终对 Agent 可用；可选工具需用户在配置 tools.allow 中主动开启。如有疑问，宁可设为 optional，让用户自主决策。

Q: registerGatewayMethod 注册的 RPC 方法名有什么限制？

A: 方法名必须使用插件特定前缀，不能占用保留的 core 管理员命名空间（config.*、exec.approvals.*、wizard.*、update.*）——这些总是解析到 operator.admin，即使插件尝试分配更窄的作用域也无效。

OpenClaw Plugin SDK 概览 ​

导入约定 ​

子路径速查表 ​

插件入口 ​

渠道子路径 ​

Provider 子路径 ​

认证与安全子路径 ​

Runtime 与存储子路径 ​

能力与测试子路径 ​

内存子路径 ​

注册 API ​

能力注册 ​

工具和命令 ​

基础设施 ​

独占槽位 ​

事件与生命周期 ​

Hook 决策语义 ​

API 对象字段 ​

插件内部模块约定 ​

相关文档 ​

常见问题 ​