提供商字段

这些清单字段告知 core 某个 provider 能做什么以及如何访问它，而无需导入 provider 运行时。属于 Plugin manifest 参考的一部分；顶层字段参考列出了所有字段。

生成 Provider 元数据参考¶

生成 Provider 元数据字段描述在匹配的 contracts.*GenerationProviders 列表中声明的 Provider 的静态认证信号。OpenClaw 在 Provider 运行时加载之前读取这些字段，以便核心工具能够决定某个生成 Provider 是否可用，而无需导入每个 Provider 插件。

这些字段仅用于廉价的声明性事实。传输、请求转换、令牌刷新、凭据验证以及实际的生成行为都保留在插件运行时中。

{
  "contracts": {
    "imageGenerationProviders": ["example-image"]
  },
  "imageGenerationProviderMetadata": {
    "example-image": {
      "aliases": ["example-image-oauth"],
      "authProviders": ["example-image"],
      "configSignals": [
        {
          "rootPath": "plugins.entries.example-image.config",
          "overlayPath": "image",
          "mode": {
            "path": "mode",
            "default": "local",
            "allowed": ["local"]
          },
          "requiredAny": ["workflow", "workflowPath"],
          "required": ["promptNodeId"]
        }
      ],
      "authSignals": [
        {
          "provider": "example-image"
        },
        {
          "provider": "example-image-oauth",
          "providerBaseUrl": {
            "provider": "example-image",
            "defaultBaseUrl": "https://api.example.com/v1",
            "allowedBaseUrls": ["https://api.example.com/v1"]
          }
        }
      ]
    }
  }
}

每个元数据条目支持：

字段	必填	类型	含义
`aliases`	否	`string[]`	附加的 Provider ID，可视为该生成 Provider 的静态认证别名。
`authProviders`	否	`string[]`	已配置的认证配置文件应视为该生成 Provider 认证依据的 Provider ID。
`configSignals`	否	`object[]`	面向本地或自托管 Provider 的廉价纯配置可用性信号；这些 Provider 无需认证配置文件或环境变量即可配置。
`authSignals`	否	`object[]`	显式认证信号。若存在，这些信号将替代由 provider id、`aliases` 和 `authProviders` 构成的默认信号集。
`referenceAudioInputs`	否	`boolean`	仅限视频生成。当 Provider 接受参考音频资源时设为 `true`；否则 `video_generate` 会隐藏音频参考参数。

每个 configSignals 条目支持：

字段	必填	类型	含义
`rootPath`	是	`string`	指向要检查的插件自有配置对象的点路径，例如 `plugins.entries.example.config`。
`overlayPath`	否	`string`	根配置内部的点路径，其对象应在评估信号前覆盖根对象。用于能力特定的配置，例如 `image`、`video` 或 `music`。
`overlayMapPath`	否	`string`	根配置内部的点路径，其对象值应逐一覆盖根对象。用于命名账户映射（如 `accounts`），其中任何已配置的账户都应符合条件。
`required`	否	`string[]`	有效配置内必须具有已配置值的点路径。字符串必须非空；对象和数组不得为空。
`requiredAny`	否	`string[]`	有效配置内的点路径，其中至少一个必须具有已配置值。
`mode`	否	`object`	有效配置内的可选字符串模式守卫。当纯配置可用性仅适用于某一种模式时使用。

每个 mode 守卫支持：

字段	必填	类型	含义
`path`	否	`string`	有效配置内的点路径。默认为 `mode`。
`default`	否	`string`	当配置省略该路径时使用的模式值。
`allowed`	否	`string[]`	若存在，仅当有效模式为这些值之一时，信号才通过。
`disallowed`	否	`string[]`	若存在，当有效模式为这些值之一时，信号失败。

每个 authSignals 条目支持：

字段	必填	类型	含义
`provider`	是	`string`	要在已配置的认证配置文件中检查的提供程序 ID。
`providerBaseUrl`	否	`object`	可选的保护条件：仅当所引用的已配置提供程序使用允许的 base URL 时，该信号才会计入。当某个认证别名仅对特定 API 有效时，请使用此选项。

每个 providerBaseUrl 保护条件支持：

字段	必填	类型	含义
`provider`	是	`string`	需要检查其 `baseUrl` 的提供程序配置 ID。
`defaultBaseUrl`	否	`string`	当提供程序配置省略 `baseUrl` 时采用的 Base URL。
`allowedBaseUrls`	是	`string[]`	此认证信号允许的 Base URL 列表。当配置的或默认的 base URL 与这些规范化值中的任何一个不匹配时，该信号将被忽略。

