package.json 元数据)、清单(openclaw.plugin.json)、设置入口和配置 schema 的参考。
包元数据
你的package.json 需要一个 openclaw 字段,用于告诉插件系统你的插件提供什么:
- Channel plugin
- Provider plugin / ClawHub baseline
在 ClawHub 上外部发布需要
compat 和 build。规范发布片段位于 docs/snippets/plugin-publish/。openclaw 字段
入口点文件(相对于包根目录)。适用于工作区和 git checkout 开发的有效源入口。
extensions 对应的已构建 JavaScript peer,在 OpenClaw 加载已安装的 npm 包时优先使用。源/构建解析顺序见 SDK 入口点。轻量的仅设置入口(可选)。
setupEntry 对应的已构建 JavaScript peer。要求同时设置 setupEntry。{ id, label } 后备插件身份,当插件没有可用于派生 id 或 label 的渠道/提供商元数据时使用。用于设置、选择器、快速开始和状态界面的渠道目录元数据。
安装提示:
npmSpec、localPath、defaultChoice、minHostVersion、expectedIntegrity、allowInvalidConfigRecovery、requiredPlatformPackages。启动行为标志。
此插件支持的
pluginApi 版本范围。外部 ClawHub 发布需要此字段。提供商 id(
providers: string[])是清单元数据,不是包元数据。请在 openclaw.plugin.json 中声明它们,而不是这里,见 插件清单。openclaw.channel
openclaw.channel 是轻量包元数据,用于运行时加载前的渠道发现和设置界面。
| 字段 | 类型 | 含义 |
|---|---|---|
id | string | 规范渠道 id。 |
label | string | 主要渠道标签。 |
selectionLabel | string | 当需要与 label 不同时,用于选择器/设置的标签。 |
detailLabel | string | 用于更丰富渠道目录和状态界面的次级详情标签。 |
docsPath | string | 用于设置和选择链接的文档路径。 |
docsLabel | string | 当文档链接标签需要与渠道 id 不同时使用的覆盖标签。 |
blurb | string | 简短的新手引导/目录描述。 |
order | number | 渠道目录中的排序顺序。 |
aliases | string[] | 用于渠道选择的额外查找别名。 |
preferOver | string[] | 此渠道应优先于的低优先级插件/渠道 id。 |
systemImage | string | 渠道 UI 目录的可选图标/系统图片名称。 |
selectionDocsPrefix | string | 选择界面中文档链接前的前缀文本。 |
selectionDocsOmitLabel | boolean | 在选择文案中直接显示文档路径,而不是带标签的文档链接。 |
selectionExtras | string[] | 追加到选择文案中的额外短字符串。 |
markdownCapable | boolean | 标记该渠道支持 markdown,用于出站格式化决策。 |
exposure | object | 控制渠道在设置、已配置列表和文档界面中的可见性。 |
quickstartAllowFrom | boolean | 将此渠道加入标准快速开始 allowFrom 设置流程。 |
forceAccountBinding | boolean | 即使只有一个账号,也要求显式账号绑定。 |
preferSessionLookupForAnnounceTarget | boolean | 为此渠道解析公告目标时优先使用会话查找。 |
exposure 支持:
configured:在已配置/状态样式的列表界面中包含该渠道setup:在交互式设置/配置选择器中包含该渠道docs:在文档/导航界面中将该渠道标记为面向公众
showConfigured 和 showInSetup 仍作为旧版别名受支持。优先使用 exposure。openclaw.install
openclaw.install 是包元数据,不是清单元数据。
| 字段 | 类型 | 含义 |
|---|---|---|
clawhubSpec | string | 用于安装/更新和新手引导按需安装流程的规范 ClawHub spec。 |
npmSpec | string | 用于安装/更新后备流程的规范 npm spec。 |
localPath | string | 本地开发或内置安装路径。 |
defaultChoice | "clawhub" | "npm" | "local" | 当有多个来源可用时,首选安装来源。 |
minHostVersion | string | 最低支持的 OpenClaw 版本,>=x.y.z 或 >=x.y.z-prerelease。 |
expectedIntegrity | string | 预期的 npm dist 完整性字符串,通常为 sha512-...,用于固定安装。 |
allowInvalidConfigRecovery | boolean | 允许内置插件重新安装流程从特定的陈旧配置失败中恢复。 |
requiredPlatformPackages | string[] | npm 安装期间验证的必需平台特定 npm 别名。 |
Onboarding behavior
Onboarding behavior
交互式新手引导会将
openclaw.install 用于按需安装界面:如果你的插件在运行时加载前暴露提供商凭证选项或渠道设置/目录元数据,新手引导可以提示选择 ClawHub、npm 或本地安装,安装或启用插件,然后继续所选流程。ClawHub 选项使用 clawhubSpec,存在时优先使用;npm 选项需要带注册表 npmSpec 的可信目录元数据(精确版本和 expectedIntegrity 是可选固定项,设置后会在安装/更新时强制执行)。将“显示什么”放在 openclaw.plugin.json 中,将“如何安装”放在 package.json 中。minHostVersion enforcement
minHostVersion enforcement
如果设置了
minHostVersion,安装和非内置清单注册表加载都会强制执行它。旧版 host 会跳过外部插件;无效版本字符串会被拒绝。内置源插件假定与 host checkout 版本一致。Pinned npm installs
Pinned npm installs
对于固定的 npm 安装,请在
npmSpec 中保留精确版本,并添加预期 artifact 完整性:allowInvalidConfigRecovery scope
allowInvalidConfigRecovery scope
allowInvalidConfigRecovery 不是损坏配置的通用绕过机制。它只用于狭义的内置插件恢复,允许重新安装/设置修复已知升级残留,例如缺少内置插件路径,或同一插件的陈旧 channels.<id> 条目。如果配置因无关原因损坏,安装仍会 fail closed,并提示操作员运行 openclaw doctor --fix。延迟完整加载
渠道插件可以通过以下配置选择延迟加载:setupEntry。完整入口会在 Gateway 网关开始监听后加载。
如果你的设置/完整入口注册 Gateway 网关 RPC 方法,请将它们放在插件专属前缀下。保留的核心 admin 命名空间(config.*、exec.approvals.*、wizard.*、update.*)仍由核心拥有,并始终规范化为 operator.admin。
插件清单
每个原生插件都必须在包根目录随附一个openclaw.plugin.json。OpenClaw 使用它在不执行插件代码的情况下验证配置。
channels(提供商插件则添加 providers):
ClawHub 发布
Skills 和插件包使用不同的 ClawHub 发布命令。对于插件包,请使用特定于包的命令:clawhub skill publish <path> 是用于发布技能文件夹的另一个命令,不是插件包。见 在 ClawHub 上发布。设置入口
setup-entry.ts 是 index.ts 的轻量替代项,OpenClaw 只需要设置界面(新手引导、配置修复、已禁用渠道检查)时会加载它:
openclaw/plugin-sdk/channel-entry-contract 中的 defineBundledChannelSetupEntry(...),而不是 defineSetupPluginEntry(...)。该内置契约还支持可选的 runtime 导出,因此设置时的运行时接线可以保持轻量且明确。
OpenClaw 何时使用 setupEntry 而不是完整入口
OpenClaw 何时使用 setupEntry 而不是完整入口
- 渠道已禁用,但需要设置/新手引导界面。
- 渠道已启用但未配置。
- 已启用延迟加载(
deferConfiguredChannelFullLoadUntilAfterListen)。
setupEntry 必须注册什么
setupEntry 必须注册什么
- 渠道插件对象(通过
defineSetupPluginEntry)。 - Gateway 网关监听前所需的任何 HTTP 路由。
- 启动期间所需的任何 Gateway 网关方法。
config.* 或 update.*。setupEntry 不应包含什么
setupEntry 不应包含什么
- CLI 注册。
- 后台服务。
- 繁重的运行时导入(加密、SDK)。
- 仅在启动后才需要的 Gateway 网关方法。
窄设置辅助导入
对于设置专用热路径,如果你只需要设置界面的一部分,请优先使用窄设置辅助接口,而不是更宽泛的plugin-sdk/setup 总入口:
| 导入路径 | 用途 | 关键导出 |
|---|---|---|
plugin-sdk/setup-runtime | 设置时运行时辅助工具,可在 setupEntry / 延迟渠道启动中保持可用 | createSetupTranslator, createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy |
plugin-sdk/setup-adapter-runtime | 已弃用的兼容别名;请使用 plugin-sdk/setup-runtime | createEnvPatchedAccountSetupAdapter |
plugin-sdk/setup-tools | 设置/安装 CLI/归档/文档辅助工具 | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
plugin-sdk/setup 接口,包括 moveSingleAccountChannelSectionToDefaultAccount(...) 等配置补丁辅助工具。
使用 createSetupTranslator(...) 处理固定的设置向导文案。它遵循 CLI 向导语言环境(OPENCLAW_LOCALE,然后是系统语言环境变量),并回退到英语。将特定于插件的设置文本保留在插件拥有的代码中,并且仅将共享目录键用于常见设置标签、状态文本和官方内置插件设置文案。
这些设置补丁适配器在导入时保持热路径安全。它们的内置单账号提升契约界面查找是惰性的,因此导入 plugin-sdk/setup-runtime 不会在适配器实际使用前提前加载内置契约界面发现。
渠道拥有的单账号提升
当渠道从单账号顶层配置升级到channels.<id>.accounts.* 时,默认共享行为会将提升后的账号级值移动到 accounts.default。
内置渠道可以通过它们的设置契约界面缩小或覆盖该提升:
singleAccountKeysToMove:应移动到提升后账号的额外顶层键namedAccountPromotionKeys:当命名账号已存在时,只有这些键会移动到提升后的账号;共享策略/投递键保留在渠道根部resolveSingleAccountPromotionTarget(...):选择哪个现有账号接收提升后的值
Matrix 是当前的内置示例。如果恰好已有一个命名 Matrix 账号,或者
defaultAccount 指向现有的非规范键(例如 Ops),提升会保留该账号,而不是创建新的 accounts.default 条目。配置 schema
插件配置会根据你的清单中的 JSON Schema 进行验证。用户通过以下方式配置插件:api.pluginConfig 接收此配置。
对于特定于渠道的配置,请改用渠道配置部分:
构建渠道配置 schema
使用buildChannelConfigSchema 将 Zod schema 转换为插件拥有的配置制品所使用的 ChannelConfigSchema 包装器:
openclaw.plugin.json#channelConfigs,这样配置 schema、设置和 UI 界面就可以在不加载运行时代码的情况下检查 channels.<id>。
设置向导
渠道插件可以为openclaw onboard 提供交互式设置向导。该向导是 ChannelPlugin 上的 ChannelSetupWizard 对象:
ChannelSetupWizard 还支持 textInputs、dmPolicy、allowFrom、groupAccess、prepare、finalize 等。完整内置示例见 Discord 插件的 src/setup-core.ts。
共享 allowFrom 提示
共享 allowFrom 提示
对于只需要标准
note -> prompt -> parse -> merge -> patch 流程的私信允许列表提示,请优先使用 openclaw/plugin-sdk/setup 中的共享设置辅助工具:createPromptParsedAllowFromForAccount(...)、createTopLevelChannelParsedAllowFromPrompt(...) 和 createNestedChannelParsedAllowFromPrompt(...)。标准渠道设置状态
标准渠道设置状态
对于仅因标签、评分和可选额外行而有所差异的渠道设置状态块,请优先使用
openclaw/plugin-sdk/setup 中的 createStandardChannelSetupStatus(...),而不是在每个插件中手写相同的 status 对象。可选渠道设置界面
可选渠道设置界面
对于只应在特定上下文中出现的可选设置界面,请使用 当你只需要该可选安装界面的一半时,
openclaw/plugin-sdk/channel-setup 中的 createOptionalChannelSetupSurface:plugin-sdk/channel-setup 还会暴露更底层的 createOptionalChannelSetupAdapter(...) 和 createOptionalChannelSetupWizard(...) 构建器。生成的可选适配器/向导会在真实配置写入时以失败即关闭的方式处理。它们在 validateInput、applyAccountConfig 和 finalize 中复用同一条需要安装的消息,并在设置了 docsPath 时追加文档链接。二进制支持的设置辅助工具
二进制支持的设置辅助工具
对于二进制支持的设置 UI,优先使用共享的委托辅助工具,而不是在每个渠道中复制相同的二进制/状态粘合逻辑:
createDetectedBinaryStatus(...)用于仅因标签、提示、评分和二进制检测而变化的状态块createCliPathTextInput(...)用于路径支持的文本输入- 当
setupEntry需要延迟转发到更重的完整向导时,使用createDelegatedSetupWizardStatusResolvers(...)、createDelegatedPrepare(...)、createDelegatedFinalize(...)和createDelegatedResolveConfigured(...) - 当
setupEntry只需要委托textInputs[*].shouldPrompt决策时,使用createDelegatedTextInputShouldPrompt(...)
发布和安装
**外部插件:**发布到 ClawHub,然后安装:- npm
- 仅 ClawHub
- npm 包规范
clawhub:、npm:、git: 或 npm-pack: 来确定性地选择来源 — 参见管理插件。对于来自 npm 的安装,
openclaw plugins install 会将包安装到 ~/.openclaw/npm/projects 下的每插件项目中,并禁用生命周期脚本(--ignore-scripts)。保持插件依赖树为纯 JS/TS,并避免需要 postinstall 构建的包。Gateway 网关启动不会安装插件依赖。npm/git/ClawHub 安装流程负责依赖收敛;本地插件必须已经安装其依赖。