Skip to content

Integración de Tencent Hunyuan y Baidu Qianfan: MaaS de grandes proveedores en la práctica ​

OpenClaw Integrar Hunyuan y Baidu Qianfan es la séptima parada de la página de modelos nacionales; esta página cubre dos proveedores a la vez: Tencent Hunyuan (doble endpoint TokenHub / TokenPlan) y Baidu Qianfan (Qianfan MaaS). Cada uno tiene su propio plugin y su propia Key, pero el procedimiento de integración es idéntico al de las lecciones anteriores.

Los tres pasos de «instalar plugin → configurar credenciales → elegir modelo» de DeepSeek, Qwen, GLM, Kimi, MiniMax y Doubao siguen aplicando en esta lección. Todo el proceso dura unos 10 minutos (el registro de cuenta en Tencent Cloud / Baidu AI Cloud se cuenta aparte).

Primero, una tabla resumen de la que parten todas las configuraciones de esta lección (propiedades y valores extraídos tal cual de la documentación oficial):

Tencent HunyuanBaidu Qianfan
Plugin@openclaw/tencent-provider@openclaw/qianfan-provider
Provider idtencent-tokenhub, tencent-tokenplanqianfan
AutenticaciónTOKENHUB_API_KEY / TOKENPLAN_API_KEYQIANFAN_API_KEY (formato bce-v3/ALTAK-...)
Endpointhttps://tokenhub.tencentmaas.com/v1 (TokenHub)
https://api.lkeap.cloud.tencent.com/plan/v3 (TokenPlan)
https://qianfan.baidubce.com/v2
APIcompatible con OpenAI (openai-completions)igual que la izquierda
onboarding por defectotencent-tokenhub/hy4-preview (en el extremo TokenPlan se elige igualmente hy4-preview)qianfan/deepseek-v4-pro

El posicionamiento de ambos, en dos frases:

  • Tencent Hunyuan: los modelos son la serie Hunyuan hy (hy4-preview, hy3), y la entrada son los dos endpoints de Tencent Cloud, TokenHub y TokenPlan; cada provider tiene su propia Key
  • Baidu Qianfan: plataforma agregadora MaaS; una sola Key enruta mediante la API unificada hacia Wenxin ERNIE, el DeepSeek alojado en Qianfan y otros muchos modelos

💡 Para quienes llegan buscando desde «OpenClaw Integración de Wenxin»

Wenxin (ERNIE) es la serie de modelos de Baidu, y OpenClaw se integra a través de Baidu Qianfan (Qianfan), esta plataforma MaaS; detrás de la API unificada de Qianfan no solo está Wenxin, sino también el DeepSeek alojado en Qianfan. Ten en cuenta: OpenClaw el catálogo de Baidu Qianfan solo incluye ernie-5.1 y ernie-5.0; modelos anteriores como ERNIE 4.5 o X1 no están (al final del artículo, el aviso de problemas comunes ofrece alternativas).

Este tutorial se basa en OpenClaw v2026.10.9.

Qué podrás hacer al terminar ​

  • Instala los dos plugins oficiales @openclaw/tencent-provider y @openclaw/qianfan-provider, y registra los tres providers tencent-tokenhub, tencent-tokenplan y qianfan
  • Distingue el doble endpoint de Tencent: TokenHub y TokenPlan tienen cada uno su propia variable de Key, y el onboarding se ejecuta por separado
  • OpenClaw Baidu Qianfan con una sola QIANFAN_API_KEY enruta hacia Wenxin ERNIE y el DeepSeek alojado en Qianfan
  • Entiende el catálogo de ambos: contexto y salida máxima de Hunyuan hy4-preview (1M de contexto) y de Wenxin ernie-5.1 (insignia de texto) / ernie-5.0 (multimodal), cada uno con los suyos
  • Evita los problemas propios del MaaS de los grandes proveedores: modelos que faltan por el alcance restringido de la Key, nombres de modelos Hunyuan antiguos no disponibles, formato de la Key de Baidu, IDs en desuso
  • Configura para el sistema de memoria de OpenClaw el modelo de embeddings en chino de Qianfan (bge-large-zh)

