接入腾讯混元与百度千帆：大厂 MaaS 实战

OpenClaw 接入混元与百度千帆，是国产模型专页的第七站，这一页一次讲两家：腾讯混元（TokenHub / TokenPlan 双端点）和百度千帆（Qianfan MaaS）。两家各配各的插件、各拿各的 Key，但接入套路和前几课完全一致。

DeepSeek、Qwen、GLM、Kimi、MiniMax、豆包的「装插件 → 配凭据 → 选模型」三步在这一课照常适用。全程约 10 分钟（腾讯云 / 百度智能云账号注册另计）。

先给你一张总表，本课所有配置都从它出发（属性与值为官方文档原样摘录）：

	腾讯混元	百度千帆
插件	`@openclaw/tencent-provider`	`@openclaw/qianfan-provider`
Provider id	`tencent-tokenhub`、`tencent-tokenplan`	`qianfan`
认证	`TOKENHUB_API_KEY` / `TOKENPLAN_API_KEY`	`QIANFAN_API_KEY`（`bce-v3/ALTAK-...` 格式）
端点	`https://tokenhub.tencentmaas.com/v1`（TokenHub） `https://api.lkeap.cloud.tencent.com/plan/v3`（TokenPlan）	`https://qianfan.baidubce.com/v2`
API	OpenAI 兼容（`openai-completions`）	同左
onboarding 默认	`tencent-tokenhub/hy4-preview`（TokenPlan 端同样选 `hy4-preview`）	`qianfan/deepseek-v4-pro`

两家的定位，两句话说清：

腾讯混元：模型是混元 hy 系列（hy4-preview、hy3），入口是腾讯云 TokenHub 与 TokenPlan 两个端点，两个 provider 各配各的 Key
百度千帆：MaaS 聚合平台，一把 Key 经统一 API 路由到文心 ERNIE 与千帆托管的 DeepSeek 等多家模型

💡 从「OpenClaw 接入文心」搜进来的朋友

文心（ERNIE）是百度的模型系列，OpenClaw 经百度千帆（Qianfan）这个 MaaS 平台接入——千帆统一 API 的后面不只有文心，还有千帆托管的 DeepSeek。注意：OpenClaw 百度千帆目录只收了 ernie-5.1 和 ernie-5.0，ERNIE 4.5、X1 等更早型号不在里面（文末踩坑提醒给了替代方案）。

本教程基于 OpenClaw v2026.10.9。

学完你能做什么

安装 @openclaw/tencent-provider 与 @openclaw/qianfan-provider 两个官方插件，注册 tencent-tokenhub、tencent-tokenplan、qianfan 三个 provider
分清腾讯双端点：TokenHub 与 TokenPlan 各有各的 Key 变量，onboarding 分别跑
OpenClaw 百度千帆一把 QIANFAN_API_KEY 路由文心 ERNIE 与千帆托管的 DeepSeek
看懂两家目录：混元 hy4-preview（1M 上下文）、文心 ernie-5.1（文本旗舰）/ ernie-5.0（多模态）各自的上下文与最大输出
避开大厂 MaaS 特有的坑：Key 受限范围漏模型、旧混元模型名不可用、百度 Key 格式、弃用 ID
给 OpenClaw 的记忆系统配上千帆中文向量模型（bge-large-zh）

🎒 开始前的准备

完成了连接模型总览：provider 体系与模型切换：「provider → 认证 → 选模型」三步和 provider/model 引用规则心里有数
OpenClaw 已安装、Gateway 在运行：openclaw gateway status 有输出
有腾讯云账号（配混元）或百度智能云账号（配千帆）至少其一——两家相互独立，只配一家完全没问题
走服务器 / 守护进程部署的话，知道 ~/.openclaw/.env 在哪——Key 最终要住那里

跟我做

第 1 步：安装腾讯混元与百度千帆 provider 插件

为什么：和 DeepSeek、豆包一样，tencent 与 qianfan 都是外部官方插件，OpenClaw 不自带——装上插件，provider 才会注册进模型体系。两家相互独立，只装你要的那家也行。

bash

# 1. 安装腾讯混元 provider 插件（TokenHub + TokenPlan 两个 provider 一起注册）
openclaw plugins install @openclaw/tencent-provider

# 2. 安装百度千帆 provider 插件
openclaw plugins install @openclaw/qianfan-provider

# 3. 重启 Gateway（Gateway 正在跑的话，安装会自动生效；重启最稳妥）
openclaw gateway restart

