Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

extensions/volcengine/api.ts

@@ -0,0 +1,58 @@
+// Volcengine API module exposes the plugin public contract.
+import type { ModelCompatConfig } from "openclaw/plugin-sdk/provider-model-shared";
+import { uniqueStrings } from "openclaw/plugin-sdk/string-coerce-runtime";
+
+export const VOLCENGINE_UNSUPPORTED_TOOL_SCHEMA_KEYWORDS = [
+  "minLength",
+  "maxLength",
+  "minItems",
+  "maxItems",
+  "minContains",
+  "maxContains",
+] as const;
+
+function mergeUnsupportedToolSchemaKeywords(existing: readonly string[] | undefined): string[] {
+  return uniqueStrings([...(existing ?? []), ...VOLCENGINE_UNSUPPORTED_TOOL_SCHEMA_KEYWORDS]);
+}
+
+export function resolveVolcengineToolSchemaCompatPatch(
+  compat?: ModelCompatConfig,
+): ModelCompatConfig {
+  return {
+    unsupportedToolSchemaKeywords: mergeUnsupportedToolSchemaKeywords(
+      compat?.unsupportedToolSchemaKeywords,
+    ),
+  };
+}
+
+export function applyVolcengineToolSchemaCompat<T extends { compat?: ModelCompatConfig }>(
+  model: T,
+): T {
+  const unsupportedToolSchemaKeywords = mergeUnsupportedToolSchemaKeywords(
+    model.compat?.unsupportedToolSchemaKeywords,
+  );
+  if (
+    model.compat?.unsupportedToolSchemaKeywords?.length === unsupportedToolSchemaKeywords.length &&
+    unsupportedToolSchemaKeywords.every(
+      (keyword, index) => model.compat?.unsupportedToolSchemaKeywords?.[index] === keyword,
+    )
+  ) {
+    return model;
+  }
+  return {
+    ...model,
+    compat: {
+      ...model.compat,
+      unsupportedToolSchemaKeywords,
+    },
+  };
+}
+
+export { buildDoubaoCodingProvider, buildDoubaoProvider } from "./provider-catalog.js";
+export {
+  buildDoubaoModelDefinition,
+  DOUBAO_BASE_URL,
+  DOUBAO_CODING_BASE_URL,
+  DOUBAO_CODING_MODEL_CATALOG,
+  DOUBAO_MODEL_CATALOG,
+} from "./models.js";

extensions/volcengine/index.test.ts

@@ -0,0 +1,93 @@
+// Volcengine tests cover index plugin behavior.
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { registerSingleProviderPlugin } from "openclaw/plugin-sdk/plugin-test-runtime";
+import { describe, expect, it } from "vitest";
+import {
+  VOLCENGINE_UNSUPPORTED_TOOL_SCHEMA_KEYWORDS,
+  resolveVolcengineToolSchemaCompatPatch,
+} from "./api.js";
+import plugin from "./index.js";
+import { DOUBAO_CODING_MODEL_CATALOG, DOUBAO_MODEL_CATALOG } from "./models.js";
+
+describe("volcengine plugin", () => {
+  it("augments the catalog with bundled standard and plan models", async () => {
+    const provider = await registerSingleProviderPlugin(plugin);
+    const entries = await provider.augmentModelCatalog?.({
+      env: process.env,
+      entries: [],
+    } as never);
+
+    expect(entries).toEqual([
+      ...DOUBAO_MODEL_CATALOG.map((entry) => ({
+        provider: "volcengine",
+        id: entry.id,
+        name: entry.name,
+        reasoning: entry.reasoning,
+        input: [...entry.input],
+        contextWindow: entry.contextWindow,
+      })),
+      ...DOUBAO_CODING_MODEL_CATALOG.map((entry) => ({
+        provider: "volcengine-plan",
+        id: entry.id,
+        name: entry.name,
+        reasoning: entry.reasoning,
+        input: [...entry.input],
+        contextWindow: entry.contextWindow,
+      })),
+    ]);
+  });
+
+  it("declares its coding provider auth alias in the manifest", () => {
+    const pluginJson = JSON.parse(
+      readFileSync(resolve(import.meta.dirname, "openclaw.plugin.json"), "utf-8"),
+    );
+
+    expect(pluginJson.providerAuthAliases).toEqual({
+      "volcengine-plan": "volcengine",
+    });
+  });
+
+  it("declares OpenAI-compatible streaming usage support in the manifest", () => {
+    const pluginJson = JSON.parse(
+      readFileSync(resolve(import.meta.dirname, "openclaw.plugin.json"), "utf-8"),
+    );
+
+    expect(pluginJson.providerRequest?.providers).toMatchObject({
+      volcengine: {
+        openAICompletions: { supportsStreamingUsage: true },
+      },
+      "volcengine-plan": {
+        openAICompletions: { supportsStreamingUsage: true },
+      },
+    });
+  });
+
+  it("marks direct and coding models with tool schema keyword compat", async () => {
+    const provider = await registerSingleProviderPlugin(plugin);
+
+    expect(provider.hookAliases).toContain("volcengine-plan");
+    expect(resolveVolcengineToolSchemaCompatPatch()).toEqual({
+      unsupportedToolSchemaKeywords: [...VOLCENGINE_UNSUPPORTED_TOOL_SCHEMA_KEYWORDS],
+    });
+
+    const normalized = provider.normalizeResolvedModel?.({
+      provider: "volcengine-plan",
+      modelId: "kimi-k2.5",
+      model: {
+        id: "kimi-k2.5",
+        provider: "volcengine-plan",
+        api: "openai-completions",
+        compat: { unsupportedToolSchemaKeywords: ["not"] },
+      },
+    } as never);
+
+    const normalizedCompat = normalized?.compat as
+      | { unsupportedToolSchemaKeywords?: string[] }
+      | undefined;
+    expect(normalizedCompat?.unsupportedToolSchemaKeywords).toEqual([
+      "not",
+      ...VOLCENGINE_UNSUPPORTED_TOOL_SCHEMA_KEYWORDS,
+    ]);
+  });
+});

extensions/volcengine/index.ts

