接入豆包/火山引擎：方舟端点与 Coding Plan

OpenClaw 接入豆包是国产模型专页的第六站。火山引擎（Volcengine）在 OpenClaw 里的玩法和前几家都不一样：一把 API Key 同时注册两个 provider——通用的 volcengine（按量付费，豆包 + 方舟托管的第三方模型）和编码的 volcengine-plan（Coding Plan 订阅面），后者还是前者的 auth 别名，不用配第二把 Key。前几课 DeepSeek、Qwen、GLM、Kimi、MiniMax 的「装插件 → 配凭据 → 选模型」三步在这一课全部适用。全程约 8 分钟（火山引擎账号注册另计）。

先给你一张总表，本课所有配置都从它出发（属性与值为官方文档原样摘录）：

	通用端（按量付费）	Coding 端（订阅）
Provider id	`volcengine`	`volcengine-plan`
端点	`ark.cn-beijing.volces.com/api/v3`	`ark.cn-beijing.volces.com/api/coding/v3`
用途	General models（豆包 + 第三方模型）	Coding models（Ark Coding Plan）
认证	`VOLCANO_ENGINE_API_KEY`	复用通用端的 auth（`volcengine-plan` 是 `volcengine` 的 auth 别名）
模型前缀	`volcengine/...`	`volcengine-plan/...`
onboarding 默认	—	`volcengine-plan/ark-code-latest`

一件必须先记住的事：两个 provider 共用一把 Key，但模型引用前缀不同——ark-code-latest 只在 volcengine-plan/ 下，doubao-seed-evolving 只在 volcengine/ 下。前缀写错，OpenClaw 就认不出模型。两个端点在同一个域名 ark.cn-beijing.volces.com（北京区域）下，区别只在路径：/api/v3 与 /api/coding/v3。

怎么选，三句话：

你的情况	选它
订阅了火山引擎 Coding Plan，主要写代码	`volcengine-plan/ark-code-latest`（onboarding 默认）
按量付费，要豆包旗舰与多模态输入	`volcengine/doubao-seed-evolving`（1M 上下文）
想用方舟托管的 GLM 5.2 / DeepSeek V4	两个端都有，前缀跟着端点走

💡 从「OpenClaw 火山引擎」「OpenClaw 字节模型」搜进来的朋友

豆包（Doubao）是字节跳动的模型系列，跑在火山引擎（字节跳动的云平台）的方舟（Ark）端点上——端点域名 ark.cn-beijing.volces.com 里的 ark 就是方舟。OpenClaw 接入它要的不是豆包 App 的账号，而是一把火山方舟 API Key；海外用户走 BytePlus（火山国际版），本页末尾单独讲。

本教程基于 OpenClaw v2026.10.9。

学完你能做什么

安装 @openclaw/volcengine-provider 插件，一把 VOLCANO_ENGINE_API_KEY 同时注册 volcengine（通用）与 volcengine-plan（Coding）两个 provider
分清方舟双端点：/api/v3（通用按量）与 /api/coding/v3（Coding Plan 订阅），模型前缀不写错
看懂内置目录：doubao-seed 系列、ark-code-latest 与方舟托管的 GLM 5.2、DeepSeek V4 各自的上下文、最大输出与价位
避开火山特有的坑：TTS Key 与模型 Key 不是一把、旧模型 ID 已弃用、Coding 端目录 cost 为 0 不代表免费
给 Claw 配上豆包 TTS（BytePlus Seed Speech），海外用户还能切换到 BytePlus 国际版

🎒 开始前的准备

完成了连接模型总览：provider 体系与模型切换：「provider → 认证 → 选模型」三步和 provider/model 引用规则心里有数
OpenClaw 已安装、Gateway 在运行：openclaw gateway status 有输出
有一把火山方舟 API Key（或准备去火山引擎控制台创建；Coding Plan 订阅用户用的也是它）
走服务器 / 守护进程部署的话，知道 ~/.openclaw/.env 在哪——Key 最终要住那里

跟我做

第 1 步：安装火山引擎（豆包）provider 插件

为什么：和 DeepSeek、Kimi 一样，volcengine 是外部官方插件，OpenClaw 不自带——装上插件，volcengine 与 volcengine-plan 两个 provider 才会注册进模型体系。

bash

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

# 2. 重启 Gateway（Gateway 正在跑的话，安装会自动生效；重启最稳妥）
openclaw gateway restart

