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

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.

apus onboard --auth-choice tokenhub-api-key

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

apus onboard --auth-choice tokenplan-api-key

apus 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=...

```bash
apus models list --provider tencent-tokenhub
apus models list --provider tencent-tokenplan
```

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

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

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

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, apus 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

Apus'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:

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

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 `~/.apus/.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.

Related

Choosing providers, model refs, and failover behavior.

Full config schema including provider settings.

Tencent Cloud's TokenHub product page.

Tencent Hunyuan Hy3 preview details and benchmarks.