导入与模块布局
应从哪个 openclaw/plugin-sdk/* 子路径导入,以及如何组织插件自身的公共和内部 barrel 文件。属于 Plugin SDK 概览 的一部分。
导入约定¶
对于具有原生 Control UI 的功能,请使用 功能插件:
feature-contract 定义共享操作,feature-plugin 注册它们的后端实现,
control-ui 暴露浏览器贡献与替换契约。
始终从特定子路径导入:
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
每个子路径都是一个小型、自包含的模块。这有助于保持快速启动,并避免循环依赖问题。对于通道特定的入口/构建辅助函数,请优先使用 openclaw/plugin-sdk/channel-core;保留 openclaw/plugin-sdk/core 用于更广泛的统一导出面和共享辅助函数,例如 buildChannelConfigSchema。
对于通道配置,请通过 openclaw.plugin.json#channelConfigs 发布通道拥有的 JSON Schema。plugin-sdk/channel-config-schema 子路径用于共享的 schema 原语和通用构建器。OpenClaw 的内置插件使用 plugin-sdk/bundled-channel-config-schema 用于保留的内置通道 schema。该内置 schema 子路径不是新插件应遵循的模式。
Warning
请勿导入带有 provider 或 channel 品牌标识的便捷接口(例如
openclaw/plugin-sdk/slack、.../discord、.../signal、.../whatsapp)。
内置插件会在自己的 api.ts /
runtime-api.ts barrel 文件中组合通用 SDK 子路径;核心使用方应使用这些插件本地
barrel 文件,或者当需求确实跨通道时,添加一个窄范围的通用 SDK 契约。
当存在已跟踪的所有者使用时,少量内置插件辅助接口仍会出现在生成的导出 映射中。它们仅用于内置插件维护,不建议作为新的第三方 插件的导入路径。
openclaw/plugin-sdk/discord 和 openclaw/plugin-sdk/telegram-account 已于
2026 年 10 月 2 日经 SDK 所有者明确批准后移除。请使用注入的运行时
辅助函数和通用通道 SDK 子路径;在升级仍导入这些 facade 的插件之前,请参阅
迁移映射。
对于只需要凭据值的 provider 发现,请使用 openclaw/plugin-sdk/secret-input 中的 readProviderEnvValue、resolveNonEnvSecretRefApiKeyMarker 以及 SecretRef 强制转换/规范化。这些辅助函数不会加载 profile 存储、provider 传输或 web-search 执行。使用 provider-web-search-config-contract 读取插件拥有的 web-search 配置。将完整的 auth 和搜索运行时导入保留在执行路径中。
子路径参考¶
插件 SDK 以一组按领域分组的窄子路径形式暴露(插件入口、通道、provider、auth、runtime、capability、memory 以及保留的内置插件辅助函数)。要查看完整目录——已分组并链接——请参阅 插件 SDK 子路径。
编译器入口点清单位于 scripts/lib/plugin-sdk-entrypoints.json;类型化公共导出会排除 scripts/lib/plugin-sdk-private-local-only-subpaths.json 中列出的内部子路径。该列表中的生产条目会为单独发布的官方插件保留仅 JavaScript 的宿主运行时导出,而仅测试条目保持未导出。运行 pnpm plugin-sdk:surface 以审计公共导出数量。足够旧且未被内置扩展生产代码使用的已弃用公共子路径记录在 scripts/lib/plugin-sdk-deprecated-public-subpaths.json 中;宽泛的已弃用重新导出 barrel 文件记录在 scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json 中。
内部模块约定¶
在你的插件内部,使用本地 barrel 文件进行内部导入:
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)
Warning
切勿在生产代码中通过 openclaw/plugin-sdk/<your-plugin> 导入你自己的插件。内部导入应通过 ./api.ts 或 ./runtime-api.ts 进行。SDK 路径仅作为外部契约。
通过 facade 加载的内置插件公共导出面(api.ts、runtime-api.ts、index.ts、setup-entry.ts 以及类似的公共入口文件)在 OpenClaw 已经运行时,优先使用活动的运行时配置快照。如果尚不存在运行时快照,它们会回退到磁盘上已解析的配置文件。打包的内置插件 facade 应通过 OpenClaw 的插件 facade 加载器加载;直接从 dist/extensions/... 导入会绕过打包安装用于插件拥有代码的 manifest 和运行时 sidecar 检查。
当某个辅助函数有意针对特定 provider,且尚不属于通用 SDK 子路径时,provider 插件可以暴露一个窄范围的插件本地契约 barrel 文件。内置示例:
- Anthropic:用于 Claude beta-header 和
service_tier流辅助函数的公共api.ts/contract-api.ts接口。 @openclaw/openai-provider:api.ts导出 provider 构建器、默认模型辅助函数以及实时 provider 构建器。@openclaw/openrouter-provider:api.ts导出 provider 构建器以及引导/配置辅助函数。
Warning
扩展生产代码也应避免 openclaw/plugin-sdk/<other-plugin> 导入。如果某个辅助函数确实共享,应将其提升为中立的 SDK 子路径,例如 openclaw/plugin-sdk/speech、.../provider-model-shared 或其他面向 capability 的导出面,而不是将两个插件耦合在一起。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw