Integrating Tencent Hunyuan and Baidu Qianfan: Big-Tech MaaS in Practice
OpenClaw Integrating Hunyuan and Baidu Qianfan is the seventh stop on the domestic models pages, and this page covers two providers at once: Tencent Hunyuan (TokenHub / TokenPlan dual endpoints) and Baidu Qianfan (Qianfan MaaS). Each has its own plugin and its own Key, but the integration routine is exactly the same as in previous lessons.
DeepSeek, Qwen, GLM, Kimi, MiniMax, Doubao — the three-step "install plugin → configure credentials → choose model" flow applies here as usual. The whole process takes about 10 minutes (Tencent Cloud / Baidu AI Cloud account registration not included).
Here is a summary table first; all configurations in this lesson build on it (properties and values are quoted verbatim from the official documentation):
| Tencent Hunyuan | Baidu Qianfan | |
|---|---|---|
| Plugin | @openclaw/tencent-provider | @openclaw/qianfan-provider |
| Provider id | tencent-tokenhub、tencent-tokenplan | qianfan |
| Authentication | TOKENHUB_API_KEY / TOKENPLAN_API_KEY | QIANFAN_API_KEY (bce-v3/ALTAK-... format) |
| Endpoint | https://tokenhub.tencentmaas.com/v1 (TokenHub)https://api.lkeap.cloud.tencent.com/plan/v3 (TokenPlan) | https://qianfan.baidubce.com/v2 |
| API | OpenAI-compatible (openai-completions) | same as above |
| Onboarding default | tencent-tokenhub/hy4-preview (the TokenPlan endpoint also selects hy4-preview) | qianfan/deepseek-v4-pro |
The positioning of the two providers, in two sentences:
- Tencent Hunyuan: the models are the Hunyuan hy series (
hy4-preview,hy3), the entry points are the two Tencent Cloud endpoints TokenHub and TokenPlan, and each provider gets its own Key - Baidu Qianfan: a MaaS aggregation platform where a single Key routes through a unified API to multiple models such as ERNIE and Qianfan-hosted DeepSeek
💡 For readers who arrived by searching "OpenClaw Integrating ERNIE"
ERNIE is Baidu's model family. OpenClaw accesses it via Baidu Qianfan, a MaaS platform—behind Qianfan's unified API there is not only ERNIE but also DeepSeek hosted by Qianfan. Note: in OpenClaw, the Baidu Qianfan catalog only includes ernie-5.1 and ernie-5.0; earlier models such as ERNIE 4.5 and X1 are not included (the pitfall reminder at the end of the article offers an alternative).
This tutorial is based on OpenClaw v2026.10.9.
What You'll Be Able to Do
- Install the two official plugins
@openclaw/tencent-providerand@openclaw/qianfan-provider, and register the three providerstencent-tokenhub,tencent-tokenplan,qianfan - Distinguish Tencent's dual endpoints: TokenHub and TokenPlan each have their own Key variable, and onboarding is run separately for each
- OpenClaw Baidu Qianfan uses one
QIANFAN_API_KEYto route to ERNIE and Qianfan-hosted DeepSeek - Understand both catalogs: the context window and max output of Hunyuan
hy4-preview(1M context), ERNIEernie-5.1(text flagship) /ernie-5.0(multimodal) respectively - Avoid pitfalls unique to big-tech MaaS: Key scope restrictions missing models, old Hunyuan model names unavailable, Baidu Key format, deprecated IDs
- Set up a Qianfan Chinese embedding model (
bge-large-zh) for OpenClaw's memory system
🎒 Preparation Before You Start
- Completed Connecting Models Overview: The Provider System and Model Switching: you're clear on the three steps "provider → authentication → choose model" and the
provider/modelreference convention - OpenClaw is installed and the Gateway is running:
openclaw gateway statusproduces output - Have at least one of a Tencent Cloud account (for Hunyuan) or a Baidu AI Cloud account (for Qianfan) — the two are independent of each other, and configuring only one is perfectly fine
- If you go with a server / daemon deployment, know where
~/.openclaw/.envis — that's where the Key ultimately lives
Follow along with me
Step 1: Install the Tencent Hunyuan and Baidu Qianfan provider plugins
Why: Like DeepSeek and Doubao, tencent and qianfan are both external official plugins — OpenClaw doesn't ship with them. Only after installing the plugin will the provider be registered into the model system. The two are independent of each other, so installing just the one you need is fine.
# 1. 安装腾讯混元 provider 插件(TokenHub + TokenPlan 两个 provider 一起注册)
openclaw plugins install @openclaw/tencent-provider
# 2. 安装百度千帆 provider 插件
openclaw plugins install @openclaw/qianfan-provider
# 3. 重启 Gateway(Gateway 正在跑的话,安装会自动生效;重启最稳妥)
openclaw gateway restartYou should see: a message that the plugin was installed successfully, and no errors after the Gateway restarts.
Know one behavior up front (the official plugin docs state it explicitly): installation takes effect automatically on a running Gateway; if the Gateway isn't running, it takes effect at the next startup.
openclaw plugins installexecuted successfully (both installed, or only the one you need), Gateway restarted
Step 2: OpenClaw connects to Hunyuan — configure the TokenHub / TokenPlan dual endpoints
Why: Tencent Hunyuan has two entry points in OpenClaw — TokenHub (tencent-tokenhub) and TokenPlan (tencent-tokenplan), corresponding to the two product endpoints of Tencent Cloud MaaS. The two providers each have their own Key variables and onboarding entry points, so you need to run each once.
First, go to the Tencent Cloud console to create an API Key. The official docs explicitly require: if you chose a restricted access scope when creating the Key, the allowed model list must include hy4 preview — if you plan to use the hy3 series on TokenHub, hy3 / hy3 preview must also be added.
Then run onboarding (once for each endpoint, verbatim from the official docs):
# TokenHub 端点
openclaw onboard --auth-choice tokenhub-api-key
# TokenPlan 端点
openclaw onboard --auth-choice tokenplan-api-keyYou should see: the Key is validated and saved. The official docs explicitly state: a fresh onboarding selects the default model hy4-preview on both endpoints; your existing model entries are preserved and not overwritten.
For non-interactive scenarios like CI / scripts, the official docs give a way to pass the Key directly (verbatim):
# 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-riskIf you don't want to run onboarding, setting only the environment variables also works (verbatim from the official docs):
export TOKENHUB_API_KEY="<你的 TokenHub Key>"
export TOKENPLAN_API_KEY="<你的 TokenPlan Key>"⚠️ Gateway running as a daemon? Don't put the Key in an interactive shell
When the Gateway runs as a launchd / systemd service, it can't see the export environment variables in your terminal. Write TOKENHUB_API_KEY and TOKENPLAN_API_KEY into ~/.openclaw/.env, or provide them to that process via env.shellEnv in the config — the tencent official docs specifically emphasize this point.
While you're at it, verify both providers are registered:
openclaw models list --provider tencent-tokenhub
openclaw models list --provider tencent-tokenplanYou should see: both the tencent-tokenhub/ and tencent-tokenplan/ model families are listed (see Step 4 for the full catalog).
There's also one official migration rule for existing users — keep it in mind: existing TokenHub configurations are not automatically upgraded to Hy4. When a model allowlist is configured, openclaw doctor --fix only changes the deprecated tencent-tokenhub/hy3-preview primary model to tencent-tokenhub/hy3.
Although the catalog's recommendation for hy3-preview is hy4-preview, Doctor doesn't perform this migration — upgrading to Hy4 is an explicit action, and you need to confirm the model access permissions and pricing differences for your chosen endpoint yourself.
openclaw models statusshows tencent's credential source
Step 3: OpenClaw connect to Baidu Qianfan — set up QIANFAN_API_KEY
Why: Qianfan is Baidu's MaaS platform — a single OpenAI-compatible API where one Key routes requests to the multiple models behind the endpoint. It has only one provider: qianfan; configure it once and everything works.
First, go to the Qianfan console to create a Key (direct link from the official docs):
- Register / log in to Baidu AI Cloud, go to the Qianfan console, and enable Qianfan API access
- Create a new application (or select an existing one) and generate an API Key — Baidu Cloud keys look like this:
bce-v3/ALTAK-...
Then run onboarding:
openclaw onboard --auth-choice qianfan-api-keyYou should see: the Key is validated and saved. The official docs explicitly state that onboarding does three things: writes the provider config, adds a QIANFAN alias for the default model, and sets qianfan/deepseek-v4-pro as the default if you haven't configured one. Connection settings and aliases are saved, but it does not copy the generated catalog entries into your config.
For non-interactive scenarios, read --qianfan-api-key <key> or the environment variable QIANFAN_API_KEY (verbatim from the official docs):
export QIANFAN_API_KEY="bce-v3/ALTAK-<你的 Key>"While you're at it, verify:
openclaw models list --provider qianfanYou should see: the model catalog with the qianfan/ prefix is listed (see Step 4 for details). If the list is empty, first check the first two items on the official troubleshooting checklist: whether the Key starts with bce-v3/ALTAK-, and whether the Qianfan service is enabled in the Baidu Cloud console.
openclaw models list --provider qianfancan list the catalog
Step 4: Pick a Hunyuan / ERNIE model and verify
Why: Neither catalog is long, but each has its quirks — Hunyuan has only three hy-series IDs, while Qianfan is a static catalog (no online discovery) that still contains deprecated old IDs, so picking wrong can trip you up.
First, the Tencent Hunyuan catalog (compiled verbatim from the official docs):
| Model reference | Name | Input | Context | Max output | Notes |
|---|---|---|---|---|---|
tencent-tokenhub/hy4-preview | hy4 preview (TokenHub) | Text | 1,024,000 | 64,000 | reasoning; default |
tencent-tokenhub/hy3 | hy3 (TokenHub) | Text | 256,000 | 128,000 | reasoning; previous-generation GA |
tencent-tokenhub/hy3-preview | hy3 preview (TokenHub) | Text | 256,000 | 128,000 | Deprecated; use hy4-preview |
tencent-tokenplan/hy4-preview | hy4 preview (TokenPlan) | Text | 1,024,000 | 64,000 | reasoning; default |
tencent-tokenplan/hy3 | hy3 (TokenPlan) | Text | 256,000 | 128,000 | reasoning; previous-generation GA |
hy4-preview is Hunyuan's large MoE language model, aimed at reasoning, long-context instruction following, code, and agent workflows; Tencent's OpenAI-compatible example uses it as the model id, supporting standard chat-completions tool calls plus reasoning_effort.
Now let's look at the Baidu Qianfan catalog (compiled verbatim from the official docs):
| Model reference | Input | Context | Max output | Reasoning | Notes |
|---|---|---|---|---|---|
qianfan/deepseek-v4-pro | Text | 1,000,000 | 393,216 | Yes | Current DeepSeek flagship |
qianfan/ernie-5.1 | Text | 128,000 | 65,536 | No | Latest ERNIE text flagship |
qianfan/ernie-5.0 | Text, images | 128,000 | 65,536 | Yes | Multimodal + thinking |
qianfan/deepseek-v3.2 | Text | 128,000 | 32,768 | No | Deprecated compatibility default; superseded by deepseek-v4-pro |
qianfan/ernie-5.0-thinking-preview | Text, images | 128,000 | 65,536 | Yes | Deprecated alias; superseded by ernie-5.0 |
The Qianfan catalog is statically built in—in the official docs' own words, "catalog is static; there is no live model discovery"; new models have to wait for the OpenClaw plugin to update the catalog.
How to choose, in five sentences:
| Your need | Pick this |
|---|---|
| Want Hunyuan's latest flagship with 1M-context reasoning | tencent-tokenhub/hy4-preview (onboarding default) |
| Key is on the TokenPlan endpoint | tencent-tokenplan/hy4-preview |
| Want ERNIE's latest text flagship | qianfan/ernie-5.1 |
| Want ERNIE with multimodal input + thinking | qianfan/ernie-5.0 |
| Key is on Qianfan and you just want DeepSeek | qianfan/deepseek-v4-pro (onboarding default) |
Change the default model:
# 混元(注意前缀跟端点走)
openclaw models set tencent-tokenhub/hy4-preview
# 文心
openclaw models set qianfan/ernie-5.1You can also switch temporarily in chat: /model qianfan/ernie-5.0 only affects the current session; see chat commands crash course for the full command family.
Finally, verify. Send a test message:
openclaw dashboardOpen the Control UI and send "Introduce yourself in one sentence" in the chat box.
You should see: the model replies normally, with no errors about missing credentials or nonexistent models. At this point, both Hunyuan and Baidu Qianfan are connected to OpenClaw.
Pricing in one sentence: TokenHub's official docs give no pricing; in the Qianfan config example, the catalog estimate for deepseek-v4-pro is 1.771957 input / 3.543915 output / 0.147663 cache read per million tokens (OpenClaw catalog figures). Actual prices and currency are always subject to the Tencent Cloud and Baidu AI Cloud official sites.
- The test message got a reply, and the provider and model match (
tencent-tokenhub/...,tencent-tokenplan/..., orqianfan/...)
Checkpoint ✅
@openclaw/tencent-provider,@openclaw/qianfan-provider: at least the one you plan to use is installed (takes effect once installed)- Hunyuan's two endpoints each have their own Key:
TOKENHUB_API_KEY(TokenHub) +TOKENPLAN_API_KEY(TokenPlan) - The Qianfan Key starts with
bce-v3/ALTAK-, and the Qianfan service is enabled in the Baidu AI Cloud console openclaw models list --provider tencent-tokenhub/--provider tencent-tokenplan/--provider qianfancan all list the catalog- The default model prefix matches the endpoint: use
tencent-tokenhub/ortencent-tokenplan/for Hunyuan, andqianfan/for Qianfan - The test message got a reply
Pitfall warnings
❌ Hunyuan Key's restricted scope doesn't include hy4 preview
Symptom: onboarding validation fails, or the Hunyuan model list is missing / calls are rejected.
Cause: when creating a Key in Tencent Cloud with a restricted access scope, the allowed model list doesn't include hy4 preview—the official docs explicitly require adding it (along with the hy3 / hy3 preview you plan to use on TokenHub) to the allowlist.
Fix: go back to the console and change the Key's allowed model scope, or switch to a Key with the full scope.
❌ Using old Hunyuan model names (hunyuan-turbo / hunyuan-larges, etc.)
Symptom: an unknown-model error.
Cause: OpenClaw's Hunyuan provider only has the hy series (hy4-preview, hy3, hy3-preview)—old names like hunyuan-turbo and hunyuan-larges don't exist in TokenHub / TokenPlan (full cross-check of sources: zero hits).
Fix: use tencent-tokenhub/hy4-preview (default) or hy3; for legacy model needs, use the custom compatibility endpoint in the next lesson.
❌ Baidu Key has the wrong format / Qianfan service not enabled
Symptom: the openclaw models list --provider qianfan list is empty, or calls report credential errors.
Cause: the first two items on the official troubleshooting checklist—the Key must start with bce-v3/ALTAK-; the account must have Qianfan API access enabled in the Baidu Cloud console.
Fix: go back to the Qianfan console to check the Key format and service activation status.
❌ Looking for earlier models like ERNIE 4.5 / X1 in the Qianfan catalog
Reason: the OpenClaw catalog for Qianfan only includes ernie-5.1 and ernie-5.0 (a static catalog, no online discovery).
Correct approach: earlier ERNIE models have no official provider—use the "custom OpenAI-compatible endpoint" flow from the next lesson, or find hosted routes from aggregators like OpenRouter / NovitaAI.
❌ Using a deprecated old ID
| Deprecated ID | Successor |
|---|---|
tencent-tokenhub/hy3-preview | Catalog recommendation hy4-preview; doctor --fix only migrates to hy3 |
qianfan/deepseek-v3.2 | qianfan/deepseek-v4-pro |
qianfan/ernie-5.0-thinking-preview | qianfan/ernie-5.0 |
Correct approach: always use the successor in new configurations; for existing configurations, run openclaw doctor and check the hints before migrating.
❌ After installing the Gateway as a daemon, the exported Key "doesn't take effect"
Reason: launchd / systemd services cannot see environment variables from an interactive shell—tencent's official documentation specifically emphasizes this point (both the TokenHub and TokenPlan variables must be provided to the service process).
Correct approach: write TOKENHUB_API_KEY, TOKENPLAN_API_KEY, and QIANFAN_API_KEY into ~/.openclaw/.env, or provide them via env.shellEnv; restart the Gateway service after changing the Key.
❌ Assuming doctor --fix will upgrade you to Hy4
Reason: the official migration rule—for existing TokenHub configurations with an allowlist configured, openclaw doctor --fix only changes the deprecated hy3-preview to hy3; it does not change to Hy4.
Correct approach: upgrading to Hy4 requires an explicit operation yourself (openclaw models set tencent-tokenhub/hy4-preview); first confirm the model access permissions and pricing differences of the chosen endpoint.
❌ An overseas account connecting directly to a domestic endpoint (or vice versa)
Reason: the TokenHub built-in endpoint is https://tokenhub.tencentmaas.com/v1; the international endpoint https://tokenhub-intl.tencentmaas.com/v1 requires explicitly overriding the baseUrl.
Correct approach: for an overseas TokenHub account, override the baseUrl as described in the next section; the same applies to Qianfan—only change the base URL when using a custom endpoint / proxy.
🔧 Advanced: endpoint overrides and Qianfan memory embeddings (optional)
Overriding the TokenHub endpoint (international version / special regions)
The built-in catalog uses https://tokenhub.tencentmaas.com/v1. Only override it if your TokenHub account or region requires a different endpoint (official example as-is, using the international endpoint here):
openclaw config set models.providers.tencent-tokenhub.baseUrl "https://tokenhub-intl.tencentmaas.com/v1"Configuring a Qianfan Chinese vector model for the memory system
Memory retrieval in OpenClaw requires an embedding model, and the Qianfan plugin can serve directly as an embedding provider—especially well-suited for Chinese content (official example as-is):
{
memory: {
search: {
provider: "qianfan",
model: "bge-large-zh",
},
},
}Three details (explicitly stated in the official documentation):
- The plugin reuses your configured Qianfan connection, resolving credentials from the saved profile or
QIANFAN_API_KEY; an explicit remote API Key / Authorization header takes precedence - The three models
bge-large-zh,bge-large-en, andEmbedding-V1accept at most 16 input items per request (following Baidu's official batch limits); other models keep the existing behavior of the compatible transport - For an existing configuration that uses
openai-compatibleto point to Qianfan, simply changememory.search.providertoqianfan—the endpoint and Key stay unchanged
For the memory system itself, see Memory System: Making Claw Remember You.
Only write models.providers when custom metadata is needed
Official rule: once the plugin is installed and auth is configured, that's enough—there is no need to write a models.providers entry; only write it when overriding the baseUrl or model metadata. The complete explicit configuration for Qianfan looks like this (excerpt from the official example as-is):
{
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,
},
],
},
},
},
}There is also a compatibility note (the gist of the official documentation): Qianfan goes through the OpenAI-compatible transport path, not native OpenAI request shaping—standard OpenAI SDK features are available, but provider-specific parameters may not be forwarded. For the official documentation of the Qianfan API, see cloud.baidu.com/doc/qianfan-api.
Next Steps
That completes OpenClaw integration with Hunyuan and Baidu Qianfan. Continue on the domestic models page:
- Next lesson More Domestic Models and Custom Relay Endpoints: models without official providers such as Spark and Baichuan, plus how to work with OpenRouter / LiteLLM / custom relays
- Other model pages (local models) can be reached from the course schedule on Model Connection Overview
- Models configured? Start daily usage with Daily Usage: Working Efficiently with Your Claw—the Control UI, chat commands, and the memory system are all in that chapter
Related Tutorials
- Local Models: Ollama, vLLM and ds4
- WeChat, QQ and Yuanbao: Connecting Tencent Channels—with Tencent Hunyuan as the model, your chat channels can also use Tencent's IM services
- Memory System: Making Claw Remember You