你应该看到：插件安装成功的提示，Gateway 重启后没有报错。

一个行为先知道（官方插件文档明确写了）：安装对正在运行的 Gateway 自动生效；Gateway 没在跑则下次启动时生效。

openclaw plugins install 执行成功（两家都装，或只装了你要的那家），Gateway 已重启

第 2 步：OpenClaw 接入混元——配好 TokenHub / TokenPlan 双端点

为什么：腾讯混元在 OpenClaw 里有两个入口——TokenHub（tencent-tokenhub）与 TokenPlan（tencent-tokenplan），对应腾讯云 MaaS 的两个产品端点。两个 provider 各有各的 Key 变量与 onboarding 入口，要分别跑一次。

先去腾讯云控制台创建 API Key。官方文档明确要求：如果建 Key 时选了受限的访问范围（access scope），允许的模型列表里必须包含 hy4 preview——计划在 TokenHub 上用 hy3 系的话，hy3 / hy3 preview 也要加进去。

然后跑 onboarding（两个端点各一次，官方文档原样）：

bash

# TokenHub 端点
openclaw onboard --auth-choice tokenhub-api-key

# TokenPlan 端点
openclaw onboard --auth-choice tokenplan-api-key

你应该看到：Key 验证通过并保存。官方文档明确写了：全新 onboarding 在两个端点上都选 hy4-preview 作默认模型；你已有的模型条目会被保留，不被覆盖。

CI / 脚本等非交互场景，官方文档给了直传 Key 的写法（原样）：

bash

# TokenHub
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice tokenhub-api-key \
  --tokenhub-api-key "$TOKENHUB_API_KEY" \
  --skip-health \
  --accept-risk

# TokenPlan
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice tokenplan-api-key \
  --tokenplan-api-key "$TOKENPLAN_API_KEY" \
  --skip-health \
  --accept-risk

不想跑 onboarding 的话，只设环境变量也认（官方文档原样）：

bash

export TOKENHUB_API_KEY="<你的 TokenHub Key>"
export TOKENPLAN_API_KEY="<你的 TokenPlan Key>"

⚠️ Gateway 跑成守护进程？Key 别放交互 shell

Gateway 作为 launchd / systemd 服务运行时，看不到你终端里 export 的环境变量。把 TOKENHUB_API_KEY 和 TOKENPLAN_API_KEY 写进 ~/.openclaw/.env，或经配置里的 env.shellEnv 提供给那个进程——tencent 官方文档特别强调了这一点。

顺手验证两个 provider 都注册了：

bash

openclaw models list --provider tencent-tokenhub
openclaw models list --provider tencent-tokenplan

你应该看到：tencent-tokenhub/ 与 tencent-tokenplan/ 两族模型都在列（目录详见第 4 步）。

还有一条给存量用户的官方迁移规则，先记住：已有 TokenHub 配置不会自动升到 Hy4。配了模型 allowlist 时，openclaw doctor --fix 只会把弃用的 tencent-tokenhub/hy3-preview 主模型改成 tencent-tokenhub/hy3。

目录对 hy3-preview 的推荐虽然是 hy4-preview，但 Doctor 不做这个迁移——升 Hy4 是显式动作，要自己确认所选端点的模型访问权限与价格差异。

openclaw models status 里能看到 tencent 的凭据来源

第 3 步：OpenClaw 接入百度千帆——配好 QIANFAN_API_KEY

为什么：千帆（Qianfan）是百度的 MaaS 平台——一个 OpenAI 兼容的统一 API，一把 Key 把请求路由到端点后面的多家模型。它只有一个 provider：qianfan，配一次就全通。

先去千帆控制台建 Key（官方文档给的直链）：

注册 / 登录百度智能云，进千帆控制台，开通千帆 API 访问
新建应用（或选已有应用），生成 API Key——百度云的 Key 长这样：bce-v3/ALTAK-...

然后跑 onboarding：

bash

openclaw onboard --auth-choice qianfan-api-key

你应该看到：Key 验证通过并保存。官方文档明确写了 onboarding 做三件事：写入 provider 配置、给默认模型加 QIANFAN 别名、在你没配过默认模型时把 qianfan/deepseek-v4-pro 设为默认。连接设置与别名会保存，但不会把生成的目录行拷进你的配置。

非交互场景读 --qianfan-api-key <key> 或环境变量 QIANFAN_API_KEY（官方文档原样）：

bash

export QIANFAN_API_KEY="bce-v3/ALTAK-<你的 Key>"