🎒 Preparativos antes de empezar ​

  • Has completado Panorama de conexión de modelos: sistema de providers y cambio de modelo: tienes claros los tres pasos de «provider → autenticación → elegir modelo» y la regla de referencia provider/model
  • OpenClaw instalado, Gateway en ejecución: openclaw gateway status produce salida
  • Tener al menos una de las dos cuentas: una cuenta de Tencent Cloud (con Hunyuan) o una cuenta de Baidu AI Cloud (con Qianfan) — ambas son independientes entre sí, y configurar solo una está perfectamente bien
  • Si optas por un despliegue de servidor / demonio, saber dónde está ~/.openclaw/.env — la Key terminará viviendo allí

Sígueme paso a paso ​

Paso 1: instalar los plugins de provider de Tencent Hunyuan y Baidu Qianfan ​

Por qué: igual que DeepSeek y Doubao, tencent y qianfan son ambos plugins oficiales externos; OpenClaw no los incluye de fábrica — solo tras instalar el plugin el provider se registra en el sistema de modelos. Ambos son independientes entre sí, y puedes instalar solo el que necesites.

bash
# 1. 安装腾讯混元 provider 插件(TokenHub + TokenPlan 两个 provider 一起注册)
openclaw plugins install @openclaw/tencent-provider

# 2. 安装百度千帆 provider 插件
openclaw plugins install @openclaw/qianfan-provider

# 3. 重启 Gateway(Gateway 正在跑的话,安装会自动生效;重启最稳妥)
openclaw gateway restart

Deberías ver: un mensaje de que el plugin se instaló correctamente y que el Gateway no arroja errores tras reiniciarse.

Un comportamiento que conviene conocer de antemano (la documentación oficial del plugin lo indica explícitamente): la instalación surte efecto automáticamente en un Gateway en ejecución; si el Gateway no está corriendo, surte efecto en el próximo inicio.

  • openclaw plugins install se ejecutó con éxito (instalaste ambos, o solo el que necesitas), y el Gateway se ha reiniciado

Paso 2: conectar OpenClaw a Hunyuan — configurar los dos endpoints TokenHub / TokenPlan ​

Por qué: Tencent Hunyuan tiene dos entradas en OpenClaw — TokenHub (tencent-tokenhub) y TokenPlan (tencent-tokenplan), correspondientes a los dos endpoints de producto del MaaS de Tencent Cloud. Cada provider tiene sus propias variables de Key y su propio flujo de onboarding, así que hay que ejecutarlo una vez por cada uno.

Primero ve a la consola de Tencent Cloud y crea una API Key. La documentación oficial exige explícitamente: si al crear la Key elegiste un alcance de acceso (access scope) restringido, la lista de modelos permitidos debe incluir hy4 preview — si planeas usar la serie hy3 en TokenHub, también hay que añadir hy3 / hy3 preview.

Luego ejecuta el onboarding (una vez por cada endpoint, tal como figura en la documentación oficial):

bash
# TokenHub 端点
openclaw onboard --auth-choice tokenhub-api-key

# TokenPlan 端点
openclaw onboard --auth-choice tokenplan-api-key

Deberías ver: la Key se valida y se guarda. La documentación oficial indica explícitamente: en un onboarding completamente nuevo, se selecciona hy4-preview como modelo predeterminado en ambos endpoints; las entradas de modelos que ya tengas se conservan y no se sobrescriben.

Para escenarios no interactivos como CI / scripts, la documentación oficial da una forma de pasar la Key directamente (tal cual):

bash
# 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

Si no quieres ejecutar el onboarding, con solo definir las variables de entorno también se reconoce (tal como figura en la documentación oficial):

bash
export TOKENHUB_API_KEY="<你的 TokenHub Key>"
export TOKENPLAN_API_KEY="<你的 TokenPlan Key>"

