agents.list[].fallback unknown config key

[marble lynx]

I am trying to setup modles to fall back on when an error occurs in the primary model. After the gateway restart I am getting unknown config keys for both agents.list[2].fallback and agents.list[2].models

[steady quest]

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

[marble lynx]

I am on version 2026.2.17

[tardy gate]

Those keys don’t exist in the config schema, and OpenClaw is strict about validation (unknown keys will stop the Gateway from booting).

What you want is:

• Per-agent model selection: agents.list[2].model
• Fallback list: model.fallbacks (plural) inside model
• Model “catalog” / allowlist for /model: agents.defaults.models (not agents.list[].models)

Example:

{
  agents: {
    defaults: {
      // this is the global model catalog + /model allowlist
      models: {

        "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
        "openai/gpt-5.2": { alias: "gpt" },
      },
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
    },

    list: [
      // ...
      {
        id: "your-agent",
        // per-agent override (string = primary only, object = primary+fallbacks)
        model: {

          primary: "anthropic/claude-opus-4-6",
          fallbacks: ["openai/gpt-5.2"],
        },
      },
    ],
  },
}

Quick next steps:

1. Run openclaw --version (schema changes over time; good to confirm)
2. Run openclaw doctor — it’ll print the exact “unknown key” paths so you can fix them quickly.

Docs:

• Config reference (agents.defaults.model + fallbacks): https://docs.openclaw.ai/gateway/configuration-reference
• Failover behavior (auth rotation, then model fallbacks): https://docs.openclaw.ai/concepts/model-failover

On 2026.2.17 those two keys are definitely invalid:

• agents.list[2].fallback → not a thing
• agents.list[2].models → not a thing

What to use instead (per-agent fallback)

Fallbacks live under the agent’s model object:

{
  agents: {
    list: [
      // ...
      {
        id: "your-agent",
        model: {

          primary: "anthropic/claude-sonnet-4-5",
          fallbacks: ["openai/gpt-5.2"],
        },
      },
    ],
  },
}

(Also valid: model: "anthropic/claude-sonnet-4-5" if you only want a primary.)

Where the “models list” goes

The model catalog / /model allowlist is global at:

• agents.defaults.models ✅

Example:

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
        "openai/gpt-5.2": { alias: "gpt" },
      },
    },
  },
}

There isn’t a per-agent agents.list[].models field in the schema (so putting it there will stop the Gateway from starting).