入口点
每个插件都导出一个默认入口对象。SDK 为每种入口形态提供辅助函数:defineToolPlugin、definePluginEntry、defineChannelPluginEntry、defineSetupPluginEntry。
所有插件 API 均为实验性,包括这些入口辅助函数。请固定并测试你的插件支持的 OpenClaw 宿主版本。
各章节迁移位置¶
单页版本中的每个章节现在都位于本页或以下八个子页面之一。单页版本中的锚点仍会解析到此处。
- 工具策略术语
- 沙箱绑定解析
- 包条目
- defineToolPlugin
- definePluginEntry
- 原生提供者工厂
- Computer Use 提供者
- defineChannelPluginEntry
- defineSetupPluginEntry
- 注册模式
插件形态¶
OpenClaw 根据注册行为对已加载插件进行分类:
| 形态 | 描述 |
|---|---|
| plain-capability | 一种能力类型(例如仅提供者) |
| hybrid-capability | 多种能力类型(例如提供者 + 语音) |
| hook-only | 仅钩子,无能力 |
| non-capability | 工具/命令/服务,但无能力 |
使用 openclaw plugins inspect <id> 查看插件的形态。
相关¶
- 插件 SDK 概览 - 注册 API 和子路径参考
- 插件运行时辅助函数 -
api.runtime和createPluginRuntimeStore - 插件设置与配置 - 清单和设置条目加载
- 构建通道插件 - 构建
ChannelPlugin对象 - 构建提供者插件 - 提供者注册和钩子
- 决策模型 -
openclaw/plugin-sdk/decisions和类型化决策提供者契约
Code Mode 执行器运行时¶
使用 openclaw/plugin-sdk/code-mode-executor-runtime 实现 quickjs 执行器选项。Code Mode 有两个可选 ID:node 由核心拥有,quickjs 由执行器插件提供。插件的安装 ID 可以与其执行器 ID 不同。在 contracts.codeModeExecutors 中声明 quickjs,并从插件顶层 code-mode-executor-api 工件导出 codeModeExecutor。宿主仅在选中 QuickJS 时解析此工件;普通插件注册保持轻量。
选中的捆绑执行器即使在插件全局禁用或存在限制性允许列表时,也会保持核心运行时可用性。显式的所有者拒绝和禁用条目仍然适用。外部执行器保留完整的插件策略。
CodeModeExecutor.execute(input, options) 接收来宾源、工具声明、命名空间描述符、资源限制和一个作用域宿主桥接。返回有界的完成或失败,或包含执行器拥有的 CodeModeExecutorContinuation 的等待结果。其 resume 方法转移一次控制权,retainedBytes 报告诊断大小估计,dispose 参与清理,并保持失败的清理可重试。释放已消费的延续没有效果。选中的执行器在配置更改期间仍保持附加到该延续。
SDK 提供通用的来宾控制器、源准备、结果捕获、有界错误文本和 worker 协议类型。执行器拥有其引擎和挂起状态。核心拥有权限、审批、工具分发、结算回执、输出交付、过期和取消。缺失或禁用的执行器会显式失败;宿主绝不会替换为隔离性更低的执行器。
控制器的 __openclaw* 钩子协议是实验性的,并随控制器源码变化。桥接结算仅限宿主:在求值 CODE_MODE_CONTROLLER_SOURCE 之前,在 __openclawHostRequest 旁边注册 __openclawHostTakeBridgeReply 回调(控制器会捕获并移除两者)。要结算,请在宿主侧暂存回复,并无参数调用 __openclawSettleBridge();控制器会从回调中拉取每个回复,直到其返回 undefined。将每个回复作为具有自有数据属性 id、ok 和 json 的对象返回,切勿通过对来宾对象的普通属性赋值来返回。曾调用 __openclawSettleBridge(id, ok, payload) 的执行器必须迁移到此拉取形式。
原生 MCP App 适配器¶
拥有 MCP 连接的智能体框架可以连同 loadMcpToolCatalog 一起实现 acquireMcpAppRuntime。获取操作接收精确的会话身份、已配置的服务器名称、会话工具覆盖、请求者身份以及 assertCurrent 调用守卫。返回基于现有连接的 SessionMcpRuntimeLease;不要创建第二个客户端来启动 App。
对于冷会话,调用可选的惰性 prepareSession 回调。Core 返回一个带版本的会话准备信封(version: 1、purpose: "mcp-app"),其 params 携带所需的已准入主机能力、已准备的凭据、环境和会话事实。在其 run 回调中执行现有的原生会话/线程生命周期,然后借用由此产生的线程拥有的连接。这是一个会话准备操作,而不是模型尝试:它没有 Prompt 或 transcript 工件,并且不得提交模型轮次。热会话不会调用准备器。保留的回调必须尊重源和主机闭包;仅当没有受支持的准备或现有原生绑定时返回 undefined。
当前 Codex app-server 的 mcpServer/resource/read 契约不接受 _meta。因此,原生远程 MCP 资源读取无法请求由元数据选择的表示;OpenClaw 会报告该限制,而不是发送不受支持的 wire 字段。受管理的 MCP 客户端仍会转发资源 _meta,并且 host-file 表示仍可通过本地 host-file owner 获得。
运行时为每个 App 视图保留原生连接和线程订阅,暴露 assertOwnerCurrent 以重新验证其确切的线程/客户端绑定,并保持服务器、工具和连接器边界。callTool 接受可选的 _meta 和 assertCurrent;在任何准备 await 之后、上游 I/O 之前立即运行守卫。主机分别强制会话共享、请求者身份、有效工具策略和审批策略。元数据不会授予权限。
Harness 适配器在 McpToolCatalog 中发布受支持的入口点、结构化设置和提及发现,而不添加模型工具。捆绑的 Codex 适配器通过其现有私有 codex-mcp-projection 门面复用核心元数据和审批提示解析器;这些实现辅助函数不是额外的公共 SDK 导出。
捆绑适配器的私有 createHarnessMcpFormResourceContext 接受 AgentHarnessMcpFormResourceParamsV1(version: 1),并将富预览和上传绑定到确切的源运行时、server、requester 和待处理问题。其工具准备器仅接收工具名称、输入、取消信号和当前权限断言;Gateway 分发选项和上传实现仍对主机保持私有。运行时仅可为能够读取主机本地文件的当前传输暴露 canReadLocalFiles(serverName)。共享表单适配器使用该事实来选择工作区上传;远程传输不会收到不可用的主机 file: URI。原生无轮次工具征询使用源请求作用域,独立于模型轮次征询路由。
MCP 子进程运行时¶
导入: 在打开连接时,使用动态 import() 从 openclaw/plugin-sdk/agent-harness-runtime 导入 mcpStdioRuntime。其冻结对象会惰性加载一个工厂:
const { mcpStdioRuntime } = await import("openclaw/plugin-sdk/agent-harness-runtime");
const { createMcpStdioClient } = await mcpStdioRuntime.load();
使用 createMcpStdioClient(params) 为调用者拥有的 MCP 代理子进程,该子进程前置一个有状态驱动。OpenClaw 拥有子进程及其后代、换行帧和 JSON-RPC 验证、初始化、请求准入、截止时间以及关闭。客户端在工厂返回时开始连接。将此运行时排除在插件注册和不开启 MCP 连接的路径之外。
提供 command、可选的 args 以及精确的 env。子进程不继承其他环境变量。设置 clientInfo(name 和 version)、必需的 protocolVersion、startupTimeoutMs、maxPendingRequests 和 maxFrameBytes。服务器必须恰好返回所请求的协议版本。OpenClaw 保留固定的 32 KiB stderr 尾部,用于意外退出诊断。解码器将 maxFrameBytes 应用于每条消息,包括其终止换行符,因此单个 stdout 块可以包含多条有效消息。它会拒绝过大的帧,而不会保留该块中的任何字节,保留碎片化的 UTF-8,跳过空行,并要求安全的整数响应 ID。
调用者提供 errors.unavailable(message, cause?) 和 errors.protocol(message, cause?),每个都返回一个 Error。第一个对进程、生命周期、准入、截止时间和取消失败进行分类。第二个对格式错误的帧、非超时 JSON-RPC 错误以及握手契约违规进行分类。插件特定的工具结果规范化仍由调用者负责。
返回的客户端暴露三个方法:
isAvailable()同步报告初始化是否完成且连接是否仍可用。request(method, params, { timeoutMs, signal? })等待启动并返回对象结果。已中止的信号或已满的待处理请求限制仅拒绝该调用。准入后,取消或超时会退役整个连接,并使用保留的致命错误拒绝待处理请求。客户端会抑制 SDK 取消通知,因为它改为终止进程。非超时 JSON-RPC 错误响应仅通过errors.protocol拒绝其匹配请求。stop()关闭准入,退役待处理请求,并等待启动结算和拥有进程清理。如果清理不确定,它会通过errors.unavailable以proxy cleanup could not be confirmed拒绝。它从不通过代理套接字停止单独启动的服务。
在 stop() 成功后,可选的只读 cleanupResult 记录强制中继退役:reason: "forced-relay-exit"、signalRequested、观察到的中继 exit 代码和信号、durationMs 以及 escalationAfterMs。当信号投递报告失败但退出随后得到确认时,它会保留 signalError。对于普通清理,它不存在。已关闭的控制/输出/谱系管道和匹配的关闭回执允许升级;待处理的强制请求会在关闭和组退出事实到达时重新考虑。存活锚点会通过其中继被杀死并回收。已确认的锚点组缺失允许直接原生终止无响应的中继。然后必须在原始硬截止时间内确认实际中继退出和服务器组消失。不确定的清理会在错误的 cause 链中保留缺失的关闭事实和计时或信号投递细节。
Malformed frames, incompatible initialization, write failures, and unexpected process exit also retire the whole connection. The first fatal error is retained. Create a new client to reconnect. Timeout classification follows the SDK error code, so a timeout-coded server error also retires the connection.
工作区访问¶
使用 openclaw/plugin-sdk/agent-workspace-runtime 声明、注册并获取
AgentWorkspaceAccess,而无需加载代理执行运行时。在注册期间声明一个
已配置的远程工作区,以便调用方无法在其服务启动前回退到
本地文件。就绪时注册其桥接,并在服务停止时释放
它。调用方保留其现有文档授权。
桥接的可选 createFileExclusive 操作仅在其路径不存在时发布完整文件,
并返回 "created" 或 "exists"。它必须使用
原子独占创建操作,绝不能先单独检查存在性,
再执行普通写入。工作区访问会转发此能力,并应用与其他桥接操作相同的
服务生命周期检查。省略该操作的提供者
仍支持其现有读取和写入,但 agents.files.set 配合
expectedMissing: true 会明确拒绝创建且不修改文件。请更新
提供者,或在其主机上创建该文件并在编辑前重新加载它。
createWorkspaceBootstrapFilePolicy({ workspaceDir, config }) 允许适配器
将此桥接限制为原生引导文档和已配置的
bootstrap-extra-files 模式。使用 canList 检查目录元数据,
使用 canRead 检查文件字节,使用 canWrite 检查四个所有者可编辑文档。
目录访问不会授予读取其他文件的权限。底层桥接
仍会强制文件系统包含关系,并返回读取的规范来源。
未启动或已停止的工作区访问会抛出
WorkspaceAccessUnavailableError。使用 isWorkspaceAccessUnavailableError(error)
通过包装错误或多个 SDK 实例识别此状态。
错误码为 WORKSPACE_ACCESS_UNAVAILABLE;不要匹配消息文本。
可选的 memoryFiles 提供者将工作区 Memory 文件保留在主机上,同时
原生索引、嵌入提供者和原始会话保留在 Gateway 上。它
提供发现、文件检查、读取和变更通知。索引
和 memory_get 都使用它;索引发布会重新检查主机文件。随读取
返回的规范来源提供来源信息,而不会解析过期的 Gateway
副本。停止工作区绑定会撤销保留的文件访问和订阅。
Memory 文件工作器支持 --files <workspace>,用于原生文件
操作,而无需打开主机索引或接收嵌入凭据。
提供者可以通过其现有子进程传输调用它。
createWorkspaceMemoryFileClient 映射 Gateway/主机路径,并为此工作器保留原生
错误。提供 request 用于一次 JSON 交换,提供 subscribe
用于 --watch-files JSON 行流,以及绑定的中止信号。
这两个回调都不依赖 Codex;提供者拥有传输和授权。
memoryFiles.maintenance 将现有的 dreaming、promotion、corpus 和 forget
文件操作路由到主机。复合写入复用原生原子发布和
冲突处理;维护决策、锁和 SQLite 状态保留在 Gateway 上。
不支持维护的远程绑定会失败,而不是使用 Gateway 文件。
文件工作器实现这些操作和原生变更通知。
配对节点文件传输适配器通过现有
服务拥有的节点通道和节点文件策略连接这些操作。
任务时 Skill 准备使用远程发现。通道原生菜单使用 Gateway 拥有的 Skills,而无需等待 Harness;远程菜单支持 跟踪在 Enterprise #241。
可选的 skillResources 提供者将 Skill 读取与 Agent
文档访问分开处理。其 readInstructions 为
Code Mode 读取所选指令文件;readSkillFiles 提供用于工作器交付的捆绑包。Gateway 拥有的
bundled、plugin、Library、Workshop 和用户级来源保留其 Gateway 路径。
工作区拥有的来源使用远程提供者。Gateway 保留来源优先级,
并使用现有资源交付机制为工作器提供服务。发现分配文件所有权;提供者不能
通过返回 source 或 path 元数据来请求 Gateway 本地读取。
停止绑定会撤销保留的主机读取器。
Skills 工作器还运行 install 和 ClawHub 操作。安装/移除使用 已认证适配器的双工通道,以便在原生文件系统操作之前运行 Gateway 策略和变更检查。 适配器允许 source roots 和 上传;工作器使用其主机账户的权限。
对于远程工作区,依赖项安装使用 installSkillDependencies。
Gateway 选择配方并运行安装策略;主机通过工作器的 installDependencies 操作运行现有
安装程序。请求包含
Skill 键、配方、安装首选项和超时。配方选择使用
主机的操作系统和二进制文件。缺少主机支持会失败,而不会在 Gateway 上安装。
检查文件的 Gateway 策略从现有 Skill
资源读取器接收临时树;Gateway 拥有的来源保持本地。资源捆绑包限制适用。
readWorkspaceSkillResources 惰性复用有界的原生捆绑包读取器。
文件传输适配器可以在返回捆绑包之前检查每个文件请求和已验证的规范路径;仅允许 Skill 目录本身并不会允许其所有子项。
主机可以提供 watchSkills(request, onChange, signal),在已允许的 Skill 来源变更时通知现有
快照缓存。保持订阅存活
直到中止,并在初始扫描和后续编辑后发送 change。如果
文件监视停止,则发送 unavailable:随后准备会在每次调用时刷新,
而不会重新打开订阅。恢复后,仅当
所有已订阅来源都经过验证的监视覆盖,并且中断期间所做的
编辑已协调一致时,才发送 available。这在不增加内容
修订的情况下恢复快照复用。仅发送 change 永远不会清除 unavailable 状态。仅发送
change 和 unavailable 的主机在中断后保留准备回退。没有
watchSkills 的主机始终使用该回退。skills.load.watch: false
禁用该订阅和此回退。
Gateway 在相同的快照失效生命周期下本地监视 Workshop。
The paired-node file-transfer adapter also connects Skill discovery, resource reads,
watching and dependency installation through workspace.skills. Its native worker
launcher uses resolveWorkspaceWorkerArgv("memory" | "skills") from
agent-workspace-runtime, then appends the operation arguments. Use the same
OpenClaw version on Gateway and node.
This adapter does not implement remote Skill source install/update/remove or ClawHub lifecycle operations; those remain tracked in Enterprise #242.
Agent workspace context¶
Native harnesses use prepareAgentWorkspaceContext from
openclaw/plugin-sdk/agent-harness-runtime to prepare bounded workspace context.
The shared owner runs the existing bootstrap hooks, privacy filters, and character
budgets. scope: "full" separates the agent instruction snapshot, persona,
remaining project context, and tool-routed memory references. It prepares recall
guidance through the active memory plugin without inventing fallback policy.
scope: "instructions-only" selects the configured workspace's root AGENTS.md
before budgeting and does not prepare persona or memory guidance.
Provider adapters own native project-document discovery, available memory tools,
path projection, context order, instruction carriers, and session/turn lifetimes.
Optional projectPath projects file paths after budgeting without changing their
contents or personal-user provenance. It describes existing execution placement;
it does not transfer or mount files.
Full-context preparation preserves Codex's existing selection timing: projecting
the root instruction path away from workspaceDir produces an empty root snapshot.
Callers preparing source-workspace instructions should omit projectPath.
buildAgentWorkspaceInstructionSnapshot(contextFiles, workspaceDir) selects and
renders that root instruction document from already-bounded context, including
hook-free child preparation. An empty instruction string is a successful capture;
preparation failures must remain distinguishable and retryable.
Agents API can consume the instruction-only snapshot at session creation. Its current client does not implement per-turn developer instructions, persona and personal-overlay refresh, turn-scoped project or memory guidance, native forks, or Gateway-to-hosted-workspace path projection. Those remain MVP integration gaps; shared preparation does not enable those operations.
Tool failure diagnostics¶
Agent harnesses can import readToolOperatorHint(error) from
openclaw/plugin-sdk/agent-harness-runtime to read optional operator advice
attached to a tool failure. Include it only in the operator log. Keep it out of
model responses, tool-result callbacks, and serialized transcripts, and preserve
the original error message. An unannotated or immutable error needs no substitute
hint; the reader returns undefined when no advice is available.
ACP harness turns¶
Pass optional currentInboundContext to resolveAgentHarnessBeforePromptBuildResult from
openclaw/plugin-sdk/agent-harness-runtime. It combines the prompt with its inbound context
and channel-provided joiner before prompt hooks run. Frame ordinary chat
with prose section labels so a leading file path cannot become a native slash command. Keep
one admitted user turn while assigning each provider attempt its own request and reply identity.
Host requestApproval normalizes the title and description within the shared display bounds
and preserves full action evidence in detail. Its response acknowledges the request with
an ID. Call waitForApproval with
that ID to obtain the decision, then recheck the turn's signal and authority before allowing
the native operation.
Use the plugin approval timeout independently of the agent-run timeout. Authenticated
Control UI reviewers can inspect detail, while channel messages retain
the bounded description. Oversized detail is rejected by the existing request schema.
Stateful CLI commands¶
openclaw/plugin-sdk/cli-state-owner exports runWithLocalStateOwner. Supply the
Gateway method, serializable params, a diagnostic target, and runLocal.
Open databases and load mutation-capable runtime state only inside runLocal;
its scope supplies the admitted config, environment, abort signal, and current
owner assertion. Close plugin-owned stores before the callback returns.
The helper routes to the local Gateway with its expected owner ID, or retains
exclusive offline ownership through resource settlement. It never replays an
uncertain Gateway mutation locally. Use onForeignOwner: "refuse" for commands
that require an offline Gateway. Optional scopes preserves the command's
existing authorization contract; the default is operator.admin.
Gateway handlers can use captureLocalStateMutationGuard from
openclaw/plugin-sdk/gateway-runtime to bind the expected owner and current
request authority, then pass the returned assertion to their existing writer
admission and privileged-effect boundaries. isImplicitLocalGatewayTargetFromCli
from that same entrypoint preserves explicit and configured remote CLI targets.
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw