插件 SDK 概览

​

导入约定

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

​

子路径参考

​

注册 API

​

能力注册

​

工具和命令

agentPromptGuidance: [
  "全局命令提示。",
  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },
];

​

基础设施

​

确认后的 Webhook 工作

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

void runDetachedWebhookWork(() => processWebhookEvent(event)).catch((error) => {
  runtime.error?.(`webhook dispatch failed: ${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）。未来受信任字段（例如 cron/子代理用户上下文）可以以追加方式加入。
• 一个插件只能拥有一个服务器名称：来自另一个插件、针对相同 serverName 的重复 registerMcpServerConnectionResolver 会被以错误诊断拒绝 （首次注册者获胜），因此连接所有权永远不依赖插件加载顺序。
• 工具名称由完整声明的服务器集合派生，因此部分解析绝不会在不同请求方或轮次之间改变安全的服务器名称。Core 不会验证不同请求方端点是否提供完全相同的工具 schema；解析器必须让每个请求方指向同一个逻辑服务，否则工具 schema（以及提示缓存稳定性）会按请求方发生分歧。
• 在没有受信任的 requesterSenderId 的运行中（cron、子代理、心跳、公共网关），永远不会实例化按请求方作用域划分的服务器。不存在共享的回退连接。
• resolve 对每个服务器的执行上限为 10 秒；超时或抛错会在本次运行中省略该服务器，而不会使静态 MCP 失败。
• 已解析的连接对每个请求方最多每 5 分钟重新校验一次：轮换会用新凭据重建传输，而 null 结果会撤销它（即使在会话中途，缓存的运行时也会被释放）。因此，已撤销或已轮换的凭据最多可能继续使用 5 分钟。
• 已解析的 headers 绝不会被记录或持久化；core 只保留一个短暂的、仅进程内的键控摘要（进程本地 HMAC）来检测凭据轮换，并将已解析的 header/URL 凭据值注册到日志/调试捕获脱敏注册表中。
• 按请求方作用域划分的服务器不会生成 MCP App 视图：视图的生命周期会超出经过请求方认证的运行，而且网关视图边界没有请求方身份，因此这些服务器的 app 预览会保持 fail-closed。工具结果不受影响。
• 没有解析器的静态服务器会保留现有的会话作用域生命周期。
• Harness 传递规则： 按请求方作用域划分的服务器绝不会进入 harness 原生 MCP 客户端配置（Codex 线程 mcp_servers、CLI -c mcp_servers=…，或任何其他会话共享的 MCP 投影）。harness 会将它们作为运行作用域工具传递：
  • 嵌入式运行器：会话 MCP 运行时 + bundle 工具（静态 + 作用域）。
  • Codex 应用服务器：通过 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：由 registrar 拥有的显式命令名称
• 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 重写（例如将 OpenClaw 思考级别映射为原生 effort 标志），使用 resolveExecutionArgs。该钩子会接收 ctx.executionMode；对于临时的 /btw 调用，使用 "side-question" 添加后端原生的隔离标志。如果这些标志能够可靠地为一个原本始终启用原生工具的 CLI 禁用原生工具，则同时声明 sideQuestionToolMode: "disabled"。
• 对于由后端负责的启动环境或临时身份验证/配置桥接，使用 prepareExecution。其 ctx.contextTokenBudget 是本次运行所选的有效 token 限制，因此支持原生压缩的后端可以自行对齐其阈值，而无需在提供商专用的核心分支中处理。它还会接收核心准备好的 ctx.env，以便后端暂存过程扩展捆绑的 MCP 设置。
• 能够在特定运行中禁用所有原生工具的后端可以声明 nativeToolMode: "selectable"。受限调用会传入精确的 ctx.toolAvailability.native 列表以及规范化的 ctx.toolAvailability.openClaw 名称。声明 toolAvailabilityEnforcement: "execution-args"，并在最终的新建/恢复 argv 中执行该约定；或者声明 "prepare-execution"，在暂存策略中执行该约定，并返回 toolAvailabilityEnforced: true。对于 cron toolsAllow 等运行时限制，OpenClaw 会禁用原生工具；当声明的执行路径不完整时，则采取故障安全拒绝策略。

​

独占槽位

​

已弃用的内存嵌入适配器

• registerMemoryCapability 是唯一的内存插件 API。
• registerMemoryCapability 还可以通过 publicArtifacts.listArtifacts(...) 暴露由主机管理的导出内容。枚举这些已声明导出内容的配套插件仍应使用保留的 openclaw/plugin-sdk/memory-host-core 外观中的 listActiveMemoryPublicArtifacts(...)，直到出现专用的公共消费者 API；它们不得 访问另一个插件的私有布局。
• 能够返回会话转录命中的内存运行时应实现 runtime.authorizeSearchHits(...)。主机会在原始搜索命中到达调用方可见的界面之前调用此钩子，并提供请求代理、会话密钥和沙箱状态。仅返回请求方可以查看的命中。如果缺少此钩子，OpenClaw 将通过隐藏会话来源的命中来采取默认拒绝策略，同时保留普通内存命中。将转录身份和可见性策略保留在所属的内存插件中；调用方不得根据路径推断授权，也不得重复实现插件特定的规则。
• 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: 请使用 ctx.config、ctx.workspaceDir 和 ctx.getCron?.() 来获取 Gateway 拥有的启动状态，而不是依赖内部的 gateway:startup 钩子。此时 Cron 可能仍在加载中。
• cron_reconciled: 在启动或调度器重新加载后，重建完整的外部 cron 投影。它包含 reason 和有效的 enabled 状态，包括 enabled: false，而 ctx.getCron?.() 返回的是精确对齐后的调度器。将 ctx.abortSignal 传入持久化投影工作；当该调度器快照被替换或 Gateway 关闭时，它会中止。
• cron_changed: 观察 Gateway 拥有的 cron 生命周期变化。scheduled 和 removed 事件是提交后的对账提示，而不是有序的增量日志。scheduled 事件的 event.nextRunAtMs 在任务没有下次唤醒时会缺失；removed 事件仍然携带已删除任务的快照。

​

API 对象字段

​

内部模块约定

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

• Anthropic: api.ts / contract-api.ts 接口用于 Claude， 适用于 beta-header 和 service_tier 流式处理 helper。
• @openclaw/openai-provider: api.ts 导出 provider 构建器、 默认模型 helper，以及实时 provider 构建器。
• @openclaw/openrouter-provider: api.ts 导出 provider 构建器 以及引导/配置 helper。

​

相关内容