插件 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 中；范围宽泛的已弃用再导出桶文件记录在 scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json 中。

注册 API

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

能力注册

工作节点提供商还必须在 contracts.workerProviders 中声明其 ID。核心会在调用 provision(profile, operationId) 前持久化长期意图。提供商必须在分配外部资源前验证设置，并在配置永久被拒绝时抛出 WorkerProviderError。当操作 ID 重复时，provision 必须接管同一个租约。 核心会将经过验证的配置设置与租约一同持久化，并将该快照提供给必须具备幂等性的 destroy({ leaseId, profile })，以及返回 active、destroyed 或 unknown 的 inspect({ leaseId, profile })。这样，提供商便可在 Gateway 网关重启或命名配置被移除后继续路由生命周期调用。SSH 端点的 keyRef 使用 SecretRef，绝不能内联密钥材料；还必须包含来自可信配置输出的 hostKey，其格式必须严格为 algorithm base64，不得包含主机名或注释。核心会固定 hostKey，绝不信任首次连接时获得的密钥。生成动态 keyRef 的提供商可以实现 resolveSshIdentity({ leaseId, profile, keyRef })；如果存在，该解析器具有权威性，而未实现该解析器的提供商则使用已配置的通用密钥解析器。 具有可续期租约的提供商还可以实现 renew(leaseId)。 遇到暂时性或无法确定的故障时，inspect 必须抛出错误；只有在权威确认不存在时才返回 unknown。核心会将活跃的本地记录标记为孤立状态；如果已有持久化的销毁请求，则将该缺失视为拆除完成。

通过 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 应用服务器的开发者指令比其他提示词接口更严格：只有显式限定到 codex_app_server 的指导才会提升到该更高优先级通道。为保持兼容性，旧式字符串指导和未限定作用域的结构化指导仍可用于非 Codex 提示词接口。

节点主机命令在已连接的节点主机上运行，而不是在 Gateway 网关进程内运行。如果存在 agentTool，节点会在成功连接 Gateway 网关后发布描述符；仅当该节点保持连接，且描述符的 command 位于该节点已批准的命令范围内时，Gateway 网关才会将其提供给智能体运行。设置 agentTool.defaultPlatforms 可将非危险命令加入默认节点命令允许列表；否则需要显式配置 gateway.nodes.allowCommands 或节点调用策略。agentTool.name 必须符合提供商安全要求：以字母开头，仅使用字母、数字、下划线或连字符，并且不超过 64 个字符。由 MCP 支持的节点工具可以设置 agentTool.mcp 元数据，以便目录和工具搜索界面显示远程 MCP 服务器/工具身份，但执行仍通过已发布的节点命令进行。

基础设施

记忆提示词补充构建器会接收可选的 agentId、agentSessionKey 和 sandboxed 上下文。记忆语料库补充的 search 和 get 调用会接收可选的 agentId 和 sandboxed 上下文。拥有智能体存储的插件应在每次调用时解析对应存储，而不是在注册期间捕获单个全局路径。如果多智能体操作需要智能体 ID 但未提供，则应采用封闭式失败，而不是任意选择一个智能体。

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: "管理 Matrix 账号、验证、设备和个人资料状态",        hasSubcommands: true,      },    ],  },);

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

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "从已配对节点捕获或渲染画布内容",        hasSubcommands: true,      },    ],  },);

仅在不需要延迟注册根 CLI 时单独使用 commands。 该即时兼容路径仍受支持，但不会安装由描述符支持的占位符， 因此无法进行解析时延迟加载。

CLI 后端注册

api.registerCliBackend(...) 允许插件拥有 claude-cli 或 my-cli 等本地 AI CLI 后端的默认配置。