顺手验证：

bash

openclaw models list --provider qianfan

你应该看到：qianfan/ 前缀的模型目录在列（详见第 4 步）。列表为空的话，先查官方排障清单的前两条：Key 是不是以 bce-v3/ALTAK- 开头、百度云控制台里千帆服务是不是已开通。

openclaw models list --provider qianfan 能列出目录

第 4 步：选择混元 / 文心模型并验证

为什么：两家目录都不长，但各有讲究——混元只有 hy 系列三个 ID，千帆是静态目录（不走在线发现），里面还躺着已弃用的旧 ID，选错会踩坑。

先看腾讯混元目录（官方文档原样整理）：

模型引用	名称	输入	上下文	最大输出	备注
`tencent-tokenhub/hy4-preview`	hy4 preview（TokenHub）	文本	1,024,000	64,000	reasoning；默认
`tencent-tokenhub/hy3`	hy3（TokenHub）	文本	256,000	128,000	reasoning；上一代 GA
`tencent-tokenhub/hy3-preview`	hy3 preview（TokenHub）	文本	256,000	128,000	已弃用；用 `hy4-preview`
`tencent-tokenplan/hy4-preview`	hy4 preview（TokenPlan）	文本	1,024,000	64,000	reasoning；默认
`tencent-tokenplan/hy3`	hy3（TokenPlan）	文本	256,000	128,000	reasoning；上一代 GA

hy4-preview 是混元的大型 MoE 语言模型，面向推理、长上下文指令跟随、代码与 agent 工作流；腾讯的 OpenAI 兼容示例用它作 model id，支持标准 chat-completions 工具调用加 reasoning_effort。

再看百度千帆目录（官方文档原样整理）：

模型引用	输入	上下文	最大输出	Reasoning	备注
`qianfan/deepseek-v4-pro`	文本	1,000,000	393,216	有	当前 DeepSeek 旗舰
`qianfan/ernie-5.1`	文本	128,000	65,536	无	最新文心文本旗舰
`qianfan/ernie-5.0`	文本、图像	128,000	65,536	有	多模态 + thinking
`qianfan/deepseek-v3.2`	文本	128,000	32,768	无	已弃用兼容默认；被 `deepseek-v4-pro` 接替
`qianfan/ernie-5.0-thinking-preview`	文本、图像	128,000	65,536	有	已弃用别名；被 `ernie-5.0` 接替

千帆目录是静态内置的——官方文档原话「catalog is static; there is no live model discovery」，新模型要等 OpenClaw 插件更新目录。

怎么选，五句话：

你的需求	选它
要混元最新旗舰、1M 上下文推理	`tencent-tokenhub/hy4-preview`（onboarding 默认）
Key 在 TokenPlan 端点	`tencent-tokenplan/hy4-preview`
要文心最新文本旗舰	`qianfan/ernie-5.1`
要多模态输入 + thinking 的文心	`qianfan/ernie-5.0`
Key 在千帆、就想用 DeepSeek	`qianfan/deepseek-v4-pro`（onboarding 默认）

换默认模型：

bash

# 混元（注意前缀跟端点走）
openclaw models set tencent-tokenhub/hy4-preview

# 文心
openclaw models set qianfan/ernie-5.1

聊天里临时切也行：/model qianfan/ernie-5.0 只影响当前会话，命令族详见聊天命令速成。

最后验证。发一条测试消息：

bash

openclaw dashboard

打开 Control UI，在聊天框发一句「用一句话介绍你自己」。

你应该看到：模型正常回复，没有凭据缺失或模型不存在的报错。到这里，OpenClaw 接入混元与百度千帆就都通了。

价格一句话：TokenHub 官方文档没给价格；千帆配置示例里 deepseek-v4-pro 的目录估价是每百万 token 输入 1.771957 / 输出 3.543915 / 缓存读 0.147663（OpenClaw 目录数字）。实际价格与币种一律以腾讯云、百度智能云官网为准。

测试消息收到了回复，provider 与模型对得上（tencent-tokenhub/...、tencent-tokenplan/... 或 qianfan/...）

检查点 ✅

@openclaw/tencent-provider、@openclaw/qianfan-provider 至少装了你要用的那个（装上即生效）
混元双端点各配各的 Key：TOKENHUB_API_KEY（TokenHub）+ TOKENPLAN_API_KEY（TokenPlan）
千帆 Key 以 bce-v3/ALTAK- 开头，千帆服务已在百度智能云控制台开通
openclaw models list --provider tencent-tokenhub / --provider tencent-tokenplan / --provider qianfan 都能列出目录
默认模型前缀与端点配套：混元写 tencent-tokenhub/ 或 tencent-tokenplan/，千帆写 qianfan/
测试消息收到了回复

踩坑提醒

❌ 混元 Key 受限范围没包含 hy4 preview

现象：onboarding 验证不过，或混元模型列表缺失、调用被拒。

原因：腾讯云建 Key 时如果选了受限访问范围，允许模型列表里没有 hy4 preview——官方文档明确要求把它（以及计划在 TokenHub 用的 hy3 / hy3 preview）加进允许列表。

正确做法：回控制台改 Key 的允许模型范围，或换一把范围完整的 Key。

❌ 用旧混元模型名（hunyuan-turbo / hunyuan-larges 等）

现象：报未知模型。

原因：OpenClaw 的混元 provider 只有 hy 系列（hy4-preview、hy3、hy3-preview）——hunyuan-turbo、hunyuan-larges 这类旧名字在 TokenHub / TokenPlan 里不存在（信息源全量核对零命中）。

正确做法：用 tencent-tokenhub/hy4-preview（默认）或 hy3；旧模型需求走下一课的自定义兼容端点。

❌ 百度 Key 格式不对 / 千帆服务没开通

现象：openclaw models list --provider qianfan 列表为空，或调用报凭据错误。

原因：官方排障清单的前两条——Key 必须以 bce-v3/ALTAK- 开头；账号必须已在百度云控制台开通千帆 API 访问。

正确做法：回千帆控制台检查 Key 格式与服务开通状态。

❌ 在千帆目录里找 ERNIE 4.5 / X1 等更早型号

原因：千帆的 OpenClaw 目录只收了 ernie-5.1 和 ernie-5.0（静态目录，无在线发现）。

正确做法：更早的文心型号没有官方 provider——走下一课的「自定义 OpenAI 兼容端点」流程，或在 OpenRouter / NovitaAI 等聚合商找托管路由。

❌ 用了已弃用的旧 ID

已弃用 ID	接替者
`tencent-tokenhub/hy3-preview`	目录推荐 `hy4-preview`；`doctor --fix` 只迁到 `hy3`
`qianfan/deepseek-v3.2`	`qianfan/deepseek-v4-pro`
`qianfan/ernie-5.0-thinking-preview`	`qianfan/ernie-5.0`

正确做法：新配置一律用接替者；存量配置跑 openclaw doctor 看提示再迁。

❌ Gateway 装成守护进程后，export 的 Key「不生效」

原因：launchd / systemd 服务看不到交互 shell 的环境变量——tencent 官方文档特别强调这一点（TokenHub 与 TokenPlan 两个变量都要给到服务进程）。

正确做法：TOKENHUB_API_KEY、TOKENPLAN_API_KEY、QIANFAN_API_KEY 写进 ~/.openclaw/.env，或经 env.shellEnv 提供；换 Key 后重启 Gateway 服务。

❌ 以为 doctor --fix 会帮你升到 Hy4

原因：官方迁移规则——配了 allowlist 的存量 TokenHub 配置，openclaw doctor --fix 只把弃用的 hy3-preview 改成 hy3，不改成 Hy4。

正确做法：升 Hy4 自己显式操作（openclaw models set tencent-tokenhub/hy4-preview），先确认所选端点的模型访问权限与价格差异。

❌ 海外账号硬连国内端点（或反过来）

原因：TokenHub 内置端点是 https://tokenhub.tencentmaas.com/v1；国际版端点 https://tokenhub-intl.tencentmaas.com/v1 需要显式覆盖 baseUrl。

正确做法：海外 TokenHub 账号按下一节覆盖 baseUrl；千帆同理，只有用自定义端点 / 代理时才改 base URL。

🔧 进阶：端点覆盖与千帆记忆嵌入（可选）

覆盖 TokenHub 端点（国际版 / 特殊区域）

内置目录用的是 https://tokenhub.tencentmaas.com/v1。只有当你的 TokenHub 账号或区域要求不同端点时才覆盖（官方示例原样，这里以国际版端点为例）：

bash

openclaw config set models.providers.tencent-tokenhub.baseUrl "https://tokenhub-intl.tencentmaas.com/v1"

给记忆系统配千帆中文向量模型

OpenClaw 的记忆检索需要 embedding 模型，千帆插件能直接当 embedding provider 用——对中文内容特别合适（官方示例原样）：