@@ -0,0 +1,81 @@
+// Volcengine plugin entrypoint registers its OpenClaw integration.
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { createProviderApiKeyAuthMethod } from "openclaw/plugin-sdk/provider-auth-api-key";
+import { ensureModelAllowlistEntry } from "openclaw/plugin-sdk/provider-onboard";
+import { applyVolcengineToolSchemaCompat } from "./api.js";
+import { VOLCENGINE_PROVIDER_CATALOG_ENTRIES } from "./provider-catalog.js";
+import { buildVolcengineSpeechProvider } from "./speech-provider.js";
+
+const PROVIDER_ID = "volcengine";
+const VOLCENGINE_DEFAULT_MODEL_REF = "volcengine-plan/ark-code-latest";
+
+export default definePluginEntry({
+  id: PROVIDER_ID,
+  name: "Volcengine Provider",
+  description: "Bundled Volcengine provider plugin",
+  register(api) {
+    api.registerProvider({
+      id: PROVIDER_ID,
+      label: "Volcengine",
+      docsPath: "/concepts/model-providers#volcano-engine-doubao",
+      envVars: ["VOLCANO_ENGINE_API_KEY"],
+      hookAliases: ["volcengine-plan"],
+      auth: [
+        createProviderApiKeyAuthMethod({
+          providerId: PROVIDER_ID,
+          methodId: "api-key",
+          label: "Volcano Engine API key",
+          hint: "API key",
+          optionKey: "volcengineApiKey",
+          flagName: "--volcengine-api-key",
+          envVar: "VOLCANO_ENGINE_API_KEY",
+          promptMessage: "Enter Volcano Engine API key",
+          defaultModel: VOLCENGINE_DEFAULT_MODEL_REF,
+          expectedProviders: ["volcengine"],
+          applyConfig: (cfg) =>
+            ensureModelAllowlistEntry({
+              cfg,
+              modelRef: VOLCENGINE_DEFAULT_MODEL_REF,
+            }),
+          wizard: {
+            choiceId: "volcengine-api-key",
+            choiceLabel: "Volcano Engine API key",
+            groupId: "volcengine",
+            groupLabel: "Volcano Engine",
+            groupHint: "API key",
+          },
+        }),
+      ],
+      catalog: {
+        order: "paired",
+        run: async (ctx) => {
+          const apiKey = ctx.resolveProviderApiKey(PROVIDER_ID).apiKey;
+          if (!apiKey) {
+            return null;
+          }
+          return {
+            providers: Object.fromEntries(
+              VOLCENGINE_PROVIDER_CATALOG_ENTRIES.map(({ id, buildProvider }) => [
+                id,
+                { ...buildProvider(), apiKey },
+              ]),
+            ),
+          };
+        },
+      },
+      augmentModelCatalog: () =>
+        VOLCENGINE_PROVIDER_CATALOG_ENTRIES.flatMap(({ id: provider, models }) =>
+          models.map((entry) => ({
+            provider,
+            id: entry.id,
+            name: entry.name,
+            reasoning: entry.reasoning,
+            input: [...entry.input],
+            contextWindow: entry.contextWindow,
+          })),
+        ),
+      normalizeResolvedModel: ({ model }) => applyVolcengineToolSchemaCompat(model),
+    });
+    api.registerSpeechProvider(buildVolcengineSpeechProvider());
+  },
+});

extensions/volcengine/models.ts

@@ -0,0 +1,29 @@
+// Volcengine plugin module implements models behavior.
+import { buildManifestModelProviderConfig } from "openclaw/plugin-sdk/provider-catalog-shared";
+import type { ModelDefinitionConfig } from "openclaw/plugin-sdk/provider-model-shared";
+import manifest from "./openclaw.plugin.json" with { type: "json" };
+
+const DOUBAO_MANIFEST_PROVIDER = buildManifestModelProviderConfig({
+  providerId: "volcengine",
+  catalog: manifest.modelCatalog.providers.volcengine,
+});
+
+const DOUBAO_CODING_MANIFEST_PROVIDER = buildManifestModelProviderConfig({
+  providerId: "volcengine-plan",
+  catalog: manifest.modelCatalog.providers["volcengine-plan"],
+});
+
+export const DOUBAO_BASE_URL = DOUBAO_MANIFEST_PROVIDER.baseUrl;
+export const DOUBAO_CODING_BASE_URL = DOUBAO_CODING_MANIFEST_PROVIDER.baseUrl;
+
+export const DOUBAO_MODEL_CATALOG: ModelDefinitionConfig[] = DOUBAO_MANIFEST_PROVIDER.models;
+export const DOUBAO_CODING_MODEL_CATALOG: ModelDefinitionConfig[] =
+  DOUBAO_CODING_MANIFEST_PROVIDER.models;
+
+export function buildDoubaoModelDefinition(entry: ModelDefinitionConfig): ModelDefinitionConfig {
+  return {
+    ...entry,
+    input: [...entry.input],
+    cost: { ...entry.cost },
+  };
+}

extensions/volcengine/openclaw.plugin.json

