本页内容
本页内容
插件 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 不存在。该路径是位置事实,而不是调用已停用插件的授权。
各部分移动的地方
单页版本的每个部分现在都位于此页面或下面的八个子页面之一上。单页版本中的锚点仍然在这里解析。
- 进口约定
- 子路径参考
- 能力注册
- 工具和命令
- 基础设施
- 文件查看容量错误
- SQLite写录取
- Webhook主体拒绝
- Post-ack webhook 工作
- 请求者范围 MCP 连接
- 工作流插件的主机挂钩
- 何时使用工具-结果中间件
- 网关发现注册
- CLI 注册元数据
- CLI 后台注册
- 专用插槽
- 内存嵌入适配器
- 事件和生命周期
- Hhook 决策语义
- 内部模块约定
对接链接阅读器
请参阅 对接链接阅读器,了解聊天旁边的被动文档。