功能插件
功能插件可以拥有自己的后端操作和 Control UI。它可以添加页面、导航、会话操作、面板、仪表板小组件和头部附件,或为工作区、会话列表、编辑器、转录和工具结果提供替换项。
所有插件 API 均为实验性,包括本页中的后端和浏览器契约。请固定并测试你的 OpenClaw 主机版本。
原生 UI 在 Control UI 源中运行受信任的 JavaScript。仅从你信任的作者处安装。原生模块共享已登录操作员的 Gateway 权限:host.request 可以调用该连接范围允许的任何方法,包括管理员的管理方法。当内容应与宿主应用隔离时,请使用现有的沙箱仪表板小组件或 MCP App 界面。
打开由已连接 Gateway 提供的 Control UI。原生插件资源需要相同的源;连接到另一个 Gateway 的独立托管 UI 无法加载它们,并会说明应打开哪个 Control UI。
经过身份验证的原生 UI 还需要 HTTPS 或浏览器信任的回环 URL,例如 http://127.0.0.1:18789/。LAN 地址上的普通 HTTP 可以配对并使用仪表板,但无法发送用于原生资源的安全 Cookie。插件页面会说明如何切换到 HTTPS/Tailscale Serve 或 localhost;后端操作仍可用。
启用自定义插件 UI¶
在 Control UI 中,打开 设置 → 实验室 → 自定义插件 UI。该设置默认关闭,并控制来自用户安装插件的原生浏览器代码,包括本地开发插件。等效配置为:
更改无需重启 Gateway 即可生效,已连接的 Control UI 页面会自动刷新其插件视图。禁用它会阻止自定义原生 UI 加载并移除其视图。重新加载浏览器标签页以清除已经运行的插件 JavaScript。这不会卸载插件,也不会禁用其后端操作、工具或服务。普通插件 API、沙箱仪表板小组件和 MCP Apps 不受影响。
随 OpenClaw 提供的原生 UI 对已启用的捆绑插件仍然可用,包括 Workboard。OpenClaw 根据已加载插件的来源确定捆绑状态,而不是根据其名称或清单声明。单独安装的副本使用自定义插件设置。
创建功能插件¶
在打开脚手架的浏览器视图之前,启用自定义插件 UI 实验室。
openclaw plugins init draft-review --name "Draft Review" --type feature
cd draft-review
npm install
npm run build
npm run validate
openclaw plugins install .
脚手架包含一个 draft-analysis 操作、一个代理工具、一个原生页面和一个编辑器替换项。从 Control UI 侧边栏打开 Draft Review,或打开 插件 → 高级 → 自定义 UI 并选择 Draft 编辑器。选择内置以恢复视图。替换选择属于当前浏览器运行时;它不是持久化配置设置。
自定义控件是 插件 → 高级 中的第一个部分。如果工作区替换项隐藏了导航,请在你的 Control UI 基础 URL 下打开 /settings/plugins?tab=advanced 以选择内置;插件设置始终使用内置工作区。
该项目有三个公共 SDK 导入:
| 导入 | 用途 |
|---|---|
openclaw/plugin-sdk/feature-contract |
共享操作架构、类型化客户端和事件订阅;浏览器安全。 |
openclaw/plugin-sdk/feature-plugin |
将后端实现注册为会话操作、可选代理工具和命令适配器。 |
openclaw/plugin-sdk/control-ui |
原生浏览器激活、宿主能力、贡献类型和组件挂载。 |
浏览器代码拥有自己的 DOM,并打包其框架依赖项。它不会导入 Control UI 内部实现,也不会返回宿主框架的模板。
一次定义操作¶
defineFeatureContract 使用 TypeBox 输入和输出架构声明命名查询和操作。defineFeaturePlugin 通过 setup(api, events) 实现它们,并将每个操作注册到现有的插件会话操作传输上。查询需要 operator.read;操作需要 operator.write。
带有 tool 声明的操作还会注册一个代理工具。可选的命令适配器会解析实际的命令上下文并格式化结果。处理程序接收一个可区分的调用上下文:source 为 session-action、tool 或 command,并带有该表面的原始上下文。工具策略、经过身份验证的命令处理以及 Gateway 范围检查仍由其现有执行路径负责。
在浏览器视图中使用 createFeatureClient(contract, context.host):
const feature = createFeatureClient(contract, context.host);
const report = await feature.invoke("analyze", { text: "A draft to inspect" });
context.signal.throwIfAborted();
output.textContent = `${report.words} words`;
后端输入、输出和事件会作为有界 JSON 进行验证。也请在架构中定义有意义的限制。使用插件现有的运行时和存储 API 来处理持久状态和服务。
对于变化的数据,请在契约中声明事件,并在插件服务启动后通过 events 参数发出它们。客户端可以使用 feature.on(...) 订阅,或使用 feature.watch(query, input, options) 在初始时、命名事件后以及重连后请求最新快照。watch 需要 onChange 和 onError,返回一个释放器,并在更新的刷新或视图释放后拒绝过期结果。它不会轮询。
贡献和替换视图¶
从浏览器入口导出 defineControlUiPlugin({ id, activate(host) })。
其 id 必须与插件清单匹配。通过 host.ui 注册贡献;每个注册都会返回一个释放函数。
| 注册 | 宿主位置 |
|---|---|
registerPage 和 registerNavigation |
插件拥有的路由和侧边栏目标。 |
registerAction |
Composer、头部或会话菜单操作。可选的 resolve 函数提供当前标签、隐藏状态和禁用状态。 |
registerPanel |
会话面板。 |
registerAccessory |
会话头部内容。 |
registerWidget |
原生仪表板小部件视图。 |
registerReplacement |
workspace、session-list、composer、transcript 或 tool-result。 |
将导航项的 parent 设置为同一插件中的另一个导航 ID,以便在父级或某个子级目标处于活动状态时将其显示为嵌套项;子项仅在已固定时才会作为顶级条目出现。设置 defaultVisible: false 可在 自定义 中提供该条目,并在注册后调用 host.ui.pinNavigation(id) 以追加一个普通的已保存侧边栏固定项。对于未知或已固定的 ID,固定操作是空操作;应在创建等用户操作时调用它,而不是在每次目录刷新时调用,以便后续手动移除后保持移除状态。
导航项可以提供 actions,其中包含 id、label、可选的 icon 和 destructive 标志,以及一个 run 回调。侧边栏会在右键单击、Shift+F10 或聚焦链接上的上下文菜单键时打开这些操作,包括嵌套和已固定的条目。选择某个操作会关闭菜单;Escape 或外部点击会将其关闭。使用 host.ui.isNavigationPinned(id) 读取已保存的固定项,并使用 host.ui.unpinNavigation(id) 幂等地移除它。插件决定提供哪些操作,并负责破坏性操作的确认。
对于仪表板小部件,还需注册一个后端 api.session.controls.registerControlUiDescriptor,其中包含 surface: "widget"、相同的小部件 id 及其 requiredScopes。Gateway 会为当前连接的 scopes 通告小部件类型;只有当匹配的后端描述符被通告时,原生视图才会渲染。
使用 host.ui.openPanel("editor", { sessionKey, agentId }) 在会话旁边打开你已注册的面板之一。省略会话时会使用当前选中的会话。宿主拥有导航和侧边栏呈现,包括在会话窗格挂载之前从插件页面打开。只能打开同一插件已注册的面板;保留的句柄会随其视图或激活而失效。
对于文档链接,使用 host.navigation.pageHref(...) 构建指向已注册插件页面的链接。该页面可以解析其文档,并使用目标会话调用 openPanel。这不会拦截普通文件链接,也不会更改 Files 插件的所有权。
当插件拥有的状态更改某个操作或其他贡献的呈现时,使用 host.ui.invalidate()。使用插件 id 为自定义元素和 CSS 设置命名空间,以便独立打包的插件可以共存。
视图会挂载到一个 HTMLElement 中,并接收 context.host、props、signal、presented 和 mountDefault。根据需要返回一个包含 update、focus 和 dispose 的对象。Surface 属性和呈现更改通过 update 到达;使用 context.host.subscribe(...) 观察宿主快照更改。当 presented 为 false 时,保持挂载的视图会保留其宿主生命周期;使用它来暂停视觉工作,同时保留状态。移除或销毁视图会中止其 signal,并使宿主句柄失效。在异步工作之后检查 signal,并在 dispose 中释放插件资源。
与会话绑定的视图和操作会接收 sessionKey 和 agentId。发起会话请求时,请同时携带两者:应用程序选中的 agent 可能与视图的 agent 不同。更改该标识的任何一部分都会使旧视图的句柄失效,包括保留的 composer 操作。头部和 composer 操作也会在其窗格停止呈现时失效。之后返回该窗格会允许新的操作;它不会恢复来自先前调用的句柄。
替换项可以通过调用 context.mountDefault(container) 来组合内置视图。当工作区替换项希望保留内置聊天状态和会话所有者时,应使用此方法。SDK 不会为完全独立的工作区暴露单独的无头聊天服务。
Composer 替换项会接收当前草稿、准入状态、禁用原因,以及规范的 setDraft、send 和可选的 abort 操作。使用这些操作,而不是发出原始聊天 RPC。send() 在获准时解析为 true,被拒绝时解析为 false,对于本地命令或未提交则解析为 undefined。显示被拒绝的提交,而不是清除草稿。当视图停止呈现时,Composer 操作会失效,即使其 DOM 和宿主生命周期仍然存在。当视图再次呈现时,使用 update 提供的新操作;先前捕获的操作仍保持失效状态。
宿主功能¶
使用 host 实现共享的应用行为:
| 能力 | 目的 |
|---|---|
agents |
代理快照、选择、作用域和刷新。 |
components |
由 host 拥有的对话框、选择器和会话仪表盘。 |
connection |
当前连接和 operator 能力。 |
dock(可选) |
使用 openSession 在当前页面旁打开对话,关闭停靠区,并观察 openSessionKey。 |
navigation |
打开插件页面并构建其 URL。 |
request 和 onEvent |
经过身份验证的 Gateway 请求和事件订阅。 |
sessions |
会话快照、独立查询、导航、创建和更新。 |
subscribe |
观察 host 快照变化,包括已停靠的会话键。 |
ui |
注册、选择和使插件贡献失效。 |
会话和代理的 refresh() 操作会获取新快照,并在失败时 reject,因此插件可以显示错误并提供重试。host.sessions.rows 是当前经过筛选和分页的会话列表。host.sessions.refresh() 会保留该列表的筛选条件。使用 host.sessions.observe(query, onChange) 可以维护一个独立的会话查询,而不会替换它。查询接受 agentId、search、archived(true、false 或 "all")、limit、configuredAgentsOnly、includeGlobal、includeUnknown、excludeDock、includeDerivedTitles 和 includeLastMessage。回调接收 { result, loading, error },初始值为当前快照;在数据可用之前,result 为 null。结果包含 sessions 以及 Gateway 的 hasMore、nextOffset 和 totalCount 分页元数据。
使用 host.sessions.create({ agentId, displayName?, label?, surface? }) 创建对话。displayName 是可复用的显示标题;label 是唯一的会话标签。对于由插件页面的停靠区拥有的对话,传入 surface: "plugin-dock"。这个不可变的创建来源标记会将对话从普通会话列表中隐藏,同时不改变其人类创建者、访问、共享或沙箱规则。行会暴露 isDock 和 createdSurface;createdVia 保留其普通 operator 来源。
独立的 host 列表查询默认排除停靠对话;在有意包含它们时传入 excludeDock: false。
会话键仍可用于 host.dock.openSession 和直接读取。
host 会获取查询,并通过会话事件、观察者恢复及其常规删除处理保持其最新。observe 返回 { refresh, dispose }:调用 refresh() 进行显式重试,在不再需要查询时调用 dispose()。错误会出现在快照中,显式刷新在失败时 reject。视图销毁也会释放其查询;保留的句柄和未完成的刷新在该生命周期结束后会 reject。
在筛选或不完整的列表中缺少某一行,并不能证明该会话已被删除。待处理的删除也可能在分页元数据变化之前隐藏行。将 { sessionKey: row.key, agentId: row.agentId } 传递给 host.sessions.open、host.sessions.patch 以及仪表盘的 session prop。
携带返回行中的身份:原始 global 键属于其查询的代理,而不是当前选择或卡片分配的代理。将未解析或模糊的搜索视为未知。当名册变化时,会话操作展示会更新,并且操作在调用时会再次检查当前行。
操作可以检查 session.hasActiveRun;值缺失表示活动状态尚未知。
host.components
从普通 props 和 DOM 内容挂载由 host 拥有的对话框、代理选择器、可搜索的选择器以及会话仪表盘。每个组件返回 update 和 dispose 方法;host 保留权限检查、焦点处理和仪表盘 provider 所有权。使用 mountSelectPicker 处理 { value, label, description? } 选项列表、选中的 value、accessibleLabel 以及 onSelect 回调。
当 searchable: true 时,超过八个选项的列表会显示搜索字段。
选择器会匹配选项的标签、值和描述。
停靠对话¶
在提供停靠操作之前,检查 host.dock。从已挂载的视图,使用 context.host.dock.openSession({ sessionKey, agentId, label, context }) 在你的插件页面旁打开指定对话。label 提供停靠选项卡标题;可选的 context 是 { page, detail? },其中 page 可以是你的插件页面 id,detail 包含字符串引用字段。
host 会复用 Home 停靠区的位置控件、聊天窗格、草稿和附件。页面导航会保持对话停靠区打开;结束插件激活会关闭该激活仍拥有的停靠区。使用 host.subscribe(...) 在 host.dock.openSessionKey 变化时刷新你的操作。有关替换、可见性、访问和上下文限制,请参阅 停靠契约。
构建并重载¶
package.json 指定浏览器 源:
openclaw plugins build 使用该插件的 esbuild dev 依赖项,将上述源及其浏览器依赖项打包。它在 dist/control-ui/<content-hash>/ 下写入不可变的 JavaScript 和 CSS,然后在 openclaw.plugin.json.controlUi 中发布其路径。构建失败会保留之前的清单和资源可用。plugins validate 和 plugins build --check 可以检测过期的源、资源或生成的元数据。
Solid 视图¶
Solid 2 支持原生插件视图。使用 .tsx 浏览器入口,并将 solid-js 和 @solidjs/web 声明为插件的运行时依赖,且版本匹配。将 @solidjs/compiler 和 esbuild 添加到其开发依赖中。在每个 Solid .tsx 文件的导入之前放置 /** @jsxImportSource @solidjs/web */。此标准 JSX 指令会选择插件自己的 Solid 编译器;其他 JSX 文件保留 esbuild 现有的渲染器语义。构建器会捆绑渲染器,宿主不提供共享运行时。对于类型检查,设置 jsx: "preserve" 和 jsxImportSource: "@solidjs/web"。
框架无关的视图契约保持不变:
/** @jsxImportSource @solidjs/web */
import { createSignal } from "solid-js";
import { render } from "@solidjs/web";
import type { ControlUiView } from "openclaw/plugin-sdk/control-ui";
const mount: ControlUiView = (container, context) => {
const [label, setLabel] = createSignal(context.props.label ?? "Ready");
const dispose = render(() => <p>{label()}</p>, container);
return {
update(next) {
setLabel(next.props.label ?? "Ready");
},
dispose,
};
};
保持每个容器的子元素由一个渲染器负责,并在视图结束时释放其根节点。Solid 2 会批量处理响应式写入;同步请求权限和变更守卫应保留在其现有所有者中。
包边界¶
构建会输出 JavaScript 入口、可选 CSS,以及用于懒加载的 JavaScript 代码块。内容哈希覆盖完整生成内容,包括其代码块。CSS 仍附着在入口上;加载 JavaScript 代码块不会附加样式表。将其他静态资源嵌入包中;任意文件不属于此构建契约。导入必须可被 esbuild 分析:字面量路径和受支持的 glob 导入可用;未解析的动态导入、间接 require 调用以及 require.resolve 会被拒绝。导入验证会在 tree-shaking 后检查输出的代码块:未使用的依赖加载器可能被移除,但每个保留的浏览器导入都必须解析到已打包的代码块。每个资源限制为 4 MiB,整个插件浏览器构建限制为 8 MiB 和 128 个资源。
具有预构建浏览器包的插件可以省略 package.json.openclaw.controlUi,并在 openclaw.plugin.json.controlUi 中声明已构建的入口和样式。打包和提供会包含该入口目录下的 JavaScript 和 CSS 依赖,包括嵌套代码块和导入的样式表,并遵循相同的字节限制。TypeScript 源代码、source map 和隐藏文件会被排除。将所有浏览器依赖保留在该目录内;遍历限制为八层嵌套目录和 128 个条目,文件和目录均计入。
仅修改浏览器端后,重新构建已安装的插件,并以管理员身份打开 插件 → 高级 → 自定义 UI → 重新加载插件 UI。Gateway 会捕获新的资源修订版本,并通知已连接的浏览器。资源加载或激活失败会在 UI 自定义控件中报告;在可能的情况下,会保留之前正常工作的激活状态。修正插件后重试,或选择“内置”以恢复被替换的视图。
已通告的资源修订版本在其后端插件的生命周期内保持可用,包括旧标签页或保留的工作视图所需的导入。共享缓存最多保存 256 个修订版本和 64 MiB,覆盖所有原生插件。当缓存填满时,重新加载会拒绝新构建并保留已通告的资源。重启 Gateway,然后重试重新加载。
首次激活时,插件页面和仪表板小部件会显示加载状态,直到目录、资源授权和初始化器完成。每个插件独立于仍在加载的其他插件变为可用。断开的视图会等待 Gateway 连接后再检查可用性。小部件会以“重试”操作显示初始化失败。
激活期间创建的注册和替换选择会在初始化成功后一起发布。在此之前释放注册也会取消其待处理的选择。无效选择会拒绝新的激活,而不会停用之前正常工作的 UI。
当贡献在该表面上仍然存在时,已选择的替换会在成功的修订后保留。注销贡献、移除其插件或重新连接会清除该选择;重用 ID 不会恢复它。
自定义元素定义属于浏览器文档。如果插件修改了现有自定义元素类,也请重新加载浏览器标签页,或使用新的带版本标签名。
后端更改使用 插件更新或重新加载 来替换正在运行的插件,而无需重启 Gateway。浏览器重新加载不会替换后端服务,也不会更改已在运行的代理的工具目录。
批准代理构建的工件¶
构建并验证后,生成一个导入归档:
回执包含归档的绝对路径、SHA-256 摘要、插件 ID 和 plugin_activate_artifact 请求。打包会捆绑后端依赖,保持宿主 openclaw 导入为外部依赖,并包含清单和已编译的 UI。归档不包含安装脚本或运行时包依赖。它必须有一个后端入口;需要单独运行时文件的功能需要使用正常的经过审查的包安装流程。打包会拒绝后端对 import.meta、__dirname、__filename 和 require.resolve 的引用,包括捆绑依赖中的引用,因为它们的原始文件和位置不会随工件一起传输。改为在后端构建中导入 JSON 或嵌入其他资源。
后端导入也必须可被 esbuild 分析。直接 CommonJS 导入可用,包括 Node 内置模块和宿主 SDK。未解析的动态导入、间接 require 调用以及带有不透明运行时加载器的预捆绑会被拒绝。提供一个未使用这些加载器编译的入口,以便打包可以捆绑其依赖,或使用正常的包安装流程。
系统代理可以提议使用该路径和摘要进行激活。在批准之前,OpenClaw 会验证并保留确切的归档,并在不执行插件的情况下检查其声明的能力和原生 UI 存在性。已批准的应用通过受管插件安装程序使用这些保留的字节。在审批挂起期间更改源文件不会改变所安装的内容。现有安装策略和能力检查仍然适用。
工件审批不会启用 Custom plugin UI lab。已安装的后端可以在该设置关闭的情况下运行;其原生浏览器 UI 仍保持门控。
待处理导入在一小时后过期。OpenClaw 最多保留八个待处理归档,每个最大 32 MiB,并在准备另一个提案时修剪过期或最旧的导入。过期或被驱逐的审查需要新的提案。已批准的归档会单独保留作为安装源,即使安装程序错误导致最终安装结果不确定也是如此。
工件激活目前要求根配置文件中包含插件配置,且没有根级 $include。对于仅包含 $include: "plugins.json5" 的 plugins 部分(配置目录下的单个文件,无嵌套 include),请从受信任的 shell 使用 openclaw plugins install <archive>。常规安装程序也会拒绝根级、嵌套和外部 include 布局;请在安装前调整这些布局。
工件激活还会拒绝替换支撑 OpenClaw 活动推理路由的插件。停止 OpenClaw,并从受信任的 shell 安装该工件。
由 Gateway 托管的工件激活会等待后端运行时应用。终端或其他没有实时 Gateway 生命周期回调的主机会保存安装并报告写入者的后续操作;该结果不是运行时应用回执。一旦 Gateway 已应用插件,检查 plugins.controlUi.status 以查看当前已连接 Control UI 客户端的激活报告。报告会指明插件修订版本以及 activated 或 failed;它是浏览器激活回执,并非证明已执行所有功能操作。没有已连接的浏览器意味着尚无浏览器激活回执。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw