definePluginEntry

提供商插件、高级工具插件、钩子插件以及任何非消息通道插件的入口辅助函数。属于 插件入口点 参考的一部分。

definePluginEntry¶

导入： openclaw/plugin-sdk/plugin-entry

适用于提供商插件、高级工具插件、钩子插件，以及任何不是消息通道的插件。

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 必须与你的 openclaw.plugin.json 清单匹配。
• 外部会话目录使用 openclaw/plugin-sdk/session-catalog，并通过 api.registerSessionCatalog(...) 注册一个 SessionCatalogProvider。必需的提供程序字段是 id、label、list 和 read；可选钩子是 createListOperation、resolveCreateSession、continueSession、copyToGatewaySession、 checkUpstreamActivity、archive、openTerminal 和 startTerminalSession。 核心拥有 sessions.catalog.* Gateway 方法；提供程序返回主机、会话、 转录和终端计划投影，而不注册 RPC。列表 提供程序应在每个主机完成时调用可选的 onHost(host) 回调；返回的主机数组仍必须作为最终兼容性快照。

可选的 allowPartialResults 标志仅当已连接的调用方明确选择加入，并且在接收没有主机选择或游标的列表的主机进度时，才为 true。为 true 时，提供程序可以返回保留的主机快照，或将仍在加载的主机标记为 pending: true，然后通过 onHost 和 waitUntil 发布其完成快照。待定主机保留现有客户端行和游标；省略的主机将被移除。在已完成的主机上清除 pending。 每次 onHost 发布对于该主机必须是权威的：即使另一个提供程序或可见性投影延迟交付，Gateway 也会在聚合响应中包含每个保留主机的最新发布。最终主机集是权威的：省略的主机是被撤回，而不是从较早的发布中恢复。刷新时保留最后已知的行；不要发布空主机来表示待定工作。 当标志缺失或为 false 时，返回完整的兼容性快照。 定向主机查找和分页保留该完整响应契约。

如果主机可以在 list 返回软失败快照后完成，请在 list 完成前使用可选的 waitUntil(completion: Promise<void>) 钩子注册其有界完成。在该 promise 中包含主机映射和 onHost 调用。使用同一 SDK 入口点的 publishSessionCatalogHost({ onHost, waitUntil }, pendingHost) 来发布主机并注册完整回调链。在 list 完成后注册将被拒绝。未注册完成工作的提供程序在其 list 完成时结束发布。

可选的 signal: AbortSignal 属于目录操作或提供程序生命周期。将其传递给可取消的工作，包括 api.runtime.nodes.invoke(...) 的顶层 signal 字段。请求客户端断开连接仅移除该客户端的订阅；它不会取消共享发现。当目录所有者退役时，Gateway 会移除排队的列表。已开始的提供程序保留其准入槽位，直到其返回的 promise 完成。保留完成不会延长原生调用或软失败响应截止时间，不会授予新权限，也不允许在所有者退役后开始工作。提供程序仍负责在取消后完成的有界工作。

Gateway 一次最多允许 16 个前台目录列表或填充步骤，每个提供程序 ID 有一个活动步骤和最多 32 个排队步骤。排队工作在每个提供程序内保持 FIFO 顺序；当容量可用时，最旧的合格步骤开始。慢速提供程序不能占用所有槽位。同一提供程序的列表按顺序等待，包括来自不同客户端的调用。

将 allowPartialResults、onHost、waitUntil 和 signal 与经过验证的目录查询对象和节点命令负载分开。请求拥有的 sessionEntries 快照和 listNodes 钩子必须在 list 完成时释放，或在下面的可选列表操作关闭时释放。在该边界之前准备迟后主机映射所需的事实。

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 会根据当前个人资料数据解析个人资料身份，包括合并。没有归属的用户条目显示为 User。

由 Gateway 托管的目录可以在每个具有 operator.read 的已认证操作员都可以查看其行时，设置 audience: "gateway-operators"。此类提供者可以实现 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 针对节点本地启动配置对其进行求值；命令处理程序在被调用时仍应验证可用性。