插件 SDK 概览

​

导入约定

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

​

子路径参考

​

注册 API

​

能力注册

​

工具和命令

agentPromptGuidance: [
  "全局命令提示。",
  { text: "仅在 OpenClaw 主提示词中显示此内容。", surfaces: ["openclaw_main"] },
];

​

基础设施

​

确认响应后的 Webhook 工作

import { runDetachedWebhookWork } from "openclaw/plugin-sdk/webhook-request-guards";

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

​

按请求者限定作用域的 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 绝不会退回使用其他请求者的凭据。

​

工作流插件的主机钩子

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(...)

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

​

Gateway 网关设备发现注册

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() };
  },
});

​

CLI 注册元数据

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

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "管理 Matrix 账户、验证、设备和个人资料状态",
        hasSubcommands: true,
      },
    ],
  },
);

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

​

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 等运行时能力限制 禁用原生工具，并在声明的执行路径不完整时以关闭方式失败。

​

独占槽位

​

已弃用的记忆嵌入适配器

• 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_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 不存在；移除事件仍携带已删除作业的快照。

​

API 对象字段

​

内部模块约定

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

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

​

相关内容