Skip to content

Integración de Doubao/Volcengine: endpoints de Ark y Coding Plan ​

La integración de Doubao en OpenClaw es la sexta parada de la página dedicada a modelos nacionales. Volcengine se juega en OpenClaw de una manera distinta a todas las anteriores: una sola API Key registra dos providers a la vez — el general volcengine (pago por uso, Doubao + modelos de terceros alojados en Ark) y el de código volcengine-plan (plan de suscripción Coding Plan), que además es un alias de auth del primero, así que no hace falta configurar una segunda Key. Los tres pasos «instalar plugin → configurar credenciales → elegir modelo» de las lecciones anteriores DeepSeek, Qwen, GLM, Kimi y MiniMax se aplican por completo en esta lección. El proceso completo lleva unos 8 minutos (el registro de la cuenta de Volcengine se cuenta aparte).

Primero te doy una tabla resumen, de la que parte toda la configuración de esta lección (propiedades y valores transcritos tal cual de la documentación oficial):

Extremo general (pago por uso)Extremo Coding (suscripción)
Provider idvolcenginevolcengine-plan
Endpointark.cn-beijing.volces.com/api/v3ark.cn-beijing.volces.com/api/coding/v3
UsoGeneral models (Doubao + modelos de terceros)Coding models (Ark Coding Plan)
AutenticaciónVOLCANO_ENGINE_API_KEYReutiliza el auth del extremo general (volcengine-plan es un alias de auth de volcengine)
Prefijo de modelovolcengine/...volcengine-plan/...
Por defecto en onboarding—volcengine-plan/ark-code-latest

Una cosa que hay que recordar primero: los dos providers comparten una misma Key, pero los prefijos de referencia de los modelos son distintos — ark-code-latest solo existe bajo volcengine-plan/, y doubao-seed-evolving solo existe bajo volcengine/. Si escribes mal el prefijo, OpenClaw no reconocerá el modelo. Los dos endpoints están bajo el mismo dominio ark.cn-beijing.volces.com (región de Pekín) y solo se diferencian en la ruta: /api/v3 y /api/coding/v3.

Cómo elegirlo, en tres frases:

Tu situaciónElige este
Tienes una suscripción a Volcengine Coding Plan y escribes principalmente códigovolcengine-plan/ark-code-latest (por defecto en onboarding)
Pago por uso, quieres el modelo insignia de Doubao y entrada multimodalvolcengine/doubao-seed-evolving (contexto de 1M)
Quieres usar el GLM 5.2 / DeepSeek V4 alojados en ArkAmbos extremos los tienen; el prefijo sigue al endpoint

💡 Para quienes llegan buscando «OpenClaw Volcengine» o «OpenClaw Modelos de ByteDance»

Doubao es la serie de modelos de ByteDance, que corre en los endpoints de Ark (方舟) de Volcengine (la plataforma cloud de ByteDance) — el ark del dominio de endpoint ark.cn-beijing.volces.com es precisamente Ark. Para integrarlo en OpenClaw no se necesita la cuenta de la App de Doubao, sino una API Key de Volcano Ark; los usuarios internacionales pasan por BytePlus (la versión internacional de Volcengine), que se explica por separado al final de esta página.

Este tutorial se basa en OpenClaw v2026.10.9.

Qué podrás hacer al terminar ​

  • Instalar el plugin @openclaw/volcengine-provider y registrar con una sola VOLCANO_ENGINE_API_KEY los dos providers volcengine (general) y volcengine-plan (Coding)
  • Distinguir los dos endpoints de Ark: /api/v3 (general, pago por uso) y /api/coding/v3 (suscripción Coding Plan), sin equivocarte con los prefijos de modelo
  • Entender el catálogo integrado: la serie doubao-seed, ark-code-latest y el GLM 5.2, DeepSeek V4 alojados en Ark, con su contexto, salida máxima y precios respectivos
  • Evitar los errores propios de Volcengine: la Key de TTS y la Key de modelos no son la misma, los IDs de modelos antiguos están deprecados, y que el cost del catálogo del extremo Coding sea 0 no significa que sea gratis
  • Configurar Doubao TTS (BytePlus Seed Speech) para Claw; los usuarios internacionales además pueden cambiar a la versión internacional de BytePlus

