On this page
On this page
Providers
Tencent Cloud (TokenHub / TokenPlan)
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.
| Property | Value |
|---|---|
| Provider ids | tencent-tokenhub, tencent-tokenplan |
| Package | @openclaw/tencent-provider |
| TokenHub auth env var | TOKENHUB_API_KEY |
| TokenPlan auth env var | TOKENPLAN_API_KEY |
| TokenHub onboarding flag | --auth-choice tokenhub-api-key |
| TokenPlan onboarding flag | --auth-choice tokenplan-api-key |
| TokenHub direct CLI flag | --tokenhub-api-key <key> |
| TokenPlan direct CLI flag | --tokenplan-api-key <key> |
| API | OpenAI-compatible (openai-completions) |
| TokenHub base URL | https://tokenhub.tencentmaas.com/v1 |
| TokenHub global base URL | https://tokenhub-intl.tencentmaas.com/v1 (override) |
| TokenPlan base URL | https://api.lkeap.cloud.tencent.com/plan/v3 |
| Default model | tencent-tokenhub/hy4-preview |
Quick start
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.
Run onboarding
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
Built-in catalog
| Model ref | Name | Input | Context | Max output | Notes |
|---|---|---|---|---|---|
tencent-tokenhub/hy4-preview |
hy4 preview (TokenHub) | text | 1,024,000 | 64,000 | reasoning-enabled; default |
tencent-tokenhub/hy3 |
hy3 (TokenHub) | text | 256,000 | 128,000 | reasoning-enabled; previous 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-enabled; default |
tencent-tokenplan/hy3 |
hy3 (TokenPlan) | text | 256,000 | 128,000 | reasoning-enabled; previous GA |
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
Endpoint override
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:
Environment availability for the daemon
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.
