Volcengine (Doubao) Provider Setup and Configuration

The Volcengine provider offers access to Doubao models as well as third-party models hosted on Volcano Engine. It exposes separate endpoints for general and coding workloads, and the same official plugin also registers Volcengine Speech as a TTS provider.

Getting started

Install the plugin

openclaw plugins install @openclaw/volcengine-provider
openclaw gateway restart

Set the API key

Launch the interactive onboarding flow:

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

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

Set a default model

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

Verify the model is available

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

Tip

For non-interactive setups such as CI or scripting, supply the key directly:

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

Providers and endpoints

Note

One API key drives both providers. Setup registers them together automatically, and the coding provider's model picker also draws on the general provider's auth (volcengine-plan acts as an auth alias for volcengine).

Built-in catalog

General (volcengine)

Coding (volcengine-plan)

Both catalogs are static, meaning no /models discovery call is made, and they support OpenAI-compatible streamed usage accounting. Tool schemas for both providers automatically strip out minLength, maxLength, minItems, maxItems, minContains, and maxContains keywords, because the Volcengine tool-call API rejects those terms.

Text-to-speech

Volcengine TTS relies on the BytePlus Seed Speech HTTP API (voice.ap-southeast-1.bytepluses.com) and uses its own credentials, separate from the OpenAI-compatible Doubao model API key. In the BytePlus console, navigate to Seed Speech > Settings > API Keys, copy the API key, and configure:

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

Next, enable it under openclaw.json:

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

Fields available under tts.providers.volcengine include apiKey, voice, speedRatio (0.2-3.0), emotion, cluster, resourceId, appKey, and baseUrl. Additionally, !emotion=<value> can serve as an inline voice directive when voice-setting overrides are permitted.

For voice-note targets, OpenClaw asks the provider for native ogg_opus. Regular audio attachments trigger a request for mp3. The provider aliases bytedance and doubao also point to this same speech provider.

By default, the resource id is seed-tts-1.0, which is the entitlement BytePlus assigns to newly created Seed Speech API keys. If your project carries TTS 2.0 entitlement, use VOLCENGINE_TTS_RESOURCE_ID=seed-tts-2.0 instead.

Warning

VOLCANO_ENGINE_API_KEY applies to the ModelArk/Doubao model endpoints and does not serve as a Seed Speech API key. TTS requires a Seed Speech API key obtained from the BytePlus Speech Console, or a legacy Speech Console AppID/token pair.

Older Speech Console applications can still authenticate with the legacy AppID/token approach:

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

Additional optional TTS environment variables include VOLCENGINE_TTS_VOICE, VOLCENGINE_TTS_APP_KEY, and VOLCENGINE_TTS_BASE_URL, which override the matching tts.providers.volcengine config fields whenever they are set.

Advanced configuration

Default model after onboarding

With openclaw onboard --auth-choice volcengine-api-key, volcengine-plan/ark-code-latest becomes the default model, and the general volcengine catalog is registered as well.

Model picker fallback behavior

During onboarding or configure model selection, the Volcengine auth choice gives preference to both volcengine/* and volcengine-plan/* entries. If those models have not been loaded yet, OpenClaw falls back to the unfiltered catalog rather than presenting an empty provider-scoped picker.

Environment variables for daemon processes

When the Gateway operates as a daemon (launchd/systemd), confirm that model and TTS environment variables such as VOLCANO_ENGINE_API_KEY, VOLCENGINE_TTS_API_KEY, BYTEPLUS_SEED_SPEECH_API_KEY, VOLCENGINE_TTS_APPID, and VOLCENGINE_TTS_TOKEN are accessible to that process (for instance, in ~/.openclaw/.env or through env.shellEnv).

Warning

If OpenClaw runs as a background service, environment variables set in your interactive shell are not passed along automatically. Refer to the daemon note above.

Related

• Model selection, How to pick providers, model refs, and failover behavior.

• Configuration, Complete config reference covering agents, models, and providers.

• Troubleshooting, Frequent problems and debugging steps.

• FAQ, Answers to common OpenClaw setup questions.