跳转至

提供商字段

用于告知核心某个提供商能够执行哪些操作以及如何访问它的清单字段,且无需导入提供商运行时。属于 插件清单 参考的一部分;顶级字段参考 列出了所有字段。

生成提供商元数据参考

生成提供商元数据字段描述为匹配的 contracts.*GenerationProviders 列表中声明的提供商提供的静态认证信号。OpenClaw 会在提供商运行时加载之前读取这些字段,以便核心工具能够在不导入每个提供商插件的情况下判断某个生成提供商是否可用。

仅将这些字段用于低成本、声明式的事实。传输、请求转换、Token 刷新、凭据验证以及实际生成行为仍保留在插件运行时中。

{
  "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[] 应被视为该生成提供商静态认证别名的其他提供商 ID。
authProviders 否 string[] 其已配置的认证配置文件应被视为该生成提供商认证的提供商 ID。
configSignals 否 object[] 针对本地或自托管提供商的低成本、仅配置可用性信号;这些提供商无需认证配置文件或环境变量即可配置。
authSignals 否 object[] 显式认证信号。存在时,这些信号会替换来自提供商 ID、aliases 和 authProviders 的默认信号集。
referenceAudioInputs 否 boolean 仅用于视频生成。当提供商接受参考音频资产时,将其设置为 true;否则 video_generate 会隐藏音频参考参数。

每个 configSignals 条目支持:

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

配置信号会检查规范 SecretRefs,以判断提供商和环境可用性。 其他非空对象是已配置元数据;仅包含 source 和 id 的对象不会被解释为 SecretRef。Doctor 会修复已声明凭据路径上的旧引用, 而不会重写不透明的插件数据。

每个 mode 守卫支持:

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

每个 authSignals 条目支持:

字段 是否必填 类型 含义
provider 是 string 要在已配置的 auth profiles 中检查的 provider id。
providerBaseUrl 否 object 可选守卫,仅当所引用的已配置 provider 使用允许的 base URL 时,该信号才生效。当 auth alias 仅对某些 API 有效时使用此项。

每个 providerBaseUrl 守卫支持:

字段 是否必填 类型 含义
provider 是 string 需要检查其 baseUrl 的 provider 配置 id。
defaultBaseUrl 否 string 当 provider 配置省略 baseUrl 时,假定使用的 base URL。
allowedBaseUrls 是 string[] 此 auth signal 允许的 base URL。当已配置或默认 base URL 不匹配这些规范化值之一时,该信号会被忽略。

mediaUnderstandingProviderMetadata 参考

当媒体理解 provider 具有默认模型、自动身份验证回退优先级或原生文档支持,且通用核心辅助函数需要在运行时加载前获取这些信息时,使用 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"
        }
      }
    }
  }
}

每个 provider 条目可以包含:

字段 类型 含义
capabilities ("image" \| "audio" \| "video")[] 此 provider 暴露的媒体能力。
defaultModels Record<string, string> 当配置未指定模型时使用的能力到模型默认值。
autoPriority Record<string, number> 对于基于凭据的自动 provider 回退,数值越小排序越靠前。
nativeDocumentInputs "pdf"[] provider 支持的原生文档输入。
documentModels { pdf?: { textExtraction?: string; image?: string \| false } } 按文档类型的模型覆盖。将 image: false 设置为禁用该文档类型的基于图像的提取。

providerEndpoints 参考

使用 providerEndpoints 进行端点分类,通用请求策略需要在 provider 运行时加载前了解该分类。核心仍负责每个 endpointClass 的含义;插件清单负责 host 和 base URL 元数据。

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

官方外部化的 provider 插件不包含在核心 dist 中,因此 它们的清单在安装前不可见。它们的 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 存储低开销的请求兼容性元数据,供通用请求策略在不加载 provider 运行时的情况下使用。将行为特定的 payload 重写保留在 provider 运行时钩子或共享 provider 家族辅助函数中。

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

Provider 字段:

字段 类型 含义
family string 用于通用请求兼容性判断和诊断的 provider 家族标签。
compatibilityFamily "moonshot" 用于共享请求辅助函数的可选 provider 家族兼容性分组。
openAICompletions object OpenAI 兼容 completions 请求标志。supportsStreamingUsage 是唯一标志。

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