@@ -0,0 +1,224 @@
+{
+  "id": "volcengine",
+  "activation": {
+    "onStartup": false
+  },
+  "enabledByDefault": true,
+  "providerCatalogEntry": "./provider-discovery.ts",
+  "providers": ["volcengine", "volcengine-plan"],
+  "setup": {
+    "providers": [
+      {
+        "id": "volcengine",
+        "envVars": ["VOLCANO_ENGINE_API_KEY"]
+      },
+      {
+        "id": "volcengine-tts",
+        "envVars": ["VOLCENGINE_TTS_API_KEY", "BYTEPLUS_SEED_SPEECH_API_KEY", "VOLCENGINE_TTS_APPID", "VOLCENGINE_TTS_TOKEN"]
+      }
+    ]
+  },
+  "providerAuthAliases": {
+    "volcengine-plan": "volcengine"
+  },
+  "providerRequest": {
+    "providers": {
+      "volcengine": {
+        "openAICompletions": {
+          "supportsStreamingUsage": true
+        }
+      },
+      "volcengine-plan": {
+        "openAICompletions": {
+          "supportsStreamingUsage": true
+        }
+      }
+    }
+  },
+  "modelCatalog": {
+    "providers": {
+      "volcengine": {
+        "baseUrl": "https://ark.cn-beijing.volces.com/api/v3",
+        "api": "openai-completions",
+        "models": [
+          {
+            "id": "doubao-seed-code-preview-251028",
+            "name": "doubao-seed-code-preview-251028",
+            "input": ["text", "image"],
+            "contextWindow": 256000,
+            "maxTokens": 4096,
+            "cost": {
+              "input": 0.0001,
+              "output": 0.0002,
+              "cacheRead": 0,
+              "cacheWrite": 0
+            }
+          },
+          {
+            "id": "doubao-seed-1-8-251228",
+            "name": "Doubao Seed 1.8",
+            "input": ["text", "image"],
+            "contextWindow": 256000,
+            "maxTokens": 4096,
+            "cost": {
+              "input": 0.0001,
+              "output": 0.0002,
+              "cacheRead": 0,
+              "cacheWrite": 0
+            }
+          },
+          {
+            "id": "kimi-k2-5-260127",
+            "name": "Kimi K2.5",
+            "input": ["text", "image"],
+            "contextWindow": 256000,
+            "maxTokens": 4096,
+            "cost": {
+              "input": 0.0001,
+              "output": 0.0002,
+              "cacheRead": 0,
+              "cacheWrite": 0
+            }
+          },
+          {
+            "id": "glm-4-7-251222",
+            "name": "GLM 4.7",
+            "input": ["text", "image"],
+            "contextWindow": 200000,
+            "maxTokens": 4096,
+            "cost": {
+              "input": 0.0001,
+              "output": 0.0002,
+              "cacheRead": 0,
+              "cacheWrite": 0
+            }
+          },
+          {
+            "id": "deepseek-v3-2-251201",
+            "name": "DeepSeek V3.2",
+            "input": ["text", "image"],
+            "contextWindow": 128000,
+            "maxTokens": 4096,
+            "cost": {
+              "input": 0.0001,
+              "output": 0.0002,
+              "cacheRead": 0,
+              "cacheWrite": 0
+            }
+          }
+        ]
+      },
+      "volcengine-plan": {
+        "baseUrl": "https://ark.cn-beijing.volces.com/api/coding/v3",
+        "api": "openai-completions",
+        "models": [
+          {
+            "id": "ark-code-latest",
+            "name": "Ark Coding Plan",
+            "input": ["text"],
+            "contextWindow": 256000,
+            "maxTokens": 4096,
+            "cost": {
+              "input": 0.0001,
+              "output": 0.0002,
+              "cacheRead": 0,
+              "cacheWrite": 0
+            }
+          },
+          {
+            "id": "doubao-seed-code",
+            "name": "Doubao Seed Code",
+            "input": ["text"],
+            "contextWindow": 256000,
+            "maxTokens": 4096,
+            "cost": {
+              "input": 0.0001,
+              "output": 0.0002,
+              "cacheRead": 0,
+              "cacheWrite": 0
+            }
+          },
+          {
+            "id": "glm-4.7",
+            "name": "GLM 4.7 Coding",
+            "input": ["text"],
+            "contextWindow": 200000,
+            "maxTokens": 4096,
+            "cost": {
+              "input": 0.0001,
+              "output": 0.0002,
+              "cacheRead": 0,
+              "cacheWrite": 0
+            }
+          },
+          {
+            "id": "kimi-k2-thinking",
+            "name": "Kimi K2 Thinking",
+            "input": ["text"],
+            "contextWindow": 256000,
+            "maxTokens": 4096,
+            "cost": {
+              "input": 0.0001,
+              "output": 0.0002,
+              "cacheRead": 0,
+              "cacheWrite": 0
+            }
+          },
+          {
+            "id": "kimi-k2.5",
+            "name": "Kimi K2.5 Coding",
+            "input": ["text"],
+            "contextWindow": 256000,
+            "maxTokens": 4096,
+            "cost": {
+              "input": 0.0001,
+              "output": 0.0002,
+              "cacheRead": 0,
+              "cacheWrite": 0
+            }
+          },
+          {
+            "id": "doubao-seed-code-preview-251028",
+            "name": "Doubao Seed Code Preview",
+            "input": ["text"],
+            "contextWindow": 256000,
+            "maxTokens": 4096,
+            "cost": {
+              "input": 0.0001,
+              "output": 0.0002,
+              "cacheRead": 0,
+              "cacheWrite": 0
+            }
+          }
+        ]
+      }
+    },
+    "discovery": {
+      "volcengine": "static",
+      "volcengine-plan": "static"
+    }
+  },
+  "providerAuthChoices": [
+    {
+      "provider": "volcengine",
+      "method": "api-key",
+      "choiceId": "volcengine-api-key",
+      "choiceLabel": "Volcano Engine API key",
+      "groupId": "volcengine",
+      "groupLabel": "Volcano Engine",
+      "groupHint": "API key",
+      "optionKey": "volcengineApiKey",
+      "cliFlag": "--volcengine-api-key",
+      "cliOption": "--volcengine-api-key <key>",
+      "cliDescription": "Volcano Engine API key"
+    }
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  },
+  "contracts": {
+    "speechProviders": ["volcengine"]
+  }
+}

extensions/volcengine/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@openclaw/volcengine-provider",
+  "version": "2026.6.11",
+  "private": true,
+  "description": "OpenClaw Volcengine provider plugin",
+  "type": "module",
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

extensions/volcengine/provider-catalog.ts

@@ -0,0 +1,34 @@
+// Volcengine provider module implements model/runtime integration.
+import { buildManifestModelProviderConfig } from "openclaw/plugin-sdk/provider-catalog-shared";
+import type { ModelProviderConfig } from "openclaw/plugin-sdk/provider-model-shared";
+import { DOUBAO_CODING_MODEL_CATALOG, DOUBAO_MODEL_CATALOG } from "./models.js";
+import manifest from "./openclaw.plugin.json" with { type: "json" };
+
+export function buildDoubaoProvider(): ModelProviderConfig {
+  return buildManifestModelProviderConfig({
+    providerId: "volcengine",
+    catalog: manifest.modelCatalog.providers.volcengine,
+  });
+}
+
+export function buildDoubaoCodingProvider(): ModelProviderConfig {
+  return buildManifestModelProviderConfig({
+    providerId: "volcengine-plan",
+    catalog: manifest.modelCatalog.providers["volcengine-plan"],
+  });
+}
+
+export const VOLCENGINE_PROVIDER_CATALOG_ENTRIES = [
+  {
+    id: "volcengine",
+    label: "Volcengine",
+    models: DOUBAO_MODEL_CATALOG,
+    buildProvider: buildDoubaoProvider,
+  },
+  {
+    id: "volcengine-plan",
+    label: "Volcengine Plan",
+    models: DOUBAO_CODING_MODEL_CATALOG,
+    buildProvider: buildDoubaoCodingProvider,
+  },
+] as const;

extensions/volcengine/provider-discovery.ts

@@ -0,0 +1,20 @@
+// Volcengine provider module implements model/runtime integration.
+import type { ProviderPlugin } from "openclaw/plugin-sdk/provider-model-shared";
+import { VOLCENGINE_PROVIDER_CATALOG_ENTRIES } from "./provider-catalog.js";
+
+const volcengineProviderDiscovery: ProviderPlugin[] = VOLCENGINE_PROVIDER_CATALOG_ENTRIES.map(
+  ({ id, label, buildProvider }) => ({
+    id,
+    label,
+    docsPath: "/providers/models",
+    auth: [],
+    staticCatalog: {
+      order: "simple",
+      run: async () => ({
+        provider: buildProvider(),
+      }),
+    },
+  }),
+);
+
+export default volcengineProviderDiscovery;

extensions/volcengine/speech-provider.ts

