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

​
Quick start

1

Create a Tencent API key

Create an API key for Tencent Cloud TokenHub and TokenPlan. If you choose a limited access scope for the key, include hy4 preview (and hy3 / hy3 preview if you plan to use them on TokenHub) in the allowed models.
2

Run onboarding

3

Verify the model

Onboarding preserves your model entries and leaves generated catalog rows to discovery. With models.mode: "replace", it also writes the built-in catalog because that mode skips discovery.

​
Non-interactive setup

--accept-risk is required alongside --non-interactive. --mode defaults to local, so these are the same runs as the direct flag commands above. Run them on the Gateway host: remote-client onboarding (--mode remote) only configures the local client connection and does not set up provider credentials on the server.

​
Built-in catalog

hy4-preview is Tencent Hunyuan’s large MoE language model for reasoning, long-context instruction following, code, and agent workflows. Tencent’s OpenAI-compatible examples use hy4-preview as the model id and support standard chat-completions tool calling plus reasoning_effort.

​
Existing TokenHub configurations

Fresh onboarding selects hy4-preview on both endpoints. Existing TokenHub configurations follow a separate migration policy: when a TokenHub model allowlist is configured, openclaw doctor --fix changes a deprecated tencent-tokenhub/hy3-preview primary to tencent-tokenhub/hy3, not Hy4. This applies to string and object primary settings and preserves fallbacks, custom aliases, and unrelated settings. Explicit hy3 and hy4-preview primaries stay unchanged. The catalog recommendation for hy3-preview remains hy4-preview, but it is not the Doctor migration destination. Moving to Hy4 is an explicit choice: review its different pricing and verify model access for the selected endpoint.

​
Advanced configuration

OpenClaw’s built-in catalog uses Tencent Cloud’s https://tokenhub.tencentmaas.com/v1 endpoint. Override it only if your TokenHub account or region requires a different one:
If the Gateway runs as a managed service (launchd, systemd, Docker), TOKENHUB_API_KEY and TOKENPLAN_API_KEY must be visible to that process. Set them in ~/.openclaw/.env or via env.shellEnv so launchd, systemd, or Docker exec environments can read them.
Keys exported only in an interactive shell are not visible to managed gateway processes. Use the env file or config seam for persistent availability.

Model providers

Choosing providers, model refs, and failover behavior.

Configuration reference

Full config schema including provider settings.

Tencent TokenHub

Tencent Cloud’s TokenHub product page.

Hy3 preview model card

Tencent Hunyuan Hy3 preview details and benchmarks.