插件 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。此路径是位置事实,而不是调用已退役插件的授权。
各章节迁移位置¶
单页版本的每个章节现在都位于此页面或以下八个子页面之一。单页版本中的锚点仍会在此处解析。
- 导入约定
- 子路径引用
- 能力注册
- 工具和命令
- 基础设施
- 文件监视容量错误
- SQLite 写入准入
- Webhook 主体拒绝
- 确认后的 Webhook 工作
- 请求者作用域的 MCP 连接
- 工作流插件的主机钩子
- 何时使用工具结果中间件
- 网关发现注册
- CLI 注册元数据
- CLI 后端注册
- 独占插槽
- 记忆嵌入适配器
- 事件和生命周期
- 钩子决策语义
- 内部模块约定
停靠链接阅读器¶
有关聊天旁边的被动文档,请参阅 停靠链接阅读器。
相关¶
definePluginEntry 和 defineChannelPluginEntry 选项。
完整的 api.runtime 命名空间参考。
打包、清单和配置模式。
测试实用工具和 lint 规则。
从已弃用接口迁移。
深度架构和能力模型。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw