跳转至

插件 SDK 概览

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

Note

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

Tip

正在寻找操作指南?请从构建插件开始。频道请使用频道插件,模型提供商请使用提供商插件,本地 AI CLI 后端请使用CLI 后端插件,原生代理执行器请使用Agent harness 插件,工具或生命周期钩子请使用插件钩子。

API 稳定性

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

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

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

各页面涵盖内容

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

注册 API

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

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

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

会话讨论提供商

为会话提供外部团队聊天界面的插件可以注册由 openclaw/plugin-sdk/session-discussion 导出的唯一进程级提供商。其 info({ sessionKey }) 方法报告讨论不可用、准备打开或已打开;open({ sessionKey }) 创建或解析讨论,并返回其嵌入和外部 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 保留发现身份;它们可能与所选工件不同。当未选择运行时工件时,runtimeSource 不存在,包括仅元数据 API。此路径是位置事实,而不是调用已退役插件的授权。

各章节迁移位置

单页版本的每个章节现在都位于此页面或以下八个子页面之一。单页版本中的锚点仍会在此处解析。

有关聊天旁边的被动文档,请参阅 停靠链接阅读器。

入口点

definePluginEntry 和 defineChannelPluginEntry 选项。

运行时辅助函数

完整的 api.runtime 命名空间参考。

设置和配置

打包、清单和配置模式。

测试

测试实用工具和 lint 规则。

SDK 迁移

从已弃用接口迁移。

插件内部结构

深度架构和能力模型。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw