插件入口点（Plugin Entry Points）

每个插件都导出一个默认的入口对象。SDK 提供了三个辅助函数来创建它们。

提示： 想找操作指南？ 请参阅渠道插件或Provider 插件，里面有一步一步的开发流程。

definePluginEntry

导入路径： openclaw/plugin-sdk/plugin-entry

用于 Provider 插件、工具插件、hook 插件，以及不是消息渠道的其他插件。

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

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
  },
});

字段	类型	必填	默认值
id	string	是	—
name	string	是	—
description	string	是	—
kind	string	否	—
configSchema	OpenClawPluginConfigSchema | () => OpenClawPluginConfigSchema	否	空对象 schema
register	(api: OpenClawPluginApi) => void	是	—

• id 必须与 openclaw.plugin.json manifest 中的 ID 匹配。
• kind 用于排他性插槽："memory" 或 "context-engine"。
• configSchema 可以是函数，实现懒加载求值。

defineChannelPluginEntry

导入路径： openclaw/plugin-sdk/core

对 definePluginEntry 的封装，增加了渠道专属接线。自动调用 api.registerChannel({ plugin })，并根据注册模式控制 registerFull 是否执行。

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

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerFull(api) {
    api.registerCli(/* ... */);
    api.registerGatewayMethod(/* ... */);
  },
});

字段	类型	必填	默认值
id	string	是	—
name	string	是	—
description	string	是	—
plugin	ChannelPlugin	是	—
configSchema	OpenClawPluginConfigSchema | () => OpenClawPluginConfigSchema	否	空对象 schema
setRuntime	(runtime: PluginRuntime) => void	否	—
registerFull	(api: OpenClawPluginApi) => void	否	—

• setRuntime 在注册期间被调用，让你可以存储 runtime 引用（通常通过 createPluginRuntimeStore）。
• registerFull 仅在 api.registrationMode === "full" 时执行，安装流程中的纯 setup 加载会跳过它。

defineSetupPluginEntry

导入路径： openclaw/plugin-sdk/core

用于轻量级的 setup-entry.ts 文件。仅返回 { plugin }，不含运行时或 CLI 接线。

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";

export default defineSetupPluginEntry(myChannelPlugin);

当渠道被禁用、未配置或启用了延迟加载时，OpenClaw 会加载这个入口而不是完整入口。详见 Setup and Config。

注册模式

api.registrationMode 告知你的插件是以何种方式被加载的：

模式	触发时机	应注册的内容
"full"	正常 gateway 启动	全部内容
"setup-only"	已禁用/未配置的渠道	仅渠道注册
"setup-runtime"	有运行时的安装流程	渠道 + 轻量运行时

defineChannelPluginEntry 会自动处理这种拆分。如果你直接用 definePluginEntry 处理渠道，需要自行检查模式：

register(api) {
  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // 仅运行时需要的重型注册
  api.registerCli(/* ... */);
  api.registerService(/* ... */);
}

插件形态

OpenClaw 根据注册行为对已加载的插件进行分类：

形态	描述
plain-capability	单一能力类型（如仅 Provider）
hybrid-capability	多种能力类型（如 Provider + 语音）
hook-only	仅有 hook，无其他能力
non-capability	工具/命令/服务，但无能力

使用 openclaw plugins inspect <id> 查看插件的形态。

相关链接

• SDK 概览 — 注册 API 和子路径参考
• 运行时辅助工具 — api.runtime 和 createPluginRuntimeStore
• Setup and Config — manifest、setup entry、延迟加载
• 渠道插件 — 构建 ChannelPlugin 对象
• Provider 插件 — Provider 注册和 hooks