OpenClaw 接入火山引擎（Volcengine / Doubao）全指南：模型 Provider、编码端点与 Seed Speech TTS 配置
【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw
本文是 OpenClaw 官方@openclaw/volcengine-provider插件的完整技术指南，覆盖火山引擎 Doubao 模型接入、通用与 Coding 双端点路由、内置模型目录以及 BytePlus Seed Speech 语音合成（TTS）的完整配置流程。读完本文，你将掌握从安装插件、配置 API Key、设定默认模型，到启用语音输出与排查后台服务环境变量问题的全链路实战方案。
插件概览与能力边界
Volcengine Provider 是 OpenClaw 的官方插件，为 OpenClaw 接入火山引擎（Volcano Engine）托管的 Doubao 系列模型，以及托管在火山引擎上的第三方模型（如 GLM、DeepSeek 等），并提供独立的通用负载与 Coding 负载端点。同一个插件还会把火山引擎语音（Volcengine Speech）注册为 OpenClaw 的 TTS 语音合成 Provider。
| Detail | Value |
|---|---|
| Providers | volcengine（通用 + TTS）、volcengine-plan（Coding） |
| Model auth | VOLCANO_ENGINE_API_KEY |
| TTS auth | VOLCENGINE_TTS_API_KEY或BYTEPLUS_SEED_SPEECH_API_KEY |
| API | OpenAI-compatible models、BytePlus Seed Speech TTS |
从源码角度看，插件入口 extensions/volcengine/index.ts 通过defineSingleProviderPluginEntry注册：provider部分用buildOpenAICompatibleProviderFamilyCatalog构建双 Provider 目录，register(api)阶段通过api.registerSpeechProvider(buildVolcengineSpeechProvider())注册语音 Provider。插件清单 extensions/volcengine/openclaw.plugin.json 同时声明了speechProviders合约下的volcengine、bytedance、doubao三个别名。
安装与快速上手
安装插件并重启 Gateway
openclaw plugins install @openclaw/volcengine-provider openclaw gateway restart插件包名为@openclaw/volcengine-provider，也可通过 ClawHub 安装：clawhub:@openclaw/volcengine-provider（参见插件参考页 docs/plugins/reference/volcengine.md）。插件在清单中默认启用（enabledByDefault: true），启动时不强制加载（onStartup: false），由按需激活机制加载。
配置 API Key（交互式）
运行交互式引导，一个 API Key 会同时注册通用（volcengine）与 Coding（volcengine-plan）两个 Provider：
openclaw onboard --auth-choice volcengine-api-key该交互项在插件清单中定义为volcengine-api-key（method: "api-key"，CLI 参数为--volcengine-api-key <key>），引导完成后会把volcengine-plan/ark-code-latest设为默认模型，同时注册通用volcengine模型目录。
配置 API Key（非交互式 / CI）
在脚本或 CI 环境中，直接通过命令行传入 Key：
openclaw onboard --non-interactive --accept-risk --skip-health \ --mode local \ --auth-choice volcengine-api-key \ --volcengine-api-key "$VOLCANO_ENGINE_API_KEY"设置默认模型
在openclaw.json中为 Agent 默认模型指定编码端点下的ark-code-latest：
{ agents: { defaults: { model: { primary: "volcengine-plan/ark-code-latest" }, }, }, }验证模型可用
openclaw models list --provider volcengine openclaw models list --provider volcengine-planProvider 与端点路由
| 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 |
两个 Provider 共用同一个 API Key。volcengine-plan是volcengine的认证别名（providerAuthAliases声明在 openclaw.plugin.json 中），因此在模型选择器里 Coding Provider 会复用通用 Provider 的认证信息，无需重复配置密钥。
端点与模型数据在清单中集中定义：volcengine指向https://ark.cn-beijing.volces.com/api/v3，volcengine-plan指向https://ark.cn-beijing.volces.com/api/coding/v3，两者 API 协议均为openai-completions，即与 OpenAI 兼容的补全接口。模型目录的构建逻辑位于 extensions/volcengine/models.ts，通过buildManifestProviderCatalogFamily把清单中两个 Provider 的模型列表包装成 OpenClaw 的目录结构，并对外导出DOUBAO_BASE_URL、DOUBAO_CODING_BASE_URL等常量。
内置模型目录
两个目录均为静态目录（不做/models动态发现请求，清单中discovery为refreshable），并支持 OpenAI 兼容的流式用量核算（supportsStreamingUsage: true）。
通用目录（volcengine）
| Model ref | Name | Input | Context |
|---|---|---|---|
volcengine/doubao-seed-evolving | Doubao Seed Evolving | text, image, video | 1,024,000 |
volcengine/doubao-seed-2-1-pro-260628 | Doubao Seed 2.1 Pro | text, image, video | 256,000 |
volcengine/doubao-seed-2-1-turbo-260628 | Doubao Seed 2.1 Turbo | text, image, video | 256,000 |
volcengine/glm-5-2-260617 | GLM 5.2 | text | 1,024,000 |
volcengine/deepseek-v4-pro-260425 | DeepSeek V4 Pro | text | 1,024,000 |
volcengine/deepseek-v4-flash-260425 | DeepSeek V4 Flash | text | 1,024,000 |
Coding 目录（volcengine-plan）
| Model ref | Name | Input | Context |
|---|---|---|---|
volcengine-plan/ark-code-latest | Ark Coding Plan | text | 256,000 |
volcengine-plan/doubao-seed-2.1-turbo | Doubao Seed 2.1 Turbo | text, image, video | 256,000 |
volcengine-plan/glm-5.2 | GLM 5.2 | text | 1,024,000 |
volcengine-plan/deepseek-v4-pro | DeepSeek V4 Pro | text | 1,024,000 |
volcengine-plan/deepseek-v4-flash | DeepSeek V4 Flash | text | 1,024,000 |
补充说明（来自清单源码 openclaw.plugin.json）：
- 每个模型条目除
id、name、input类型与contextWindow外，还预置了maxTokens与cost元数据（input/output/cacheRead/cacheWrite四档单价），OpenClaw 据此进行用量核算；volcengine-plan目录下的glm-5.2、deepseek-v4-pro、deepseek-v4-flash额外声明了compat.codeMode: "capable"，标记其适用于代码模式。 - 通用目录中仍保留了一批标记为
deprecated的旧模型（如kimi-k2-5-260127、glm-4-7-251222、deepseek-v3-2-251201），并在replacedBy字段中指明替代模型，便于存量配置平滑迁移。 - 测试 extensions/volcengine/index.test.ts 验证了通用与 Coding 两个目录的配对顺序、
augmentModelCatalog的注入结果，以及volcengine-plan/ark-code-latest作为引导默认模型（starterModel）的行为。
工具 Schema 兼容处理
火山引擎的工具调用 API 会拒绝 JSON Schema 中的minLength、maxLength、minItems、maxItems、minContains、maxContains关键字，因此插件在模型解析阶段自动剥离这些字段。实现位于 extensions/volcengine/api.ts：VOLCENGINE_UNSUPPORTED_TOOL_SCHEMA_KEYWORDS常量列出六个关键字，applyVolcengineToolSchemaCompat通过applyModelCompatPatch把它们合并进模型的compat.unsupportedToolSchemaKeywords；入口插件在normalizeResolvedModel中调用该函数（index.ts），测试中也对关键字清单做了断言。
文本转语音（Text-to-Speech）
Volcengine TTS 走的是 BytePlus Seed Speech HTTP API（voice.ap-southeast-1.bytepluses.com），与 OpenAI 兼容的 Doubao 模型 API Key 相互独立，需要单独配置。
获取并配置 Seed Speech 凭据
在 BytePlus 控制台进入 Seed Speech > Settings > API Keys，复制 API Key 后设置：
export VOLCENGINE_TTS_API_KEY="byteplus_seed_speech_api_key" export VOLCENGINE_TTS_RESOURCE_ID="seed-tts-1.0"然后在openclaw.json中启用：
{ tts: { auto: "always", provider: "volcengine", providers: { volcengine: { apiKey: "byteplus_seed_speech_api_key", voice: "en_female_anna_mars_bigtts", speedRatio: 1.0, }, }, }, }可配置字段
tts.providers.volcengine支持以下字段：
| 字段 | 说明 | 默认值 |
|---|---|---|
apiKey | BytePlus Seed Speech API Key，也可由环境变量提供 | 无 |
voice | 发音人 ID（见下方内置发音人列表） | en_female_anna_mars_bigtts |
speedRatio | 语速倍率，取值范围 0.2–3.0 | 1.0 |
emotion | 情感参数，可选 | 无 |
cluster | 语音集群（legacy 认证使用） | volcano_tts |
resourceId | Seed Speech 资源 ID | seed-tts-1.0 |
appKey | Seed Speech 应用 Key | aGjiRDfUWi |
baseUrl | 服务地址覆盖，用于代理或自建网关场景 | 官方 BytePlus 端点 |
speedRatio的范围（0.2–3.0）在源码中由normalizeSpeedRatio通过asFiniteNumberInRange(value, { min: 0.2, max: 3 })强制校验（speech-provider.ts），越界值会被丢弃。!emotion=<value>也可作为内联语音指令使用（在允许语音设置覆盖的场景下生效）。
语音输出编码与别名
- 对语音消息（voice-note）目标，OpenClaw 会请求 Provider 原生支持的
ogg_opus编码；普通音频附件则请求mp3。该逻辑位于 speech-provider.ts 的synthesize实现中，按req.target === "voice-note"决定编码，并同步返回对应的outputFormat与文件扩展名。 - Provider 别名
bytedance与doubao同样解析到该语音 Provider（aliases定义于 speech-provider.ts）。 - 内置发音人（
VOLCENGINE_VOICES）包括：en_female_anna_mars_bigtts、en_male_adam_mars_bigtts、en_female_sarah_mars_bigtts、en_male_smith_mars_bigtts、zh_female_cancan_mars_bigtts、zh_female_qingxinnvsheng_mars_bigtts、zh_female_linjia_mars_bigtts、zh_male_wennuanahu_moon_bigtts、zh_male_shaonianzixin_moon_bigtts、zh_female_shuangkuaisisi_moon_bigtts。
Resource ID 说明
默认资源 ID 为seed-tts-1.0，这是 BytePlus 为新建 Seed Speech API Key 默认授予的 entitlement。如果你的项目已开通 TTS 2.0，可将VOLCENGINE_TTS_RESOURCE_ID设为seed-tts-2.0。
⚠️ 注意：
VOLCANO_ENGINE_API_KEY仅用于 ModelArk / Doubao 模型端点，不是Seed Speech API Key。TTS 需要 BytePlus Speech 控制台的 Seed Speech API Key，或旧版 Speech 控制台的 AppID/token 凭据对。
旧版 AppID / Token 认证
旧版 Speech Console 应用仍支持 AppID/token 认证方式：
export VOLCENGINE_TTS_APPID="speech_app_id" export VOLCENGINE_TTS_TOKEN="speech_access_token" export VOLCENGINE_TTS_CLUSTER="volcano_tts"其他可选 TTS 环境变量：VOLCENGINE_TTS_VOICE、VOLCENGINE_TTS_APP_KEY、VOLCENGINE_TTS_BASE_URL，设置后会覆盖tts.providers.volcengine中对应的配置字段。
TTS 底层实现要点
两种认证路径的 HTTP 实现均位于 extensions/volcengine/tts.ts：
- Seed Speech 路径（
seedSpeechTTS）：POST 到https://voice.ap-southeast-1.bytepluses.com/api/v3/tts/unidirectional，请求头携带X-Api-Key、X-Api-Resource-Id、X-Api-App-Key，请求体为user+req_params（含speaker、audio_params.format、sample_rate: 24000、可选的speed_ratio与emotion）。响应为流式 JSON 帧，插件逐帧解析，只拼接code === 0且携带 base64 音频数据的帧，code === 20000000的帧被跳过，其他错误码直接抛出带错误信息的异常。 - 旧版路径（
legacyVolcengineTTS）：POST 到https://openspeech.bytedance.com/api/v1/tts，使用Bearer;${token}认证，app段携带appid/token/cluster，audio段支持voice_type、encoding、speed_ratio、volume_ratio、pitch_ratio、emotion，request段以 UUID 作为reqid且operation: "query"，成功时要求业务码code === 3000。 - 两条路径都经由 OpenClaw 的
fetchWithSsrFGuard发起（带 hostname 白名单，防止 SSRF）、通过readResponseWithLimit限制响应上限（16 MiB），并对返回的 base64 音频做规范化处理；isConfigured校验逻辑（speech-provider.ts）接受 Seed Speech API Key 或（AppID 且 Token）任一组合。
高级配置
引导后的默认模型
openclaw onboard --auth-choice volcengine-api-key会把volcengine-plan/ark-code-latest设为默认模型，同时注册通用volcengine目录。入口插件通过readManifestProviderDefaultModelRef从清单读取该默认 ref（index.ts），并在manifestAuth.applyConfig中通过ensureModelAllowlistEntry确保默认模型在模型白名单中。
模型选择器回退行为
在 onboarding / 配置模型选择阶段，Volcengine 认证项会同时优先展示volcengine/*与volcengine-plan/*两行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的完整目录，而不是显示一个空的、限定 Provider 的选择器。
守护进程（daemon）环境变量
如果 Gateway 以守护进程方式运行（launchd / systemd），交互式 shell 中设置的环境变量不会被自动继承。务必确保模型与 TTS 相关变量对该进程可见，例如写入~/.openclaw/.env，或在配置中通过env.shellEnv注入：
- 模型：
VOLCANO_ENGINE_API_KEY - TTS：
VOLCENGINE_TTS_API_KEY、BYTEPLUS_SEED_SPEECH_API_KEY、VOLCENGINE_TTS_APPID、VOLCENGINE_TTS_TOKEN
⚠️ 当 OpenClaw 作为后台服务运行时，交互式 shell 里
export的变量不会自动进入服务进程，请按上面的 daemon 说明显式配置。
相关文档
- 模型选择与 Provider 概念：Provider、模型 ref 与故障切换行为的整体说明
- Gateway 配置参考：agents、models、providers 的完整配置项
- 故障排查：常见问题与调试步骤
- FAQ：OpenClaw 安装配置高频问答
- 插件参考页：
@openclaw/volcengine-provider的分布、Surface 与相关文档索引
【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
