Plugin SDK 概览

Plugin SDK 是插件与 core 之间的类型化契约。本页是导入什么和可以注册什么的参考文档——就像给你的"小龙虾"看一份完整的外设接口手册。

提示： 在找操作指南？
第一个插件？从快速入门开始
渠道插件？看渠道插件
Provider 插件？看 Provider 插件

导入约定

始终从具体的子路径导入：

typescript

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

每个子路径都是一个小型、独立的模块。这样可以保持启动速度，并避免循环依赖问题。

子路径参考

以下是按用途分组的最常用子路径。完整的 100+ 子路径列表在 scripts/lib/plugin-sdk-entrypoints.json 中。

插件入口

子路径	主要导出
`plugin-sdk/plugin-entry`	`definePluginEntry`
`plugin-sdk/core`	`defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema`

渠道子路径：

子路径	主要导出
`plugin-sdk/channel-setup`	`createOptionalChannelSetupSurface`
`plugin-sdk/channel-pairing`	`createChannelPairingController`
`plugin-sdk/channel-reply-pipeline`	`createChannelReplyPipeline`
`plugin-sdk/channel-config-helpers`	`createHybridChannelConfigAdapter`
`plugin-sdk/channel-config-schema`	渠道配置 schema 类型
`plugin-sdk/channel-policy`	`resolveChannelGroupRequireMention`
`plugin-sdk/channel-lifecycle`	`createAccountStatusSink`
`plugin-sdk/channel-inbound`	防抖、mention 匹配、信封辅助工具
`plugin-sdk/channel-send-result`	回复结果类型
`plugin-sdk/channel-actions`	`createMessageToolButtonsSchema`, `createMessageToolCardSchema`
`plugin-sdk/channel-targets`	目标解析/匹配辅助工具
`plugin-sdk/channel-contract`	渠道契约类型
`plugin-sdk/channel-feedback`	反馈/reaction 接线

Provider 子路径：

子路径	主要导出
`plugin-sdk/cli-backend`	CLI 后端默认值 + watchdog 常量
`plugin-sdk/provider-auth`	`createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`
`plugin-sdk/provider-models`	`normalizeModelCompat`
`plugin-sdk/provider-catalog`	目录类型重新导出
`plugin-sdk/provider-usage`	`fetchClaudeUsage` 等
`plugin-sdk/provider-stream`	流包装类型
`plugin-sdk/provider-onboard`	引导配置补丁辅助工具

认证和安全子路径：

子路径	主要导出
`plugin-sdk/command-auth`	`resolveControlCommandGate`
`plugin-sdk/allow-from`	`formatAllowFromLowercase`
`plugin-sdk/secret-input`	密钥输入解析辅助工具
`plugin-sdk/webhook-ingress`	Webhook 请求/目标辅助工具

运行时和存储子路径：

子路径	主要导出
`plugin-sdk/runtime-store`	`createPluginRuntimeStore`
`plugin-sdk/config-runtime`	配置加载/写入辅助工具
`plugin-sdk/infra-runtime`	系统事件/心跳辅助工具
`plugin-sdk/agent-runtime`	Agent 目录/身份/工作区辅助工具
`plugin-sdk/directory-runtime`	配置驱动的目录查询/去重
`plugin-sdk/keyed-async-queue`	`KeyedAsyncQueue`

能力和测试子路径：

子路径	主要导出
`plugin-sdk/image-generation`	图像生成 Provider 类型
`plugin-sdk/media-understanding`	媒体理解 Provider 类型
`plugin-sdk/speech`	语音 Provider 类型
`plugin-sdk/testing`	`installCommonResolveTargetErrorCases`, `shouldAckReaction`

注册 API

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

能力注册

方法	注册内容
`api.registerProvider(...)`	文本推理（LLM）
`api.registerCliBackend(...)`	本地 CLI 推理后端
`api.registerChannel(...)`	消息渠道
`api.registerSpeechProvider(...)`	TTS / STT 合成
`api.registerMediaUnderstandingProvider(...)`	图像/音频/视频分析
`api.registerImageGenerationProvider(...)`	图像生成
`api.registerWebSearchProvider(...)`	网络搜索

工具和命令

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

基础设施

方法	注册内容
`api.registerHook(events, handler, opts?)`	事件 hook
`api.registerHttpRoute(params)`	Gateway HTTP 端点
`api.registerGatewayMethod(name, handler)`	Gateway RPC 方法
`api.registerCli(registrar, opts?)`	CLI 子命令
`api.registerService(service)`	后台服务
`api.registerInteractiveHandler(registration)`	交互式处理器

CLI 后端注册

api.registerCliBackend(...) 让插件拥有本地 AI CLI 后端（如 claude-cli 或 codex-cli）的默认配置。

后端 id 成为模型引用（如 claude-cli/opus）中的 Provider 前缀。
后端 config 与 agents.defaults.cliBackends.<id> 的格式相同。
用户配置优先。OpenClaw 在运行 CLI 之前会将 agents.defaults.cliBackends.<id> 合并到插件默认值之上。
当后端需要在合并后进行兼容性重写时，使用 normalizeConfig（例如规范化旧的 flag 形式）。

排他性插槽

方法	注册内容
`api.registerContextEngine(id, factory)`	上下文引擎（同一时间只有一个激活）
`api.registerMemoryPromptSection(builder)`	记忆 Prompt 片段 builder
`api.registerMemoryFlushPlan(resolver)`	记忆刷新计划解析器
`api.registerMemoryRuntime(runtime)`	记忆运行时适配器

记忆嵌入适配器

方法	注册内容
`api.registerMemoryEmbeddingProvider(adapter)`	活跃插件的记忆嵌入适配器

registerMemoryPromptSection、registerMemoryFlushPlan 和 registerMemoryRuntime 专属于记忆插件。
registerMemoryEmbeddingProvider 让活跃记忆插件注册一个或多个嵌入适配器 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 } 是终止性的。一旦有处理器设置了它，低优先级处理器会被跳过。
before_tool_call：返回 { block: false } 被视为无决策（与省略 block 相同），不是覆盖。
message_sending：返回 { cancel: true } 是终止性的。一旦有处理器设置了它，低优先级处理器会被跳过。
message_sending：返回 { cancel: false } 被视为无决策（与省略 cancel 相同），不是覆盖。

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`	`"full"`、`"setup-only"` 或 `"setup-runtime"`
`api.resolvePath(input)`	`(string) => string`	相对于插件根目录解析路径

内部模块约定

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

my-plugin/
  api.ts            # 供外部使用者的公共导出
  runtime-api.ts    # 仅内部使用的运行时导出
  index.ts          # 插件入口点
  setup-entry.ts    # 轻量级 setup-only 入口（可选）

警告： 绝对不要在生产代码中通过 openclaw/plugin-sdk/<your-plugin> 导入你自己的插件。内部导入应通过 ./api.ts 或 ./runtime-api.ts 路由。SDK 路径仅是对外契约。

Plugin SDK 概览 ​

导入约定 ​

子路径参考 ​

插件入口 ​

注册 API ​

能力注册 ​

工具和命令 ​

基础设施 ​

CLI 后端注册 ​

排他性插槽 ​

记忆嵌入适配器 ​

事件和生命周期 ​

Hook 决策语义 ​

API 对象字段 ​

内部模块约定 ​

相关链接 ​