Failing to switch over to a backup model

[hexed saffron]

I've setup a backup model in the model config to allow a failover between a codex based model and a local model. It's not working, what's the right way to think about this and what should I check in the config?

[silk marlin]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[spare lance]

Ed, first quick check: what does openclaw --version show? Version matters a lot for model fallback behavior.

Mental model: model fallback is not runtime fallback.

For normal model failover, think:

1. OpenClaw starts with agents.defaults.model.primary
2. It rotates auth profiles inside that provider first
3. Only on failover-worthy errors — auth/rate-limit/timeout/billing/overload — it moves to agents.defaults.model.fallbacks
4. Explicit user-selected models via /model, model picker, or session patch are strict and won’t silently fall back
5. Existing sessions can be pinned, so use /new or /reset after config changes

The biggest Codex gotcha:

• openai-codex/<model> = Codex OAuth/subscription provider through normal OpenClaw/PI runner. This can participate in normal model fallback.
• openai/<model> + agentRuntime.id: "codex" = native Codex app-server runtime. That is a different layer; harness/runtime failures generally surface directly and are not the same as “try local model next.”

So for “Codex-ish primary → local fallback”, the safer config shape is usually:

{
  agents: {
    defaults: {
      model: {
        primary: "openai-codex/gpt-5.5",
        fallbacks: ["ollama/your-local-model"]
      },
      models: {
        "openai-codex/gpt-5.5": {},
        "ollama/your-local-model": {}
      },
      agentRuntime: { id: "pi" }
    }

  }
}

If you’re using a local OpenAI-compatible server, also check:

{
  models: {
    mode: "merge",
    providers: {
      local: {
        baseUrl: "http://127.0.0.1:8000/v1",
        apiKey: "sk-local",
        api: "openai-completions",

        timeoutSeconds: 300,
        models: [
          {
            id: "your-local-model",
            name: "Your Local Model",
            input: ["text"],
            contextWindow: 120000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

Checklist I’d run:

openclaw --version
openclaw status --all
openclaw models status
openclaw config get agents.defaults.model
openclaw config get agents.defaults.models
openclaw config get agents.defaults.agentRuntime
openclaw config get models.mode

Then verify the local model directly:

openclaw infer model run \