title: "models.providers.<id>.api enum mismatch crashes gateway on startup — no recovery without manual config edit" labels: bug

Summary

When the models.providers.<id>.api enum values are refined across versions (or when a provider is configured with a value that is later removed from the enum), the gateway enters a crash loop on startup. doctor --fix reinstalls the systemd unit but does not migrate or warn about stale enum values in the config file, leaving the gateway completely down until the user manually edits openclaw.json.

Context

OpenRouter (and similar OpenAI-compatible proxies) use https://openrouter.ai/api/v1/chat/completions, which is an OpenAI Chat Completions-compatible endpoint. It is intuitive — and was apparently valid at some point — to configure api: "openai" for such providers. After the api enum was refined into openai-completions / openai-responses / openai-codex-responses, the bare "openai" value became invalid, causing the following failure:

Invalid config:
- models.providers.openrouter.api: Invalid option:
  expected one of "openai-completions"|"openai-responses"|"openai-codex-responses"
  |"anthropic-messages"|"google-generative-ai"|"github-copilot"
  |"bedrock-converse-stream"|"ollama"|"azure-openai-responses"

Note: I was not able to determine the exact version where "openai" was a valid api value. It may have been valid in an earlier release, or it may have been set by the onboarding flow / user intuition. Either way, the resilience problem is the same — see proposals below.

Reproduction

1. Have openclaw.json with models.providers.openrouter.api = "openai"
2. Upgrade openclaw to a version where the enum no longer includes "openai"
3. systemctl --user restart openclaw-gateway.service
4. Gateway crashes on every start with Invalid config → Main process exited, code=exited, status=1/FAILURE → restart loop

Impact

• Gateway completely down until manual config edit
• doctor --fix does not resolve (it fixes the unit, not the config value)
• No degradation path — a single stale enum value kills the entire service
• A user encountering this after an upgrade has no guided path to recovery

Root Cause (Codebase Verification)

Verified against v2026.4.24:

1. The api enum is defined in runtime-schema as:

   "openai-completions", "openai-responses", "openai-codex-responses",
   "anthropic-messages", "google-generative-ai", "github-copilot",
   "bedrock-converse-stream", "ollama", "azure-openai-responses"

2. Fatal abort on validation error: lifecycle-core calls getConfigValidationError() on both start and restart. Any config error (including enum mismatch) triggers fail(), aborting the gateway entirely.

3. No migration for api enum: doctor --fix has a legacyConfigRules + normalizeCompatibilityConfig framework that migrates other stale config keys (e.g., threadBindings.ttlHours→idleHours, sandbox.perSession→scope), but has no rule for models.providers.<id>.api.

Proposed Fix (two parts)

1. doctor --fix should auto-migrate stale api enum values

The existing legacyConfigRules framework can accommodate a new migration rule. Suggested mapping:

Caveat: Users targeting OpenAI's Responses API or Codex API would need "openai-responses" or "openai-codex-responses" respectively. The migration could emit a warning when replacing "openai", prompting the user to verify the correct adapter if they need a non-default variant.

If no deterministic mapping exists, fall back to a warning + prompt.

2. Invalid provider api should be a warning, not a fatal error — scoped narrowly

Proposed scope: Only downgrade models.providers.<id>.api enum mismatches from fatal to warning. Other validation errors (missing required fields, type mismatches) would remain fatal.

The affected provider would be excluded from the provider registry at runtime (treated as if absent), with a warning logged. This preserves the existing safety model for genuine misconfigurations while handling upgrade-artifact enum drift gracefully.

Current behavior (lifecycle-core):

const configError = await getConfigValidationError();
if (configError) {
  fail(`config is invalid.\n${configError}\nFix the config and retry, or run "openclaw doctor" to repair.`);
  return;
}

Open Questions

• Was "openai" ever a valid api value? I couldn't verify this from the current codebase alone. If it was never valid, this shifts from a "regression" to a "usability/resilience" issue — but the impact is the same either way.
• Should other enum mismatches also be non-fatal? I've scoped this proposal narrowly to api only, but there may be other enum fields where the same resilience argument applies.
• What's the full list of stale values that need migration? Only "openai" → "openai-completions" is known; there may be others from older versions.

Environment

• OpenClaw version: 2026.4.24
• OS: WSL2 (Ubuntu)
• Install method: npm global