⚠️ ¿El Gateway corre como demonio? No pongas la Key en una shell interactiva

Cuando el Gateway se ejecuta como servicio de launchd / systemd, no ve las variables de entorno de export en tu terminal. Escribe TOKENHUB_API_KEY y TOKENPLAN_API_KEY en ~/.openclaw/.env, o propórselos a ese proceso mediante env.shellEnv en la configuración — la documentación oficial de tencent hace especial hincapié en este punto.

De paso, verifica que ambos providers quedaron registrados:

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

Deberías ver: las dos familias de modelos tencent-tokenhub/ y tencent-tokenplan/ aparecen en la lista (el catálogo se detalla en el paso 4).

Hay además una regla oficial de migración para usuarios existentes que conviene memorizar: una configuración existente de TokenHub no se actualiza automáticamente a Hy4. Cuando hay una allowlist de modelos configurada, openclaw doctor --fix solo cambia el modelo principal tencent-tokenhub/hy3-preview, que está deprecado, por tencent-tokenhub/hy3.

Aunque la recomendación del catálogo para hy3-preview es hy4-preview, Doctor no realiza esta migración — actualizar a Hy4 es una acción explícita, y debes verificar por tu cuenta los permisos de acceso a modelos del endpoint elegido y las diferencias de precio.

  • En openclaw models status puedes ver el origen de las credenciales de tencent

Paso 3: conectar OpenClaw a Baidu Qianfan — configurar QIANFAN_API_KEY ​

Por qué: Qianfan es la plataforma MaaS de Baidu — una API unificada compatible con OpenAI, donde una sola Key enruta las solicitudes a múltiples modelos detrás del endpoint. Solo tiene un provider: qianfan; se configura una vez y queda todo habilitado.

Primero ve a la consola de Qianfan y crea una Key (enlace directo de la documentación oficial):

  1. Regístrate / inicia sesión en Baidu AI Cloud, entra en la consola de Qianfan y habilita el acceso a la API de Qianfan
  2. Crea una aplicación nueva (o elige una existente) y genera una API Key — las Key de Baidu Cloud se ven así: bce-v3/ALTAK-...

Luego ejecuta el onboarding:

bash
openclaw onboard --auth-choice qianfan-api-key

Deberías ver: la Key se valida y se guarda. La documentación oficial indica explícitamente que el onboarding hace tres cosas: escribe la configuración del provider, añade el alias QIANFAN al modelo predeterminado y, si nunca configuraste un modelo predeterminado, establece qianfan/deepseek-v4-pro como tal. Los ajustes de conexión y los alias se guardan, pero no copia en tu configuración las líneas del catálogo generado.

En escenarios no interactivos se lee --qianfan-api-key <key> o la variable de entorno QIANFAN_API_KEY (tal como figura en la documentación oficial):

bash
export QIANFAN_API_KEY="bce-v3/ALTAK-<你的 Key>"

De paso, verifica:

bash
openclaw models list --provider qianfan

Deberías ver: el catálogo de modelos con prefijo qianfan/ aparece en la lista (se detalla en el paso 4). Si la lista está vacía, revisa primero los dos primeros ítems de la lista oficial de resolución de problemas: que la Key empiece por bce-v3/ALTAK- y que el servicio de Qianfan esté habilitado en la consola de Baidu Cloud.

  • openclaw models list --provider qianfan puede listar el catálogo

Paso 4: elegir un modelo Hunyuan / Wenxin y verificar ​

Por qué: ninguno de los dos catálogos es muy largo, pero cada uno tiene sus peculiaridades — Hunyuan solo tiene tres ID de la serie hy, y Qianfan es un catálogo estático (sin descubrimiento en línea) que además contiene ID antiguos ya deprecados; elegir mal te hará tropezar.

Primero mira el catálogo de Tencent Hunyuan (ordenado tal como la documentación oficial):

