插件 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。该内置 schema 子路径不应作为新插件的范式。

子路径参考

插件 SDK 以一组按领域划分的窄子路径公开（插件入口、渠道、提供商、身份验证、运行时、能力、记忆以及保留的内置插件辅助函数）。完整目录及其分组链接请参阅插件 SDK 子路径。

编译器入口点清单位于 scripts/lib/plugin-sdk-entrypoints.json；类型化公共导出不包括 scripts/lib/plugin-sdk-private-local-only-subpaths.json 中列出的内部子路径。该列表中的生产入口会为单独发布的官方插件保留仅限 JavaScript 的宿主运行时导出，而仅用于测试的入口仍不导出。运行 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 对象：

为会话提供外部团队聊天界面的插件，可以注册由 openclaw/plugin-sdk/session-discussion 导出的单个进程级提供商。其 info({ sessionKey }) 方法会报告讨论是不可用、可打开还是已打开；open({ sessionKey }) 会创建或解析讨论，并返回其嵌入 URL 和外部 URL。注册另一个提供商会替换当前提供商。

能力注册

工作节点提供商还必须在 contracts.workerProviders 中声明其 ID。 核心会在 provision(profile, operationId) 之前持久化持久意图。提供商须在外部分配之前验证设置，并在配置文件被永久拒绝时抛出 WorkerProviderError。当操作 ID 重复时，provision 必须采用同一租约。 核心会将已验证的配置文件设置与租约一起持久化，并将该快照提供给必须具备幂等性的 destroy({ leaseId, profile })，以及返回 active、destroyed 或 unknown 的 inspect({ leaseId, profile })。这样，即使 Gateway 网关重启或命名配置文件被移除，提供商仍可路由生命周期调用。SSH 端点使用 SecretRef 表示 keyRef，绝不内联密钥材料；并包含来自可信预配输出的 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: [  "全局命令提示。",  { text: "仅在 OpenClaw 主提示词中显示此内容。", 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 提示表面使用。

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

基础设施

确认响应后的 Webhook 工作

在处理完成前确认请求的 Webhook 路由必须将 这项分离的工作转移到其自身的受跟踪准入根上：

 void runDetachedWebhookWork(() => processWebhookEvent(event)).catch((error) => {  runtime.error?.(`Webhook 分派失败：${String(error)}`);});

必须在 HTTP 请求仍处于准入状态时同步调用 runDetachedWebhookWork(...)。 该辅助函数会立即预留一个独立根，然后在下一个微任务中启动 回调，以便请求处理程序先写入 确认响应。返回的 Promise 会采用回调结果；调用方 仍负责处理拒绝。这样可确保确认响应后的队列工作被接受，并让 重启或暂停时的排空操作等待该工作完成。返回前会等待所有处理 完成的处理程序不需要此辅助函数。

按请求者限定作用域的 MCP 连接

在 mcp.servers、原生插件的 mcpServers 清单字段或捆绑包清单中，将 MCP 服务器的身份 （名称、工具筛选器）保持为静态。可以选择注册连接解析器，使每个受信任的 消息请求者都获得自己的传输：

api.registerMcpServerConnectionResolver({  serverName: "user-email",  resolve: async (ctx) => {    // ctx.requesterSenderId 由主机信任；绝不要在这里虚构发送者身份。    const token = await lookupUserToken(ctx.requesterSenderId);    if (!token) {      return null; // 为当前运行省略此服务器    }    return {      url: "https://mcp.example.com/email",      headers: { Authorization: `Bearer ${token}` },    };  },});

契约说明：

• 解析器上下文仅携带受信任的主机身份（requesterSenderId， 以及可选的 agentAccountId / messageChannel）。未来的受信任字段（例如 定时任务/子智能体用户上下文）可以通过附加方式添加。
• 一个服务器名称仅归一个插件所有：如果另一个 插件为同一 serverName 重复注册 registerMcpServerConnectionResolver，系统会拒绝并生成错误诊断（首次注册生效），因此 连接所有权绝不会取决于插件加载顺序。
• 工具名称根据完整的已声明服务器集合派生，因此部分解析 绝不会导致不同请求者或轮次之间的安全服务器名称发生变化。核心不会 验证不同请求者端点是否提供相同的工具架构；解析器 必须让每个请求者都指向同一逻辑服务，否则工具 架构（以及提示缓存稳定性）会因请求者而异。
• 没有受信任 requesterSenderId 的运行（定时任务、子智能体、Heartbeat、公共 Gateway 网关）绝不会实例化按请求者限定作用域的服务器。不存在共享的 后备连接。
• 每台服务器的 resolve 时限为 10 秒；超时或抛出异常会在该次 运行中省略相应服务器，但不会导致静态 MCP 失败。
• 每个请求者的已解析连接最多每 5 分钟重新验证一次： 轮换会使用新凭据重建传输，而 null 结果 会撤销连接（即使会话正在进行，也会释放缓存的运行时）。因此，已撤销或 已轮换的凭据最多可能继续使用 5 分钟。
• 已解析的 headers 绝不会被记录或持久化；核心只保留临时的 内存键控摘要（进程本地 HMAC）来检测凭据轮换，并将 已解析的标头/URL 凭据值注册到日志/调试捕获 脱敏注册表中。
• 按请求者限定作用域的服务器不会创建 MCP App 视图：视图的生命周期长于 经请求者身份验证的运行，而 Gateway 网关视图边界没有请求者 身份，因此这些服务器的应用预览保持故障时关闭。工具结果 不受影响。
• 没有解析器的静态服务器会保持现有的会话作用域生命周期。
• **Harness 交付规则：**按请求者限定作用域的服务器绝不会进入 harness 原生 MCP 客户端配置（Codex 线程 mcp_servers、CLI -c mcp_servers=… 或任何 其他会话共享的 MCP 投影）。Harness 会改为将其作为运行作用域 工具交付：
  • 嵌入式运行器：会话 MCP 运行时 + 捆绑包工具（静态 + 限定作用域）。
  • Codex app-server：通过 materializeRequesterScopedMcpToolsForHarnessRun 提供动态工具（仅限限定作用域的工具；静态 服务器仍使用 Codex 的原生 MCP 客户端）。
• 限定作用域的工具规格在该会话中首次成功解析后保持会话稳定， 因此共享线程的 harness（Codex）不会在 发送者变化时轮换线程。在任何请求者完成解析前，不会公布限定作用域的规格。
• 共享线程 harness 上未经身份验证的请求者仍能看到已公布的 限定作用域工具；调用此类工具会为该请求者返回明确的未连接工具错误。 OpenClaw 绝不会退回使用其他请求者的凭据。

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

当提示文本依赖异步 插件状态时，使用 registerMemoryPromptPreparation(...)。该回调会在每次完整智能体提示前运行一次，并接收 与同步记忆提示构建器相同的工具、智能体、会话和沙箱 上下文。加载持久化状态前验证当前的存储所有者实例， 然后仅返回该次运行所需的行。OpenClaw 会冻结这些行，并将 不可变结果交给同步提示组装。持久化、 原子替换和移除所有者时的删除操作应保留在所属插件内；不要 从提示构建器轮询或读取文件。

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 会对缺少这些操作员权限范围的连接隐藏该标签页：

对于受 Gateway 网关保护的外部标签页，请在同一插件的 auth: "gateway" HTTP 路由下注册描述符 path。完成身份验证引导后，浏览器会获得一个 作用域限定于该插件和路由根目录、短期有效且采用 HttpOnly 的授权，使 沙箱隔离的框架无需将 Gateway 网关不记名令牌复制到其 URL 或 JavaScript 中即可加载。经过身份验证的父页面会在外部标签页 处于活动状态时续期该授权，并在导航或浏览器恢复后挂载标签页前续期。它还会 在挂载前从同一不透明沙箱中探测该授权，因此 阻止 Cookie 的浏览器隐私模式会以安全关闭方式显示不可用面板。 框架授权仅接受 GET 和 HEAD，并且始终携带 operator.read；requiredScopes 控制标签页可见性，但绝不会扩大 Cookie 授权范围。变更操作仍需通过显式的、经 Gateway 网关身份验证的父页面或 不记名令牌界面进行。外部标签页要求使用 HTTPS/Tailscale Serve 或 浏览器信任的 local loopback 源；LAN 主机上的纯 HTTP 会显示 安全上下文错误，而不会挂载无法进行身份验证的面板。 完全阻止第三方 Cookie 也会导致受 Gateway 网关保护的标签页不可用。 与所有原生插件界面一样，该框架仍处于已安装 插件的信任边界内；OpenClaw 不会将已安装插件视为彼此 隔离的浏览器安全主体。 Cookie 授权使用浏览器的主机名边界，而不是端口边界。即使使用其他 端口，也不要在 Gateway 网关主机名上共同托管互不信任的服务。 由插件管理身份验证支持的标签页会保留其直接 iframe 行为，且不会 请求或要求此 Gateway 网关授权。

api.session.controls.registerControlUiDescriptor({  surface: "tab",  id: "logbook",  label: "日志簿",  description: "以屏幕快照构建时间线，记录你的一天。",  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 和 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(...) 允许插件拥有本地 AI CLI 后端（例如 claude-cli 或 my-cli）的默认配置。

• 后端 id 会成为模型引用（例如 my-cli/gpt-5）中的提供商前缀。
• 后端 config 是权威命令适配器：argv、环境、 解析器、会话、图像和可靠性行为均位于插件代码中。
• 用户通过模型引用或模型范围的 agentRuntime.id 选择后端； openclaw.json 不会重写适配器。
• 当已注册的静态字段需要运行时感知的 规范化处理时，请使用 normalizeConfig。
• 对于属于 CLI 方言的请求范围 argv 重写，请使用 resolveExecutionArgs， 例如将 OpenClaw 思考级别映射到原生工作量 标志。该钩子接收 ctx.executionMode；使用 "side-question" 为临时 /btw 调用添加 后端原生隔离标志。如果这些标志 能可靠地为原本始终启用原生工具的 CLI 禁用这些工具，还应声明 sideQuestionToolMode: "disabled"。
• 对于后端拥有的启动环境或临时 身份验证/配置桥接，请使用 prepareExecution。其 ctx.contextTokenBudget 是为本次运行选择的有效令牌 限制，因此支持原生压缩的后端可以对齐自身 阈值，而无需在核心中添加提供商专用分支。它还会接收 核心准备的 ctx.env，以供后端暂存需要扩展内置 MCP 设置时使用。
• 能够为特定运行禁用所有原生工具的后端可以声明 nativeToolMode: "selectable"。受限调用会传入精确的 ctx.toolAvailability.native 列表以及规范的 ctx.toolAvailability.openClaw 名称。请声明 toolAvailabilityEnforcement: "execution-args" 并在最终的新建/恢复 argv 中强制执行该契约，或者声明 "prepare-execution"， 在暂存策略中强制执行该契约，并返回 toolAvailabilityEnforced: true。OpenClaw 会针对定时任务 toolsAllow 等运行时能力限制 禁用原生工具，并在声明的执行路径不完整时以关闭方式失败。

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

独占槽位

已弃用的记忆嵌入适配器

• registerMemoryCapability 是独占的记忆插件 API。
• registerMemoryCapability 还可以公开 publicArtifacts.listArtifacts(...) 以用于宿主管理的导出。枚举这些已声明 工件的配套插件仍使用保留的 openclaw/plugin-sdk/memory-host-core 外观中的 listActiveMemoryPublicArtifacts(...)，直至出现专门的公共使用方 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：对于 Gateway 网关拥有的启动状态，请使用 ctx.config、ctx.workspaceDir 和 ctx.getCron?.()，而不是依赖内部 gateway:startup 钩子。此时定时任务可能仍在加载。
• cron_reconciled：在启动或调度器重新加载后重建完整的外部定时任务投影。它包含 reason 和有效的 enabled 状态（包括 enabled: false），而 ctx.getCron?.() 返回准确的已协调调度器。将 ctx.abortSignal 传入持久投影工作；当该调度器快照被取代或 Gateway 网关关闭时，它会中止。
• cron_changed：观察 Gateway 网关拥有的定时任务生命周期变化。scheduled 和 removed 事件是提交后的协调提示，而不是有序的增量日志。当作业没有下次唤醒时间时，计划事件的 event.nextRunAtMs 不存在；移除事件仍携带已删除作业的快照。

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

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

有关具备持久替换、重试/退避和干净 关闭机制的单次执行适配器，请参阅安全的外部定时任务投影。

API 对象字段

内部模块约定

在插件内部，对内部导入使用本地桶文件：

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

通过 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 接口。
• @openclaw/openai-provider：api.ts 导出提供商构建器、 默认模型辅助函数和实时提供商构建器。
• @openclaw/openrouter-provider：api.ts 导出提供商构建器 以及新手引导/配置辅助函数。

相关内容