导入与模块布局

应导入哪个 openclaw/plugin-sdk/* 子路径，以及如何组织插件自身的公共 barrel 和内部 barrel。属于 插件 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 子路径不是新插件应采用的模式。

对于只需要凭据值的 provider 发现，使用 openclaw/plugin-sdk/secret-input 来调用 readProviderEnvValue、 resolveNonEnvSecretRefApiKeyMarker 以及 SecretRef 强制转换/规范化。 这些辅助函数不会加载 profile 存储、provider 传输或 web-search 执行。使用 provider-web-search-config-contract 读取插件拥有的 web-search 配置。将完整的 auth 和搜索运行时导入保留在执行路径中。

子路径参考¶

插件 SDK 以一组按领域分组的窄子路径形式暴露（插件 入口、通道、provider、认证、运行时、能力、内存以及保留的 捆绑插件辅助函数）。要查看完整目录——按组并带链接——请参阅 插件 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)

通过 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 构建器 以及入门/配置辅助函数。