Referencia del modeloNombreEntradaContextoSalida máximaNotas
tencent-tokenhub/hy4-previewhy4 preview (TokenHub)texto1,024,00064,000reasoning; predeterminado
tencent-tokenhub/hy3hy3 (TokenHub)texto256,000128,000reasoning; GA de la generación anterior
tencent-tokenhub/hy3-previewhy3 preview (TokenHub)texto256,000128,000deprecado; usa hy4-preview
tencent-tokenplan/hy4-previewhy4 preview (TokenPlan)texto1,024,00064,000reasoning; predeterminado
tencent-tokenplan/hy3hy3 (TokenPlan)texto256,000128,000reasoning; la generación anterior GA

hy4-preview es el gran modelo MoE de Hunyuan, orientado a razonamiento, seguimiento de instrucciones con contexto largo, código y flujos de trabajo de agentes; los ejemplos compatibles con OpenAI de Tencent lo usan como model id, y admite llamadas de herramientas estándar de chat-completions más reasoning_effort.

Ahora veamos el catálogo de Qianfan de Baidu (recopilado tal cual de la documentación oficial):

Referencia del modeloEntradaContextoSalida máximaReasoningNotas
qianfan/deepseek-v4-protexto1,000,000393,216síDeepSeek insignia actual
qianfan/ernie-5.1texto128,00065,536noúltimo modelo insignia de texto de Ernie
qianfan/ernie-5.0texto, imágenes128,00065,536símultimodal + thinking
qianfan/deepseek-v3.2texto128,00032,768nocompatibilidad por defecto ya obsoleta; reemplazado por deepseek-v4-pro
qianfan/ernie-5.0-thinking-previewtexto, imágenes128,00065,536síalias obsoleto; reemplazado por ernie-5.0

El catálogo de Qianfan es estático e integrado: palabras textuales de la documentación oficial «catalog is static; there is no live model discovery»; los modelos nuevos deben esperar a que el plugin OpenClaw actualice el catálogo.

Cómo elegir, en cinco frases:

Tu necesidadElígelos
Quieres el último insignia de Hunyuan, razonamiento con contexto de 1Mtencent-tokenhub/hy4-preview(onboarding por defecto)
La Key está en el endpoint de TokenPlantencent-tokenplan/hy4-preview
Quieres el último modelo insignia de texto de Ernieqianfan/ernie-5.1
Quieres un Ernie con entrada multimodal + thinkingqianfan/ernie-5.0
La Key está en Qianfan y solo quieres usar DeepSeekqianfan/deepseek-v4-pro(onboarding por defecto)

Cambiar el modelo por defecto:

bash
# 混元(注意前缀跟端点走)
openclaw models set tencent-tokenhub/hy4-preview

# 文心
openclaw models set qianfan/ernie-5.1

También puedes cambiarlo temporalmente en el chat: /model qianfan/ernie-5.0 solo afecta a la sesión actual; la familia de comandos se detalla en comandos de chat exprés.

Por último, verificar. Envía un mensaje de prueba:

bash
openclaw dashboard

Abre la Control UI y escribe en el cuadro de chat «preséntate en una frase».

Deberías ver: el modelo responde con normalidad, sin errores de credenciales faltantes ni de modelo inexistente. Con esto, la integración de OpenClaw con Hunyuan y Baidu Qianfan queda completada.

Precios en una frase: la documentación oficial de TokenHub no da precios; en el ejemplo de configuración de Qianfan, la estimación del catálogo para deepseek-v4-pro es por millón de tokens: entrada 1.771957 / salida 3.543915 / lectura de caché 0.147663(números del catálogo de OpenClaw). Los precios reales y la moneda se rigen siempre por los sitios oficiales de Tencent Cloud y Baidu AI Cloud.

  • El mensaje de prueba recibió respuesta, y el provider y el modelo coinciden(tencent-tokenhub/...、tencent-tokenplan/... o qianfan/...)

