插件 SDK 概览

插件 SDK 是插件与核心之间的类型化契约。本页是关于要导入什么以及可以注册什么的参考。

导入约定

始终从具体子路径导入：

每个子路径都是小型、自包含的模块。这样可以保持启动速度，并防止循环依赖问题。对于渠道专用的入口/构建辅助工具，优先使用 openclaw/plugin-sdk/channel-core；将 openclaw/plugin-sdk/core 留给更宽泛的总括表面和共享辅助工具，例如 buildChannelConfigSchema。

对于渠道配置，请通过 openclaw.plugin.json#channelConfigs 发布渠道自有的 JSON Schema。plugin-sdk/channel-config-schema 子路径用于共享 schema 原语和通用构建器。OpenClaw 的内置插件使用 plugin-sdk/bundled-channel-config-schema 来保留内置渠道 schema。已弃用的兼容性导出仍保留在 plugin-sdk/channel-config-schema-legacy；这两个内置 schema 子路径都不是新插件应采用的模式。

子路径参考

插件 SDK 以一组按领域分组的窄子路径公开（插件入口、渠道、提供商、认证、运行时、能力、记忆，以及保留的内置插件辅助工具）。完整目录按组列出并带链接，见插件 SDK 子路径。

编译器入口点清单位于 scripts/lib/plugin-sdk-entrypoints.json；包导出是在扣除 scripts/lib/plugin-sdk-private-local-only-subpaths.json 中列出的仓库本地测试/内部子路径后，从公共子集生成的。运行 pnpm plugin-sdk:surface 来审计公共导出数量。足够旧且未被内置扩展生产代码使用的已弃用公共子路径在 scripts/lib/plugin-sdk-deprecated-public-subpaths.json 中跟踪；宽泛的已弃用重导出 barrel 在 scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json 中跟踪。

注册 API

register(api) 回调会收到一个包含以下方法的 OpenClawPluginApi 对象：

能力注册

通过 api.registerEmbeddingProvider(...) 注册的嵌入提供商还必须列在插件清单的 contracts.embeddingProviders 中。这是用于可复用向量生成的通用嵌入表面。记忆搜索可以使用这个通用提供商表面。较旧的 api.registerMemoryEmbeddingProvider(...) 和 contracts.memoryEmbeddingProviders 接口是已弃用的兼容性保留，供现有记忆专用提供商迁移期间使用。

仍暴露运行时 batchEmbed(...) 的记忆专用提供商会继续使用现有的按文件批处理契约，除非它们的运行时显式设置 sourceWideBatchEmbed: true。这个选择加入项允许记忆宿主在一次 batchEmbed(...) 调用中提交来自多个脏记忆文件和已启用来源的块，直到达到宿主批处理限制。上传 JSONL 请求文件的批处理适配器还必须在达到上传大小上限以及请求数量上限前拆分提供商任务。提供商必须按与 batch.chunks 相同的顺序为每个输入块返回一个嵌入；当提供商期望文件本地批次或无法在更大的跨来源任务中保持输入顺序时，请省略该标志。

工具和命令

对于工具名称固定的简单纯工具插件，请使用 defineToolPlugin。对于混合插件或完全动态的工具注册，请直接使用 api.registerTool(...)。

当智能体需要一条由命令拥有的简短路由提示时，插件命令可以设置 agentPromptGuidance。让这段文本只描述命令本身；不要向核心提示构建器添加提供商或插件专用策略。

指导条目可以是旧式字符串，适用于每个提示表面；也可以是结构化条目：

agentPromptGuidance: [  "Global command hint.",  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },];

结构化的 surfaces 可以包含 openclaw_main、codex_app_server、cli_backend、acp_backend 或 subagent。pi_main 仍是 openclaw_main 的已弃用别名。对于有意应用到所有表面的指导，请省略 surfaces。不要传入空的 surfaces 数组；它会被拒绝，以免意外丢失作用域后变成全局提示文本。

原生 Codex app-server 开发者指令比其他提示表面更严格：只有显式限定到 codex_app_server 的指导才会被提升到该更高优先级通道。为兼容性，旧式字符串指导和未限定作用域的结构化指导仍可用于非 Codex 提示表面。

基础设施

Telegram 交互式处理程序可以返回 { submitText }，在处理程序成功后通过 Telegram 的常规入站智能体路径路由文本。当入站策略跳过文本或处理失败时，OpenClaw 会保留回调按钮，因此用户可以在阻塞条件变化后重试。此结果字段是 Telegram 专用的；其他渠道保留各自的交互式结果契约。

工作流插件的主机钩子

主机钩子是供需要参与主机生命周期的插件使用的 SDK 接缝，而不仅仅是添加一个提供商、渠道或工具。它们是通用契约；Plan Mode 可以使用它们，审批工作流、工作区策略门禁、后台监视器、设置向导和 UI 配套插件也可以使用。

