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 id | volcengine | volcengine-plan |
| Endpoint | ark.cn-beijing.volces.com/api/v3 | ark.cn-beijing.volces.com/api/coding/v3 |
| Purpose | General models (Doubao + third-party models) | Coding models (Ark Coding Plan) |
| Authentication | VOLCANO_ENGINE_API_KEY | Reuses the general side's auth (volcengine-plan is an auth alias of volcengine) |
| Model prefix | volcengine/... | 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 situation | Choose this |
|---|---|
| Subscribed to the Volcengine Coding Plan, mainly writing code | volcengine-plan/ark-code-latest (onboarding default) |
| Pay-as-you-go, want Doubao flagships and multimodal input | volcengine/doubao-seed-evolving (1M context) |
| Want to use Ark-hosted GLM 5.2 / DeepSeek V4 | Both 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-providerplugin and use oneVOLCANO_ENGINE_API_KEYto register bothvolcengine(general) andvolcengine-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/modelreference rules - OpenClaw is installed and the Gateway is running:
openclaw gateway statusproduces 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/.envis — 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.
# 1. 安装火山引擎 provider 插件
openclaw plugins install @openclaw/volcengine-provider
# 2. 重启 Gateway(Gateway 正在跑的话,安装会自动生效;重启最稳妥)
openclaw gateway restartYou 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 enablestep — the plugin manifest is markedenabledByDefault: true, so it's enabled once installed (compare with MiniMax: built in, but you must explicitly enable it)openclaw plugins install @openclaw/volcengine-providerexecuted 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:
openclaw onboard --auth-choice volcengine-api-keyYou 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):
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):
export VOLCANO_ENGINE_API_KEY="<你的 API Key>"{
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:
openclaw models list --provider volcengine
openclaw models list --provider volcengine-planYou 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/*andvolcengine-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 pickerExisting 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 setyourself (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 reference | Name | Input | Context | Max output | Catalog price (per million tokens) |
|---|---|---|---|---|---|
volcengine/doubao-seed-evolving | Doubao Seed Evolving | Text, image, video | 1,024,000 | 256,000 | $0.885 Input / $4.427 Output / $0.177 Cache read |
volcengine/doubao-seed-2-1-pro-260628 | Doubao Seed 2.1 Pro | Text, image, video | 256,000 | 256,000 | $0.885 / $4.427 / $0.177 |
volcengine/doubao-seed-2-1-turbo-260628 | Doubao Seed 2.1 Turbo | Text, image, video | 256,000 | 256,000 | $0.443 / $2.214 / $0.089 |
volcengine/glm-5-2-260617 | GLM 5.2 | Text | 1,024,000 | 128,000 | $1.181 / $4.132 / $0.295 |
volcengine/deepseek-v4-pro-260425 | DeepSeek V4 Pro | Text | 1,024,000 | 384,000 | $1.771 / $3.542 / $0.148 |
volcengine/deepseek-v4-flash-260425 | DeepSeek V4 Flash | Text | 1,024,000 | 384,000 | $0.148 / $0.295 / $0.030 |
Coding endpoint (volcengine-plan, subscription-based):
| Model reference | Name | Input | Context | Max output |
|---|---|---|---|---|
volcengine-plan/ark-code-latest | Ark Coding Plan | Text | 256,000 | 4,096 |
volcengine-plan/doubao-seed-2.1-turbo | Doubao Seed 2.1 Turbo | Text, image, video | 256,000 | 256,000 |
volcengine-plan/glm-5.2 | GLM 5.2 | Text | 1,024,000 | 128,000 |
volcengine-plan/deepseek-v4-pro | DeepSeek V4 Pro | Text | 1,024,000 | 384,000 |
volcengine-plan/deepseek-v4-flash | DeepSeek V4 Flash | Text | 1,024,000 | 384,000 |
Catalog behavior and compatibility — all four points come verbatim from the official docs / plugin manifest:
- Both catalogs arestatically built in (no
/modelsdiscovery calls involved) and support OpenAI-compatible streaming usage statistics - Except for
ark-code-latest, all models in the catalogs are markedreasoning: 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 ID | Successor |
|---|---|
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 need | Pick this | Rationale |
|---|---|---|
| Subscribed to Coding Plan, mainly writing code | volcengine-plan/ark-code-latest | onboarding default; used within the subscription quota |
| Pay-as-you-go, want the latest flagship with multimodal input | volcengine/doubao-seed-evolving | 1M context, text + image + video input |
| Pay-as-you-go and want to save money | volcengine/doubao-seed-2-1-turbo-260628 | catalog price is about half of Pro |
| Just want to use DeepSeek / GLM, with the key on Ark | volcengine/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):
# Coding 端(订阅)
openclaw models set volcengine-plan/ark-code-latest
# 通用端(按量)
openclaw models set volcengine/doubao-seed-evolvingYou 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:
openclaw dashboardOpen 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/...orvolcengine-plan/...)
Checkpoint ✅
- The
@openclaw/volcengine-providerplugin is installed (enabled upon installation, no plugins enable needed) - One
VOLCANO_ENGINE_API_KEYregisters two providers:volcengine(general) +volcengine-plan(Coding) - Both
openclaw models list --provider volcengineand--provider volcengine-plancan list the catalogs - The default model prefix matches the endpoint: write
volcengine-plan/ark-code-latestfor the Coding endpoint,volcengine/doubao-seed-evolvingfor 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):
# 在 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):
{
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.volcengineavailable 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, setVOLCENGINE_TTS_RESOURCE_ID=seed-tts-2.0 - The provider aliases
bytedanceanddoubaoalso 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(defaultvolcano_tts); there are alsoVOLCENGINE_TTS_VOICE,VOLCENGINE_TTS_APP_KEY,VOLCENGINE_TTS_BASE_URLto 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 side | Coding side | |
|---|---|---|
| Plugin | @openclaw/byteplus-provider | Same plugin |
| Provider id | byteplus | byteplus-plan |
| Authentication | BYTEPLUS_API_KEY | Reused (onboarding registers both sides at once) |
| auth-choice | openclaw onboard --auth-choice byteplus-api-key | Same as left |
| Default model | — | byteplus-plan/ark-code-latest |
Install with two commands (verbatim from the official example):
openclaw plugins install @openclaw/byteplus-provider
openclaw gateway restartConfiguration to pin the default model manually (verbatim from the official example):
{
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/*andbyteplus-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 hasbyteplus-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:
- Next lesson Integrating Tencent Hunyuan and Baidu Qianfan: big-tech MaaS in practice: Tencent Hunyuan and Baidu Qianfan, two big-tech MaaS providers, covered in one page
- Other model pages (relays, local models) start from the course schedule in Connecting Models Overview
- Models configured? For daily use, start with Daily Use: Getting Along Efficiently with Your Claw—Control UI, chat commands, and the memory system are all in that chapter