OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Providers

Volcengine (Doubao)

The Volcengine provider gives access to Doubao models and third-party models hosted on Volcano Engine, with separate endpoints for general and coding workloads. The same bundled plugin also registers Volcengine Speech as a TTS provider.

Detail Value
Providers volcengine (general + TTS), volcengine-plan (coding)
Model auth VOLCANO_ENGINE_API_KEY
TTS auth VOLCENGINE_TTS_API_KEY or BYTEPLUS_SEED_SPEECH_API_KEY
API OpenAI-compatible models, BytePlus Seed Speech TTS

Getting started

  • Set the API key

    Run interactive onboarding:

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

    This registers both the general (volcengine) and coding (volcengine-plan) providers from a single API key.

  • Set a default model

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

  • Verify the model is available

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

    • Providers and endpoints

    Provider Endpoint Use case
    volcengine ark.cn-beijing.volces.com/api/v3 General models
    volcengine-plan ark.cn-beijing.volces.com/api/coding/v3 Coding models

    Built-in catalog

    General (volcengine)

    Model ref Name Input Context
    volcengine/deepseek-v3-2-251201 DeepSeek V3.2 text, image 128,000
    volcengine/doubao-seed-1-8-251228 Doubao Seed 1.8 text, image 256,000
    volcengine/doubao-seed-code-preview-251028 doubao-seed-code-preview-251028 text, image 256,000
    volcengine/glm-4-7-251222 GLM 4.7 text, image 200,000
    volcengine/kimi-k2-5-260127 Kimi K2.5 text, image 256,000

    Coding (volcengine-plan)

    Model ref Name Input Context
    volcengine-plan/ark-code-latest Ark Coding Plan text 256,000
    volcengine-plan/doubao-seed-code Doubao Seed Code text 256,000
    volcengine-plan/doubao-seed-code-preview-251028 Doubao Seed Code Preview text 256,000
    volcengine-plan/glm-4.7 GLM 4.7 Coding text 200,000
    volcengine-plan/kimi-k2-thinking Kimi K2 Thinking text 256,000
    volcengine-plan/kimi-k2.5 Kimi K2.5 Coding text 256,000

    Both catalogs are static (no /models discovery call) and support OpenAI-compatible streamed usage accounting. Tool schemas for both providers automatically drop minLength, maxLength, minItems, maxItems, minContains, and maxContains keywords, since the Volcengine tool-call API rejects them.

    Text-to-speech

    Volcengine TTS uses the BytePlus Seed Speech HTTP API (voice.ap-southeast-1.bytepluses.com) and is configured separately from the OpenAI-compatible Doubao model API key. In the BytePlus console, open Seed Speech > Settings > API Keys, copy the API key, then set:

    bash
    export VOLCENGINE_TTS_API_KEY="byteplus_seed_speech_api_key"export VOLCENGINE_TTS_RESOURCE_ID="seed-tts-1.0"

    Then enable it in openclaw.json:

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

    Available fields under messages.tts.providers.volcengine: apiKey, voice, speedRatio (0.2-3.0), emotion, cluster, resourceId, appKey, and baseUrl. !emotion=<value> also works as an inline voice directive when voice-setting overrides are allowed.

    For voice-note targets, OpenClaw requests provider-native ogg_opus. For normal audio attachments, it requests mp3. Provider aliases bytedance and doubao also resolve to this speech provider.

    The default resource id is seed-tts-1.0, the entitlement BytePlus grants to newly created Seed Speech API keys by default. If your project has TTS 2.0 entitlement, set VOLCENGINE_TTS_RESOURCE_ID=seed-tts-2.0.

    Legacy AppID/token auth remains supported for older Speech Console applications:

    bash
    export VOLCENGINE_TTS_APPID="speech_app_id"export VOLCENGINE_TTS_TOKEN="speech_access_token"export VOLCENGINE_TTS_CLUSTER="volcano_tts"

    Other optional TTS env vars: VOLCENGINE_TTS_VOICE, VOLCENGINE_TTS_APP_KEY, and VOLCENGINE_TTS_BASE_URL override the corresponding messages.tts.providers.volcengine config fields when set.

    Advanced configuration

    Default model after onboarding

    openclaw onboard --auth-choice volcengine-api-key sets volcengine-plan/ark-code-latest as the default model while also registering the general volcengine catalog.

    Model picker fallback behavior

    During onboarding/configure model selection, the Volcengine auth choice prefers both volcengine/* and volcengine-plan/* rows. If those models are not loaded yet, OpenClaw falls back to the unfiltered catalog instead of showing an empty provider-scoped picker.

    Environment variables for daemon processes

    If the Gateway runs as a daemon (launchd/systemd), make sure model and TTS env vars such as VOLCANO_ENGINE_API_KEY, VOLCENGINE_TTS_API_KEY, BYTEPLUS_SEED_SPEECH_API_KEY, VOLCENGINE_TTS_APPID, and VOLCENGINE_TTS_TOKEN are available to that process (for example, in ~/.openclaw/.env or via env.shellEnv).

    Model selection

    Choosing providers, model refs, and failover behavior.
    Configuration

    Full config reference for agents, models, and providers.
    Troubleshooting

    Common issues and debugging steps.
    FAQ

    Frequently asked questions about OpenClaw setup.
    Was this useful?
    On this page

    On this page