mediaUnderstandingProviderMetadata 参考¶

当媒体理解型提供程序具有默认模型、自动认证回退优先级或原生文档支持，而通用核心辅助程序需要在运行时加载前了解这些信息时，请使用 mediaUnderstandingProviderMetadata。这些键还必须在 contracts.mediaUnderstandingProviders 中声明。

{
  "contracts": {
    "mediaUnderstandingProviders": ["example"]
  },
  "mediaUnderstandingProviderMetadata": {
    "example": {
      "capabilities": ["image", "audio"],
      "defaultModels": {
        "image": "example-vision-latest",
        "audio": "example-transcribe-latest"
      },
      "autoPriority": {
        "image": 40
      },
      "nativeDocumentInputs": ["pdf"],
      "documentModels": {
        "pdf": {
          "textExtraction": "example-doc-text-latest",
          "image": "example-doc-vision-latest"
        }
      }
    }
  }
}

每个提供程序条目可包含：

字段	类型	含义
`capabilities`	`("image" \\| "audio" \\| "video")[]`	此提供程序公开的媒体能力。
`defaultModels`	`Record<string, string>`	在配置未指定模型时使用的功能到模型默认值映射。
`autoPriority`	`Record<string, number>`	数字越低，在基于凭据的自动提供程序回退中排序越靠前。
`nativeDocumentInputs`	`"pdf"[]`	提供程序支持的原生文档输入。
`documentModels`	`{ pdf?: { textExtraction?: string; image?: string \\| false } }`	按文档类型划分的模型覆盖项。将 `image: false` 可禁用该文档类型的基于图像的提取。

providerEndpoints 参考¶

使用 providerEndpoints 进行端点分类，通用请求策略必须在提供程序运行时加载之前了解这些端点分类。核心仍然拥有每个 endpointClass 的含义；插件清单拥有主机和 base URL 元数据。

当操作员设置 models.providers.<id>.baseUrl 时，同一端点元数据控制隐式模型目录的资格。目录、别名和原生模型的 base URL 也计为已声明的端点。不匹配的提供程序级 URL 会排除清单中的、发现的、静态的和生成的目录行；显式编写的模型仍保留在清单中。没有原生端点声明的插件保持其现有的发现行为。主机和后缀匹配保留其请求分类规则，因此目录资格并不建立精确来源信任，也不能证明请求一定成功。

已正式外部化的提供程序插件不包含在核心发行版中，因此其清单在安装之前不可见。它们的 providerEndpoints 还必须在 scripts/lib/official-external-provider-catalog.json 中镜像，以便在没有该插件的情况下端点分类仍能正常工作；契约测试会强制检查镜像一致性。

端点字段：

字段	类型	含义
`endpointClass`	`string`	已知的核心端点类，例如 `openrouter`、`moonshot-native` 或 `google-vertex`。
`hosts`	`string[]`	映射到该端点类的确切主机名。
`hostSuffixes`	`string[]`	映射到该端点类的主机后缀。以 `.` 开头仅匹配域名后缀。
`baseUrls`	`string[]`	映射到该端点类的规范化 HTTP(S) 基础 URL。
`googleVertexRegion`	`string`	用于精确全局主机的静态 Google Vertex 区域。
`googleVertexRegionHostSuffix`	`string`	从匹配的主机中移除的后缀，以暴露 Google Vertex 区域前缀。

providerRequest 参考¶

对于通用请求策略所需的低成本请求兼容性元数据，请使用 providerRequest，无需加载提供程序运行时。将特定于行为的负载重写保留在提供程序运行时钩子或共享的提供程序族辅助函数中。

{
  "providerRequest": {
    "providers": {
      "vllm": {
        "family": "vllm",
        "openAICompletions": {
          "supportsStreamingUsage": true
        }
      }
    }
  }
}

提供程序字段：

字段	类型	含义
`family`	`string`	提供程序族标签，用于通用请求兼容性决策和诊断。
`compatibilityFamily`	`"moonshot"`	可选提供程序族兼容性类别，用于共享的请求辅助函数。
`openAICompletions`	`object`	OpenAI 兼容的补全请求标志。`supportsStreamingUsage` 是唯一标志。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw