插件 SDK 概览

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/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

​

能力注册

​

工具和命令

​

基础设施

​

工作流插件的主机钩子

• 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：注册器拥有的显式命令名称
• descriptors：用于 CLI 帮助、路由和懒加载插件 CLI 注册的解析时命令描述符
• parentPath：嵌套命令组的可选父命令路径，例如 ["nodes"]

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Manage Matrix accounts, verification, devices, and profile state",
        hasSubcommands: true,
      },
    ],
  },
);

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "Capture or render canvas content from a paired node",
        hasSubcommands: true,
      },
    ],
  },
);

​

CLI 后端注册

• 后端 id 会成为 codex-cli/gpt-5 等模型引用中的提供商前缀。
• 后端 config 使用与 agents.defaults.cliBackends.<id> 相同的形状。
• 用户配置仍然优先。OpenClaw 会先将 agents.defaults.cliBackends.<id> 合并到插件默认值之上，然后再运行 CLI。
• 当后端需要在合并后进行兼容性重写时，使用 normalizeConfig（例如规范化旧标志形状）。
• 对于属于 CLI 方言的请求级 argv 重写，使用 resolveExecutionArgs，例如将 OpenClaw 思考级别映射到原生 effort 标志。

​

独占槽位

​

记忆嵌入适配器

• 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：先使用类型化 replyToId / threadId 路由字段，再回退到渠道特定的 metadata。
• 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            # Public exports for external consumers
  runtime-api.ts    # Internal-only runtime exports
  index.ts          # Plugin entry point
  setup-entry.ts    # Lightweight setup-only entry (optional)

• Anthropic：用于 Claude beta-header 和 service_tier 流式助手的公共 api.ts / contract-api.ts 边界。
• @openclaw/openai-provider：api.ts 导出提供商构建器、 默认模型助手和实时提供商构建器。
• @openclaw/openrouter-provider：api.ts 导出提供商构建器 以及新手引导/配置助手。

​

相关内容