• 后端 id 会成为 my-cli/gpt-5 等模型引用中的提供商前缀。
• 后端 config 使用与 agents.defaults.cliBackends.<id> 相同的结构。
• 用户配置仍然优先。运行 CLI 前，OpenClaw 会将 agents.defaults.cliBackends.<id> 合并到插件默认配置之上。
• 当后端需要在合并后进行兼容性重写时，请使用 normalizeConfig （例如规范化旧版标志结构）。
• 对于属于 CLI 方言的请求范围 argv 重写，请使用 resolveExecutionArgs， 例如将 OpenClaw 思考级别映射到原生工作强度标志。该钩子接收 ctx.executionMode；对于临时 /btw 调用，请使用 "side-question" 添加后端原生隔离标志。如果这些标志能可靠地为默认始终启用原生工具的 CLI 禁用原生工具，也请声明 sideQuestionToolMode: "disabled"。
• 能够为特定运行禁用所有原生工具的后端可以声明 nativeToolMode: "selectable"。受限调用会传入空的 ctx.toolAvailability.native 元组以及精确的主机隔离 MCP 允许列表； resolveExecutionArgs 必须在最终的全新或恢复 argv 中同时强制执行两者。 如果后端无法做到这一点，OpenClaw 会采用故障关闭策略。

有关端到端编写指南，请参阅 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：应先使用类型化的 replyToId / threadId 路由字段，再回退到渠道特定的 metadata。
• gateway_start：对于 Gateway 网关负责的启动状态，请使用 ctx.config、ctx.workspaceDir 和 ctx.getCron?.()，不要依赖内部 gateway:startup 钩子。此时 Cron 可能仍在加载。
• cron_reconciled：在启动或调度器重新加载后，重新构建完整的外部 Cron 投影。它包含 reason 和实际生效的 enabled 状态（包括 enabled: false），而 ctx.getCron?.() 返回完成协调后的确切调度器。请将 ctx.abortSignal 传入持久投影工作；当该调度器快照被取代或 Gateway 网关闭时，它会中止。
• cron_changed：观察由 Gateway 网关负责的 Cron 生命周期变更。scheduled 和 removed 事件是提交后的协调提示，而不是有序的增量日志。当任务没有下一次唤醒时间时，已调度事件中不会包含 event.nextRunAtMs；已移除事件仍会携带被删除任务的快照。

外部唤醒调度器应对 cron_changed 事件进行防抖或合并， 然后从 cron_reconciled 最后捕获的调度器中重新读取完整的持久视图。 不要采用 cron_changed 上下文中的调度器：来自旧调度器的游离提示 可能与后续的重新加载重叠。

对于在 Gateway 网关启动或调度器替换时加载的持久状态，请使用 cron_reconciled 作为完整快照触发器。仅重新热加载插件时不会重放该事件。 观察处理程序并行运行，且即发即弃的分派可能重叠，因此使用方不得依赖事件 完成顺序。到期检查和执行应始终以 OpenClaw 为事实来源。

有关支持持久替换、重试/退避和干净关闭的单次执行适配器，请参阅 安全的外部 Cron 投影。

API 对象字段

内部模块约定

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

my-plugin/  api.ts            # 面向外部使用方的公共导出  runtime-api.ts    # 仅供内部使用的运行时导出  index.ts          # 插件入口点  setup-entry.ts    # 仅用于轻量级设置的入口（可选）

通过门面加载的内置插件公共接口（api.ts、runtime-api.ts、 index.ts、setup-entry.ts 和类似的公共入口文件）在 OpenClaw 已运行时， 优先使用活跃的运行时配置快照。如果尚无运行时快照， 则回退到磁盘上已解析的配置文件。 已打包内置插件的门面应通过 OpenClaw 的插件门面加载器加载；直接从 dist/extensions/... 导入会绕过已打包安装在处理插件自有代码时所使用的 清单和运行时伴随文件检查。

如果某个辅助工具被有意设计为提供商特定功能，且尚不适合放入通用 SDK 子路径，提供商插件可以公开一个范围有限的插件本地契约桶文件。内置示例：

• Anthropic：面向 Claude 测试版请求头和 service_tier 流辅助工具的公共 api.ts / contract-api.ts 接口。
• @openclaw/openai-provider：api.ts 导出提供商构建器、 默认模型辅助工具和实时提供商构建器。
• @openclaw/openrouter-provider：api.ts 导出提供商构建器， 以及新手引导/配置辅助工具。

相关内容