surface: "tab" 描述符会向 Control UI 添加一个侧边栏标签页。活动插件的标签页描述符会在 Gateway 网关 hello（controlUiTabs）中通告给仪表板客户端，因此该标签页仅在插件启用时出现。内置插件可以为其标签页提供一等仪表板视图；其他插件可以将 path 设置为插件 HTTP 路由（参见 api.registerHttpRoute(...)），由仪表板在沙箱隔离框架中渲染。icon 是仪表板图标名称提示，group 选择侧边栏区段（control 或 agent），order 在插件标签页之间排序，requiredScopes 会对缺少这些操作员权限范围的连接隐藏标签页：

api.session.controls.registerControlUiDescriptor({  surface: "tab",  id: "logbook",  label: "Logbook",  description: "Your day as a timeline, built from screen snapshots.",  icon: "sun",  group: "control",  requiredScopes: ["operator.write"],});

新插件代码使用分组命名空间：

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

等价的扁平方法仍作为面向现有插件的已弃用兼容别名提供。不要添加直接调用 api.registerSessionExtension、api.enqueueNextTurnInjection、api.registerControlUiDescriptor、api.registerRuntimeLifecycle、api.registerAgentEventSubscription、api.emitAgentEvent、api.setRunContext、api.getRunContext、api.clearRunContext、api.registerSessionSchedulerJob、api.registerSessionAction、api.sendSessionAttachment、api.scheduleSessionTurn 或 api.unscheduleSessionTurnsByTag 的新插件代码。

scheduleSessionTurn(...) 是基于 Gateway 网关 Cron 调度器的会话作用域便捷方法。Cron 拥有计时，并在轮次运行时创建后台任务记录；插件 SDK 只约束目标会话、插件拥有的命名和清理。当工作本身需要持久的多步骤 Task Flow 状态时，请在定时轮次内部使用 api.runtime.tasks.managedFlows。

这些契约有意拆分权限：

• 外部插件可以拥有会话扩展、UI 描述符、命令、工具元数据、下一轮次注入和常规钩子。
• 可信工具策略会在普通 before_tool_call 钩子之前运行，并受到主机信任。内置策略先运行；已安装插件策略需要显式启用，并且其本地 ID 必须出现在 contracts.trustedToolPolicies 中，然后按插件加载顺序运行。策略 ID 的作用域限定在注册它的插件内。
• 保留命令所有权仅限内置插件。外部插件应使用自己的命令名称或别名。
• allowPromptInjection=false 会禁用会修改提示的钩子，包括 agent_turn_prepare、before_prompt_build、heartbeat_prompt_contribution、旧版 before_agent_start 中的提示字段，以及 enqueueNextTurnInjection。

非 Plan 使用方示例：

Gateway 网关设备发现注册

api.registerGatewayDiscoveryService(...) 允许插件在本地设备发现传输协议（例如 mDNS/Bonjour）上通告活动 Gateway 网关。当启用本地设备发现时，OpenClaw 会在 Gateway 网关启动期间调用该服务，传入当前 Gateway 网关端口和非机密 TXT 提示数据，并在 Gateway 网关关闭期间调用返回的 stop 处理程序。

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

Gateway 网关设备发现插件不得将通告的 TXT 值视为机密或身份认证。设备发现只是路由提示；Gateway 网关认证和 TLS 固定仍然拥有信任。

CLI 注册元数据

api.registerCli(registrar, opts?) 接受两类命令元数据：

• commands：注册器拥有的显式命令名称
• descriptors：解析时命令描述符，用于 CLI 帮助、路由和惰性插件 CLI 注册
• parentPath：嵌套命令组的可选父命令路径，例如 ["nodes"]

对于配对节点功能，优先使用 api.registerNodeCliFeature(registrar, opts?)。它是 api.registerCli(..., { parentPath: ["nodes"] }) 的一个小包装，并让诸如 openclaw nodes canvas 之类的命令成为显式的插件拥有节点功能。

如果你希望插件命令在常规根 CLI 路径中保持惰性加载，请提供覆盖该注册器暴露的每个顶级命令根的 descriptors。

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Manage Matrix accounts, verification, devices, and profile state",        hasSubcommands: true,      },    ],  },);

嵌套命令接收已解析的父命令作为 program：

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Capture or render canvas content from a paired node",        hasSubcommands: true,      },    ],  },);

仅在不需要延迟注册根 CLI 时，才单独使用 commands。 该预加载兼容路径仍受支持，但它不会安装由描述符支持、用于解析时延迟加载的占位符。

CLI 后端注册

api.registerCliBackend(...) 让插件拥有本地 AI CLI 后端的默认配置，例如 claude-cli 或 my-cli。