🎒 Preparativos antes de empezar ​

  • Has completado Conexión de modelos: visión general del sistema de providers y cambio de modelo: tienes claro el flujo de 3 pasos «provider → autenticación → elección de modelo» y las reglas de referencia provider/model
  • OpenClaw está instalado y el Gateway está en ejecución: openclaw gateway status muestra salida
  • Tienes una API Key de Volcano Ark (o estás listo para crearla en la consola de Volcano Engine; los suscriptores de Coding Plan usan la misma)
  • Si optas por un despliegue en servidor / demonio, sabes dónde está ~/.openclaw/.env — la Key terminará viviendo ahí

Hazlo conmigo ​

Paso 1: instalar el plugin provider de Volcano Engine (Doubao) ​

Por qué: igual que DeepSeek y Kimi, volcengine es un plugin oficial externo que OpenClaw no incluye de fábrica — al instalar el plugin, los dos providers volcengine y volcengine-plan se registran en el sistema de modelos.

bash
# 1. 安装火山引擎 provider 插件
openclaw plugins install @openclaw/volcengine-provider

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

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

Dos comportamientos que conviene conocer de antemano (la documentación oficial lo indica claramente):

  • 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

  • El flujo oficial no incluye un paso plugins enable — el manifiesto del plugin marca enabledByDefault: true, así que se activa al instalarlo (compárese con MiniMax: integrado, pero hay que nombrarlo para habilitarlo)

  • openclaw plugins install @openclaw/volcengine-provider se ejecutó con éxito y el Gateway se ha reiniciado

Paso 2: conectar OpenClaw a Doubao — configurar VOLCANO_ENGINE_API_KEY ​

Por qué: la autenticación de Volcano Ark usa una sola Key. El onboarding la usa para registrar simultáneamente los dos providers, el general y el Coding — volcengine-plan es un alias de auth de volcengine, y el lado de coding reutiliza la misma credencial, sin necesidad de configurar una segunda Key.

Primero ve a la consola de Volcano Engine, crea una API Key de Ark y cópiala en un lugar seguro:

Luego ejecuta el onboarding:

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

Deberías ver: la Key se valida y se guarda; los dos providers, el general y el Coding, se registran a la vez, y el modelo por defecto queda en volcengine-plan/ark-code-latest (la documentación oficial lo indica claramente: al definir el modelo por defecto, también se registra el catálogo general volcengine).

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

bash
openclaw onboard --non-interactive --accept-risk --skip-health \
  --mode local \
  --auth-choice volcengine-api-key \
  --volcengine-api-key "$VOLCANO_ENGINE_API_KEY"

Si prefieres no ejecutar el onboarding, la configuración manual mínima solo requiere dos cosas — la Key en una variable de entorno y el modelo por defecto escrito en la configuración (ejemplo oficial tal cual):

bash
export VOLCANO_ENGINE_API_KEY="<你的 API Key>"
json5
{
  agents: {
    defaults: {
      model: { primary: "volcengine-plan/ark-code-latest" },
    },
  },
}

El plugin oficial no necesita una entrada models.providers — basta con instalar el plugin, configurar el auth y elegir el modelo; solo se escribe al sobrescribir el endpoint por defecto / la lista de modelos (esta regla se explicó en la lección de visión general).

⚠️ ¿El Gateway corre como demonio? No pongas la Key en un shell interactivo

Cuando el Gateway se ejecuta como servicio de launchd / systemd, no ve las variables de entorno de tu terminal export. Escribe VOLCANO_ENGINE_API_KEY (y las variables de TTS que uses) en ~/.openclaw/.env, o propórcialas a ese proceso mediante env.shellEnv en la configuración.

De paso, verifica que ambos providers se hayan registrado:

bash
openclaw models list --provider volcengine
openclaw models list --provider volcengine-plan