@@ -0,0 +1,238 @@
+// Volcengine provider module implements model/runtime integration.
+import { normalizeResolvedSecretInputString } from "openclaw/plugin-sdk/secret-input";
+import type {
+  SpeechDirectiveTokenParseContext,
+  SpeechProviderConfig,
+  SpeechProviderOverrides,
+  SpeechProviderPlugin,
+} from "openclaw/plugin-sdk/speech-core";
+import {
+  asObject,
+  parseSpeechDirectiveNumberOverride,
+  trimToUndefined,
+} from "openclaw/plugin-sdk/speech-core";
+import { asFiniteNumberInRange } from "openclaw/plugin-sdk/string-coerce-runtime";
+import { volcengineTTS, type VolcengineTtsEncoding } from "./tts.js";
+
+const DEFAULT_VOICE = "en_female_anna_mars_bigtts";
+const DEFAULT_CLUSTER = "volcano_tts";
+const DEFAULT_RESOURCE_ID = "seed-tts-1.0";
+const DEFAULT_APP_KEY = "aGjiRDfUWi";
+
+const VOLCENGINE_VOICES: readonly string[] = [
+  "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",
+];
+
+type VolcengineTtsProviderConfig = {
+  apiKey?: string;
+  appId?: string;
+  token?: string;
+  voice: string;
+  cluster: string;
+  resourceId: string;
+  appKey: string;
+  baseUrl?: string;
+  speedRatio?: number;
+  emotion?: string;
+};
+
+type VolcengineTtsProviderOverrides = {
+  voice?: string;
+  speedRatio?: number;
+  emotion?: string;
+};
+
+function normalizeSpeedRatio(value: unknown): number | undefined {
+  return asFiniteNumberInRange(value, { min: 0.2, max: 3 });
+}
+
+function normalizeVolcengineProviderConfig(
+  rawConfig: Record<string, unknown>,
+): VolcengineTtsProviderConfig {
+  const providers = asObject(rawConfig.providers);
+  const raw = asObject(providers?.volcengine) ?? asObject(rawConfig.volcengine);
+  return {
+    apiKey: normalizeResolvedSecretInputString({
+      value: raw?.apiKey,
+      path: "messages.tts.providers.volcengine.apiKey",
+    }),
+    appId: trimToUndefined(raw?.appId),
+    token: normalizeResolvedSecretInputString({
+      value: raw?.token,
+      path: "messages.tts.providers.volcengine.token",
+    }),
+    voice:
+      trimToUndefined(raw?.voice) ??
+      trimToUndefined(process.env.VOLCENGINE_TTS_VOICE) ??
+      DEFAULT_VOICE,
+    cluster:
+      trimToUndefined(raw?.cluster) ??
+      trimToUndefined(process.env.VOLCENGINE_TTS_CLUSTER) ??
+      DEFAULT_CLUSTER,
+    resourceId:
+      trimToUndefined(raw?.resourceId) ??
+      trimToUndefined(process.env.VOLCENGINE_TTS_RESOURCE_ID) ??
+      DEFAULT_RESOURCE_ID,
+    appKey:
+      trimToUndefined(raw?.appKey) ??
+      trimToUndefined(process.env.VOLCENGINE_TTS_APP_KEY) ??
+      DEFAULT_APP_KEY,
+    baseUrl: trimToUndefined(raw?.baseUrl) ?? trimToUndefined(process.env.VOLCENGINE_TTS_BASE_URL),
+    speedRatio: normalizeSpeedRatio(raw?.speedRatio),
+    emotion: trimToUndefined(raw?.emotion),
+  };
+}
+
+function resolveSeedSpeechApiKey(configApiKey?: string): string | undefined {
+  return (
+    configApiKey ??
+    trimToUndefined(process.env.VOLCENGINE_TTS_API_KEY) ??
+    trimToUndefined(process.env.BYTEPLUS_SEED_SPEECH_API_KEY)
+  );
+}
+
+function readProviderConfig(config: SpeechProviderConfig): VolcengineTtsProviderConfig {
+  const normalized = normalizeVolcengineProviderConfig({});
+  return {
+    apiKey:
+      normalizeResolvedSecretInputString({
+        value: config.apiKey,
+        path: "messages.tts.providers.volcengine.apiKey",
+      }) ?? normalized.apiKey,
+    appId: trimToUndefined(config.appId) ?? normalized.appId,
+    token: trimToUndefined(config.token) ?? normalized.token,
+    voice: trimToUndefined(config.voice) ?? normalized.voice,
+    cluster: trimToUndefined(config.cluster) ?? normalized.cluster,
+    resourceId: trimToUndefined(config.resourceId) ?? normalized.resourceId,
+    appKey: trimToUndefined(config.appKey) ?? normalized.appKey,
+    baseUrl: trimToUndefined(config.baseUrl) ?? normalized.baseUrl,
+    speedRatio: normalizeSpeedRatio(config.speedRatio) ?? normalized.speedRatio,
+    emotion: trimToUndefined(config.emotion) ?? normalized.emotion,
+  };
+}
+
+function readVolcengineOverrides(
+  overrides: SpeechProviderOverrides | undefined,
+): VolcengineTtsProviderOverrides {
+  if (!overrides) {
+    return {};
+  }
+  return {
+    voice: trimToUndefined(overrides.voice),
+    speedRatio: normalizeSpeedRatio(overrides.speedRatio),
+    emotion: trimToUndefined(overrides.emotion),
+  };
+}
+
+function parseDirectiveToken(ctx: SpeechDirectiveTokenParseContext): {
+  handled: boolean;
+  overrides?: SpeechProviderOverrides;
+  warnings?: string[];
+} {
+  switch (ctx.key) {
+    case "voice":
+    case "volcengine_voice":
+    case "volcenginevoice":
+      if (!ctx.policy.allowVoice) {
+        return { handled: true };
+      }
+      return { handled: true, overrides: { ...ctx.currentOverrides, voice: ctx.value } };
+    case "speed":
+    case "speedratio":
+    case "speed_ratio": {
+      return parseSpeechDirectiveNumberOverride({
+        ctx,
+        overrideKey: "speedRatio",
+        range: { min: 0.2, max: 3 },
+        warning: (value) => `invalid Volcengine speedRatio "${value}"`,
+        mergeCurrentOverrides: true,
+      });
+    }
+    case "emotion":
+      if (!ctx.policy.allowVoiceSettings) {
+        return { handled: true };
+      }
+      return { handled: true, overrides: { ...ctx.currentOverrides, emotion: ctx.value } };
+    default:
+      return { handled: false };
+  }
+}
+
+export function buildVolcengineSpeechProvider(): SpeechProviderPlugin {
+  return {
+    id: "volcengine",
+    label: "Volcengine",
+    autoSelectOrder: 90,
+    aliases: ["bytedance", "doubao"],
+    voices: VOLCENGINE_VOICES,
+    resolveConfig: ({ rawConfig }) => normalizeVolcengineProviderConfig(rawConfig),
+    parseDirectiveToken,
+
+    listVoices: async () =>
+      VOLCENGINE_VOICES.map((v) => ({
+        id: v,
+        name: v.replace(/^(?:en|zh)_(female|male)_/, "").replace(/_.*$/, ""),
+        locale: v.startsWith("en_") ? "en-US" : "zh-CN",
+        gender: v.includes("_female_") ? "female" : "male",
+      })),
+
+    isConfigured: ({ providerConfig }) => {
+      const cfg = readProviderConfig(providerConfig);
+      return Boolean(
+        resolveSeedSpeechApiKey(cfg.apiKey) ||
+        ((cfg.appId || process.env.VOLCENGINE_TTS_APPID) &&
+          (cfg.token || process.env.VOLCENGINE_TTS_TOKEN)),
+      );
+    },
+
+    synthesize: async (req) => {
+      const cfg = readProviderConfig(req.providerConfig);
+      const overrides = readVolcengineOverrides(req.providerOverrides);
+      const apiKey = resolveSeedSpeechApiKey(cfg.apiKey);
+      const appId = cfg.appId || process.env.VOLCENGINE_TTS_APPID;
+      const token = cfg.token || process.env.VOLCENGINE_TTS_TOKEN;
+
+      if (!apiKey && (!appId || !token)) {
+        throw new Error(
+          "Volcengine TTS credentials missing. Set VOLCENGINE_TTS_API_KEY, " +
+            "BYTEPLUS_SEED_SPEECH_API_KEY, or legacy VOLCENGINE_TTS_APPID and VOLCENGINE_TTS_TOKEN.",
+        );
+      }
+
+      const isVoiceNote = req.target === "voice-note";
+      const encoding: VolcengineTtsEncoding = isVoiceNote ? "ogg_opus" : "mp3";
+
+      const audioBuffer = await volcengineTTS({
+        text: req.text,
+        apiKey,
+        appId,
+        token,
+        voice: overrides.voice ?? cfg.voice,
+        cluster: cfg.cluster,
+        resourceId: cfg.resourceId,
+        appKey: cfg.appKey,
+        baseUrl: cfg.baseUrl,
+        speedRatio: overrides.speedRatio ?? cfg.speedRatio,
+        emotion: overrides.emotion ?? cfg.emotion,
+        encoding,
+        timeoutMs: req.timeoutMs,
+      });
+
+      return {
+        audioBuffer,
+        outputFormat: encoding === "ogg_opus" ? "opus" : "mp3",
+        fileExtension: encoding === "ogg_opus" ? ".opus" : ".mp3",
+        voiceCompatible: isVoiceNote,
+      };
+    },
+  };
+}

