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 can also register 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:
Terminal window
```
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

{
  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 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

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

Model ref	Name	Input	Context
`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/kimi-k2-5-260127`	Kimi K2.5	text, image	256,000
`volcengine/glm-4-7-251222`	GLM 4.7	text, image	200,000
`volcengine/deepseek-v3-2-251201`	DeepSeek V3.2	text, image	128,000

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/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
`volcengine-plan/doubao-seed-code-preview-251028`	Doubao Seed Code Preview	text	256,000

Text-to-speech

Volcengine TTS uses the BytePlus Seed Speech HTTP API and is configured separately from the OpenAI-compatible Doubao model API key. In the BytePlus console, open Seed Speech > Settings > API Keys and 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,
        },
      },
    },
  },
}

For voice-note targets, OpenClaw asks Volcengine for provider-native ogg_opus. For normal audio attachments, it asks for mp3. Provider aliases bytedance and doubao also resolve to the same speech provider.

The default resource id is seed-tts-1.0 because that is what BytePlus grants to newly created Seed Speech API keys in the default project. 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:

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

Advanced configuration

Default model after onboarding

openclaw onboard --auth-choice volcengine-api-key currently 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.