OpenClaw 接入火山引擎（Volcengine）后，可以使用豆包（Doubao）系列模型以及平台托管的 Kimi、GLM、DeepSeek 等第三方模型，并且支持通用 (volcengine) 和编程 (volcengine-plan) 双端点，单 API Key 即可同时注册两个 provider。TTS 功能需要单独从 BytePlus 控制台获取 Seed Speech API Key，通过环境变量 VOLCENGINE_TTS_API_KEY 和 VOLCENGINE_TTS_RESOURCE_ID 配置。配置完成后可用 openclaw models list --provider volcengine 验证模型是否加载。

OpenClaw 火山引擎（豆包模型）配置与 TTS 接入

火山引擎（Volcengine）provider 提供对豆包（Doubao）模型及火山引擎平台托管的第三方模型（如 Kimi、GLM、DeepSeek）的访问，针对通用和编程工作负载分别提供独立端点。同一插件还能将 Volcengine Speech 注册为 TTS 提供方。

详情	值
Providers	volcengine（通用 + TTS） + volcengine-plan（编程）
模型认证	VOLCANO_ENGINE_API_KEY
TTS 认证	VOLCENGINE_TTS_API_KEY 或 BYTEPLUS_SEED_SPEECH_API_KEY
API	OpenAI 兼容模型，BytePlus Seed Speech TTS

快速上手

设置 API Key

运行交互式配置向导：

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

该命令会用一个 API Key 同时注册通用 (`volcengine`) 和编程 (`volcengine-plan`) 两个 provider。

设置默认模型

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

验证模型是否可用

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

TIP

非交互式配置（CI/脚本）可直接传入 API Key：

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

Provider 与端点对照

Provider	端点	用途
volcengine	ark.cn-beijing.volces.com/api/v3	通用模型
volcengine-plan	ark.cn-beijing.volces.com/api/coding/v3	编程模型

INFO

两个 provider 共用同一个 API Key，配置一次即可自动注册两者。

内置模型目录

通用（volcengine）

| 模型引用                                     | 名称                            | 输入       | 上下文     |
| -------------------------------------------- | ------------------------------- | ---------- | ---------- |
| `volcengine/doubao-seed-1-8-251228`          | Doubao Seed 1.8                 | text, image | 256,000    |
| `volcengine/doubao-seed-code-preview-251028` | doubao-seed-code-preview-251028 | text, image | 256,000    |
| `volcengine/kimi-k2-5-260127`                | Kimi K2.5                       | text, image | 256,000    |
| `volcengine/glm-4-7-251222`                  | GLM 4.7                         | text, image | 200,000    |
| `volcengine/deepseek-v3-2-251201`            | DeepSeek V3.2                   | text, image | 128,000    |

编程（volcengine-plan）

| 模型引用                                         | 名称                     | 输入 | 上下文 |
| ------------------------------------------------- | ------------------------ | ---- | ------ |
| `volcengine-plan/ark-code-latest`                 | Ark Coding Plan          | text | 256,000 |
| `volcengine-plan/doubao-seed-code`                | Doubao Seed Code         | text | 256,000 |
| `volcengine-plan/glm-4.7`                         | GLM 4.7 Coding           | text | 200,000 |
| `volcengine-plan/kimi-k2-thinking`                | Kimi K2 Thinking         | text | 256,000 |
| `volcengine-plan/kimi-k2.5`                       | Kimi K2.5 Coding         | text | 256,000 |
| `volcengine-plan/doubao-seed-code-preview-251028` | Doubao Seed Code Preview | text | 256,000 |

文本转语音（TTS）

火山引擎 TTS 使用 BytePlus Seed Speech HTTP API，需要单独配置（与 OpenAI 兼容的豆包模型 API Key 不同）。在 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 中启用：

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

对于 voice-note 类型的目标，OpenClaw 会向火山引擎请求 provider 原生的 ogg_opus 格式；对于普通音频附件，则请求 mp3。provider 别名 bytedance 和 doubao 也指向同一个语音提供方。

默认的 resource id 是 seed-tts-1.0，因为 BytePlus 在新创建的 Seed Speech API Key 的默认项目中会授予该资源。如果你的项目拥有 TTS 2.0 权限，请设置 VOLCENGINE_TTS_RESOURCE_ID=seed-tts-2.0。

WARNING

VOLCANO_ENGINE_API_KEY 是用于 ModelArk/Doubao 模型端点的，不是 Seed Speech API Key。TTS 需要从 BytePlus Speech Console 获取 Seed Speech API Key，或者使用旧版 Speech Console 的 AppID/token 对。

旧版 AppID/token 认证仍受支持（用于旧版 Speech Console 应用）：

export VOLCENGINE_TTS_APPID="speech_app_id"
export VOLCENGINE_TTS_TOKEN="speech_access_token"
export VOLCENGINE_TTS_CLUSTER="volcano_tts"

高级配置

配置向导后的默认模型

执行 `openclaw onboard --auth-choice volcengine-api-key` 后，当前会将 `volcengine-plan/ark-code-latest` 设为默认模型，同时注册通用 `volcengine` 目录。

模型选择器降级行为

在配置向导/模型选择过程中，Volcengine 认证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 的模型行。如果这些模型尚未加载，OpenClaw 会降级为显示完整目录，而不是展示空白的 provider 范围选择器。

守护进程的环境变量问题

如果 Gateway 以守护进程（launchd / systemd）方式运行，请确保模型和 TTS 相关的环境变量（如 `VOLCANO_ENGINE_API_KEY`、`VOLCENGINE_TTS_API_KEY`、`BYTEPLUS_SEED_SPEECH_API_KEY`、`VOLCENGINE_TTS_APPID`、`VOLCENGINE_TTS_TOKEN`）对该进程可见。例如，写入 `~/.openclaw/.env` 或通过 `env.shellEnv` 配置。

WARNING

当 OpenClaw 作为后台服务运行时，交互式 shell 中设置的环境变量不会自动继承。请参考上面的守护进程说明。

相关文档

模型选择

选择 provider、模型引用和故障回退策略。

配置参考

智能体、模型和 provider 的完整配置参考。

故障排查

常见问题与调试步骤。

FAQ

OpenClaw 设置常见问题。

常见问题

怎么验证火山引擎 API Key 是否配置成功？

运行 openclaw models list --provider volcengine 和 openclaw models list --provider volcengine-plan，如果能看到模型列表则说明 Key 有效且 provider 已加载。

豆包模型的编程端点和通用端点有什么区别？

通用端点 (volcengine) 对应 ark.cn-beijing.volces.com/api/v3，适合对话、文本生成等任务；编程端点 (volcengine-plan) 对应 ark.cn-beijing.volces.com/api/coding/v3，针对代码生成场景优化，两者共用同一个 API Key。

TTS 配置后没有声音输出怎么办？

先确认环境变量 VOLCENGINE_TTS_API_KEY 和 VOLCENGINE_TTS_RESOURCE_ID 已正确设置，并且 openclaw.json 中 tts.provider 设为 "volcengine"。如果仍然无声，检查 BytePlus 控制台中的资源 ID 是否匹配（新用户默认 seed-tts-1.0，有 TTS 2.0 权限的改为 seed-tts-2.0）。同时注意：后台服务运行时环境变量须写入 ~/.openclaw/.env 或通过 env.shellEnv 传递。