extensions/volcengine/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}

extensions/volcengine/tts.live.test.ts

@@ -0,0 +1,31 @@
+// Volcengine tests cover tts plugin behavior.
+import { describe, expect, it } from "vitest";
+import { volcengineTTS } from "./tts.js";
+
+const seedSpeechApiKey =
+  process.env.VOLCENGINE_TTS_API_KEY ?? process.env.BYTEPLUS_SEED_SPEECH_API_KEY;
+const hasVolcengineTtsCredentials = Boolean(
+  seedSpeechApiKey || (process.env.VOLCENGINE_TTS_APPID && process.env.VOLCENGINE_TTS_TOKEN),
+);
+const describeLive =
+  process.env.OPENCLAW_LIVE_TEST === "1" && hasVolcengineTtsCredentials ? describe : describe.skip;
+
+describeLive("Volcengine TTS live", () => {
+  it("synthesizes mp3 audio with .profile credentials", async () => {
+    const audio = await volcengineTTS({
+      text: "OpenClaw live test.",
+      apiKey: seedSpeechApiKey,
+      appId: process.env.VOLCENGINE_TTS_APPID,
+      token: process.env.VOLCENGINE_TTS_TOKEN,
+      voice: process.env.VOLCENGINE_TTS_VOICE,
+      cluster: process.env.VOLCENGINE_TTS_CLUSTER,
+      resourceId: process.env.VOLCENGINE_TTS_RESOURCE_ID,
+      appKey: process.env.VOLCENGINE_TTS_APP_KEY,
+      baseUrl: process.env.VOLCENGINE_TTS_BASE_URL,
+      encoding: "mp3",
+      timeoutMs: 30_000,
+    });
+
+    expect(audio.length).toBeGreaterThan(128);
+  });
+});

extensions/volcengine/tts.test.ts

