Skip to content

Integrating Doubao/Volcengine: Ark Endpoints and Coding Plan ​

OpenClaw Integrating Doubao is the sixth stop on the domestic-models track. Volcengine plays differently in OpenClaw than the previous providers: one API Key registers two providers at once — the general volcengine (pay-as-you-go, Doubao + third-party models hosted on Ark) and the coding volcengine-plan (the Coding Plan subscription side), where the latter is an auth alias of the former, so no second Key is needed. The three steps "install plugin → configure credentials → pick a model" from the earlier lessons DeepSeek, Qwen, GLM, Kimi, MiniMax all apply in this lesson. The whole process takes about 8 minutes (Volcengine account registration not included).

First, here is a summary table — all the configuration in this lesson starts from it (properties and values are quoted verbatim from the official documentation):

General side (pay-as-you-go)Coding side (subscription)
Provider idvolcenginevolcengine-plan
Endpointark.cn-beijing.volces.com/api/v3ark.cn-beijing.volces.com/api/coding/v3
PurposeGeneral models (Doubao + third-party models)Coding models (Ark Coding Plan)
AuthenticationVOLCANO_ENGINE_API_KEYReuses the general side's auth (volcengine-plan is an auth alias of volcengine)
Model prefixvolcengine/...volcengine-plan/...
Onboarding default—volcengine-plan/ark-code-latest

One thing you must remember first: the two providers share one Key, but their model reference prefixes differ — ark-code-latest only exists under volcengine-plan/, and doubao-seed-evolving only exists under volcengine/. Get the prefix wrong, and OpenClaw won't recognize the model. Both endpoints live under the same domain ark.cn-beijing.volces.com (Beijing region), differing only in the path: /api/v3 and /api/coding/v3.

How to choose, in three sentences:

Your situationChoose this
Subscribed to the Volcengine Coding Plan, mainly writing codevolcengine-plan/ark-code-latest (onboarding default)
Pay-as-you-go, want Doubao flagships and multimodal inputvolcengine/doubao-seed-evolving (1M context)
Want to use Ark-hosted GLM 5.2 / DeepSeek V4Both sides have them; the prefix follows the endpoint

💡 For readers who arrived by searching "OpenClaw Volcengine" or "OpenClaw ByteDance Models"

Doubao is ByteDance's model family, running on the Ark endpoints of Volcengine (ByteDance's cloud platform) — the ark in the endpoint domain ark.cn-beijing.volces.com refers to Ark. To integrate it, OpenClaw does not need a Doubao App account but a Volcengine Ark API Key; overseas users go through BytePlus (the international version of Volcengine), covered separately at the end of this page.

This tutorial is based on OpenClaw v2026.10.9.

What you'll be able to do after this lesson ​

  • Install the @openclaw/volcengine-provider plugin and use one VOLCANO_ENGINE_API_KEY to register both volcengine (general) and volcengine-plan (Coding) providers
  • Tell the two Ark endpoints apart: /api/v3 (general pay-as-you-go) and /api/coding/v3 (Coding Plan subscription), without getting the model prefixes wrong
  • Understand the built-in catalog: the doubao-seed series, ark-code-latest, and Ark-hosted GLM 5.2, DeepSeek V4 — their respective context sizes, max outputs, and pricing
  • Avoid Volcengine-specific pitfalls: the TTS Key and the model Key are not the same one, old model IDs are deprecated, and a cost of 0 in the Coding-side catalog doesn't mean it's free
  • Configure Doubao TTS for Claw (BytePlus Seed Speech); overseas users can also switch to the international BytePlus version

🎒 Prerequisites ​

  • Completed Model Connection Overview: the Provider System and Model Switching: you're clear on the three steps "provider → authentication → pick a model" and the provider/model reference rules
  • OpenClaw is installed and the Gateway is running: openclaw gateway status produces output
  • You have a Volcano Ark API Key (or are ready to create one in the Volcano Engine console; Coding Plan subscribers use the same one)
  • If you go with server / daemon deployment, know where ~/.openclaw/.env is — that's where the Key will ultimately live

Follow along with me ​