Punto de control ✅ ​

  • @openclaw/tencent-provider、@openclaw/qianfan-provider al menos instalaste el que vas a usar(se activa al instalarlo)
  • Hunyuan con su propia Key en cada endpoint: TOKENHUB_API_KEY(TokenHub)+ TOKENPLAN_API_KEY(TokenPlan)
  • La Key de Qianfan empieza con bce-v3/ALTAK- y el servicio de Qianfan ya está activado en la consola de Baidu AI Cloud
  • openclaw models list --provider tencent-tokenhub / --provider tencent-tokenplan / --provider qianfan pueden listar el catálogo
  • El prefijo del modelo por defecto coincide con el endpoint: para Hunyuan escribe tencent-tokenhub/ o tencent-tokenplan/, para Qianfan escribe qianfan/
  • El mensaje de prueba recibió respuesta

Avisos de errores comunes ​

❌ El alcance restringido de la Key de Hunyuan no incluye hy4 preview ​

Síntoma: la validación del onboarding no pasa, o faltan modelos de Hunyuan en la lista, o las llamadas son rechazadas.

Causa: al crear la Key en Tencent Cloud, si se eligió un alcance de acceso restringido, la lista de modelos permitidos no incluye hy4 preview; la documentación oficial exige explícitamente añadirlo (junto con hy3 / hy3 preview que planeas usar en TokenHub) a la lista de permitidos.

Solución correcta: vuelve a la consola a modificar el alcance de modelos permitidos de la Key, o cambia por una Key con el alcance completo.

❌ Usar nombres antiguos de modelos Hunyuan(hunyuan-turbo / hunyuan-larges, etc.) ​

Síntoma: error de modelo desconocido.

Causa: el provider de Hunyuan de OpenClaw solo tiene la serie hy(hy4-preview、hy3、hy3-preview); nombres antiguos como hunyuan-turbo、hunyuan-larges no existen en TokenHub / TokenPlan(verificación exhaustiva de las fuentes: cero coincidencias).

Solución correcta: usa tencent-tokenhub/hy4-preview(por defecto)o hy3; para necesidades de modelos antiguos, usa el endpoint de compatibilidad personalizado de la siguiente lección.

❌ Formato de Key de Baidu incorrecto / servicio de Qianfan no activado ​

Síntoma: la lista de openclaw models list --provider qianfan está vacía, o las llamadas dan error de credenciales.

Causa: los dos primeros puntos de la lista oficial de solución de problemas: la Key debe empezar con bce-v3/ALTAK-; la cuenta debe tener ya activado el acceso a la API de Qianfan en la consola de Baidu Cloud.

Solución correcta: vuelve a consola de Qianfan para comprobar el formato de la Key y el estado de activación del servicio.

❌ Buscar en el catálogo de Qianfan modelos ERNIE 4.5 / X1 y otros más antiguos ​

Causa: el catálogo de OpenClaw de Qianfan solo incluye ernie-5.1 y ernie-5.0(catálogo estático, sin descubrimiento en línea).

Solución correcta: los modelos de Ernie más antiguos no tienen provider oficial; usa el flujo de «endpoint compatible con OpenAI personalizado» de la siguiente lección, o busca rutas alojadas en agregadores como OpenRouter / NovitaAI.

❌ Usar un ID antiguo ya obsoleto ​

ID obsoletosucesor
tencent-tokenhub/hy3-previewrecomendación del catálogo hy4-preview; doctor --fix solo migra a hy3
qianfan/deepseek-v3.2qianfan/deepseek-v4-pro
qianfan/ernie-5.0-thinking-previewqianfan/ernie-5.0

Forma correcta: para las configuraciones nuevas usa siempre el sucesor; para las configuraciones existentes ejecuta openclaw doctor y revisa las sugerencias antes de migrar.

❌ Tras instalar Gateway como daemon, la Key exportada «no surte efecto» ​

Causa: los servicios de launchd / systemd no ven las variables de entorno de la shell interactiva — la documentación oficial de tencent lo subraya especialmente (tanto TokenHub como TokenPlan, ambas variables deben entregarse al proceso del servicio).

Forma correcta: escribe TOKENHUB_API_KEY, TOKENPLAN_API_KEY, QIANFAN_API_KEY en ~/.openclaw/.env, o proporciónalos vía env.shellEnv; tras cambiar la Key, reinicia el servicio de Gateway.