你应该看到：插件安装成功的提示，Gateway 重启后没有报错。

两个行为先知道（官方文档明确写了）：

安装对正在运行的 Gateway 自动生效；Gateway 没在跑则下次启动时生效
官方流程没有 plugins enable 这一步——插件清单标记 enabledByDefault: true，装上即启用（对照 MiniMax：内置但要点名 enable）
openclaw plugins install @openclaw/volcengine-provider 执行成功，Gateway 已重启

第 2 步：OpenClaw 接入豆包——配好 VOLCANO_ENGINE_API_KEY

为什么：火山方舟的认证就一把 Key。onboarding 用它同时注册通用与 Coding 两个 provider——volcengine-plan 是 volcengine 的 auth 别名，coding 端复用同一份凭据，不用配第二把 Key。

先去火山引擎控制台创建一把方舟 API Key，复制放到安全的地方：

然后跑 onboarding：

bash

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

你应该看到：Key 验证通过并保存；通用与 Coding 两个 provider 同时注册，默认模型落在 volcengine-plan/ark-code-latest（官方文档明确写了：设默认模型的同时，也注册通用 volcengine 目录）。

CI / 脚本等非交互场景，官方文档给了直传 Key 的写法（原样）：

bash

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

不想跑 onboarding 的话，手动配置最小只需要两处——Key 进环境变量，默认模型写进配置（官方示例原样）：

bash

export VOLCANO_ENGINE_API_KEY="<你的 API Key>"

json5

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

官方插件不需要写 models.providers 条目——装插件、设 auth、选模型即可；只有覆盖默认端点 / 模型列表时才写（总览课讲过这条规则）。

⚠️ Gateway 跑成守护进程？Key 别放交互 shell

Gateway 作为 launchd / systemd 服务运行时，看不到你终端里 export 的环境变量。把 VOLCANO_ENGINE_API_KEY（以及要用的 TTS 变量）写进 ~/.openclaw/.env，或经配置里的 env.shellEnv 提供给那个进程。

顺手验证两个 provider 都注册了：

bash

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

你应该看到：volcengine/ 前缀的通用目录（doubao-seed 系 + GLM / DeepSeek）与 volcengine-plan/ 前缀的 Coding 目录（ark-code-latest 打头）都在列。

还有两个行为先知道（官方文档明确写了）：