Step 1: Install the Volcengine (Doubao) provider plugin ​

Why: Like DeepSeek and Kimi, volcengine is an external official plugin and OpenClaw does not ship with it — once the plugin is installed, the volcengine and volcengine-plan providers get registered into the model system.

bash
# 1. 安装火山引擎 provider 插件
openclaw plugins install @openclaw/volcengine-provider

# 2. 重启 Gateway(Gateway 正在跑的话,安装会自动生效;重启最稳妥)
openclaw gateway restart

You should see: a message that the plugin installed successfully, and no errors after the Gateway restarts.

Two behaviors to know up front (explicitly stated in the official docs):

  • Installation takes effect** automatically on a running Gateway**; if the Gateway isn't running, it takes effect at next startup

  • The official procedure has no plugins enable step — the plugin manifest is marked enabledByDefault: true, so it's enabled once installed (compare with MiniMax: built in, but you must explicitly enable it)

  • openclaw plugins install @openclaw/volcengine-provider executed successfully, Gateway restarted

Step 2: Connect OpenClaw to Doubao — set up VOLCANO_ENGINE_API_KEY ​

Why: Volcano Ark authentication uses a single Key. Onboarding uses it to** register both** the general-purpose and Coding providers at once — volcengine-plan is an auth alias of volcengine, and the coding side reuses the same credential, so you don't need to configure a second Key.

First, go to the Volcano Engine console to create an Ark API Key, and copy it somewhere safe:

Then run onboarding:

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

You should see: the Key validated and saved; both the general-purpose and Coding providers registered at once, with the default model landing on volcengine-plan/ark-code-latest (the official docs explicitly state: setting the default model also registers the general volcengine catalog).

For non-interactive scenarios like CI / scripts, the official docs give a way to pass the Key directly (verbatim):

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

If you'd rather not run onboarding, manual configuration only needs two things — the Key goes into an environment variable, and the default model is written into the config (official example, verbatim):

bash
export VOLCANO_ENGINE_API_KEY="<你的 API Key>"
json5
{
  agents: {
    defaults: {
      model: { primary: "volcengine-plan/ark-code-latest" },
    },
  },
}

The official plugindoes not need a models.providers entry — install the plugin, set auth, pick a model, and you're done; you only write one when overriding the default endpoint / model list (this rule was covered in the overview lesson).

⚠️ Running the Gateway as a daemon? Don't put the Key in an interactive shell

When the Gateway runs as a launchd / systemd service, it can't see the environment variables you export in your terminal. Write VOLCANO_ENGINE_API_KEY (plus any TTS variables you need) into ~/.openclaw/.env, or provide them to that process via env.shellEnv in the config.

While you're at it, verify both providers are registered:

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

You should see: the general catalog with the volcengine/ prefix (doubao-seed series + GLM / DeepSeek) and the Coding catalog with the volcengine-plan/ prefix (starting with ark-code-latest) both listed.