❌ Creer que doctor --fix te actualizará a Hy4 ​

Causa: regla oficial de migración — para las configuraciones existentes de TokenHub con allowlist configurado, openclaw doctor --fix solo cambia el obsoleto hy3-preview por hy3; no se cambia a Hy4.

Forma correcta: para subir a Hy4 hazlo tú mismo de forma explícita (openclaw models set tencent-tokenhub/hy4-preview), y confirma primero los permisos de acceso a los modelos del endpoint elegido y las diferencias de precio.

❌ Conectar a la fuerza una cuenta de ultramar al endpoint nacional (o viceversa) ​

Causa: el endpoint integrado de TokenHub es https://tokenhub.tencentmaas.com/v1; el endpoint de la versión internacional https://tokenhub-intl.tencentmaas.com/v1 requiere sobrescribir baseUrl explícitamente.

Forma correcta: para las cuentas de TokenHub de ultramar, sobrescribe baseUrl según la siguiente sección; con Qianfan es igual, solo cambia el base URL cuando uses un endpoint o proxy personalizado.

🔧 Avanzado: sobrescritura de endpoints y embeddings de memoria con Qianfan (opcional) ​

Sobrescribir el endpoint de TokenHub (versión internacional / regiones especiales) ​

El catálogo integrado usa https://tokenhub.tencentmaas.com/v1. Solo sobrescribe cuando tu cuenta o región de TokenHub exija un endpoint distinto (ejemplo oficial tal cual, aquí con el endpoint de la versión internacional):

bash
openclaw config set models.providers.tencent-tokenhub.baseUrl "https://tokenhub-intl.tencentmaas.com/v1"

Configurar el modelo de embeddings en chino de Qianfan para el sistema de memoria ​

La recuperación de memoria de OpenClaw necesita un modelo de embedding, y el plugin de Qianfan puede usarse directamente como embedding provider — especialmente adecuado para contenido en chino (ejemplo oficial tal cual):

json5
{
  memory: {
    search: {
      provider: "qianfan",
      model: "bge-large-zh",
    },
  },
}

Tres detalles (la documentación oficial los indica claramente):

  • El plugin reutiliza la conexión de Qianfan que ya configuraste; las credenciales se resuelven desde el perfil guardado o de QIANFAN_API_KEY; un API Key remoto o header Authorization explícito tiene prioridad
  • Los tres modelos bge-large-zh, bge-large-en y Embedding-V1aceptan como máximo 16 entradas por solicitud (siguiendo el límite de lotes oficial de Baidu); los demás modelos mantienen el comportamiento existente del transporte compatible
  • Si una configuración existente usa openai-compatible para apuntar a Qianfan, basta con cambiar memory.search.provider por qianfan — el endpoint y la Key se mantienen sin cambios

El sistema de memoria en sí se describe en Sistema de memoria: haz que Claw te recuerde.

Solo escribe models.providers cuando necesites metadatos personalizados ​

Regla oficial: con el plugin instalado + la autenticación configurada ya es suficiente, no hace falta escribir una entrada en models.providers; solo escríbela para sobrescribir baseUrl o metadatos de modelos. La configuración explícita completa de Qianfan se ve así (extracto del ejemplo oficial tal cual):

json5
{
  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,
          },
        ],
      },
    },
  },
}

Hay además una nota de compatibilidad (sentido original de la documentación oficial): Qianfan usa la ruta de transporte compatible con OpenAI, no un shaping nativo de peticiones OpenAI — las características estándar del SDK de OpenAI están disponibles, pero los parámetros específicos del provider podrían no reenviarse. La documentación oficial de la API de Qianfan está en cloud.baidu.com/doc/qianfan-api.

Siguiente paso ​

Con esto queda completada la integración de Hunyuan y Baidu Qianfan en OpenClaw. Continúa en la página dedicada a los modelos nacionales:

Tutoriales relacionados ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.