本页是 OpenClaw 插件入口辅助函数的完整参考。覆盖 definePluginEntry（Provider/工具/hook 插件用）、defineChannelPluginEntry（渠道插件用）和 defineSetupPluginEntry（轻量 Setup 入口用）的所有参数字段、注册模式（full/setup-only/setup-runtime/cli-metadata）含义和插件形态分类。

OpenClaw 插件入口点

每个插件默认导出一个入口对象。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: "简短摘要",
  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 可以是函数（懒执行），OpenClaw 在首次访问时解析并缓存

defineChannelPluginEntry

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

在 definePluginEntry 基础上加入渠道特定接线。自动调用 api.registerChannel({ plugin })，暴露可选的根 help CLI 元数据接缝，并通过注册模式控制 registerFull。

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

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

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

注意：

• setRuntime 在注册时调用，通常通过 createPluginRuntimeStore 存储 runtime 引用；CLI 元数据捕获时跳过
• registerCliMetadata 在 "cli-metadata" 和 "full" 两种模式下都执行，是放置渠道自有 CLI 描述符的规范位置
• registerFull 仅在 "full" 模式下执行，setup-only 加载时跳过
• 插件自有的根 CLI 命令，在需要懒加载但不从根 CLI 解析树消失时，优先用 api.registerCli(..., { descriptors: [...] })
• 插件向 gateway 注册 RPC 方法时，保持插件特定前缀；保留核心管理员命名空间（config.*、exec.approvals.*、wizard.*、update.*）总是解析到 operator.admin

defineSetupPluginEntry

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

用于轻量的 setup-entry.ts 文件。仅返回 { plugin }，无 runtime 或 CLI 接线。

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

export default defineSetupPluginEntry(myChannelPlugin);

渠道禁用、未配置或启用了延迟加载时，OpenClaw 加载此文件而非完整入口，避免引入繁重的 runtime 代码。

实践中，将 defineSetupPluginEntry(...) 与以下窄型 setup helper 配合使用：

• openclaw/plugin-sdk/setup-runtime — runtime 安全的 setup helper（patch 适配器、lookup-note 输出、promptResolvedAllowFrom 等）
• openclaw/plugin-sdk/channel-setup — 可选安装的 setup 面
• openclaw/plugin-sdk/setup-tools — setup/安装 CLI/归档/文档 helper

繁重的 SDK、CLI 注册和长期 runtime 服务保留在完整入口中。

注册模式

api.registrationMode 告诉插件当前的加载方式：

模式	触发时机	应注册的内容
"full"	正常网关启动	所有内容
"setup-only"	禁用/未配置的渠道	仅渠道注册
"setup-runtime"	带 runtime 的 Setup 流程	渠道注册 + 完整入口加载前所需的轻量 runtime
"cli-metadata"	根 help / CLI 元数据捕获	仅 CLI 描述符

defineChannelPluginEntry 自动处理这种分离。如果你直接用 definePluginEntry 实现渠道，需要手动检查模式：

register(api) {
  if (api.registrationMode === "cli-metadata" || api.registrationMode === "full") {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

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

  // 繁重的 runtime 专有注册
  api.registerService(/* ... */);
}

"setup-runtime" 是 setup-only 启动面必须在完整入口加载前存在的窗口期。适合的内容：渠道注册、setup 安全的 HTTP 路由、setup 安全的 gateway 方法和委托 setup helper。繁重的后台服务、CLI 注册器和 Provider/客户端 SDK 初始化仍属于 "full" 模式。

插件形态

OpenClaw 根据注册行为（非静态元数据）将插件分为四种形态：

形态	说明
plain-capability	恰好注册一种能力类型（如仅 Provider 的 mistral）
hybrid-capability	注册多种能力类型（如 openai 同时拥有文本推理、语音、媒体理解和图像生成）
hook-only	只注册 hook，无能力/工具/命令/服务
non-capability	注册工具、命令、服务或路由，但无能力

运行 openclaw plugins inspect <id> 查看插件形态。

相关文档

• SDK 概览 — 注册 API 和子路径参考
• 运行时辅助工具 — api.runtime 和 createPluginRuntimeStore
• 插件打包与配置 — manifest、setup entry、延迟加载
• 渠道插件开发 — 构建 ChannelPlugin 对象
• Provider 插件开发 — Provider 注册与 hook

常见问题

Q: registerCliMetadata 和 registerFull 里都能注册 CLI 吗？

A: 可以，但推荐做法是只在 registerCliMetadata 中注册 CLI 描述符，让根 CLI help 无需激活完整 runtime 即可展示命令。registerFull 中注册的 CLI 只会在完整模式下生效。如果两者都注册了同一命令，会有重复注册的风险。

Q: 插件的 id 字段必须和 manifest 里的 id 一致吗？

A: 是的，OpenClaw 要求 definePluginEntry({ id }) 中的 id 与 openclaw.plugin.json 中的 id 字段完全一致，否则加载时会报错。

Q: "setup-runtime" 模式和 "setup-only" 模式有什么区别？

A: "setup-only" 适用于渠道禁用或未配置时，只需要暴露 setup/onboarding 面，不需要任何运行时能力。"setup-runtime" 是一个过渡窗口：渠道需要在完整入口加载之前就具备部分轻量运行时能力（如特定的 HTTP 路由或 gateway 方法）时使用，典型场景是延迟加载启动。