插件 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"] },
];

​

Infrastructure

​

工作流插件的宿主钩子

• 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 钩子之前运行，并且仅限捆绑插件，因为它们参与宿主安全策略。
• 保留命令所有权仅限捆绑插件。外部插件应使用它们 自己的命令名称或别名。
• allowPromptInjection=false 会禁用会改变提示词的钩子，包括 agent_turn_prepare、before_prompt_build、heartbeat_prompt_contribution、 旧版 before_agent_start 中的提示词字段，以及 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 的形状与 agents.defaults.cliBackends.<id> 相同。
• 用户配置仍然优先。OpenClaw 会在运行 CLI 前，将 agents.defaults.cliBackends.<id> 叠加在插件默认值之上。
• 当后端在合并后需要兼容性重写时，请使用 normalizeConfig （例如规范化旧的标志形状）。
• 当需要属于 CLI 方言的、请求作用域的 argv 重写时，请使用 resolveExecutionArgs， 例如将 OpenClaw 的思考级别映射到原生的 effort 标志。

​

独占槽位

​

Deprecated memory embedding adapters

• registerMemoryCapability is the preferred exclusive memory-plugin API.
• registerMemoryCapability may also expose publicArtifacts.listArtifacts(...) so companion plugins can consume exported memory artifacts through openclaw/plugin-sdk/memory-host-core instead of reaching into a specific memory plugin’s private layout.
• registerMemoryPromptSection, registerMemoryFlushPlan, and registerMemoryRuntime are legacy-compatible exclusive memory-plugin APIs.
• MemoryFlushPlan.model can pin the flush turn to an exact provider/model reference, such as ollama/qwen3:8b, without inheriting the active fallback chain.
• registerMemoryEmbeddingProvider is deprecated. New embedding providers should use api.registerEmbeddingProvider(...) and contracts.embeddingProviders.
• Existing memory-specific providers continue to work during the migration window, but plugin inspection reports this as compatibility debt for non-bundled plugins.

​

事件和生命周期

​

钩子决策语义

• 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_changed：观察 gateway 拥有的 cron 生命周期变化。在同步外部唤醒调度器时，请使用 event.job?.state?.nextRunAtMs 和 ctx.getCron?.()，并让 OpenClaw 作为到期检查和执行的真实来源。

​

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，以及 live provider 构建器。
• @openclaw/openrouter-provider: api.ts 导出 provider 构建器 以及 bootstrap/配置 helper。

​

相关内容