Volcengine (Doubao)

Volcengine 提供方允许访问托管在火山引擎上的 Doubao 模型和第三方模型，并为通用与编程工作负载提供独立的端点。该官方插件同时还会将 Volcengine Speech 注册为 TTS 提供方。

快速开始¶

1. 安装插件

openclaw plugins install @openclaw/volcengine-provider

安装会自动应用到正在运行的 Gateway；否则将在下次启动时生效。请参阅应用更改并检查。

2. 设置 API 密钥

运行交互式引导：

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

这会通过同一个 API 密钥同时注册通用（volcengine）和编程（volcengine-plan）提供方。

3. 设置默认模型

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

4. 验证模型可用

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

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

提供方与端点¶

内置目录¶

两个目录均为静态目录（不执行 /models 发现调用），并支持 OpenAI 兼容的流式用量统计。由于 Volcengine 的工具调用 API 会拒绝 minLength、maxLength、minItems、maxItems、minContains 和 maxContains 关键字，因此两个提供方的工具模式会自动移除这些关键字。

文本转语音¶

Volcengine TTS 使用 BytePlus Seed Speech HTTP API（voice.ap-southeast-1.bytepluses.com），并且与 OpenAI 兼容的 Doubao 模型 API 密钥分开配置。在 BytePlus 控制台中，打开 Seed Speech > 设置 > API 密钥，复制 API 密钥，然后设置：

export VOLCENGINE_TTS_API_KEY="<seed-speech-api-key>"
export VOLCENGINE_TTS_RESOURCE_ID="seed-tts-1.0"

然后在 openclaw.json 中启用：

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

tts.providers.volcengine 下可用的字段包括 apiKey、voice、speedRatio（0.2-3.0）、emotion、cluster、resourceId、appKey 和 baseUrl。当允许覆盖语音设置时，!emotion=<value> 也可以作为内联语音指令使用。

对于语音留言目标，OpenClaw 会请求提供方原生的 ogg_opus 格式。对于普通音频附件，它会请求 mp3 格式。提供方别名 bytedance 和 doubao 也会解析到此语音提供方。

默认资源 ID 是 seed-tts-1.0，这是 BytePlus 默认授予新创建的 Seed Speech API 密钥的权限。如果您的项目拥有 TTS 2.0 权限，请设置 VOLCENGINE_TTS_RESOURCE_ID=seed-tts-2.0。

旧版 AppID/token 认证仍受支持，适用于较早的 Speech Console 应用：

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 配置字段。

高级配置¶

相关¶

模型选择

选择提供商、模型引用和故障转移行为。

配置

代理、模型和提供商的完整配置参考。

故障排除

常见问题和调试步骤。

常见问题

关于 OpenClaw 设置的常见问题。