• 后端 id 会成为模型引用中的提供商前缀，例如 my-cli/gpt-5。
• 后端 config 使用与 agents.defaults.cliBackends.<id> 相同的结构。
• 用户配置仍然优先。OpenClaw 会先将 agents.defaults.cliBackends.<id> 合并到插件默认值之上，然后再运行 CLI。
• 当后端需要在合并后执行兼容性重写时，使用 normalizeConfig（例如规范化旧的标志结构）。
• 对于属于 CLI 方言、按请求作用域改写 argv 的场景，使用 resolveExecutionArgs，例如将 OpenClaw 思考级别映射到原生 effort 标志。该钩子会接收 ctx.executionMode；使用 "side-question" 为临时 /btw 调用添加后端原生隔离标志。如果这些标志能可靠地为原本始终开启的 CLI 禁用原生工具，也请声明 sideQuestionToolMode: "disabled"。

有关端到端编写指南，请参阅 CLI 后端插件。

独占槽位

已弃用的记忆嵌入适配器

• registerMemoryCapability 是首选的独占记忆插件 API。
• registerMemoryCapability 也可以暴露 publicArtifacts.listArtifacts(...)，这样配套插件可以通过 openclaw/plugin-sdk/memory-host-core 使用导出的记忆工件，而不是访问某个特定记忆插件的私有布局。
• registerMemoryPromptSection、registerMemoryFlushPlan 和 registerMemoryRuntime 是兼容旧版的独占记忆插件 API。
• MemoryFlushPlan.model 可以将刷新轮次固定到精确的 provider/model 引用，例如 ollama/qwen3:8b，而不继承活动的回退链。
• registerMemoryEmbeddingProvider 已弃用。新的嵌入提供商应使用 api.registerEmbeddingProvider(...) 和 contracts.embeddingProviders。
• 在迁移窗口期间，现有的记忆专用提供商会继续工作，但插件检查会将其报告为非内置插件的兼容性债务。

事件和生命周期

参阅 插件钩子，了解示例、常见钩子名称和守卫语义。

钩子决策语义

before_install 是插件运行时生命周期钩子，不是操作员安装策略表面。当允许/阻止决策必须覆盖 CLI 和由 Gateway 网关支持的安装或更新路径时，请使用 security.installPolicy。

• before_tool_call：返回 { block: true } 是终止性决策。一旦任何处理程序设置它，优先级较低的处理程序会被跳过。
• before_tool_call：返回 { block: false } 会被视为没有决策（与省略 block 相同），而不是覆盖。
• before_install：返回 { block: true } 是终止性决策。一旦任何处理程序设置它，优先级较低的处理程序会被跳过。
• before_install：返回 { block: false } 会被视为没有决策（与省略 block 相同），而不是覆盖。
• reply_dispatch：返回 { handled: true, ... } 是终止性决策。一旦任何处理程序声明已分发，优先级较低的处理程序和默认模型分发路径会被跳过。
• message_sending：返回 { cancel: true } 是终止性决策。一旦任何处理程序设置它，优先级较低的处理程序会被跳过。
• message_sending：返回 { cancel: false } 会被视为没有决策（与省略 cancel 相同），而不是覆盖。
• message_received：当你需要入站线程/主题路由时，使用类型化的 threadId 字段。将 metadata 保留给特定渠道的额外信息。
• message_sending：在回退到特定渠道的 metadata 之前，先使用类型化的 replyToId / threadId 路由字段。
• gateway_start：使用 ctx.config、ctx.workspaceDir 和 ctx.getCron?.() 获取 Gateway 网关拥有的启动状态，而不是依赖内部 gateway:startup 钩子。
• cron_changed：观察 Gateway 网关拥有的 cron 生命周期变化。在同步外部唤醒调度器时使用 event.job?.state?.nextRunAtMs 和 ctx.getCron?.()，并让 OpenClaw 作为到期检查和执行的事实来源。

API 对象字段

内部模块约定

在你的插件内，使用本地 barrel 文件进行内部导入：

my-plugin/  api.ts            # Public exports for external consumers  runtime-api.ts    # Internal-only runtime exports  index.ts          # Plugin entry point  setup-entry.ts    # Lightweight setup-only entry (optional)

由 facade 加载的内置插件公共表面（api.ts、runtime-api.ts、index.ts、setup-entry.ts 以及类似公共入口文件）在 OpenClaw 已运行时优先使用活动运行时配置快照。如果运行时快照尚不存在，它们会回退到磁盘上解析出的配置文件。打包后的内置插件 facade 应通过 OpenClaw 的插件 facade 加载器加载；直接从 dist/extensions/... 导入会绕过打包安装用于插件自有代码的清单和运行时 sidecar 检查。

当辅助工具有意提供商专用、且尚不适合放入通用 SDK 子路径时，提供商插件可以暴露一个狭窄的插件本地契约 barrel。内置示例：

• Anthropic：为 Claude beta-header 和 service_tier 流辅助工具提供公共 api.ts / contract-api.ts seam。
• @openclaw/openai-provider：api.ts 导出提供商构建器、默认模型辅助工具和实时提供商构建器。
• @openclaw/openrouter-provider：api.ts 导出提供商构建器以及新手引导/配置辅助工具。

相关