跳转至

导入与模块布局

应从哪个 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