json5

{
  memory: {
    search: {
      provider: "qianfan",
      model: "bge-large-zh",
    },
  },
}

三个细节（官方文档明确写了）：

插件复用你配好的千帆连接，凭据从保存的 profile 或 QIANFAN_API_KEY 解析；显式的远程 API Key / Authorization header 优先
bge-large-zh、bge-large-en、Embedding-V1 三个模型每次请求最多 16 条输入（遵循百度官方批量限制），其他模型沿用兼容传输的既有行为
已有配置如果用 openai-compatible 指向千帆，把 memory.search.provider 改成 qianfan 即可——端点和 Key 保持不变

记忆系统本身见记忆系统：让 Claw 记住你。

需要自定义元数据时才写 models.providers

官方规则：插件装好 + auth 配好就够，不需要写 models.providers 条目；只有覆盖 baseUrl 或模型元数据时才写。千帆的完整显式配置长这样（官方示例原样节选）：

json5

{
  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,
          },
        ],
      },
    },
  },
}

还有一条兼容性说明（官方文档原意）：千帆走 OpenAI 兼容传输路径，不是原生 OpenAI 请求 shaping——标准 OpenAI SDK 特性可用，但 provider 专属参数可能不被转发。千帆 API 的官方文档见 cloud.baidu.com/doc/qianfan-api。

下一步

OpenClaw 接入混元与百度千帆到此通关。国产模型专页继续走：

下一课更多国产模型与自定义中转端点：星火、百川等没有官方 provider 的模型，以及 OpenRouter / LiteLLM / 自定义中转的玩法
其他模型专页（本地模型）从连接模型总览的课程表进
模型配好了？日常使用从日常使用：和你的 Claw 高效相处开始——Control UI、聊天命令、记忆系统都在那一章

接入腾讯混元与百度千帆：大厂 MaaS 实战 ​

学完你能做什么 ​

🎒 开始前的准备 ​

跟我做 ​

第 1 步：安装腾讯混元与百度千帆 provider 插件 ​

第 2 步：OpenClaw 接入混元——配好 TokenHub / TokenPlan 双端点 ​

第 3 步：OpenClaw 接入百度千帆——配好 QIANFAN_API_KEY ​

第 4 步：选择混元 / 文心模型并验证 ​

检查点 ✅ ​

踩坑提醒 ​

❌ 混元 Key 受限范围没包含 hy4 preview ​

❌ 用旧混元模型名（hunyuan-turbo / hunyuan-larges 等） ​

❌ 百度 Key 格式不对 / 千帆服务没开通 ​

❌ 在千帆目录里找 ERNIE 4.5 / X1 等更早型号 ​

❌ 用了已弃用的旧 ID ​

❌ Gateway 装成守护进程后，export 的 Key「不生效」 ​

❌ 以为 doctor --fix 会帮你升到 Hy4 ​

❌ 海外账号硬连国内端点（或反过来） ​

🔧 进阶：端点覆盖与千帆记忆嵌入（可选） ​

覆盖 TokenHub 端点（国际版 / 特殊区域） ​

给记忆系统配千帆中文向量模型 ​

需要自定义元数据时才写 models.providers ​

下一步 ​

相关教程 ​

接入腾讯混元与百度千帆：大厂 MaaS 实战

学完你能做什么

🎒 开始前的准备

跟我做

第 1 步：安装腾讯混元与百度千帆 provider 插件

第 2 步：OpenClaw 接入混元——配好 TokenHub / TokenPlan 双端点

第 3 步：OpenClaw 接入百度千帆——配好 QIANFAN_API_KEY

第 4 步：选择混元 / 文心模型并验证

检查点 ✅

踩坑提醒

❌ 混元 Key 受限范围没包含 hy4 preview

❌ 用旧混元模型名（hunyuan-turbo / hunyuan-larges 等）

❌ 百度 Key 格式不对 / 千帆服务没开通

❌ 在千帆目录里找 ERNIE 4.5 / X1 等更早型号

❌ 用了已弃用的旧 ID

❌ Gateway 装成守护进程后，export 的 Key「不生效」

❌ 以为 doctor --fix 会帮你升到 Hy4

❌ 海外账号硬连国内端点（或反过来）

🔧 进阶：端点覆盖与千帆记忆嵌入（可选）

覆盖 TokenHub 端点（国际版 / 特殊区域）

给记忆系统配千帆中文向量模型

需要自定义元数据时才写 models.providers

下一步

相关教程