OpenClaw Qianfan 插件指南：从 @openclaw/qianfan-provider 的分发、接入到模型目录源码实现
OpenClaw Qianfan 插件指南从 openclaw/qianfan-provider 的分发、接入到模型目录源码实现【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文以 OpenClaw 仓库中的插件参考文档 docs/plugins/reference/qianfan.md 为主体讲清 Qianfan 官方插件的分发方式、安装路径与 Provider Surface并结合 extensions/qianfan 下的插件入口、模型目录、Onboard 模块及其测试用例深入拆解该插件从注册、鉴权到默认模型落盘的完整实现链路。读完本文你可以独立完成 Qianfan 插件的安装与配置并理解其静态模型目录与配置写入逻辑在源码层的真实行为。插件定位与分发方式Qianfan 是百度的 MaaSModel as a Service平台提供统一的 OpenAI 兼容 API可以在单一端点、单一 API Key 背后路由到多个模型。OpenClaw 将其以官方外部插件openclaw/qianfan-provider的形式提供参考文档将其定位为“为 OpenClaw 增加 Qianfan 模型供应商支持”的插件。分发信息来自参考文档 docs/plugins/reference/qianfan.md 及插件 package.json属性值包名openclaw/qianfan-provider安装途径npm或 ClawHubclawhub:openclaw/qianfan-provider当前版本2026.9.3宿主最低版本minHostVersion: 2026.6.8插件 API 兼容pluginApi: 2026.9.3发布渠道publishToClawHub: true且publishToNpm: true默认选择 npmdefaultChoice: npm内置产物bundledDist: false不以预构建产物形式内置安装并重启 Gateway 的标准操作为openclaw plugins install openclaw/qianfan-provider openclaw gateway restart从插件清单 openclaw.plugin.json 看该插件enabledByDefault为true但activation.onStartup为false——从源码结构看即插件默认启用而不在 Gateway 启动时立即激活具体请求时才加载 Provider。Provider Surface 与鉴权注册参考文档明确该插件的 Surface能力面只暴露一个 Providerqianfan。在 openclaw.plugin.json 中这一声明具体落实为providers: [qianfan]插件对外注册的 Provider IDsetup.providers声明qianfan支持api-key鉴权方式环境变量为QIANFAN_API_KEYproviderAuthChoices定义了 Onboarding 向导中的鉴权选项——choiceId: qianfan-api-key、method: api-key、appGuidedSecret: true应用引导式密钥录入CLI 旗标为--qianfan-api-key key分组标识groupId: qianfan。插件入口 index.ts 通过插件 SDK 的单 Provider 注册器完成集成export default defineSingleProviderPluginEntry({ id: PROVIDER_ID, name: Qianfan Provider, description: Bundled Qianfan provider plugin, manifest, provider: { label: Qianfan, docsPath: /providers/qianfan, manifestAuth: { defaultModel: QIANFAN_DEFAULT_MODEL_REF, applyConfig: applyQianfanConfig, }, catalog: { liveModelDiscovery: true, discoveryMode: strict }, }, });可以看到三处关键接线manifest直接导入自 openclaw.plugin.json即模型目录、鉴权选项都来自这份清单文件manifestAuth把默认模型引用QIANFAN_DEFAULT_MODEL_REF与配置写入器applyQianfanConfig来自 onboard.ts绑定到 Provider入口还声明catalog: { liveModelDiscovery: true, discoveryMode: strict }。需注意官方 Provider 文档同时指出“目录是静态的没有实时模型发现The catalog is static; there is no live model discovery”且清单中discovery字段标注为refreshable——从源码结构看请求路由仍基于清单里的静态模型行这里的 strict/refreshable 语义更多体现在目录刷新策略上而非动态拉取模型列表。extensions/qianfan/index.test.ts 的第一个用例验证了注册结果Provider ID 为qianfan、label 为Qianfan、docsPath 为/providers/qianfan、envVars恰为[QIANFAN_API_KEY]且鉴权选项qianfan-api-key能解析到providerId: qianfanmethodId: api-key这一唯一组合。静态模型目录五个模型、分层计价与废弃项Qianfan 插件的模型目录完整定义在 openclaw.plugin.json 的modelCatalog.providers.qianfan字段中由 provider-catalog.ts 构建export const QIANFAN_BASE_URL https://qianfan.baidubce.com/v2; export const QIANFAN_DEFAULT_MODEL_ID deepseek-v4-pro; export function buildQianfanProvider(): ModelProviderConfig { return buildManifestModelProviderConfig({ providerId: qianfan, catalog: manifest.modelCatalog.providers.qianfan, }); }即 Base URL 固定为https://qianfan.baidubce.com/v2API 类型为openai-completions默认模型 ID 为deepseek-v4-pro。目录内容与 Provider 文档 docs/providers/qianfan.md 中的 Built-in catalog 一致如下模型引用输入上下文窗口最大输出推理说明qianfan/deepseek-v4-protext1,000,000393,216Yes当前 DeepSeek 旗舰模型qianfan/ernie-5.1text128,00065,536No最新 ERNIE 文本旗舰qianfan/ernie-5.0text, image128,00065,536Yes当前多模态与思考模型qianfan/deepseek-v3.2text128,00032,768No已废弃的 Onboarding 兼容默认值由deepseek-v4-pro取代qianfan/ernie-5.0-thinking-previewtext, image128,00065,536Yes已废弃别名由ernie-5.0取代清单中每个模型行还携带cost字段含input/output/cacheRead/cacheWrite数值其中ernie-5.1、ernie-5.0、deepseek-v3.2、ernie-5.0-thinking-preview额外定义了tieredPricing分层计价上下文长度在[0, 32001]区间与超过 32,001 token 时适用两档不同的输入/输出价格。两个废弃模型行则带有status: deprecated、statusReason与replacedBy字段——例如deepseek-v3.2的replacedBy指向deepseek-v4-pro且注明“仍可通过精确引用使用但新的 Qianfan 配置应改用 deepseek-v4-pro”。extensions/qianfan/index.test.ts 的第二个用例对该静态目录做了强断言目录顺序必须是deepseek-v4-pro → ernie-5.1 → ernie-5.0 → deepseek-v3.2 → ernie-5.0-thinking-preview五个模型的contextWindow、maxTokens、reasoning、input与cost含分层计价区间逐字段匹配并验证两个废弃行的status: deprecated与replacedBy映射。Onboarding 流程openclaw onboard 如何写入配置官方文档给出的完整接入步骤如下创建百度智能云账号在 Qianfan 控制台注册或登录并确保已开通 Qianfan API 访问权限生成 API Key新建或选择已有应用后生成密钥百度智能云密钥格式为bce-v3/ALTAK-...运行 Onboardingopenclaw onboard --auth-choice qianfan-api-key非交互运行下密钥从--qianfan-api-key key或环境变量QIANFAN_API_KEY读取。Onboarding 会写入 Provider 配置为默认模型添加QIANFAN别名并在未配置任何模型时将qianfan/deepseek-v4-pro设为默认模型验证模型可用openclaw models list --provider qianfan这些行为在源码 onboard.ts 中有明确对应QIANFAN_DEFAULT_MODEL_REF被定义为qianfan/${QIANFAN_DEFAULT_MODEL_ID}即qianfan/deepseek-v4-proresolveQianfanPreset(cfg)会读取已有配置中的models.providers.qianfan若用户已显式设置baseUrl非空字符串则保留否则回落到QIANFAN_BASE_URLapi同理默认openai-completions别名固定写入为{ modelRef: qianfan/deepseek-v4-pro, alias: QIANFAN }由createDefaultModelsPresetAppliers统一应用。一个容易忽略的细节是defaultModels的取值逻辑cfg.models?.mode replace ? (buildQianfanProvider().models ?? []) : []——只有显式models.mode: replace时Onboarding 才会把目录模型行写入配置其余模式下配置中不落普通目录行仅保存连接设置与别名。index.test.ts 用参数化用例逐模式验证了这一点models.mode主模型落盘结果写入配置的模型行undefinedqianfan/deepseek-v4-pro无mergeqianfan/deepseek-v4-pro无replaceqianfan/deepseek-v4-pro全部 5 个目录模型这与 Provider 文档中的说明一致“Setup 只保存连接设置与别名不会把生成的目录行复制进你的配置显式models.mode: replace会保持目录播种catalog seeding启用自定义模型行不受影响。”配置示例与自定义覆盖Provider 文档提供了一个显式选择当前 DeepSeek 旗舰也是 Onboarding 默认值的完整配置示例可复制到openclaw.json使用{ env: { vars: { QIANFAN_API_KEY: bce-v3/ALTAK-... } }, agents: { defaults: { model: { primary: qianfan/deepseek-v4-pro }, models: { qianfan/deepseek-v4-pro: { alias: QIANFAN }, }, }, }, models: { providers: { qianfan: { baseUrl: https://qianfan.baidubce.com/v2, api: openai-completions, models: [ { id: deepseek-v4-pro, name: DeepSeek V4 Pro, reasoning: true, input: [text], cost: { input: 1.771957, output: 3.543915, cacheRead: 0.147663, cacheWrite: 0, }, contextWindow: 1000000, maxTokens: 393216, }, ], }, }, }, }要点模型引用统一使用qianfan/前缀例如qianfan/deepseek-v4-pro官方文档给出的建议是只有需要自定义 Base URL 或模型元数据时才需要覆写models.providers.qianfan其余场景用 Onboarding 生成的默认连接设置即可结合resolveQianfanPreset的实现可以确认你对baseUrl、api的自定义会被 Onboarding 保留而不会被默认值覆盖。清单中的configSchema为空对象type: object、additionalProperties: false、properties: {}从源码结构看该插件本身不引入额外的插件级配置字段所有可调项都走标准的models.providers.qianfan配置面。传输路径、兼容性与故障排查传输路径Qianfan 走 OpenAI 兼容传输路径openai-completions而非原生 OpenAI 请求塑形。标准 OpenAI SDK 特性可用但供应商特定参数可能不会被转发鉴权排查确认 API Key 以bce-v3/ALTAK-开头且已在百度智能云控制台开通 Qianfan API 访问模型列表为空确认账号已激活 Qianfan 服务Base URL仅在自研端点或代理场景下才修改baseUrl默认值https://qianfan.baidubce.com/v2来自 provider-catalog.ts 中的常量。相关文档与源码位置围绕本插件可进一步阅读的文件均为仓库相对路径docs/plugins/reference/qianfan.md本插件的参考文档由pnpm plugins:inventory:gen生成手工内容仅保留在 manual 标记注释之间docs/providers/qianfan.mdQianfan Provider 的完整接入与配置指南extensions/qianfan/index.ts插件入口与 Provider 注册extensions/qianfan/openclaw.plugin.jsonProvider、鉴权选项与静态模型目录清单extensions/qianfan/onboard.tsOnboarding 配置写入器与默认模型/别名逻辑extensions/qianfan/provider-catalog.tsBase URL、默认模型 ID 与目录构建extensions/qianfan/index.test.ts注册、目录内容与各models.mode落盘行为的测试验证。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考