用于 provider 插件、高级工具插件、钩子插件以及任何非消息通道插件的入口辅助函数。属于 插件入口点 参考文档。¶
definePluginEntry¶
导入: openclaw/plugin-sdk/plugin-entry
用于 provider 插件、高级工具插件、钩子插件以及任何非消息通道插件。
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
export default definePluginEntry({
id: "my-plugin",
name: "My Plugin",
description: "Short summary",
register(api) {
api.registerProvider({/* ... */});
api.registerTool({/* ... */});
},
});
| 字段 | 类型 | 必填 | 默认值 |
|---|---|---|---|
id |
string |
是 | - |
name |
string |
是 | - |
description |
string |
是 | - |
kind |
string(已弃用,见下文) |
否 | - |
configSchema |
OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema |
否 | 空对象 schema |
reload |
OpenClawPluginReloadRegistration |
否 | - |
nodeHostCommands |
OpenClawPluginNodeHostCommand[] |
否 | - |
securityAuditCollectors |
OpenClawPluginSecurityAuditCollector[] |
否 | - |
register |
(api: OpenClawPluginApi) => void |
是 | - |
id必须与你的openclaw.plugin.json清单相匹配。- 外部会话目录使用
openclaw/plugin-sdk/session-catalog,并通过api.registerSessionCatalog(...)注册一个SessionCatalogProvider。 必需的 provider 字段为id、label、list和read;可选钩子包括createListOperation、resolveCreateSession、continueSession、copyToGatewaySession、checkUpstreamActivity、archive、openTerminal和startTerminalSession。 Core 拥有sessions.catalog.*Gateway 方法;provider 返回 host、会话、 transcript 和 terminal-plan 投影,而无需注册 RPC。list provider 应在每个 host 稳定时调用可选的onHost(host)回调; 返回的 host 数组仍然是最终兼容性快照所必需的。
可选的 allowPartialResults 标志仅在连接的调用方明确选择启用时才为 true,
此时调用方正在接收某个列表的 host 进度,且该列表没有 host 选择或游标。
当为 true 时,provider 可以返回保留的 host 快照,或将仍在加载的
host 标记为 pending: true,然后通过 onHost 和 waitUntil
发布其完成的快照。Pending 状态的 host 会保留现有的客户端行和游标;
被省略的 host 会被移除。在已完成的 host 上清除 pending。
每次 onHost 发布对该 host 都必须是权威性的:Gateway
会在聚合响应中包含每个保留 host 的最新发布,即使另一个 provider
或可见性投影延迟了投递。最终的 host 集合是权威性的:
被省略的 host 会被撤销,而不会从较早的发布中恢复。
刷新时请保留最后已知的行;不要发布空的 host 来表示待处理的工作。
当该标志不存在或为 false 时,返回完整的兼容性快照。
定向的 host 查询和分页保留这种完整响应契约。
如果某个 host 可能在 list 返回 fail-soft 快照之后才完成,
请在 list 稳定之前通过可选的 waitUntil(completion: Promise<void>)
钩子注册其有界完成。在该 promise 中包含 host 映射和 onHost 调用。
请使用来自同一 SDK 入口点的 publishSessionCatalogHost({ onHost, waitUntil }, pendingHost)
发布该 host,并注册完整的回调链。在 list 稳定之后的注册会被拒绝。
未注册完成工作的 provider 会在其 list 稳定时完成发布。
可选的 signal: AbortSignal 属于目录操作或 provider 的生命周期。
请将其传递给可取消的工作,包括 api.runtime.nodes.invoke(...)
的顶层 signal 字段。请求方客户端断开连接只会移除该客户端的订阅;
它不会取消共享的发现。Gateway 会在其目录所有者退出时移除排队的列表。
已启动的 provider 会保留其准入槽位,直到其返回的 promise 稳定。
保留完成并不会延长原生调用或 fail-soft 响应的截止时间,不会授予新的权限,
也不会允许在所有者退出后启动工作。Provider 仍需对取消后稳定的有界工作负责。
Gateway 一次最多接纳 16 个前台目录列表或填充步骤, 每个 provider ID 有一个活动步骤和最多 32 个排队步骤。 排队的工作在每个 provider 内保持 FIFO 顺序;当容量可用时, 最旧的符合条件的步骤开始执行。慢速 provider 不能占用所有槽位。 同一 provider 的列表按顺序等待,包括来自不同客户端的调用。
将 allowPartialResults、onHost、waitUntil 和 signal
与已验证的目录查询对象和节点命令载荷分开。请求拥有的 sessionEntries 快照
和 listNodes 钩子必须在 list 稳定时,或在下方的可选列表操作关闭时释放。
请在该边界之前准备好延迟 host 映射所需的事实。
sessionEntries.revision,当存在时,是用于不可变的本地条目事实的不透明令牌,包括配置和选择范围。提供者可以基于该令牌弱缓存派生元数据,连同其自身的查询和配置输入。新令牌会使这些事实失效;缺失令牌需要重新读取条目。列表返回后不要保留快照或条目对象,也不要将该令牌用作当前授权或原生主机数据的修订版本。
具有多步填充的提供者可以实现可选的 SessionCatalogProvider.createListOperation(params) 钩子。其同步工厂返回 { next, close },且不会启动源工作。Gateway 在首次准入内调用一次工厂,并串行调用 next():
{ done: false }表示该步骤已结算,且只剩下惰性的继续状态。同一请求会重新加入现有提供者 FIFO,位于等待的调用者之后;不会向客户端发送部分结果。{ done: true, hosts }提供list将返回的完整填充结果。没有此钩子的提供者继续只使用一次list。
sessions.catalog.list 在每一步之前以及其结算之后,都会检查其原始 Gateway 和目录注册所有者。过期的所有者会结束分步列表,并关闭其操作,而不会启动进一步的源工作。
每个 next() 返回一个 Promise,并且必须在结算前等待其启动的所有前台工作完成。交接不能留下源页面、分类或必需投影仍在运行。保留源现有的限制、共享生产者所有权、顺序和失败行为。一个逻辑请求在每一步中保持相同的 sessionEntries、listNodes、onHost、waitUntil 和 signal 生命周期。在逻辑列表结算之前注册发布工作,如上所述使用 publishSessionCatalogHost;异步发布回调仍然是单独计账的工作,而不是前台步骤。
Gateway 在完成、失败或排队期间取消后,会调用一次同步 close()。活动取消仍会等待实际的 next() Promise 后再关闭。首先将操作标记为已关闭,拒绝任何未完成的逻辑主机结果,并仅释放操作拥有的引用。关闭不会启动任何源工作或异步清理,并且不得取消共享生产者。后续的 next() 调用必须在 I/O 之前失败;重复关闭是惰性的。原生发现同意会在工厂构造之前以及每一步之前和之后进行检查。初始禁用会在不构造源的情况下返回空结果;后续撤销会拒绝逻辑列表。
转录项可以包含一个 sender,具有限定的 SessionParticipant 身份以及可选的显示标签或头像。仅提供源已知的归属;查看者和会话采用者不是转录作者。Core 会根据当前个人资料数据解析个人资料身份,包括合并。没有归属的用户项显示为 用户。
Gateway 托管的目录可以设置 audience: "gateway-operators",当每个具有 operator.read 的已认证操作员都可以查看其行时。这样的提供者可以实现 copyToGatewaySession(...),为独立的 Gateway 拥有的延续返回有界的显示名称和可选的首选模型。Core 拥有操作员和代理授权、会话创建、模型就绪和策略检查、回滚以及不受信任内容包装。提供者通过 read(...) 提供转录文本;它不得写入目标会话。
由另一个 Gateway 发布的会话的只读目录可以设置 audience: "session-viewers"。查看者需要 operator.read;配置的角色还必须允许查看他人的会话(sessions.others: "view"、"suggest" 或 "write")。源发布和接收者角色会独立检查。Core 会在异步读取后重新检查接收者的访问权限;提供者在返回其转录之前必须重新检查源会话是否仍保持发布状态。提供者归属仍然是显示元数据,并且不会将源会话纳入接收 Gateway。
原生源标题是展示信息,而不是唯一的会话标签。采用新源时,将其标题作为 displayName 传递给拥有者授权的 会话创建者;主机将该快照约束并随新行存储。保持源身份与命名独立,在重用或恢复时保留现有标签和快照,并且不要重新同步原生重命名。
提供者可以使用 shareRoute 声明一个可读转录路由。这是一个封闭契约,而不是自由形式的路由提示:
const shareRoute = {
kind: "thread-id-prefix",
routeSegment: "my-sessions",
hostId: "gateway",
identifierAlphabet: "lowercase-hex",
fullLength: 32,
minPrefixLength: 12,
lookup: "catalog-list-search-by-thread-id-prefix",
ambiguity: "multiple-results-or-next-cursor",
} as const;
提供者必须在声明的主机上返回恰好 32 个字符的小写十六进制 threadId 值。当 list(...) 接收到一个有效的 12-32 个字符前缀的 search 值时,该主机必须只返回 threadId 以前缀开头的行。返回所有匹配项,直到达到请求的限制,并在可能还有更多时设置 nextCursor。Control UI 只解析没有下一页的单个结果;多行或 nextCursor 明确表示歧义,并且从不选择第一行。
命名共享链接使用 /<routeSegment>/<title-slug>-<id-prefix>,具有与普通会话链接相同的有界 slug。在目录行的 name 中返回标题;Control UI 使用它来刷新装饰性 slug。只有 id 后缀选择转录。裸 id 和过期标题链接仍然有效,并且标题从不解析歧义 id。
routeSegment 不得使用内置 Control UI 路由或别名的第一段,并且必须在活动会话目录中唯一。无效、不受支持、保留或多重拥有的描述符会失败关闭;目录会话仍然可以通过通用 /chat/<agent>?catalog=...&host=...&thread=... URL 访问。共享会话 URL 契约拥有内置保留决策:其共享路径构建器对保留段返回 null,并且 Gateway 在发布目录之前会省略保留描述符。保留一个插件拥有的描述符常量,并将其重用于注册、前缀查找和 URL 生成,以便这些义务不会漂移。
基于 CLI 的目录,如果暴露相同的本地加配对节点的结构,可以使用
createSessionCatalogFamily(...)。家族组合器拥有规范游标
验证、节点负载验证、主机投影、已采用会话
投影、按主机发布、读取路由、每个已解析 agent 和 source 的单飞续传,以及终端计划路由。不同 agent
不共享进行中的采用结果;已采用 source 的查找键仍为主机/线程对。提供方必须提供其本地存储读取、
标识符和命令、错误文本、能力投影、续传可用性和持久化操作、上游活动检查,以及终端
可执行文件/参数。没有默认的续传、能力变更或终端权限。使用 createSessionCatalogNodeHostBindings(...) 来
从这些显式提供方输入构建匹配的 list/read/terminal 节点命令和仅限终端的调用策略。
同一入口导出 sessionCatalogPaging,它分组了有界的
list/read 参数解析器、规范 base64url 游标编解码器,以及有界
UTF-8 转录分页器。提供方将各自的标识符模式和验证消息传入 parseReadParams(...) 和 parseListParams(...)。
resolveCreateSession({ agentId }) 必须在 OpenClaw 通告 model-chat 创建之前返回由配置派生的 model/runtime
目标。原生终端就绪状态独立于此目标。
使用
api.runtime.agent.resolveSessionCatalogCreateTarget(...)
来应用主机的 runtime 和 model-allowlist 策略,而不是重复实现它。
startTerminalSession 独立于 model-chat 创建通告 capabilities.startTerminal: true。
从普通目录 list 回调中,为每个符合条件的主机返回 canStartTerminal: true,包括空主机。在渐进式 onHost 帧和最终结果中发布同一标志;当就绪状态变化时显式返回 false。转录列表失败不会撤销其他方面可用的 CLI。节点主机要求其精确的已连接、可调用 fresh-start 命令;仅启动节点不得调用缺失的 list 命令。保留本地 source ID 和进程主目录隔离。随附的 createSession.startTerminal 字段仍是 model-chat 元数据;新的终端调用方使用独立能力和原始目录主机。
startTerminalSession({ agentId, cwd, initialMessage?, nodeId?, hostId? }) 创建新的 CLI 终端计划。返回本地计划(kind: "local"、argv 和精确的 cwd,以及可选的 env、pathEnv 和 title)或配对节点计划(kind: "node"、nodeId、command、paramsJSON 和精确的 cwd)。sessions.catalog.startTerminal RPC 需要 operator.admin 以及 gateway.cliAgents.enabled 和 gateway.terminal.enabled。调用方提供 cwd;Gateway 要求一个已存在的绝对本地目录,拒绝已更改的计划 cwd 或主机,并在打开 PTY 之前应用常规的 agent-sandbox、node-pairing、deadline 和 connection-ownership 检查。hostId 携带所选本地 source;nodeId 标识一个节点。初始提示限制为 16,384 个字符,cwd 限制为 4,096 个字符(在节点上为 4,096 个 UTF-8 字节)。新的节点命令使用来自 node-host 的 decodeNodePtyStartParams 和 runNodePtyCommand({ ..., requiredCwd: true }, io) 来要求一个已存在的绝对节点目录,包括在生成前立即重新检查。Resume 保留其现有的 cwd 回退契约。节点负载不得接受可执行文件、argv、环境、凭据或 Gateway agent 作为原生账户选择。
直接运行交互式 CLI 的配对节点计划,如果其接受双引号 POSIX 路径以及简单双引号 Windows 驱动器或 UNC 路径作为文件引用,可以声明 uploadPathStyle: "native"。原生 Windows 格式保留撇号和反斜杠,并拒绝双引号和控制字符。通过 createSessionCatalogFamily(...) 中的 terminal.uploadPathStyle 声明相同契约。对于 shell 或其他输入语法,保持该字段缺失。Gateway 仅对通告 terminal-upload-path-style 的客户端在 terminal.upload 结果中包含它。没有上传样式时,客户端使用终端的 shell 引号规则。
终端管理器在 attach 和重连期间保留原生标题和实际 connection/agent 所有者。客户端通告 terminal-session-metadata 以接收 attach 标题/所有者和列表标题;旧的 closed 响应形状保持不变。
kind已弃用:请改为在openclaw.plugin.json清单的kind字段中声明一个独占槽位("memory"或"context-engine")。运行时入口kind仅作为旧插件的兼容性回退保留。configSchema可以是函数,用于惰性求值。OpenClaw 在首次访问时解析并记忆化 schema,因此昂贵的 schema 构建器只运行一次。nodeHostCommands描述符可以定义isAvailable({ config, env })。返回false会从无头节点的 Gateway 声明中省略该命令及其能力。OpenClaw 针对节点本地启动配置对其进行求值;命令处理程序在被调用时仍应验证可用性。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw