OpenClaw 接入百度千帆Qianfan统一 API 密钥打通 DeepSeek 与 ERNIE 多模型【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本篇技术指南围绕 OpenClaw 官方外部插件openclaw/qianfan-provider展开讲解如何通过百度千帆QianfanMaaS 平台的 OpenAI 兼容 API以单一端点与单一密钥接入 DeepSeek、ERNIE 等多个大模型并深入源码级原理与配置实操。读者学完后将能独立完成千帆插件的安装、API Key 开通、onboarding 引导、模型目录核验以及自定义 Base URL 与模型元数据的完整配置。Qianfan 是什么一个端点、一把密钥、多个模型Qianfan 是百度的 MaaSModel-as-a-Service平台其核心价值在于提供了一个统一、且与 OpenAI 兼容的 API它把许多模型的路由请求收敛在同一个端点和同一把 API Key之后。OpenClaw 将千帆以官方外部插件openclaw/qianfan-provider的形式内置集成插件源码位于 extensions/qianfan文档本体见 docs/providers/qianfan.md。插件的基础属性如下表PropertyValueProviderqianfanAuthQIANFAN_API_KEYAPIOpenAI-compatible (openai-completions)Base URLhttps://qianfan.baidubce.com/v2Default modelqianfan/deepseek-v4-pro这些属性并非仅仅写在文档里而是同时硬编码在插件源码中extensions/qianfan/provider-catalog.ts中导出了QIANFAN_BASE_URL https://qianfan.baidubce.com/v2与QIANFAN_DEFAULT_MODEL_ID deepseek-v4-pro插件清单 extensions/qianfan/openclaw.plugin.json 中同样登记了baseUrl、api: openai-completions以及模型目录。也就是说文档与实现保持一致可直接信赖。安装插件两条命令完成接入在 OpenClaw 中安装千帆插件非常轻量执行官方插件的安装命令并重启 Gateway 即可openclaw plugins install openclaw/qianfan-provider openclaw gateway restart从插件清单 extensions/qianfan/openclaw.plugin.json 可以看到该插件声明了两种安装来源clawhub:openclaw/qianfan-provider与npmSpec: openclaw/qianfan-provider默认走 npm并要求宿主版本minHostVersion: 2026.6.8、插件 API 兼容pluginApi: 2026.9.4。同时插件的activation.onStartup为falseenabledByDefault为true属于随装随用的被动激活型插件。快速开始从创建密钥到验证模型第一步创建百度智能云账号前往千帆控制台的 API Key 管理页面https://console.bce.baidu.com/qianfan/ais/console/apiKey注册或登录并确认已开通千帆 API 访问权限。第二步生成 API Key创建新应用或选用已有应用然后生成 API Key。百度智能云的密钥采用bce-v3/ALTAK-...格式这是后续排查配置问题时的首要检查点。第三步运行 onboarding 引导openclaw onboard --auth-choice qianfan-api-key该命令是交互式引导非交互式运行则从--qianfan-api-key key参数或QIANFAN_API_KEY环境变量读取密钥。Onboarding 完成后会自动完成三件事写入 provider 配置API 类型与 Base URL为默认模型添加QIANFAN别名在未显式配置默认模型时将qianfan/deepseek-v4-pro设为默认模型。从源码看这一步的实际行为由 extensions/qianfan/onboard.ts 中的applyQianfanConfig实现它通过createDefaultModelsPresetAppliers将primaryModelRef设置为qianfan/deepseek-v4-pro并把aliases生成为[{ modelRef: qianfan/deepseek-v4-pro, alias: QIANFAN }]。注意一个细节resolveQianfanPreset会优先读取用户配置中已有的models.providers.qianfan.baseUrl只有为空时才回退到官方默认地址这保证了自定义端点的用户配置不会被 onboarding 覆盖。第四步验证模型可用openclaw models list --provider qianfan执行后应能看到下方内置目录中的模型 ref。若列表为空请检查千帆服务是否已在百度智能云控制台开通。内置模型目录静态目录无动态发现千帆插件的模型目录是静态的不存在实时模型发现机制。当前插件内置的模型如下Model refInputContextMax outputReasoningNotesqianfan/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取代上述目录完整对应 extensions/qianfan/openclaw.plugin.json 中modelCatalog.providers.qianfan.models的 5 个条目并通过extensions/qianfan/index.test.ts中的builds the static Qianfan model catalog测试用例逐一断言包括每个模型的id、name、reasoning、input、contextWindow、maxTokens与cost字段。测试还专门校验了两个已弃用模型的迁移关系deepseek-v3.2→replacedBy: deepseek-v4-proernie-5.0-thinking-preview→replacedBy: ernie-5.0两者都标记为status: deprecated且“仍可通过精确引用使用”即旧配置中的 ref 不会立刻失效但新接入应以新版模型为准。关于静态目录文档特别强调两点使用原则Setup 只保存连接设置与别名不会把生成的目录行复制进你的配置文件显式设置models.mode: replace可以保持目录注入catalog seeding开启同时你自定义的模型行保持不变。这一点有测试直接佐证index.test.ts中的it.each用例覆盖了mode为undefined、merge、replace三种情况验证applyQianfanConfig在非 replace 模式下不会把目录模型写入models.providers.qianfan.models为空数组只有replace模式才写入全部 5 个模型 ID而无论哪种模式primary都会被解析为qianfan/deepseek-v4-pro。提示只有在需要自定义 Base URL 或模型元数据时才需要覆盖models.providers.qianfan。配置示例详解显式选用 DeepSeek 旗舰下面的示例显式选择了当前 DeepSeek 旗舰模型这与 onboarding 设默认模型时的选择一致{ 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, }, ], }, }, }, }字段含义与取值范围env.vars.QIANFAN_API_KEY千帆 API Key必须以bce-v3/ALTAK-开头。也可以不写进配置文件改用环境变量注入onboarding 与运行时均支持该变量。agents.defaults.model.primaryAgent 的默认主模型 ref格式为qianfan/model-id。agents.defaults.models为模型 ref 绑定快捷别名alias: QIANFAN让你在对话或配置中直接用QIANFAN指代该模型。models.providers.qianfan.baseUrl默认https://qianfan.baidubce.com/v2仅在使用自定义端点或代理时才需要改动。models.providers.qianfan.api固定为openai-completions标识走 OpenAI 兼容补全协议。models[].id模型 ID如deepseek-v4-pro与目录中的 id 一致。models[].reasoning布尔值标识是否为推理thinking模型影响调用方式与超时策略。models[].input支持的输入模态[text]或[text, image]后者见于 ERNIE 5.0。models[].cost计费元数据单位通常为美元/百万 token 量级包含input、output、cacheRead、cacheWrite四项。models[].contextWindow/models[].maxTokens上下文窗口与最大输出 token 数。需要特别说明模型 ref 统一使用qianfan/前缀例如qianfan/deepseek-v4-proqianfan/deepseek-v3.2。所有 ref 均指向插件内置目录或你的自定义 models 数组二者不可混淆。源码级原理插件如何注册与生效插件入口与 Provider 注册extensions/qianfan/index.ts 是整个插件的入口它调用defineSingleProviderPluginEntry注册一个单 Provider 插件id: qianfan、name: Qianfan Providerprovider.docsPath: /providers/qianfan即文档页面的路由manifestAuth.defaultModel与applyConfig直接引用 onboarding 模块导出的默认 ref 与配置应用函数catalog: { liveModelDiscovery: true, discoveryMode: strict }结合清单中discovery.qianfan: refreshable说明目录虽为静态内置但支持刷新机制可理解为允许后续通过插件更新刷新目录而非对千帆服务端做实时探测。index.test.ts的registers Qianfan with api-key auth wizard metadata用例进一步确认插件的envVars为[QIANFAN_API_KEY]auth 方法恰有一个api-key且qianfan-api-key这个 choice 能正确解析到{ providerId: qianfan, methodId: api-key }。认证配置的来源openclaw.plugin.json中的providerAuthChoices定义了向导元数据cliFlag: --qianfan-api-key即 onboarding 非交互模式使用的参数choiceId: qianfan-api-key对应文档中openclaw onboard --auth-choice qianfan-api-key的值appGuidedSecret: true表示密钥可通过应用引导方式安全录入。目录构建provider-catalog.ts中的buildQianfanProvider()通过buildManifestModelProviderConfig从插件清单的modelCatalog构建ModelProviderConfig因此清单 JSON 是模型目录的唯一事实来源这也是文档目录是静态的在实现层面的体现。传输与兼容性说明千帆走的是OpenAI 兼容传输路径openai-completions而非 OpenAI 原生请求整形request shaping。这意味着标准 OpenAI SDK 的能力开箱即用千帆特有、非标准的 provider 参数可能不会被转发。如果你依赖千帆的私有扩展参数请先在配置中验证实际请求行为或通过自定义端点/代理做适配。故障排查清单确认 API Key 以bce-v3/ALTAK-开头并且已在百度智能云控制台开通千帆 API 访问权限如果openclaw models list --provider qianfan列不出模型先确认账号已激活千帆服务仅在确实使用自定义端点或代理时才改动baseUrl默认值应保持https://qianfan.baidubce.com/v2使用旧模型 ref如deepseek-v3.2、ernie-5.0-thinking-preview时注意其已标记 deprecated新环境请迁移至deepseek-v4-pro与ernie-5.0。延伸阅读模型与 Provider 选择docs/concepts/model-providers.md了解 provider 选择、模型 ref 与故障转移failover行为。OpenClaw 配置参考docs/gateway/configuration-reference.md完整的配置项参考。Agent 配置docs/concepts/agent.md配置 agent 默认值与模型分配。插件自身说明见 extensions/qianfan/README.md测试用例见 extensions/qianfan/index.test.ts。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考