@@ -0,0 +1,379 @@
+// Volcengine tests cover tts plugin behavior.
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { buildVolcengineSpeechProvider } from "./speech-provider.js";
+import { volcengineTTS } from "./tts.js";
+
+const { fetchWithSsrFGuardMock } = vi.hoisted(() => ({
+  fetchWithSsrFGuardMock: vi.fn(),
+}));
+
+const PROVIDER_RESPONSE_MAX_BYTES = 16 * 1024 * 1024;
+
+vi.mock("openclaw/plugin-sdk/ssrf-runtime", () => ({
+  fetchWithSsrFGuard: fetchWithSsrFGuardMock,
+}));
+
+function requireFirstGuardedFetchCall(): unknown {
+  const [call] = fetchWithSsrFGuardMock.mock.calls;
+  if (!call) {
+    throw new Error("expected Volcengine guarded fetch call");
+  }
+  return call[0];
+}
+
+function makeProviderConfig(overrides?: Record<string, unknown>) {
+  return {
+    apiKey: "test-api-key",
+    voice: "en_female_anna_mars_bigtts",
+    ...overrides,
+  };
+}
+
+function makeLegacyProviderConfig(overrides?: Record<string, unknown>) {
+  return {
+    appId: "test-app-id",
+    token: "test-token",
+    voice: "zh_female_xiaohe_uranus_bigtts",
+    cluster: "volcano_tts",
+    ...overrides,
+  };
+}
+
+function clearTtsEnv() {
+  delete process.env.BYTEPLUS_API_KEY;
+  delete process.env.BYTEPLUS_SEED_SPEECH_API_KEY;
+  delete process.env.VOLCENGINE_TTS_API_KEY;
+  delete process.env.VOLCENGINE_TTS_APPID;
+  delete process.env.VOLCENGINE_TTS_TOKEN;
+}
+
+function makeOversizedStreamResponse(): Response {
+  return new Response(
+    new ReadableStream<Uint8Array>({
+      start(controller) {
+        controller.enqueue(new Uint8Array(PROVIDER_RESPONSE_MAX_BYTES));
+        controller.enqueue(new Uint8Array(1));
+        controller.close();
+      },
+    }),
+  );
+}
+
+function restoreOptionalEnv(key: string, value: string | undefined) {
+  if (value === undefined) {
+    delete process.env[key];
+  } else {
+    process.env[key] = value;
+  }
+}
+
+describe("Volcengine speech provider", () => {
+  const provider = buildVolcengineSpeechProvider();
+
+  beforeEach(() => {
+    fetchWithSsrFGuardMock.mockReset();
+  });
+
+  it("has correct id, label, and aliases", () => {
+    expect(provider.id).toBe("volcengine");
+    expect(provider.label).toBe("Volcengine");
+    expect(provider.aliases).toContain("bytedance");
+    expect(provider.aliases).toContain("doubao");
+  });
+
+  it("reports configured when an API key is present in providerConfig", () => {
+    expect(provider.isConfigured({ providerConfig: makeProviderConfig(), timeoutMs: 30000 })).toBe(
+      true,
+    );
+  });
+
+  it("reports configured for legacy appId and token in providerConfig", () => {
+    expect(
+      provider.isConfigured({ providerConfig: makeLegacyProviderConfig(), timeoutMs: 30000 }),
+    ).toBe(true);
+  });
+
+  it("reports not configured when credentials are missing", () => {
+    const oldBytePlusKey = process.env.BYTEPLUS_API_KEY;
+    const oldSeedKey = process.env.BYTEPLUS_SEED_SPEECH_API_KEY;
+    const oldApiKey = process.env.VOLCENGINE_TTS_API_KEY;
+    const oldAppId = process.env.VOLCENGINE_TTS_APPID;
+    const oldToken = process.env.VOLCENGINE_TTS_TOKEN;
+    clearTtsEnv();
+    try {
+      expect(provider.isConfigured({ providerConfig: {}, timeoutMs: 30000 })).toBe(false);
+    } finally {
+      restoreOptionalEnv("BYTEPLUS_API_KEY", oldBytePlusKey);
+      restoreOptionalEnv("BYTEPLUS_SEED_SPEECH_API_KEY", oldSeedKey);
+      restoreOptionalEnv("VOLCENGINE_TTS_API_KEY", oldApiKey);
+      restoreOptionalEnv("VOLCENGINE_TTS_APPID", oldAppId);
+      restoreOptionalEnv("VOLCENGINE_TTS_TOKEN", oldToken);
+    }
+  });
+
+  it("falls back to env vars for credentials", () => {
+    const oldBytePlusKey = process.env.BYTEPLUS_API_KEY;
+    const oldSeedKey = process.env.BYTEPLUS_SEED_SPEECH_API_KEY;
+    const oldApiKey = process.env.VOLCENGINE_TTS_API_KEY;
+    const oldAppId = process.env.VOLCENGINE_TTS_APPID;
+    const oldToken = process.env.VOLCENGINE_TTS_TOKEN;
+    clearTtsEnv();
+    process.env.BYTEPLUS_SEED_SPEECH_API_KEY = "env-api-key";
+    try {
+      expect(provider.isConfigured({ providerConfig: {}, timeoutMs: 30000 })).toBe(true);
+    } finally {
+      restoreOptionalEnv("BYTEPLUS_API_KEY", oldBytePlusKey);
+      restoreOptionalEnv("BYTEPLUS_SEED_SPEECH_API_KEY", oldSeedKey);
+      restoreOptionalEnv("VOLCENGINE_TTS_API_KEY", oldApiKey);
+      restoreOptionalEnv("VOLCENGINE_TTS_APPID", oldAppId);
+      restoreOptionalEnv("VOLCENGINE_TTS_TOKEN", oldToken);
+    }
+  });
+
+  it("lists voices with locale and gender", async () => {
+    const listVoices = provider.listVoices;
+    if (!listVoices) {
+      throw new Error("Expected Volcengine provider listVoices");
+    }
+    const voices = await listVoices({});
+    expect(voices.length).toBeGreaterThan(0);
+    expect(voices[0]).toEqual({
+      id: "en_female_anna_mars_bigtts",
+      name: "anna",
+      locale: "en-US",
+      gender: "female",
+    });
+  });
+
+  it("rejects non-decimal speedRatio directive values", () => {
+    expect(
+      provider.parseDirectiveToken?.({
+        key: "speed",
+        value: "0x1",
+        policy: {
+          enabled: true,
+          allowText: true,
+          allowProvider: true,
+          allowVoice: true,
+          allowModelId: true,
+          allowVoiceSettings: true,
+          allowNormalization: true,
+          allowSeed: true,
+        },
+      }),
+    ).toEqual({
+      handled: true,
+      warnings: ['invalid Volcengine speedRatio "0x1"'],
+    });
+  });
+
+  it("sends the documented Seed Speech API key payload and returns voice-note Opus metadata", async () => {
+    const release = vi.fn();
+    fetchWithSsrFGuardMock.mockResolvedValue({
+      response: new Response(
+        JSON.stringify({
+          code: 0,
+          data: Buffer.from("voice-audio").toString("base64"),
+        }),
+      ),
+      release,
+    });
+
+    const result = await provider.synthesize({
+      text: "hello",
+      cfg: {},
+      providerConfig: makeProviderConfig({ emotion: "happy", speedRatio: 1.2 }),
+      target: "voice-note",
+      providerOverrides: { voice: "zh_male_aojiao_mars_bigtts", speedRatio: 0.9 },
+      timeoutMs: 1234,
+    });
+
+    expect(result.audioBuffer.toString()).toBe("voice-audio");
+    expect(result.outputFormat).toBe("opus");
+    expect(result.fileExtension).toBe(".opus");
+    expect(result.voiceCompatible).toBe(true);
+
+    const call = requireFirstGuardedFetchCall();
+    expect(call).toEqual({
+      url: "https://voice.ap-southeast-1.bytepluses.com/api/v3/tts/unidirectional",
+      init: {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Connection: "keep-alive",
+          "X-Api-Key": "test-api-key",
+          "X-Api-Resource-Id": "seed-tts-1.0",
+          "X-Api-App-Key": "aGjiRDfUWi",
+        },
+        body: JSON.stringify({
+          user: { uid: "openclaw" },
+          req_params: {
+            text: "hello",
+            speaker: "zh_male_aojiao_mars_bigtts",
+            audio_params: {
+              format: "ogg_opus",
+              sample_rate: 24000,
+            },
+            speed_ratio: 0.9,
+            emotion: "happy",
+          },
+        }),
+      },
+      timeoutMs: 1234,
+      policy: { hostnameAllowlist: ["voice.ap-southeast-1.bytepluses.com"] },
+      auditContext: "volcengine.tts",
+    });
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it("drops malformed speed ratios before synthesis", async () => {
+    const release = vi.fn();
+    fetchWithSsrFGuardMock.mockResolvedValue({
+      response: new Response(
+        JSON.stringify({
+          code: 0,
+          data: Buffer.from("voice-audio").toString("base64"),
+        }),
+      ),
+      release,
+    });
+
+    await provider.synthesize({
+      text: "hello",
+      cfg: {},
+      providerConfig: makeProviderConfig({ speedRatio: 4 }),
+      target: "audio-file",
+      providerOverrides: { speedRatio: -1 },
+      timeoutMs: 1234,
+    });
+
+    const call = requireFirstGuardedFetchCall() as { init: { body: string } };
+    const body = JSON.parse(call.init.body) as {
+      req_params?: { speed_ratio?: number };
+    };
+    expect(body.req_params).not.toHaveProperty("speed_ratio");
+  });
+});
+
+describe("volcengineTTS", () => {
+  beforeEach(() => {
+    fetchWithSsrFGuardMock.mockReset();
+  });
+
+  it("joins streamed Seed Speech audio frames", async () => {
+    const release = vi.fn();
+    fetchWithSsrFGuardMock.mockResolvedValue({
+      response: new Response(
+        [
+          JSON.stringify({ code: 0, message: "" }),
+          JSON.stringify({ code: 0, data: Buffer.from("audio-1").toString("base64") }),
+          JSON.stringify({ code: 0, data: Buffer.from("audio-2").toString("base64") }),
+          JSON.stringify({ code: 20000000, message: "ok", data: null }),
+        ].join("\n"),
+      ),
+      release,
+    });
+
+    const audio = await volcengineTTS({
+      text: "hello",
+      apiKey: "secret-api-key",
+      voice: "zh_female_xiaohe_uranus_bigtts",
+      encoding: "mp3",
+      timeoutMs: 1000,
+    });
+
+    expect(audio.toString()).toBe("audio-1audio-2");
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it("reports Seed Speech provider errors without exposing credentials", async () => {
+    const release = vi.fn();
+    fetchWithSsrFGuardMock.mockResolvedValue({
+      response: new Response(
+        JSON.stringify({ header: { code: 45000000, message: "speaker permission denied" } }),
+        { status: 403 },
+      ),
+      release,
+    });
+
+    let error: unknown;
+    try {
+      await volcengineTTS({
+        text: "hello",
+        apiKey: "secret-api-key",
+        timeoutMs: 1000,
+      });
+    } catch (err) {
+      error = err;
+    }
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toBe(
+      "BytePlus Seed Speech TTS error 45000000: speaker permission denied",
+    );
+    expect((error as Error).message).not.toContain("secret-api-key");
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it("bounds Seed Speech success response reads", async () => {
+    const release = vi.fn();
+    fetchWithSsrFGuardMock.mockResolvedValue({
+      response: makeOversizedStreamResponse(),
+      release,
+    });
+
+    await expect(
+      volcengineTTS({
+        text: "hello",
+        apiKey: "secret-api-key",
+        timeoutMs: 1000,
+      }),
+    ).rejects.toThrow("BytePlus Seed Speech TTS response exceeds 16777216 bytes");
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it("reports provider errors without exposing credentials", async () => {
+    const release = vi.fn();
+    fetchWithSsrFGuardMock.mockResolvedValue({
+      response: new Response(JSON.stringify({ code: 3001, message: "load grant failed" }), {
+        status: 401,
+      }),
+      release,
+    });
+
+    let error: unknown;
+    try {
+      await volcengineTTS({
+        text: "hello",
+        appId: "app-id",
+        token: "secret-token",
+        timeoutMs: 1000,
+      });
+    } catch (err) {
+      error = err;
+    }
+
+    expect(error).toBeInstanceOf(Error);
+    expect((error as Error).message).toBe("Volcengine TTS error 3001: load grant failed");
+    expect((error as Error).message).not.toContain("secret-token");
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it("bounds legacy Volcengine success response reads", async () => {
+    const release = vi.fn();
+    fetchWithSsrFGuardMock.mockResolvedValue({
+      response: makeOversizedStreamResponse(),
+      release,
+    });
+
+    await expect(
+      volcengineTTS({
+        text: "hello",
+        appId: "app-id",
+        token: "secret-token",
+        timeoutMs: 1000,
+      }),
+    ).rejects.toThrow("Volcengine TTS response exceeds 16777216 bytes");
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+});

extensions/volcengine/tts.ts

@@ -0,0 +1,281 @@
+// Volcengine plugin module implements tts behavior.
+import * as crypto from "node:crypto";
+import { readResponseWithLimit } from "openclaw/plugin-sdk/response-limit-runtime";
+import { fetchWithSsrFGuard } from "openclaw/plugin-sdk/ssrf-runtime";
+
+export type VolcengineTtsEncoding = "ogg_opus" | "mp3" | "pcm" | "wav";
+
+type VolcengineTTSParams = {
+  text: string;
+  apiKey?: string;
+  appId?: string;
+  token?: string;
+  voice?: string;
+  cluster?: string;
+  resourceId?: string;
+  appKey?: string;
+  baseUrl?: string;
+  speedRatio?: number;
+  volumeRatio?: number;
+  pitchRatio?: number;
+  emotion?: string;
+  encoding?: VolcengineTtsEncoding;
+  timeoutMs?: number;
+};
+
+const DEFAULT_SEED_VOICE = "en_female_anna_mars_bigtts";
+const DEFAULT_LEGACY_VOICE = "zh_female_xiaohe_uranus_bigtts";
+const DEFAULT_CLUSTER = "volcano_tts";
+const DEFAULT_SEED_TTS_RESOURCE_ID = "seed-tts-1.0";
+const DEFAULT_SEED_TTS_APP_KEY = "aGjiRDfUWi";
+const VOLCENGINE_TTS_RESPONSE_MAX_BYTES = 16 * 1024 * 1024;
+const BYTEPLUS_SEED_TTS_URL =
+  "https://voice.ap-southeast-1.bytepluses.com/api/v3/tts/unidirectional";
+const VOLCENGINE_LEGACY_TTS_URL = "https://openspeech.bytedance.com/api/v1/tts";
+
+type VolcengineTtsResponse = {
+  code?: number;
+  message?: string;
+  data?: string;
+};
+
+function parseJsonObject(text: string, providerName: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("expected JSON object");
+    }
+    return parsed as Record<string, unknown>;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`${providerName} TTS: failed to parse response JSON: ${detail}`, {
+      cause: err,
+    });
+  }
+}
+
+function toTtsResponse(parsed: Record<string, unknown>): VolcengineTtsResponse {
+  const header =
+    parsed.header && typeof parsed.header === "object" && !Array.isArray(parsed.header)
+      ? (parsed.header as Record<string, unknown>)
+      : undefined;
+  return {
+    code:
+      typeof parsed.code === "number"
+        ? parsed.code
+        : typeof header?.code === "number"
+          ? header.code
+          : undefined,
+    message:
+      typeof parsed.message === "string"
+        ? parsed.message
+        : typeof header?.message === "string"
+          ? header.message
+          : undefined,
+    data: typeof parsed.data === "string" ? parsed.data : undefined,
+  };
+}
+
+function parseLegacyTtsResponse(text: string): VolcengineTtsResponse {
+  return toTtsResponse(parseJsonObject(text, "Volcengine"));
+}
+
+function parseSeedTtsFrames(text: string): VolcengineTtsResponse[] {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return [];
+  }
+
+  try {
+    return [toTtsResponse(parseJsonObject(trimmed, "BytePlus Seed Speech"))];
+  } catch {
+    // The HTTP API streams JSON frames; Response.text() preserves line breaks.
+  }
+
+  const frames: VolcengineTtsResponse[] = [];
+  for (const line of trimmed.split(/\r?\n/)) {
+    const item = line.trim();
+    if (!item) {
+      continue;
+    }
+    const json = item.startsWith("data:") ? item.slice("data:".length).trim() : item;
+    frames.push(toTtsResponse(parseJsonObject(json, "BytePlus Seed Speech")));
+  }
+  return frames;
+}
+
+function hostnameAllowlist(url: string): string[] {
+  return [new URL(url).hostname];
+}
+
+function seedAudioFormat(encoding: VolcengineTtsEncoding): "ogg_opus" | "mp3" | "pcm" {
+  return encoding === "wav" ? "pcm" : encoding;
+}
+
+async function seedSpeechTTS(params: VolcengineTTSParams & { apiKey: string }): Promise<Buffer> {
+  const {
+    text,
+    apiKey,
+    voice = DEFAULT_SEED_VOICE,
+    resourceId = DEFAULT_SEED_TTS_RESOURCE_ID,
+    appKey = DEFAULT_SEED_TTS_APP_KEY,
+    baseUrl = BYTEPLUS_SEED_TTS_URL,
+    speedRatio = 1,
+    emotion,
+    encoding = "ogg_opus",
+    timeoutMs = 30_000,
+  } = params;
+  const audioFormat = seedAudioFormat(encoding);
+
+  const payload = JSON.stringify({
+    user: { uid: "openclaw" },
+    req_params: {
+      text,
+      speaker: voice,
+      audio_params: {
+        format: audioFormat,
+        sample_rate: 24_000,
+      },
+      ...(speedRatio !== 1 ? { speed_ratio: speedRatio } : {}),
+      ...(emotion ? { emotion } : {}),
+    },
+  });
+
+  const { response, release } = await fetchWithSsrFGuard({
+    url: baseUrl,
+    init: {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Connection: "keep-alive",
+        "X-Api-Key": apiKey,
+        "X-Api-Resource-Id": resourceId,
+        "X-Api-App-Key": appKey,
+      },
+      body: payload,
+    },
+    timeoutMs,
+    policy: { hostnameAllowlist: hostnameAllowlist(baseUrl) },
+    auditContext: "volcengine.tts",
+  });
+
+  try {
+    const responseText = new TextDecoder().decode(
+      await readResponseWithLimit(response, VOLCENGINE_TTS_RESPONSE_MAX_BYTES, {
+        onOverflow: ({ maxBytes }) =>
+          new Error(`BytePlus Seed Speech TTS response exceeds ${maxBytes} bytes`),
+      }),
+    );
+    const frames = parseSeedTtsFrames(responseText);
+    const chunks: Buffer[] = [];
+    for (const frame of frames) {
+      if (frame.code === 0) {
+        if (frame.data) {
+          chunks.push(Buffer.from(frame.data, "base64"));
+        }
+        continue;
+      }
+      if (frame.code === 20000000) {
+        continue;
+      }
+      throw new Error(
+        `BytePlus Seed Speech TTS error ${frame.code ?? response.status}: ${
+          frame.message ?? "unknown"
+        }`,
+      );
+    }
+
+    if (!response.ok || chunks.length === 0) {
+      throw new Error(`BytePlus Seed Speech TTS error ${response.status}: no audio data`);
+    }
+
+    return Buffer.concat(chunks);
+  } finally {
+    await release();
+  }
+}
+
+async function legacyVolcengineTTS(
+  params: VolcengineTTSParams & { appId: string; token: string },
+): Promise<Buffer> {
+  const {
+    text,
+    appId,
+    token,
+    voice = DEFAULT_LEGACY_VOICE,
+    cluster = DEFAULT_CLUSTER,
+    baseUrl = VOLCENGINE_LEGACY_TTS_URL,
+    speedRatio = 1,
+    volumeRatio = 1,
+    pitchRatio = 1,
+    emotion,
+    encoding = "ogg_opus",
+    timeoutMs = 30_000,
+  } = params;
+
+  const payload = JSON.stringify({
+    app: { appid: appId, token, cluster },
+    user: { uid: "openclaw" },
+    audio: {
+      voice_type: voice,
+      encoding,
+      speed_ratio: speedRatio,
+      volume_ratio: volumeRatio,
+      pitch_ratio: pitchRatio,
+      ...(emotion ? { emotion } : {}),
+    },
+    request: {
+      reqid: crypto.randomUUID(),
+      text,
+      text_type: "plain",
+      operation: "query",
+    },
+  });
+
+  const { response, release } = await fetchWithSsrFGuard({
+    url: baseUrl,
+    init: {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer;${token}`,
+      },
+      body: payload,
+    },
+    timeoutMs,
+    policy: { hostnameAllowlist: hostnameAllowlist(baseUrl) },
+    auditContext: "volcengine.tts",
+  });
+
+  try {
+    const responseText = new TextDecoder().decode(
+      await readResponseWithLimit(response, VOLCENGINE_TTS_RESPONSE_MAX_BYTES, {
+        onOverflow: ({ maxBytes }) =>
+          new Error(`Volcengine TTS response exceeds ${maxBytes} bytes`),
+      }),
+    );
+    const body = parseLegacyTtsResponse(responseText);
+    if (!response.ok || body.code !== 3000 || !body.data) {
+      throw new Error(
+        `Volcengine TTS error ${body.code ?? response.status}: ${body.message ?? "unknown"}`,
+      );
+    }
+    return Buffer.from(body.data, "base64");
+  } finally {
+    await release();
+  }
+}
+
+export async function volcengineTTS(params: VolcengineTTSParams): Promise<Buffer> {
+  if (params.apiKey) {
+    return seedSpeechTTS({ ...params, apiKey: params.apiKey });
+  }
+
+  if (params.appId && params.token) {
+    return legacyVolcengineTTS({ ...params, appId: params.appId, token: params.token });
+  }
+
+  throw new Error(
+    "Volcengine TTS credentials missing. Set a BytePlus Seed Speech API key or legacy AppID/token.",
+  );
+}