openclaw - 💡(How to fix) Fix Every upgrade breaks custom provider configs — 5.12 is no exception (400 Param Incorrect + auth regression)

Description

Every single OpenClaw minor version upgrade (5.2 → 5.7 → 5.12) has broken working custom provider configurations. This is not a one-off — it's a pattern that shows a fundamental disregard for config stability and backward compatibility.

I've been using the same custom provider config since 5.2. It has worked perfectly and stably. Then I upgrade to 5.12 and everything is broken again.

Current Breakage (5.12)

Problem 1: Tool schema change breaks custom providers

5.12 changelog says:

"Agents: add permissive items schemas to array tool parameters before provider submission, preventing OpenAI-compatible schema validation from rejecting plugin tools that omit items."

This "fix" introduced the exact problem it was supposed to prevent. My custom provider (token-plan-cn-xm with openai-completions API type) now returns:

400 Param Incorrect
providerRuntimeFailureKind: "schema"

The provider was working fine before 5.12. The new items schema you're injecting into tool parameters is being rejected by providers that don't expect it. You added a schema modification that breaks real-world providers while claiming it "prevents" schema rejections. Irony.

Problem 2: Auth system regression — "No API key found"

The fallback model (ollama) now fails with:

No API key found for provider "ollama". Auth store: .../auth-profiles.json

5.12 changelog says:

"resolve config-backed provider apiKey values only through structured env SecretRefs (secrets.providers[id] / secrets.defaults), so unrelated env vars cannot accidentally become provider credentials"

Translation: you changed how API keys are resolved, breaking existing auth configurations that were working. The apiKey field in openclaw.json is now apparently ignored in favor of a new SecretRef system that existing users don't have set up.

The cascade failure

Primary model (token-plan-cn-xm/mimo-v2.5-pro) → 400 schema rejection
  ↓ fallback
Secondary model (ollama/glm-4.7) → "No API key found" (auth regression)
  ↓
User sees: "⚠️ Missing API key for the selected provider"

The error message is misleading — it blames "missing API key" when the real problem is a schema compatibility issue in the primary model.

Historical Pattern

This is NOT an isolated incident. Every upgrade has broken something:

• 5.2: Removed stock qqbot plugin, broke all QQ Bot users. Required force-installing npm plugin.
• 5.7: Config file structure changes, providers silently lost.
• 5.12: Tool schema injection + auth key resolution change = complete breakage.

What OpenClaw Should Do

1. Config stability is NOT optional. The config file is the single most critical file for users. Every time you change how it's interpreted, you break every user's setup. Treat it like an API — backward compatible, versioned, with migration paths.

2. Stop injecting runtime changes that providers can't handle. Adding items schemas to tool payloads is a runtime behavior change that should be opt-in per provider, not forced globally.

3. Auth system changes need migration paths. If you change how API keys are resolved (from config apiKey field to SecretRefs), provide automatic migration. Don't silently break existing configs.

4. Test with real-world custom providers. Not just OpenAI, Anthropic, and Google. The whole point of openai-completions API type is to support third-party providers. Test your changes against them.

5. The error messages are misleading. "Missing API key" when the real problem is schema incompatibility wastes everyone's debugging time.

Environment

• OpenClaw: 2026.5.12 (f066dd2)
• Node: v22.17.1
• OS: Ubuntu (Linux)
• Provider: custom token-plan-cn-xm via openai-completions API type
• Working config since 5.2, broken on 5.12 upgrade