插件 SDK 概览

插件 SDK 是插件与核心之间的类型化契约。本页是导入什么和可以注册什么的参考。

Note

本页面向在 OpenClaw 内部使用 openclaw/plugin-sdk/* 的插件作者。对于希望通过 Gateway 运行 agent 的外部应用、脚本、仪表盘、CI 作业和 IDE 扩展，请改用外部应用的 Gateway 集成。

Tip

如果您想找操作指南，请从构建插件开始。通道请使用通道插件，模型提供方请使用提供方插件，本地 AI CLI 后端请使用 CLI 后端插件，原生 agent 执行器请使用 Agent harness 插件，工具或生命周期钩子请使用插件钩子。

API 稳定性¶

所有 OpenClaw 插件 API 均为实验性。这包括每个 openclaw/plugin-sdk/* 子路径、注册和运行时 API、通道与提供方契约、钩子，以及原生 Control UI API。这些契约可能会在 OpenClaw 版本之间发生变化。

请固定用于开发和部署插件的 OpenClaw 版本，并测试您声明兼容的每个宿主版本。根据这些已测试版本设置包兼容范围；不要假设某个可工作的构建支持未来版本。现有的兼容窗口和升级迁移仍然适用。实验性状态不会移除已记录的迁移路径。

用户安装插件提供的原生 UI 还需要默认关闭的自定义插件 UI 实验功能。后端插件 API 和普通插件加载不需要该设置。

各页面涵盖内容¶

导入和模块布局 — 应从哪个子路径导入、子路径目录，以及内部 barrel 约定。
能力注册 — 提供方注册器，以及 worker-provider 和 embedding 运行时契约。
工具和命令 — agent 工具、自定义命令、node-host 命令和 widget 展示器。
基础设施注册 — 钩子、HTTP 路由、Gateway 方法、服务，以及 webhook 和 SQLite 辅助工具。
宿主钩子 — 会话扩展、可信工具策略、Control UI 描述符和运行时生命周期。
CLI 和发现 — Gateway 发现广告器、插件 CLI 注册和 CLI 后端。
记忆和上下文槽位 — 独占的 context-engine 和 memory-capability 槽位及其适配器。
事件和钩子语义 — 类型化生命周期钩子，以及每个钩子应用的决策规则。

注册 API¶

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

每组注册方法都有自己的页面：

分组	注册内容
能力注册	推理、媒体、搜索、转录、worker 和 embedding 提供方
工具和命令	agent 工具、自定义命令、node-host 命令、widget 展示器
基础设施	钩子、HTTP 路由、Gateway 方法、CLI、服务、迁移
宿主钩子	会话扩展、可信工具策略、Control UI 描述符
CLI 和发现	Gateway 发现广告器、CLI 注册器、CLI 后端
独占槽位	上下文引擎和记忆能力，同一时间只有一个处于活动状态
事件和生命周期	类型化生命周期钩子和会话绑定回调

会话讨论提供方¶

为会话提供外部团队聊天界面的插件，可以注册由 openclaw/plugin-sdk/session-discussion 导出的唯一进程级提供方。其 info({ sessionKey }) 方法报告讨论不可用、准备就绪可打开，还是已经打开；open({ sessionKey }) 创建或解析讨论，并返回其嵌入 URL 和外部 URL。注册另一个提供方会替换当前提供方。

API 对象字段¶

字段	类型	描述
`api.id`	`string`	插件 id
`api.name`	`string`	显示名称
`api.version`	`string?`	插件版本（可选）
`api.description`	`string?`	插件描述（可选）
`api.source`	`string`	插件源路径

字段	类型	说明
`api.runtimeSource`	`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`	当前加载模式；`"setup-runtime"` 是带有可用运行时的轻量级设置流程
`api.resolvePath(input)`	`(string) => string`	解析相对于插件根目录的路径

使用 api.runtimeSource 定位所选运行时入口点旁边的私有模块。它记录加载器选择的来源、独立包或捆绑工件，并始终标识主运行时入口，即使在设置注册期间也是如此。api.source 和 api.rootDir 保留发现身份；它们可能与所选工件不同。当未选择运行时工件时（包括仅元数据 API），runtimeSource 不存在。此路径是位置事实，而不是调用已退役插件的授权。