onboarding / configure 的模型选择器会同时偏好 volcengine/* 与 volcengine-plan/* 两族模型；它们还没加载时，OpenClaw 退回未过滤的完整目录，不会给你一个空选择器
已经有默认模型的老用户注意：追加新的 provider auth 不会改动已有默认模型——要换就自己跑 openclaw models set（下一节）
openclaw models status 的凭据概览里，能看到 volcengine 的凭据来源

第 3 步：选择豆包/方舟模型并验证

为什么：onboarding 默认把默认模型设到 Coding 端的 ark-code-latest，够直接用；但通用端还有 1M 上下文的 doubao-seed-evolving 和目录价减半的 turbo——看一眼目录再决定不亏。

先看内置目录（官方文档 + 插件清单原样整理）。

通用端（volcengine，按量付费）：

模型引用	名称	输入	上下文	最大输出	目录估价（每百万 token）
`volcengine/doubao-seed-evolving`	Doubao Seed Evolving	文本、图像、视频	1,024,000	256,000	$0.885 输入 / $4.427 输出 / $0.177 缓存读
`volcengine/doubao-seed-2-1-pro-260628`	Doubao Seed 2.1 Pro	文本、图像、视频	256,000	256,000	$0.885 / $4.427 / $0.177
`volcengine/doubao-seed-2-1-turbo-260628`	Doubao Seed 2.1 Turbo	文本、图像、视频	256,000	256,000	$0.443 / $2.214 / $0.089
`volcengine/glm-5-2-260617`	GLM 5.2	文本	1,024,000	128,000	$1.181 / $4.132 / $0.295
`volcengine/deepseek-v4-pro-260425`	DeepSeek V4 Pro	文本	1,024,000	384,000	$1.771 / $3.542 / $0.148
`volcengine/deepseek-v4-flash-260425`	DeepSeek V4 Flash	文本	1,024,000	384,000	$0.148 / $0.295 / $0.030

Coding 端（volcengine-plan，订阅制）：

模型引用	名称	输入	上下文	最大输出
`volcengine-plan/ark-code-latest`	Ark Coding Plan	文本	256,000	4,096
`volcengine-plan/doubao-seed-2.1-turbo`	Doubao Seed 2.1 Turbo	文本、图像、视频	256,000	256,000
`volcengine-plan/glm-5.2`	GLM 5.2	文本	1,024,000	128,000
`volcengine-plan/deepseek-v4-pro`	DeepSeek V4 Pro	文本	1,024,000	384,000
`volcengine-plan/deepseek-v4-flash`	DeepSeek V4 Flash	文本	1,024,000	384,000

目录行为与兼容性，四条都来自官方文档 / 插件清单原样：

两个目录都是静态内置的（不走 /models 发现调用），支持 OpenAI 兼容的流式用量统计
除 ark-code-latest 外，目录里的模型都标记了 reasoning: true（推理 / 思考能力）
工具调用兼容：两个 provider 会自动剔除 minLength、maxLength、minItems、maxItems、minContains、maxContains 这些 JSON Schema 关键字——火山的 tool-call API 会拒绝它们，OpenClaw 帮你处理了，正常配置下不用管
Coding 端目录的 cost 字段全是 0——那是「订阅制不按 token 单独计价」，不代表免费，走的是 Coding Plan 订阅额度

通用目录里还躺着三个已弃用的旧 ID（插件清单标记 deprecated，仅为存量配置保留），新配置别用：

已弃用 ID	接替者
`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`

怎么选，四句话：

你的需求	选它	依据
订阅 Coding Plan，主要写代码	`volcengine-plan/ark-code-latest`	onboarding 默认；订阅额度内用
按量付费要最新旗舰、多模态输入	`volcengine/doubao-seed-evolving`	1M 上下文，文本 + 图像 + 视频输入
按量付费想省钱	`volcengine/doubao-seed-2-1-turbo-260628`	目录价约是 Pro 的一半
就想用 DeepSeek / GLM，Key 在方舟	`volcengine/deepseek-v4-flash-260425` 等	方舟托管的第三方模型，前缀写 `volcengine/`

换默认模型（注意前缀跟端点走）：

bash

# Coding 端（订阅）
openclaw models set volcengine-plan/ark-code-latest

# 通用端（按量）
openclaw models set volcengine/doubao-seed-evolving

聊天里临时切也行：/model volcengine/doubao-seed-2-1-turbo-260628 只影响当前会话，命令族详见聊天命令速成。

最后验证。发一条测试消息：

bash

openclaw dashboard

打开 Control UI，在聊天框发一句「用一句话介绍你自己」。

你应该看到：模型正常回复，没有凭据缺失或模型不存在的报错。到这里，OpenClaw 接入豆包就通了。

价格一句话：通用端按量计费，上表估价是 OpenClaw 插件清单里的目录数字（每百万 token 口径）；Coding 端走订阅额度。实际价格与币种一律以火山引擎官网为准。

测试消息收到了回复，provider 与模型对得上（volcengine/... 或 volcengine-plan/...）

检查点 ✅

@openclaw/volcengine-provider 插件已安装（装上即启用，无需 plugins enable）
一把 VOLCANO_ENGINE_API_KEY 注册了两个 provider：volcengine（通用）+ volcengine-plan（Coding）
openclaw models list --provider volcengine 与 --provider volcengine-plan 都能列出目录
默认模型前缀与端点配套：Coding 端写 volcengine-plan/ark-code-latest，通用端写 volcengine/doubao-seed-evolving
测试消息收到了回复；TTS 没配也不影响聊天（TTS 是独立凭据）

踩坑提醒

❌ 拿 Seed Speech 的 Key（或豆包 App 的凭据）当模型 Key 用

现象：onboarding 验证不过，或发消息报凭据错误。

原因：VOLCANO_ENGINE_API_KEY 对应的是方舟 ModelArk / 豆包模型端点；Seed Speech TTS 的 Key、旧语音控制台的 AppID / token 都不是它。官方 Warning 写得明白：TTS 需要单独的 Seed Speech API Key。

正确做法：模型用 VOLCANO_ENGINE_API_KEY；TTS 另配 VOLCENGINE_TTS_API_KEY（见下方专属能力节）。

❌ 模型前缀写错端点

现象：报未知模型，或计费面不对。

原因：两个 provider 的目录不同——ark-code-latest 只在 volcengine-plan/ 下，doubao-seed-evolving 只在 volcengine/ 下。前缀就是端点。

正确做法：照本页目录表抄前缀；不确定就先 openclaw models list --provider volcengine-plan 查一遍再写配置。

❌ 用了已弃用的旧模型 ID

现象：配置里写 volcengine/deepseek-v3-2-251201、volcengine/glm-4-7-251222、volcengine/kimi-k2-5-260127 这类旧 ID。

原因：插件清单把它们标记为 deprecated（仅为存量配置保留），分别由 deepseek-v4-flash-260425、glm-5-2-260617、doubao-seed-evolving 接替。

正确做法：新配置一律用接替者；存量配置看到弃用标记就迁移。

❌ Gateway 装成守护进程后，export 的 Key「不生效」

原因：launchd / systemd 服务看不到交互 shell 的环境变量——volcengine 文档同样强调这一点（模型与 TTS 变量都要给到服务进程）。

正确做法：VOLCANO_ENGINE_API_KEY（及 TTS 变量）写进 ~/.openclaw/.env，或经 env.shellEnv 提供；换 Key 后重启 Gateway 服务。

❌ Coding 端目录 cost 全是 0，以为免费

原因：volcengine-plan 是订阅制——插件清单里这些模型的 cost 字段写 0，只是「不按 token 单独计价」，实际走 Coding Plan 订阅额度。

正确做法：成本看订阅额度与配额；订阅价格以火山引擎官网为准，别拿目录 0 价做成本核算。

❌ 目录估价和实际账单对不上

原因：本页目录表的 $ 数字是 OpenClaw 插件清单里的估价（每百万 token 口径），不是火山的官方报价。

正确做法：成本核算以火山引擎官网价格页为准；目录估价只用来做模型之间的相对比较（比如 turbo 约是 Pro 的一半）。

❌ 带数组 / 字符串参数的工具调用被方舟 API 拒绝

现象：工具调用报 schema 相关错误。

原因：火山的 tool-call API 会拒绝 minLength / maxLength / minItems / maxItems / minContains / maxContains 这些 JSON Schema 关键字。

正确做法：确认模型引用前缀是 volcengine/ 或 volcengine-plan/——OpenClaw 的这两个 provider 会自动剔除上述关键字（官方文档明确写了），正常配置下你不需要做任何事。

❌ 海外团队误用国内端点（或反过来）

原因：volcengine / volcengine-plan 走的是 ark.cn-beijing.volces.com（国内）；海外账号要用独立的 BytePlus 插件（byteplus / byteplus-plan），插件与 Key 都是独立一套。

正确做法：海外用户按本页末尾的 BytePlus 小节配置；国内 Key 别硬填到 BytePlus 插件里。

🔧 豆包专属能力：Seed Speech TTS 与 BytePlus（可选）

同一个插件还把**火山语音（Volcengine Speech）**注册成 TTS provider——配好之后，Claw 的回复能变成语音条。它走 BytePlus Seed Speech 的 HTTP API（voice.ap-southeast-1.bytepluses.com），与模型 Key 完全分开。

给 Claw 配上豆包语音（Seed Speech TTS）

为什么：模型 Key 管聊天，语音 Key 管开口——两把 Key 出自两个控制台，别混用。

先设环境变量（官方文档原样）：

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"

然后在 openclaw.json 里启用（官方示例原样）：

json5

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

你应该看到：Claw 的语音回复能正常播放；语音条渠道（如 Telegram）收到 ogg_opus，普通音频附件收到 mp3。

四个细节：

tts.providers.volcengine 可用字段：apiKey、voice、speedRatio（0.2–3.0）、emotion、cluster、resourceId、appKey、baseUrl；!emotion=<值> 还能作内联语音指令
默认 resource id 是 seed-tts-1.0（BytePlus 给新建 Seed Speech Key 的默认授权）；有 TTS 2.0 授权就设 VOLCENGINE_TTS_RESOURCE_ID=seed-tts-2.0
provider 别名 bytedance、doubao 也指向这个语音 provider
旧版语音控制台的 AppID / token 认证仍支持：VOLCENGINE_TTS_APPID / VOLCENGINE_TTS_TOKEN / VOLCENGINE_TTS_CLUSTER（默认 volcano_tts）；另有 VOLCENGINE_TTS_VOICE、VOLCENGINE_TTS_APP_KEY、VOLCENGINE_TTS_BASE_URL 可覆盖对应配置字段

⚠️ 两把 Key 别混

VOLCANO_ENGINE_API_KEY 是方舟模型端点的 Key，不是 Seed Speech Key。TTS 要 BytePlus Speech 控制台的 Key（或旧控制台的 AppID / token 对）——官方 Warning 特别强调了这一点。

语音实战玩法（配图、转语音、语音条）见图片与语音：给内容配图、把文章转语音。

BytePlus：火山国际版（海外用户）

人在海外？BytePlus ARK 提供与火山方舟相同的模型，但走独立插件，Key 也是独立一把（BYTEPLUS_API_KEY）：

	通用端	Coding 端
插件	`@openclaw/byteplus-provider`	同一个插件
Provider id	`byteplus`	`byteplus-plan`
认证	`BYTEPLUS_API_KEY`	复用（onboarding 同时注册两端）
auth-choice	`openclaw onboard --auth-choice byteplus-api-key`	同左
默认模型	—	`byteplus-plan/ark-code-latest`

安装两条命令（官方示例原样）：

bash

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

手动钉死默认模型的配置（官方示例原样）：

json5

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

三个行为与国内版一致（官方文档明确写了）：

onboarding 默认走 coding 面，同时注册通用 byteplus/* 目录
模型选择器同样偏好 byteplus/* 与 byteplus-plan/* 两族；没加载时退回未过滤目录
例子模型：通用端有 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；Coding 端有 byteplus-plan/ark-code-latest、byteplus-plan/kimi-k2.5（Kimi K2.5 Coding）

下一步

OpenClaw 接入豆包/火山引擎到此通关。国产模型专页继续走：

下一课接入腾讯混元与百度千帆：大厂 MaaS 实战：腾讯混元与百度千帆两家大厂 MaaS 一页讲完
其他模型专页（中转、本地模型）从连接模型总览的课程表进
模型配好了？日常使用从日常使用：和你的 Claw 高效相处开始——Control UI、聊天命令、记忆系统都在那一章

接入豆包/火山引擎：方舟端点与 Coding Plan ​

学完你能做什么 ​

🎒 开始前的准备 ​

跟我做 ​

第 1 步：安装火山引擎（豆包）provider 插件 ​

第 2 步：OpenClaw 接入豆包——配好 VOLCANO_ENGINE_API_KEY ​

第 3 步：选择豆包/方舟模型并验证 ​

检查点 ✅ ​

踩坑提醒 ​

❌ 拿 Seed Speech 的 Key（或豆包 App 的凭据）当模型 Key 用 ​

❌ 模型前缀写错端点 ​

❌ 用了已弃用的旧模型 ID ​

❌ Gateway 装成守护进程后，export 的 Key「不生效」 ​

❌ Coding 端目录 cost 全是 0，以为免费 ​

❌ 目录估价和实际账单对不上 ​

❌ 带数组 / 字符串参数的工具调用被方舟 API 拒绝 ​

❌ 海外团队误用国内端点（或反过来） ​

🔧 豆包专属能力：Seed Speech TTS 与 BytePlus（可选） ​

给 Claw 配上豆包语音（Seed Speech TTS） ​

BytePlus：火山国际版（海外用户） ​

下一步 ​

相关教程 ​

接入豆包/火山引擎：方舟端点与 Coding Plan

学完你能做什么

🎒 开始前的准备

跟我做

第 1 步：安装火山引擎（豆包）provider 插件

第 2 步：OpenClaw 接入豆包——配好 VOLCANO_ENGINE_API_KEY

第 3 步：选择豆包/方舟模型并验证

检查点 ✅

踩坑提醒

❌ 拿 Seed Speech 的 Key（或豆包 App 的凭据）当模型 Key 用

❌ 模型前缀写错端点

❌ 用了已弃用的旧模型 ID

❌ Gateway 装成守护进程后，export 的 Key「不生效」

❌ Coding 端目录 cost 全是 0，以为免费

❌ 目录估价和实际账单对不上

❌ 带数组 / 字符串参数的工具调用被方舟 API 拒绝

❌ 海外团队误用国内端点（或反过来）

🔧 豆包专属能力：Seed Speech TTS 与 BytePlus（可选）

给 Claw 配上豆包语音（Seed Speech TTS）

BytePlus：火山国际版（海外用户）

下一步

相关教程