Deberías ver: tanto el catálogo general con prefijo volcengine/ (serie doubao-seed + GLM / DeepSeek) como el catálogo Coding con prefijo volcengine-plan/ (encabezado por ark-code-latest) aparecen en la lista.

Hay dos comportamientos más que conviene conocer de antemano (la documentación oficial lo indica claramente):

  • El selector de modelos del onboarding / configure favorece simultáneamente a las dos familias de modelos volcengine/* y volcengine-plan/*; cuando aún no se han cargado, OpenClaw retrocede al catálogo completo sin filtrar y no te muestra un selector vacío

  • Atención a quienes ya tienen un modelo por defecto: añadir un nuevo auth de provider no modifica el modelo por defecto existente — si quieres cambiarlo, ejecuta tú mismo openclaw models set (siguiente sección)

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

Paso 3: elegir un modelo Doubao / Ark y verificar ​

Por qué: el onboarding por defecto asigna como modelo por defecto el ark-code-latest del lado Coding, suficiente para empezar; pero en el lado general también está el doubao-seed-evolving con contexto de 1M y el turbo con la mitad del precio de catálogo — no pierdes nada echando un vistazo al catálogo antes de decidir.

Primero, el catálogo integrado (recopilado tal cual de la documentación oficial + el manifiesto del plugin).

Lado general (volcengine, pago por uso):

Referencia del modeloNombreEntradaContextoSalida máximaPrecio estimado de catálogo (por millón de tokens)
volcengine/doubao-seed-evolvingDoubao Seed Evolvingtexto, imagen, video1,024,000256,000$0.885 entrada / $4.427 salida / $0.177 lectura de caché
volcengine/doubao-seed-2-1-pro-260628Doubao Seed 2.1 Protexto, imagen, video256,000256,000$0.885 / $4.427 / $0.177
volcengine/doubao-seed-2-1-turbo-260628Doubao Seed 2.1 Turbotexto, imagen, video256,000256,000$0.443 / $2.214 / $0.089
volcengine/glm-5-2-260617GLM 5.2texto1,024,000128,000$1.181 / $4.132 / $0.295
volcengine/deepseek-v4-pro-260425DeepSeek V4 Protexto1,024,000384,000$1.771 / $3.542 / $0.148
volcengine/deepseek-v4-flash-260425DeepSeek V4 Flashtexto1,024,000384,000$0.148 / $0.295 / $0.030

Lado Coding (volcengine-plan, por suscripción):

referencia del modelonombreentradacontextosalida máxima
volcengine-plan/ark-code-latestArk Coding Plantexto256,0004,096
volcengine-plan/doubao-seed-2.1-turboDoubao Seed 2.1 Turbotexto, imagen, vídeo256,000256,000
volcengine-plan/glm-5.2GLM 5.2texto1,024,000128,000
volcengine-plan/deepseek-v4-proDeepSeek V4 Protexto1,024,000384,000
volcengine-plan/deepseek-v4-flashDeepSeek V4 Flashtexto1,024,000384,000

Comportamiento del catálogo y compatibilidad, las cuatro provienen textualmente de la documentación oficial / del manifiesto del plugin:

  • Ambos catálogos son estáticos e integrados (no usan la llamada de descubrimiento /models) y admiten estadísticas de uso en streaming compatibles con OpenAI
  • Excepto ark-code-latest, todos los modelos del catálogo están marcados con reasoning: true (capacidad de razonamiento / pensamiento)
  • Compatibilidad con tool-call: ambos providers eliminan automáticamente minLength, maxLength, minItems, maxItems, minContains, maxContains, estas palabras clave de JSON Schema — la API de tool-call de Volcano las rechaza, OpenClaw lo gestiona por ti, así que con una configuración normal no hay que preocuparse
  • El campo cost del catálogo del lado Codinges todo 0 — eso significa «suscripción sin tarificación por token separada», no significa que sea gratis, se usa la cuota de la suscripción del Coding Plan

En el catálogo general además hay tresobsoletos antiguos IDs (marcados deprecated en el manifiesto del plugin, conservados solo para configuraciones existentes), no los uses en configuraciones nuevas:

ID obsoletosustituto
volcengine/kimi-k2-5-260127 (Kimi K2.5)volcengine/doubao-seed-evolving
volcengine/glm-4-7-251222(GLM 4.7)volcengine/glm-5-2-260617
volcengine/deepseek-v3-2-251201 (DeepSeek V3.2)volcengine/deepseek-v4-flash-260425

Cómo elegir, en cuatro frases:

tu necesidadelige estecriterio
Tienes suscripción al Coding Plan, principalmente para escribir códigovolcengine-plan/ark-code-latestvalor por defecto del onboarding; dentro de la cuota de suscripción
Pago por uso y quieres el último modelo insignia, entrada multimodalvolcengine/doubao-seed-evolving1M de contexto, entrada de texto + imagen + vídeo
Pago por uso y quieres ahorrarvolcengine/doubao-seed-2-1-turbo-260628el precio del catálogo es aproximadamente la mitad del Pro
Simplemente quieres usar DeepSeek / GLM, con la Key en Arkvolcengine/deepseek-v4-flash-260425 etc.Modelos de terceros alojados en Ark; escribe el prefijo volcengine/

Cambiar el modelo por defecto (ten en cuenta que el prefijo va según el endpoint):

bash
# Coding 端(订阅)
openclaw models set volcengine-plan/ark-code-latest

# 通用端(按量)
openclaw models set volcengine/doubao-seed-evolving

También puedes cambiarlo temporalmente en el chat: /model volcengine/doubao-seed-2-1-turbo-260628 solo afecta a la sesión actual, la familia de comandos se detalla en curso rápido de comandos de chat.

Verificación final. 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 conexión de OpenClaw con Doubao queda funcionando.

El precio en una frase: el lado general se factura por uso, las estimaciones de la tabla anterior son los números del catálogo del manifiesto del plugin OpenClaw (en unidades de millón de tokens); el lado Coding usa la cuota de la suscripción. El precio real y la moneda se rigen siempre por el sitio web oficial de Volcano Engine.

  • El mensaje de prueba recibió respuesta, el provider y el modelo coinciden (volcengine/... o volcengine-plan/...)

Punto de control ✅ ​

  • El plugin @openclaw/volcengine-provider está instalado (se activa al instalarlo, no hace falta plugins enable)
  • Una sola VOLCANO_ENGINE_API_KEY registra dos providers: volcengine (general) + volcengine-plan (Coding)
  • openclaw models list --provider volcengine y --provider volcengine-plan pueden listar el catálogo
  • El prefijo del modelo por defecto va acorde al endpoint: en el lado Coding escribe volcengine-plan/ark-code-latest, en el lado general escribe volcengine/doubao-seed-evolving
  • El mensaje de prueba recibió respuesta; no configurar TTS no afecta al chat (TTS es una credencial independiente)

Advertencia de errores comunes ​

❌ Usar la Key de Seed Speech (o las credenciales de la App de Doubao) como Key del modelo ​

Síntoma: la validación del onboarding no pasa, o el envío de mensajes da error de credenciales.

Causa: VOLCANO_ENGINE_API_KEY corresponde alendpoint de modelos Ark ModelArk / Doubao; la Key de Seed Speech TTS y el AppID / token de la antigua consola de voz no lo son. El Warning oficial lo dice claramente: TTS necesita una Seed Speech API Key aparte.

Forma correcta: para el modelo usa VOLCANO_ENGINE_API_KEY; para TTS configura aparte VOLCENGINE_TTS_API_KEY (ver la sección de capacidades dedicadas más abajo).

❌ Escribir el prefijo del modelo en el endpoint equivocado ​

Síntoma: da error de modelo desconocido, o el plan de facturación no es el correcto.

Causa: los catálogos de los dos provider son distintos: ark-code-latest solo está bajo volcengine-plan/, y doubao-seed-evolving solo bajo volcengine/. El prefijo es el endpoint.

Forma correcta: copia el prefijo tal cual de la tabla de catálogo de esta página; si no estás seguro, primero verifica con openclaw models list --provider volcengine-plan y luego escribe la configuración.

❌ Se usó un ID de modelo antiguo y descontinuado ​

Síntoma: en la configuración se escriben IDs antiguos como volcengine/deepseek-v3-2-251201, volcengine/glm-4-7-251222, volcengine/kimi-k2-5-260127.

Causa: el manifiesto del plugin los marca como deprecated (conservados solo para configuraciones existentes), y han sido reemplazados respectivamente por deepseek-v4-flash-260425, glm-5-2-260617, doubao-seed-evolving.

Forma correcta: las configuraciones nuevas deben usar siempre los reemplazos; si ves la marca de descontinuación en una configuración existente, migrala.

❌ Tras instalar Gateway como demonio, 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 de volcengine también lo subraya (tanto las variables del modelo como las de TTS deben entregarse al proceso del servicio).

Forma correcta: escribe VOLCANO_ENGINE_API_KEY (y las variables de TTS) en ~/.openclaw/.env, o proporciónalas vía env.shellEnv; tras cambiar la Key, reinicia el servicio de Gateway.

❌ En el catálogo del extremo Coding el cost es todo 0 y se asume que es gratis ​

Causa: volcengine-plan es por suscripción: en el manifiesto del plugin el campo cost de estos modelos figura como 0, lo que solo significa «sin tarificación por token aparte»; en realidad se consume la cuota de la suscripción Coding Plan.

Forma correcta: el costo se mira en la cuota y el límite de la suscripción; el precio de la suscripción se rige por el sitio oficial de Volcano Engine, no uses el precio 0 del catálogo para calcular costos.

❌ La estimación del catálogo no coincide con la factura real ​

Causa: las cifras en $ de la tabla de catálogo de esta página son estimaciones del manifiesto del plugin de OpenClaw (en base por millón de tokens), no son las tarifas oficiales de Volcano.

Forma correcta: el cálculo de costos se rige por la página de precios del sitio oficial de Volcano Engine; la estimación del catálogo sirve solo para comparaciones relativas entre modelos (por ejemplo, turbo es aproximadamente la mitad de Pro).

❌ Las llamadas a herramientas con parámetros de tipo array / string son rechazadas por la API de Ark ​

Síntoma: las llamadas a herramientas reportan errores relacionados con el schema.

Causa: la API de tool-call de Volcano rechaza las palabras clave de JSON Schema minLength / maxLength / minItems / maxItems / minContains / maxContains.

Forma correcta: confirma que el prefijo de referencia del modelo sea volcengine/ o volcengine-plan/: estos dos provider de OpenClaw eliminan automáticamente las palabras clave anteriores (la documentación oficial lo indica expresamente); con una configuración normal no tienes que hacer nada.

❌ Un equipo de ultramar usa por error el endpoint de China continental (o viceversa) ​

Causa: volcengine / volcengine-plan apuntan a ark.cn-beijing.volces.com (China continental); las cuentas de ultramar deben usar el plugin independiente de BytePlus (byteplus / byteplus-plan), con plugin y Key completamente independientes.

Forma correcta: los usuarios de ultramar configuran según la sección de BytePlus al final de esta página; no fuerces una Key de China continental en el plugin de BytePlus.

🔧 Capacidades exclusivas de Doubao: Seed Speech TTS y BytePlus (opcional) ​

El mismo plugin también registra Volcengine Speech (voz de Volcano) como provider de TTS: una vez configurado, las respuestas de Claw pueden convertirse en mensajes de voz. Usa la API HTTP de BytePlus Seed Speech (voice.ap-southeast-1.bytepluses.com), completamente separada de la Key del modelo.

Configurar la voz de Doubao para Claw (Seed Speech TTS) ​

Por qué: la Key del modelo gestiona el chat y la Key de voz gestiona el habla; las dos Keys provienen de dos consolas distintas, no las mezcles.

Primero define las variables de entorno (tal cual en la documentación oficial):

bash
# 在 BytePlus 控制台打开 Seed Speech → Settings → API Keys,复制 Key 后:
export VOLCENGINE_TTS_API_KEY="<seed-speech-api-key>"
export VOLCENGINE_TTS_RESOURCE_ID="seed-tts-1.0"

Luego actívalo en openclaw.json (ejemplo oficial tal cual):

json5
{
  tts: {
    auto: "always",
    provider: "volcengine",
    providers: {
      volcengine: {
        apiKey: "${VOLCENGINE_TTS_API_KEY}",
        voice: "en_female_anna_mars_bigtts",
        speedRatio: 1.0,
      },
    },
  },
}

Deberías ver: las respuestas de voz de Claw se reproducen con normalidad; los canales de mensajes de voz (como Telegram) reciben ogg_opus y los adjuntos de audio normales reciben mp3.

Cuatro detalles:

  • Campos disponibles en tts.providers.volcengine: apiKey, voice, speedRatio (0.2–3.0), emotion, cluster, resourceId, appKey, baseUrl; !emotion=<值> además puede usarse como comando de voz en línea
  • El resource id por defecto es seed-tts-1.0 (la autorización por defecto que BytePlus da a las nuevas Seed Speech Key); si tienes autorización TTS 2.0, define VOLCENGINE_TTS_RESOURCE_ID=seed-tts-2.0
  • Los alias de provider bytedance, doubao también apuntan a este provider de voz
  • Sigue admitiéndose la autenticación por AppID / token de la consola de voz antigua: VOLCENGINE_TTS_APPID / VOLCENGINE_TTS_TOKEN / VOLCENGINE_TTS_CLUSTER (por defecto volcano_tts); además, VOLCENGINE_TTS_VOICE, VOLCENGINE_TTS_APP_KEY, VOLCENGINE_TTS_BASE_URL pueden sobrescribir los campos de configuración correspondientes

⚠️ No mezcles las dos Keys

VOLCANO_ENGINE_API_KEY es la Key del endpoint del modelo de Ark, no la Seed Speech Key. Para TTS se necesita la Key de la consola de BytePlus Speech (o el par AppID / token de la consola antigua); el Warning oficial lo recalca especialmente.

Las prácticas de voz (imágenes, conversión a voz, mensajes de voz) se describen en Imágenes y voz: añadir imágenes al contenido, convertir artículos en voz.

BytePlus: la versión internacional de Volcano (usuarios de ultramar) ​

¿Estás en el extranjero? BytePlus ARK ofrece los mismos modelos que Volcano Ark, pero mediante un plugin independiente, con una Key también independiente (BYTEPLUS_API_KEY):

Extremo generalExtremo Coding
Plugin@openclaw/byteplus-providerEl mismo plugin
Provider idbyteplusbyteplus-plan
AutenticaciónBYTEPLUS_API_KEYReutilizada (onboarding registra ambos extremos a la vez)
auth-choiceopenclaw onboard --auth-choice byteplus-api-keyIgual que a la izquierda
Modelo por defecto—byteplus-plan/ark-code-latest

Instalación con dos comandos (ejemplo oficial tal cual):

bash
openclaw plugins install @openclaw/byteplus-provider
openclaw gateway restart

Configuración para fijar manualmente el modelo por defecto (ejemplo oficial tal cual):

json5
{
  agents: {
    defaults: { model: { primary: "byteplus-plan/ark-code-latest" } },
  },
}

Tres comportamientos coinciden con la versión de China continental (la documentación oficial lo indica expresamente):

  • onboarding va por defecto al extremo coding y registra a la vez el catálogo general byteplus/*
  • El selector de modelos también prefiere las dos familias byteplus/* y byteplus-plan/*; si no están cargadas, retrocede al catálogo sin filtrar
  • Modelos de ejemplo: en el extremo general están byteplus/dola-seed-2-1-turbo-260628, byteplus/seed-2-0-code-preview-260328, byteplus/glm-5-2-260617, byteplus/deepseek-v4-pro-260425, byteplus/deepseek-v4-flash-260425; en el extremo Coding están byteplus-plan/ark-code-latest, byteplus-plan/kimi-k2.5 (Kimi K2.5 Coding)

Siguiente paso ​

OpenClaw La integración de Doubao/Volcengine queda completada aquí. Continúa por la página dedicada a 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.