Skip to main content
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.
DetailValue
Providersvolcengine (general + TTS), volcengine-plan (coding)
Model authVOLCANO_ENGINE_API_KEY
TTS authVOLCENGINE_TTS_API_KEY or BYTEPLUS_SEED_SPEECH_API_KEY
APIOpenAI-compatible models, BytePlus Seed Speech TTS

​
Getting started

1

Set the API key

Run interactive onboarding:
openclaw onboard --auth-choice volcengine-api-key
This registers both the general (volcengine) and coding (volcengine-plan) providers from a single API key.
2

Set a default model

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

Verify the model is available

openclaw models list --provider volcengine
openclaw models list --provider volcengine-plan
For non-interactive setup (CI, scripting), pass the key directly:
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice volcengine-api-key \
  --volcengine-api-key "$VOLCANO_ENGINE_API_KEY"

​
Providers and endpoints

ProviderEndpointUse case
volcengineark.cn-beijing.volces.com/api/v3General models
volcengine-planark.cn-beijing.volces.com/api/coding/v3Coding models
Both providers are configured from a single API key. Setup registers both automatically, and the coding provider’s model picker also reuses the general provider’s auth (volcengine-plan is an auth alias of volcengine).

​
Built-in catalog

Model refNameInputContext
volcengine/deepseek-v3-2-251201DeepSeek V3.2text, image128,000
volcengine/doubao-seed-1-8-251228Doubao Seed 1.8text, image256,000
volcengine/doubao-seed-code-preview-251028doubao-seed-code-preview-251028text, image256,000
volcengine/glm-4-7-251222GLM 4.7text, image200,000
volcengine/kimi-k2-5-260127Kimi K2.5text, image256,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: 
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: 
{
  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.
VOLCANO_ENGINE_API_KEY is for the ModelArk/Doubao model endpoints and is not a Seed Speech API key. TTS needs a Seed Speech API key from the BytePlus Speech Console, or a legacy Speech Console AppID/token pair.
Legacy AppID/token auth remains supported for older Speech Console applications: 
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

openclaw onboard --auth-choice volcengine-api-key sets volcengine-plan/ark-code-latest as the default model while also registering the general volcengine catalog.
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.
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).
When running OpenClaw as a background service, environment variables set in your interactive shell are not automatically inherited. See the daemon note above.

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.