插件 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 对象：

能力注册

工具和命令

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

基础设施

工作流插件的主机钩子

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

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

• 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 钩子之前运行，并且仅限内置，因为它们参与宿主安全策略。
• 预留命令所有权仅限内置。外部插件应使用自己的命令名称或别名。
• 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 后端（例如 codex-cli）的默认配置。

• 后端 id 会成为 codex-cli/gpt-5 等模型引用中的提供商前缀。
• 后端 config 使用与 agents.defaults.cliBackends.<id> 相同的形状。
• 用户配置仍然优先。OpenClaw 会先将 agents.defaults.cliBackends.<id> 合并到插件默认值之上，然后再运行 CLI。
• 当后端需要在合并后进行兼容性重写时，使用 normalizeConfig（例如规范化旧标志形状）。
• 对于属于 CLI 方言的请求级 argv 重写，使用 resolveExecutionArgs，例如将 OpenClaw 思考级别映射到原生 effort 标志。

端到端编写指南见 CLI 后端插件。

独占槽位

记忆嵌入适配器

• registerMemoryCapability 是首选的独占记忆插件 API。
• registerMemoryCapability 也可以暴露 publicArtifacts.listArtifacts(...)， 使配套插件能够通过 openclaw/plugin-sdk/memory-host-core 消费导出的记忆工件，而不是访问特定记忆插件的私有布局。
• registerMemoryPromptSection、registerMemoryFlushPlan 和 registerMemoryRuntime 是旧版兼容的独占记忆插件 API。
• MemoryFlushPlan.model 可以将刷写轮次固定到精确的 provider/model 引用，例如 ollama/qwen3:8b，而不继承活动回退链。
• registerMemoryEmbeddingProvider 允许活动记忆插件注册一个或多个嵌入适配器 ID（例如 openai、gemini，或自定义插件定义的 ID）。
• 用户配置（例如 agents.defaults.memorySearch.provider 和 agents.defaults.memorySearch.fallback）会根据这些已注册的适配器 ID 解析。

事件和生命周期

示例、常见钩子名称和守卫语义见 插件钩子。

钩子决策语义

• 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：使用 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 检查。

提供商插件可以公开一个狭窄的插件本地合约 barrel，适用于某个 助手有意保持提供商专属，且尚不属于通用 SDK 子路径的情况。内置示例：

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

相关内容