Two more behaviors to know up front (explicitly stated in the official docs):

  • The model picker in onboarding / configure will** prefer** both the volcengine/* and volcengine-plan/* model families at once; if they haven't loaded yet, OpenClaw falls back to the unfiltered full catalog instead of giving you an empty picker

  • Existing users with a default model already set, note: adding a new provider auth does not change the existing default model — to switch it, run openclaw models set yourself (next section)

  • In openclaw models status's credentials overview, you can see the source of the volcengine credential

Step 3: Pick a Doubao/Ark model and verify ​

Why: Onboarding sets the default model to ark-code-latest on the Coding side by default, which is good to use directly; but the general side also has 1M-context doubao-seed-evolving and turbo at half the catalog price — it costs nothing to check the catalog before deciding.

First, look at the built-in catalog (compiled verbatim from the official docs + plugin manifest).

General side (volcengine, pay-as-you-go):

Model referenceNameInputContextMax outputCatalog price (per million tokens)
volcengine/doubao-seed-evolvingDoubao Seed EvolvingText, image, video1,024,000256,000$0.885 Input / $4.427 Output / $0.177 Cache read
volcengine/doubao-seed-2-1-pro-260628Doubao Seed 2.1 ProText, image, video256,000256,000$0.885 / $4.427 / $0.177
volcengine/doubao-seed-2-1-turbo-260628Doubao Seed 2.1 TurboText, image, video256,000256,000$0.443 / $2.214 / $0.089
volcengine/glm-5-2-260617GLM 5.2Text1,024,000128,000$1.181 / $4.132 / $0.295
volcengine/deepseek-v4-pro-260425DeepSeek V4 ProText1,024,000384,000$1.771 / $3.542 / $0.148
volcengine/deepseek-v4-flash-260425DeepSeek V4 FlashText1,024,000384,000$0.148 / $0.295 / $0.030

Coding endpoint (volcengine-plan, subscription-based):

Model referenceNameInputContextMax output
volcengine-plan/ark-code-latestArk Coding PlanText256,0004,096
volcengine-plan/doubao-seed-2.1-turboDoubao Seed 2.1 TurboText, image, video256,000256,000
volcengine-plan/glm-5.2GLM 5.2Text1,024,000128,000
volcengine-plan/deepseek-v4-proDeepSeek V4 ProText1,024,000384,000
volcengine-plan/deepseek-v4-flashDeepSeek V4 FlashText1,024,000384,000

Catalog behavior and compatibility — all four points come verbatim from the official docs / plugin manifest:

  • Both catalogs arestatically built in (no /models discovery calls involved) and support OpenAI-compatible streaming usage statistics
  • Except for ark-code-latest, all models in the catalogs are marked reasoning: true (reasoning / thinking capability)
  • Tool-call compatibility: both providers automatically strip minLength, maxLength, minItems, maxItems, minContains, maxContains — JSON Schema keywords that Volcano's tool-call API rejects; OpenClaw handles this for you, so under normal configuration you don't need to worry about it
  • The cost field in the Coding endpoint catalogis all 0 — that means "subscription-based, not priced per token", not free; it draws on the Coding Plan subscription quota

The general catalog also still contains three deprecated old IDs (marked deprecated in the plugin manifest, kept only for existing configurations) — don't use them in new configurations:

Deprecated IDSuccessor
volcengine/kimi-k2-5-260127(Kimi K2.5)volcengine/doubao-seed-evolving
volcengine/glm-4-7-251222(GLM 4.7)volcengine/glm-5-2-260617
volcengine/deepseek-v3-2-251201(DeepSeek V3.2)volcengine/deepseek-v4-flash-260425

How to choose, in four sentences:

Your needPick thisRationale
Subscribed to Coding Plan, mainly writing codevolcengine-plan/ark-code-latestonboarding default; used within the subscription quota
Pay-as-you-go, want the latest flagship with multimodal inputvolcengine/doubao-seed-evolving1M context, text + image + video input
Pay-as-you-go and want to save moneyvolcengine/doubao-seed-2-1-turbo-260628catalog price is about half of Pro
Just want to use DeepSeek / GLM, with the key on Arkvolcengine/deepseek-v4-flash-260425 etc.third-party models hosted on Ark, write the prefix volcengine/

Change the default model (note that the prefix follows the endpoint):

bash
# Coding 端(订阅)
openclaw models set volcengine-plan/ark-code-latest

# 通用端(按量)
openclaw models set volcengine/doubao-seed-evolving

You can also switch temporarily in chat: /model volcengine/doubao-seed-2-1-turbo-260628 only affects the current session; see Chat Commands Crash Course for the full command family.

Finally, verify. Send a test message:

bash
openclaw dashboard

Open the Control UI and send "Introduce yourself in one sentence" in the chat box.

You should see: the model replies normally, with no errors about missing credentials or nonexistent models. At this point, OpenClaw is connected to Doubao.

Pricing in one sentence: the general endpoint is pay-as-you-go, and the estimates in the table above are the catalog figures from the OpenClaw plugin manifest (per million tokens); the Coding endpoint uses the subscription quota. Actual prices and currencies are always subject to the Volcano Engine official website.

  • The test message received a reply, and the provider and model match (volcengine/... or volcengine-plan/...)

Checkpoint ✅ ​

  • The @openclaw/volcengine-provider plugin is installed (enabled upon installation, no plugins enable needed)
  • One VOLCANO_ENGINE_API_KEY registers two providers: volcengine (general) + volcengine-plan (Coding)
  • Both openclaw models list --provider volcengine and --provider volcengine-plan can list the catalogs
  • The default model prefix matches the endpoint: write volcengine-plan/ark-code-latest for the Coding endpoint, volcengine/doubao-seed-evolving for the general endpoint
  • The test message received a reply; not configuring TTS doesn't affect chat (TTS uses separate credentials)

Pitfall Reminders ​

❌ Using a Seed Speech key (or Doubao App credentials) as the model key ​

Symptom: onboarding verification fails, or sending a message reports a credential error.

Cause: VOLCANO_ENGINE_API_KEY corresponds to the Ark ModelArk / Doubao model endpoint; the Seed Speech TTS key and the legacy voice console's AppID / token are not it. The official Warning states it clearly: TTS requires a separate Seed Speech API Key.

Correct approach: use VOLCANO_ENGINE_API_KEY for the model; configure TTS separately with VOLCENGINE_TTS_API_KEY (see the dedicated capabilities section below).

❌ Writing the model prefix for the wrong endpoint ​

Symptom: an unknown model error, or the wrong billing surface.

Cause: the two providers have different catalogs — ark-code-latest only exists under volcengine-plan/, and doubao-seed-evolving only exists under volcengine/. The prefix is the endpoint.

Correct approach: copy prefixes from the catalog table on this page; if unsure, run openclaw models list --provider volcengine-plan first to check before writing the configuration.

❌ Using a deprecated old model ID ​

Symptom: the configuration contains old IDs such as volcengine/deepseek-v3-2-251201, volcengine/glm-4-7-251222, volcengine/kimi-k2-5-260127.

Cause: the plugin manifest marks them as deprecated (kept only for existing configurations); they are succeeded by deepseek-v4-flash-260425, glm-5-2-260617, and doubao-seed-evolving respectively.

Correct approach: always use the successors in new configurations; migrate existing configurations when you see the deprecation marker.

❌ After installing the Gateway as a daemon, the exported key "doesn't take effect" ​

Cause: launchd / systemd services can't see the interactive shell's environment variables — the volcengine documentation likewise stresses this point (both the model and TTS variables must be provided to the service process).

Correct approach: write VOLCANO_ENGINE_API_KEY (and the TTS variables) into ~/.openclaw/.env, or provide them via env.shellEnv; after changing the Key, restart the Gateway service.

❌ The cost fields in the Coding-side catalog are all 0, so people assume it's free ​

Cause: volcengine-plan is subscription-based—the cost field for these models in the plugin catalog says 0, which only means "not billed separately per token"; in reality they draw on the Coding Plan subscription quota.

Correct approach: judge cost by subscription quota and limits; for subscription prices, refer to the Volcano Engine official website—don't use the catalog's 0 price for cost accounting.

❌ Catalog estimates don't match the actual bill ​

Cause: the $ figures in the catalog table on this page are estimates from the OpenClaw plugin catalog (per-million-token basis), not Volcano's official pricing.

Correct approach: base cost accounting on the Volcano Engine official pricing page; use catalog estimates only for relative comparison between models (e.g., turbo is roughly half of Pro).

❌ Tool calls with array / string parameters rejected by the Ark API ​

Symptom: tool calls report schema-related errors.

Cause: Volcano's tool-call API rejects these JSON Schema keywords: minLength / maxLength / minItems / maxItems / minContains / maxContains.

Correct approach: confirm the model reference prefix is volcengine/ or volcengine-plan/—these two providers in OpenClaw will automatically strip out the above keywords (the official docs state this explicitly); under normal configuration you don't need to do anything.

❌ Overseas teams mistakenly using the domestic endpoint (or vice versa) ​

Cause: volcengine / volcengine-plan go through ark.cn-beijing.volces.com (domestic); overseas accounts need the separate BytePlus plugins (byteplus / byteplus-plan), with their own independent plugin and Key.

Correct approach: overseas users should follow the BytePlus section at the end of this page; don't force a domestic Key into the BytePlus plugin.

🔧 Doubao-exclusive capabilities: Seed Speech TTS and BytePlus (optional) ​

The same plugin also registers Volcengine Speech as a TTS provider—once configured, Claw's replies can turn into voice messages. It uses BytePlus Seed Speech's HTTP API (voice.ap-southeast-1.bytepluses.com) and is completely separate from the model Key.

Set up Doubao voice for Claw (Seed Speech TTS) ​

Why: the model Key handles chat, the voice Key handles speech—two Keys from two different consoles, don't mix them up.

First set the environment variables (verbatim from the official docs):

bash
# 在 BytePlus 控制台打开 Seed Speech → Settings → API Keys,复制 Key 后:
export VOLCENGINE_TTS_API_KEY="<seed-speech-api-key>"
export VOLCENGINE_TTS_RESOURCE_ID="seed-tts-1.0"

Then enable it in openclaw.json (verbatim from the official example):

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

What you should see: Claw's voice replies play normally; voice-message channels (e.g., Telegram) receive ogg_opus, while ordinary audio attachments receive mp3.

Four details:

  • tts.providers.volcengine available fields: apiKey, voice, speedRatio (0.2–3.0), emotion, cluster, resourceId, appKey, baseUrl; !emotion=<值> can also be used as an inline voice command
  • The default resource id is seed-tts-1.0 (the default authorization BytePlus gives to newly created Seed Speech Keys); if you have TTS 2.0 authorization, set VOLCENGINE_TTS_RESOURCE_ID=seed-tts-2.0
  • The provider aliases bytedance and doubao also point to this voice provider
  • The legacy voice console's AppID / token authentication is still supported: VOLCENGINE_TTS_APPID / VOLCENGINE_TTS_TOKEN / VOLCENGINE_TTS_CLUSTER (default volcano_tts); there are also VOLCENGINE_TTS_VOICE, VOLCENGINE_TTS_APP_KEY, VOLCENGINE_TTS_BASE_URL to override the corresponding config fields

⚠️ Don't mix the two Keys

VOLCANO_ENGINE_API_KEY is the Key for the Ark model endpoint and is not a Seed Speech Key. TTS needs a Key from the BytePlus Speech console (or an AppID / token pair from the legacy console)—the official Warning stresses this point in particular.

For hands-on voice usage (images, text-to-speech, voice messages), see Images and Voice: adding images to content, turning articles into speech.

BytePlus: the international version of Volcano Engine (for overseas users) ​

Based overseas? BytePlus ARK offers the same models as Volcano Ark, but through a separate plugin, with its own independent Key (BYTEPLUS_API_KEY):

General sideCoding side
Plugin@openclaw/byteplus-providerSame plugin
Provider idbyteplusbyteplus-plan
AuthenticationBYTEPLUS_API_KEYReused (onboarding registers both sides at once)
auth-choiceopenclaw onboard --auth-choice byteplus-api-keySame as left
Default model—byteplus-plan/ark-code-latest

Install with two commands (verbatim from the official example):

bash
openclaw plugins install @openclaw/byteplus-provider
openclaw gateway restart

Configuration to pin the default model manually (verbatim from the official example):

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

Three behaviors match the domestic version (the official docs state this explicitly):

  • onboarding defaults to the coding side, while also registering the general byteplus/* catalog
  • The model selector likewise prefers the byteplus/* and byteplus-plan/* families; when not loaded, it falls back to the unfiltered catalog
  • Example models: the general side has byteplus/dola-seed-2-1-turbo-260628, byteplus/seed-2-0-code-preview-260328, byteplus/glm-5-2-260617, byteplus/deepseek-v4-pro-260425, byteplus/deepseek-v4-flash-260425; the Coding side has byteplus-plan/ark-code-latest, byteplus-plan/kimi-k2.5 (Kimi K2.5 Coding)

Next steps ​

OpenClaw Doubao / Volcengine integration is now complete. Continue with the Chinese-model pages:

Related tutorials ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.