openclaw - 💡(How to fix) Fix `agents.defaults.agentRuntime` silently ignored after update — Claude CLI agents surface misleading "API key has run out of credits" error instead of a runtime-fallback warning

Summary

After updating to OpenClaw 2026.5.12, agents configured with agents.defaults.agentRuntime: { id: "claude-cli" } stop working. The user-visible error is:

API provider returned a billing error — your API key has run out of credits or has an insufficient balance. Check your provider's billing dashboard and top up.

This is misleading. There is no billing problem. The legacy key agents.defaults.agentRuntime is silently dropped during config load; the runtime falls back to pi (label: OpenClaw Pi Default), which requires a direct Anthropic API key that subscription / OAuth users do not have. The resulting auth failure surfaces as a "credits" error from the provider plugin.

openclaw status confirms the wrong runtime:

"model": "claude-opus-4-7",
"runtime": "OpenClaw Pi Default"

The deprecation is visible only via openclaw doctor — there is no startup warning, no migration prompt during update, and no error at the point where the config key is dropped.

Environment

• OpenClaw 2026.5.12 (f066dd2)
• Runtime: claude-cli (Claude Code subscription, OAuth)
• Node v22.22.2
• OS: Ubuntu 24.04.1, kernel 6.17.0-29-generic
• Config path: ~/.openclaw/openclaw.json

Minimal reproduction

1. Start with a working pre-deprecation config that relies on agents.defaults.agentRuntime:

   {
     "agents": {
       "defaults": {
         "models": {
           "anthropic/claude-opus-4-7": {}
         },
         "model": { "primary": "anthropic/claude-opus-4-7" },
         "agentRuntime": { "id": "claude-cli" }
       }
     }
   }

2. Update OpenClaw to 2026.5.12.

3. Send a message to any bound agent. The turn fails with:

   API provider returned a billing error — your API key has run out of credits or has an insufficient balance. Check your provider's billing dashboard and top up.

4. openclaw status shows:

   "model": "claude-opus-4-7",
   "runtime": "OpenClaw Pi Default"

5. openclaw doctor is the only place the actual cause is reported:

   ◇  Legacy config keys detected
   │
   │  - agents.defaults.agentRuntime: agents.defaults.agentRuntime is
   │    ignored; set models.providers.<provider>.agentRuntime or a
   │    model-scoped agentRuntime instead. Run "openclaw doctor --fix".

Expected vs actual

Expected: Either (a) the legacy key continues to be honored with a deprecation warning at every config load (CLI invocation, gateway boot), or (b) the update process auto-migrates the key and notifies the user. In either case, the user-visible error must point at the real cause (missing runtime / no auth profile), not at provider billing.

Actual: The legacy key is silently dropped during config load. The runtime falls back to pi (OpenClaw Pi Default), which expects an Anthropic API key that subscription / OAuth users do not have. The auth failure is forwarded from the provider plugin as a "credits" error. No deprecation warning, no migration, no gateway-start error — only openclaw doctor flags it.

Impact

• Every Claude Code subscription / OAuth user with the legacy key loses all agents on update, with no log or UI explanation that points at the real cause.
• The "billing error" message sends users to the wrong place (Anthropic billing dashboard) and delays root-cause discovery by hours.
• Multi-bot deployments (e.g., several Telegram accounts bound to the same defaults) break simultaneously, amplifying the operator impact.
• Recovery requires reading source or running openclaw doctor, neither of which is part of a normal update flow.

Suggestions

• Emit the deprecation warning at every config load (every CLI invocation and every gateway start), not only on explicit doctor.
• Auto-migrate the legacy key on first load and persist the new shape, with a one-line notice.
• When the active runtime has no auth profile, surface the actual error (e.g. runtime "pi" has no Anthropic API key configured; did you mean to use "claude-cli"?) instead of forwarding the provider's billing message.
• Treat "config key dropped → runtime fell back to a different provider that cannot authenticate" as an error worth raising at gateway start, not at first message.

Workaround

Set agentRuntime explicitly inside each model entry under agents.defaults.models:

"agents": {
  "defaults": {
    "models": {
      "anthropic/claude-opus-4-7": {
        "agentRuntime": { "id": "claude-cli" }
      }
    }
  }
}

Then restart the gateway:

openclaw gateway restart

Discovery context

Encountered in a multi-Telegram-bot deployment after updating OpenClaw. Symptom presented as "all bots stopped responding after update" with the misleading billing error above. Root cause located by comparing openclaw status output (runtime: OpenClaw Pi Default) against prior backups of openclaw.json and finally confirmed by openclaw doctor.