本页内容

本页内容

插件 SDK 参考

插件 SDK 概览

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

API 稳定性

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

固定用于开发和部署插件的 OpenClaw 版本,并测试您声明兼容的每个主机版本。从那些经过测试的版本中设置包兼容性范围;不要假设工作版本支持未来版本。现有的 兼容性窗口和升级迁移 仍然适用。实验状态不会删除记录的迁移路径。

用户安装的插件中​​的本机 UI 还需要默认关闭的 自定义插件 UI lab。后端插件 API 和普通插件加载不需要该设置。

每页涵盖的内容

  • 导入和模块布局 — 从哪个子路径导入、子路径目录和内部桶约定。
  • 能力注册 - 提供者注册商加上存储、工作人员和嵌入运行时合约。
  • 工具和命令 — 代理工具、自定义命令、节点主机命令和小部件呈现器。
  • 基础设施注册 — 挂钩、HTTP 路由、网关方法、服务以及 Webhook 和 SQLite 帮助程序。
  • 主机挂钩 — 会话扩展、可信工具策略、Control UI 描述符和运行时生命周期。
  • CLI 和 discovery — 网关发现广告商、插件 CLI 注册和 CLI 后端。
  • 内存和上下文插槽 - 专有的上下文引擎和内存功能插槽及其适配器。
  • 事件和钩子语义 — 类型化生命周期钩子以及每个钩子应用的决策规则。

注册 API

register(api) 回调会接收一个 OpenClawPluginApi 对象,其中包含这些方法:

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

团体 注册内容
能力注册 推理、媒体、搜索、转录、工作人员和嵌入提供程序
工具和命令 代理工具、自定义命令、节点主机命令、小部件呈现器
基础设施 挂钩、HTTP 路由、网关方法、CLI、服务、迁移
主机挂钩 会话扩展、可信工具策略、Control UI 描述符
CLI 和发现 网关发现广告商、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保留发现身份;它们可能与所选工件不同。当未选择运行时工件(包括仅元数据 API)时,runtimeSource 不存在。该路径是位置事实,而不是调用已停用插件的授权。

各部分移动的地方

单页版本的每个部分现在都位于此页面或下面的八个子页面之一上。单页版本中的锚点仍然在这里解析。

对接链接阅读器

请参阅 对接链接阅读器,了解聊天旁边的被动文档。

相关内容

本页有帮助吗?