Tencent Cloud TokenHub and TokenPlan Provider Setup

Install the official Tencent Cloud provider plugin to reach Tencent Hunyuan chat models (hy4-preview, hy3) through two endpoints, TokenHub (tencent-tokenhub) and TokenPlan (tencent-tokenplan), over an OpenAI-compatible API.

Quick start

Create a Tencent API key

Generate an API key for Tencent Cloud TokenHub and TokenPlan. Should you give the key a restricted access scope, add hy4 preview to the permitted models, along with hy3 and hy3 preview if you intend to use those on TokenHub.

Run onboarding

openclaw onboard --auth-choice tokenhub-api-key

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

openclaw onboard --auth-choice tokenplan-api-key

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

export TOKENHUB_API_KEY=...
export TOKENPLAN_API_KEY=...

Verify the model

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

Your model entries survive onboarding, and the generated catalog rows are left to discovery. When models.mode: "replace" is used, onboarding also writes the built-in catalog, since that mode does not run discovery.

Non-interactive setup

# 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

Note

--accept-risk must be supplied together with --non-interactive. Because --mode defaults to local, these runs match the direct flag commands listed above. Execute them on the Gateway host: onboarding from a remote client (--mode remote) only configures the local client connection and leaves provider credentials unset on the server.

Built-in catalog

hy4-preview is Tencent Hunyuan's large MoE language model, built for reasoning, long-context instruction following, code, and agent workflows. Tencent's OpenAI-compatible samples pass hy4-preview as the model id, and they support standard chat-completions tool calling as well as reasoning_effort.

Existing TokenHub configurations

A fresh onboarding picks hy4-preview on both endpoints. TokenHub configurations that already exist follow their own migration policy: if a TokenHub model allowlist is set, openclaw doctor --fix swaps a deprecated tencent-tokenhub/hy3-preview primary for tencent-tokenhub/hy3 rather than Hy4. This covers both string and object primary settings, and it keeps fallbacks, custom aliases, and unrelated settings intact. Primaries set explicitly to hy3 or hy4-preview are left as they are.

The catalog still recommends hy4-preview for hy3-preview, yet that is not where the Doctor migration sends you. Choosing Hy4 is a deliberate step: check its different pricing and confirm model access for the endpoint you selected.

Advanced configuration

Endpoint override

The built-in catalog in OpenClaw points at Tencent Cloud's https://tokenhub.tencentmaas.com/v1 endpoint. Override it only when your TokenHub account or region needs a different one:

openclaw config set models.providers.tencent-tokenhub.baseUrl "https://your-endpoint/v1"

Environment availability for the daemon

When the Gateway is deployed as a managed service (launchd, systemd, Docker), both TOKENHUB_API_KEY and TOKENPLAN_API_KEY have to be readable by that process. Provide them in ~/.openclaw/.env or through env.shellEnv, so the launchd, systemd, or Docker exec environments can pick them up.

Warning

Variables exported only inside an interactive shell will not be seen by managed gateway processes. For availability that persists, use the env file or the config setting.

Related

• Model providers, How providers, model refs, and failover behavior are chosen.

• Configuration reference, The complete config schema, provider settings included.

• Tencent TokenHub, The TokenHub product page from Tencent Cloud.

• Hy3 preview model card, Benchmarks and details for Tencent Hunyuan Hy3 preview.