插件 SDK 概览

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

导入约定

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

​

子路径参考

​

注册 API

​

能力注册

​

工具和命令

​

基础设施

​

工作流插件的宿主钩子

• 外部插件可以拥有会话扩展、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 注册的解析期命令描述符

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

​

CLI 后端注册

• 后端 id 会成为模型引用中的提供方前缀，例如 codex-cli/gpt-5。
• 后端 config 使用与 agents.defaults.cliBackends.<id> 相同的结构。
• 用户配置仍然优先。OpenClaw 会在运行 CLI 之前，将 agents.defaults.cliBackends.<id> 与插件默认配置合并。
• 当后端在合并后需要兼容性重写时，使用 normalizeConfig （例如规范化旧的参数形状）。

​

独占槽位

​

内存嵌入适配器

• 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：在回退到渠道特定的 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：面向 Claude 的 api.ts / contract-api.ts 接口， 用于 beta-header 和 service_tier 流式辅助工具。
• @openclaw/openai-provider：api.ts 导出提供者构建器、 默认模型辅助工具，以及实时提供者构建器。
• @openclaw/openrouter-provider：api.ts 导出提供者构建器 以及引导/配置辅助工具。

​

相关内容