openclaw - 💡(How to fix) Fix [Bug]: 2026.3.28 removes messages.tts.edge from Zod schema without auto-migration, breaking existing Edge TTS configs [2 comments, 2 participants]

Summary

Upgrading from 2026.3.24 to 2026.3.28 causes Gateway to reject existing messages.tts.edge config with:

messages.tts: Unrecognized key: "edge"

This is a breaking change that was listed under "Changes" (not "Breaking") in the 2026.3.28 changelog:

Config/TTS: auto-migrate legacy speech config on normal reads and secret resolution, keep legacy diagnostics for Doctor, and remove regular-mode runtime fallback for old bundled tts.<provider> API-key shapes.

Root Cause (code-verified)

2026.3.24 TtsConfigSchema (zod-schema.agent-runtime-DNndkpI8.js:328):

const TtsConfigSchema = z.object({
  auto, enabled, mode, provider, summaryModel,
  modelOverrides: { ... },
  elevenlabs: { ... },
  openai: { ... },
  edge: TtsMicrosoftConfigSchema,    // ← present
  microsoft: TtsMicrosoftConfigSchema, // ← present
  prefsPath, maxTextLength, timeoutMs
}).strict().optional();

2026.3.28 TtsConfigSchema (zod-schema.core-CGoKjdG2.js:278):

const TtsConfigSchema = z.object({
  auto, enabled, mode, provider, summaryModel,
  modelOverrides: { ... },
  providers: z.record(z.string(), TtsProviderConfigSchema).optional(),  // ← new
  prefsPath, maxTextLength, timeoutMs
}).strict().optional();

edge, microsoft, elevenlabs, and openai sub-objects were removed from the Zod schema and replaced with a generic providers record. The schema uses .strict(), so any unrecognized key causes a hard validation failure.

Note: The JSON Schema export in bundled voice-call plugin metadata (chat-meta-xAV2SRO1.js:14476) still includes edge as a property — but this is the voice-call plugin's TTS schema, not the main messages.tts schema. The Zod schema (which is used for actual config validation) does not include edge.

Auto-migration gap

The changelog says "auto-migrate legacy speech config on normal reads", but the auto-migration (env-D1ktUnAV.js, applyLegacyMigrations) only handles messages.tts.enabled → messages.tts.auto. It does not migrate messages.tts.edge → messages.tts.providers.edge.

Expected new config format

Based on the new schema, the correct format should be:

{
  "messages": {
    "tts": {
      "auto": "off",
      "mode": "final",
      "provider": "edge",
      "providers": {
        "edge": {
          "voice": "en-US-JennyNeural",
          "lang": "en-US",
          "outputFormat": "ogg-24khz-16bit-mono-opus",
          "pitch": "+0Hz",
          "rate": "+0%",
          "volume": "+0%",
          "timeoutMs": 30000
        }
      }
    }
  }
}

Steps to Reproduce

1. Have working Edge TTS config in 2026.3.24:

{
  "messages": {
    "tts": {
      "provider": "edge",
      "edge": {
        "voice": "en-US-JennyNeural",
        "lang": "en-US",
        "outputFormat": "ogg-24khz-16bit-mono-opus"
      }
    }
  }
}

1. Upgrade to 2026.3.28
2. Gateway refuses to start: messages.tts: Unrecognized key: "edge"
3. openclaw doctor --fix does not fix this

Suggested Fix

Add auto-migration in applyLegacyMigrations() to move messages.tts.<provider> sub-objects into messages.tts.providers.<provider> for all four affected providers (edge, microsoft, elevenlabs, openai).

Environment

• OpenClaw: 2026.3.28 (reverted to 2026.3.24)
• macOS arm64, Node 22.22.1

Related

• #56220 (same symptom reported by another user)