Volcengine (Doubao) Provider

기준일: 2026-07-26
난이도: 중급
공식 기준: Volcengine (Doubao)

개요

이 페이지는 OpenClaw Volcengine (Doubao) provider의 인증, 모델 ref, 온보딩 플래그, 설정 키를 공식 문서 기준으로 정리합니다.

공식 요약: Volcano Engine setup (Doubao models, coding endpoints, and Seed Speech TTS)

model ref는 보통 provider/model 형식입니다. API key·endpoint·model id는 아래 원문 값을 그대로 쓰세요. 임의로 키나 엔드포인트를 만들지 마세요.

빠른 참조

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

공식 문서 기반 상세

아래는 공식 providers/volcengine 문서를 Mintlify 컴포넌트만 정리하고 공통 제목을 한국어로 맞춘 내용입니다. 설정 키, env, model ref, CLI 플래그는 원문 그대로 유지합니다.

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

시작하기

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

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

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


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

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:

{
  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 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 tts.providers.volcengine config fields when set.

고급 설정

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`).

When running OpenClaw as a background service, environment variables set in your interactive shell are not automatically inherited. See the daemon note above.

관련 문서

Choosing providers, model refs, and failover behavior.


Full config reference for agents, models, and providers.


Common issues and debugging steps.


Frequently asked questions about OpenClaw setup.

검증 체크리스트

• openclaw models list --provider volcengine 로 모델이 보이는지 확인
• 기본 model alias를 agents.defaults.model.primary에 설정했는지 확인
• API key / OAuth / 로컬 런타임 인증 경로를 공식 문서와 대조했는지 확인
• failover 시 데이터가 다른 provider로 이동할 수 있는지 검토

관련

• Provider 목록 인덱스
• 로컬 모델과 Provider
• 공식: Provider directory, Model providers