Model and Auth Profile FAQ: Defaults, Switching, Failover

Model and auth profile FAQ. For setup, sessions, gateway, channels, and troubleshooting, refer to the main FAQ.

Models: defaults, selection, aliases, switching

What is the "default model"?

Configure it with:

agents.defaults.model.primary

Models are provider/model refs (for instance, openai/gpt-5.5, anthropic/claude-sonnet-4-6). Make sure to set provider/model explicitly. When the provider is left out, OpenClaw tries an alias match first, then a unique configured-provider match for that model id, and finally the configured default provider (a deprecated compatibility path). If that provider no longer has the configured default model, OpenClaw uses the first configured provider/model rather than an outdated default.

What model do you recommend?

Pick the strongest latest-generation model your provider stack supports, particularly for tool-enabled or untrusted-input agents. Weaker or over-quantized models are more prone to prompt injection and unsafe behavior (see Security). Assign cheaper models to routine or low-stakes chat by agent role.

Assign models per agent and use sub-agents to parallelize long tasks (each sub-agent consumes its own tokens). See Models, Sub-agents, MiniMax, and Local models.

How do I switch models without wiping my config?

Only touch the model fields, avoid full config replaces.

• /model <model> -s in chat (current session only; see Slash commands)
• direct owner/admin /model <model> (current session plus a best-effort configured-default update request)
• openclaw models set ... (updates just model config)
• openclaw configure --section model (interactive)
• edit agents.defaults.model in ~/.openclaw/openclaw.json directly

For RPC edits, inspect with config.schema.lookup first (normalized path, shallow schema docs, child summaries), then prefer config.patch over config.apply with a partial object. If you did overwrite config, restore from backup or run openclaw doctor to repair.

Docs: Models, Configure, Config, Doctor.

Can I use self-hosted models (llama.cpp, vLLM, Ollama)?

Yes, Ollama is the simplest route. Quick setup:

1. Install Ollama from https://ollama.com/download
2. Pull a local model, e.g. ollama pull gemma4
3. For cloud models too, run ollama signin
4. Run openclaw onboard, choose Ollama, then Local or Cloud + Local

Cloud + Local provides cloud models plus your local Ollama models; cloud models such as kimi-k2.5:cloud require no local pull. To switch manually: openclaw models list, then openclaw models set ollama/<model>.

Smaller or heavily quantized models are more susceptible to prompt injection. Use large models for any bot with tool access; if you use small models anyway, enable sandboxing and strict tool allowlists.

Docs: Ollama, Local models, Model providers, Security, Sandboxing.

How do I switch models on the fly (without restarting)?

Send /model <name> -s as a standalone message for a temporary switch. A direct owner/admin /model <name> without -s also requests a best-effort configured-default update. See Slash commands for the full command list, including the numbered picker (/model, /model list, /model 3), /model default to clear a session model override, and /model status for endpoint/API-mode detail.

Force a specific auth profile per session with @profile:

/model opus@anthropic:default -s
/model opus@anthropic:work -s

A model selection without @profile leaves an existing compatible profile pin intact. To swap it out, choose a different explicit @profile suffix. The active auth profile can be checked with /model status. While /model default retains a compatible auth pin, it removes one that fails to match the configured default provider.

If two providers expose the same model id, which one does /model use?

/model provider/model picks that exact provider route. As an illustration, qianfan/deepseek-v4-flash and deepseek/deepseek-v4-flash are distinct refs even though the model id is the same, and OpenClaw never quietly changes providers based solely on a matching id.

A user-selected /model ref is strict when it comes to fallback: if that provider/model is unavailable, the reply fails visibly rather than reverting to agents.defaults.model.fallbacks. Configured fallback chains still apply to configured defaults, cron job primaries, and auto-selected fallback state. When a run without a session override is permitted to use fallback, OpenClaw attempts the requested provider/model first, followed by configured fallbacks, then the configured primary, so duplicate bare model ids never jump straight back to the default provider.

See Models and Model failover.

Can I use GPT 5.5 for daily tasks and Codex 5.5 for coding?

Indeed, model choice and runtime choice are independent:

• Native Codex coding agent: assign agents.defaults.model.primary the value openai/gpt-5.5. Sign in with openclaw models auth login --provider openai for ChatGPT/Codex subscription auth.
• Direct OpenAI API tasks outside the agent loop: set up OPENAI_API_KEY for images, embeddings, speech, realtime, and other non-agent OpenAI API surfaces.
• OpenAI agent API-key auth: use /model openai/gpt-5.5 with an ordered openai API-key profile.
• Sub-agents: direct coding tasks to a Codex-focused agent that has its own openai/gpt-5.5 model.

See Models and Slash commands.

How do I configure fast mode for GPT 5.5?

• Per session: send /fast on while openai/gpt-5.5 is in use.
• Per model default: configure agents.defaults.models["openai/gpt-5.5"].params.fastMode to true.
• Automatic cutoff: /fast auto or params.fastMode: "auto" runs new model calls fast until the cutoff, then later retry, fallback, tool-result, or continuation calls run without fast mode. The cutoff is 60 seconds by default; override it with params.fastAutoOnSeconds on the model.

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: {
            fastMode: "auto",
            fastAutoOnSeconds: 30,
          },
        },
      },
    },
  },
}

Fast mode maps to service_tier = "priority" on native OpenAI Responses requests; existing service_tier values are kept, and fast mode does not alter reasoning or text.verbosity. Session /fast overrides take precedence over config defaults.

See Thinking and fast mode and the Fast mode section under Advanced configuration on the OpenAI provider page.

Why do I see "Model ... is not allowed" and then no reply?

When agents.defaults.modelPolicy.allow is non-empty, it serves as the allowlist for /model, session overrides, and --model. Choosing a model outside that list yields this instead of a normal reply:

Model override "provider/model" is not allowed by agents.defaults.modelPolicy.allow.

Fix: add the exact model or a provider wildcard like "provider/*" to the named modelPolicy.allow list, clear or empty that list, or select a model from /model list. If the command also included --runtime codex, update the allowlist first, then rerun the same /model provider/model --runtime codex command.

Why do I see "Unknown model: minimax/MiniMax-M3"?

On an older OpenClaw release, upgrade first (or run from source main) and restart the gateway, since MiniMax-M3 may not yet be in your installed release's catalog. Otherwise the MiniMax provider is unconfigured (no provider entry or auth profile found), leaving the model unresolvable. See the Troubleshooting section on the MiniMax provider page for the complete fix checklist, provider/model id table, and config-block example.

Can I use MiniMax as my default and OpenAI for complex tasks?

Yes. Make MiniMax the default and switch models per session, since fallbacks handle errors, not "hard tasks", so use /model or a separate agent.

Option A: switch per session

{
  env: { vars: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." } },
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M3" },
      models: {
        "minimax/MiniMax-M3": { alias: "minimax" },
        "openai/gpt-5.5": { alias: "gpt" },
      },
    },
  },
}

Then /model gpt -s.

Option B: separate agents, where Agent A defaults to MiniMax and Agent B defaults to OpenAI; route by agent or use /agent to switch.

Docs: Models, Multi-Agent Routing, MiniMax, OpenAI.

Are opus / sonnet / gpt built-in shortcuts?

Yes, built-in shorthands, applied only when the target model exists in agents.defaults.models:

Your own alias with the same name overrides the built-in one.

How do I define/override model shortcuts (aliases)?

Aliases live at agents.defaults.models.<modelId>.alias:

{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
      },
    },
  },
}

Then /model sonnet -s resolves to that model id for the current session. Omit -s only when an owner/admin also wants to request a configured-default update.

How do I add models from other providers like OpenRouter or Z.AI?

OpenRouter (pay-per-token; many models):

{
  agents: {
    defaults: {
      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },
      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },
    },
  },
  env: { vars: { OPENROUTER_API_KEY: "sk-or-..." } },
}

Z.AI (GLM models):

{
  agents: {
    defaults: {
      model: { primary: "zai/glm-5.1" },
      models: { "zai/glm-5.1": {} },
    },
  },
  env: { vars: { ZAI_API_KEY: "..." } },
}

Missing provider key for a referenced provider/model raises a runtime auth error (e.g. No API key found for provider "zai").

No API key found for provider after adding a new agent

A new agent has an empty auth store, auth is per-agent, stored at:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Fix: run openclaw agents add <id> and configure auth in the wizard, or copy only portable static api_key/token profiles from the main agent's store. For OAuth, sign in from the new agent when it needs its own account. See Multi-Agent Routing for the full agentDir reuse and credential-sharing rules, never reuse agentDir across agents.

Model failover and "All models failed"

How does failover work?

Two stages:

1. Auth profile rotation within the same provider.
2. Model fallback to the next model in agents.defaults.model.fallbacks.

Cooldowns apply to failing profiles (exponential backoff), so OpenClaw keeps responding when a provider is rate-limited or temporarily failing.

The rate-limit bucket covers more than plain 429: Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, resource exhausted, and periodic usage-window limits (weekly/monthly limit reached) all count as failover-worthy rate limits.

Billing responses aren't always 402, and some 402s stay in the transient/rate-limit bucket rather than the billing lane. Explicit billing text on 401/403 can still route to billing; provider-specific text matchers (e.g. OpenRouter Key limit exceeded) stay scoped to their own provider. A 402 that reads like a retryable usage-window or org/workspace spend limit (daily limit reached, resets tomorrow, organization spending limit exceeded) is treated as rate_limit, not a long billing disable.

Context-overflow errors never touch the fallback path. Signatures such as request_too_large, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model, or ollama error: context length exceeded route to compaction or retry instead of triggering model fallback.

Generic server-error text is more limited than "anything containing unknown or error". Provider-specific transient shapes that do count as failover signals: Anthropic bare An unknown error occurred, OpenRouter bare Provider returned error, stop-reason errors like Unhandled stop reason: error, JSON api_error payloads with transient server text (internal server error, unknown error, 520, upstream error, backend error), and provider-busy errors like ModelNotReadyException when the provider context matches. Generic internal fallback text like LLM request failed with an unknown error. stays conservative and does not trigger fallback by itself.

What does "No credentials found for profile anthropic:default" mean?

The auth profile id anthropic:default has no credentials in the expected auth store.

Fix checklist:

• Verify where profiles reside, current: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json; legacy: ~/.openclaw/agent/* (migrated by openclaw doctor).
• Verify the Gateway loads your env var. ANTHROPIC_API_KEY set only in your shell won't reach a Gateway run via systemd/launchd, place it in ~/.openclaw/.env or enable env.shellEnv.
• Verify you're editing the correct agent, multi-agent setups have multiple auth-profiles.json files.
• Run openclaw models status to see configured models and provider auth state.

For "No credentials found for profile anthropic" (no email suffix):

The run is pinned to an Anthropic profile the Gateway can't find.

• Use Claude CLI: run openclaw models auth login --provider anthropic --method cli --set-default on the gateway host.

• Prefer an API key instead: put ANTHROPIC_API_KEY in ~/.openclaw/.env on the gateway host, then clear any pinned order that forces the missing profile:

  openclaw models auth order clear --provider anthropic
  

• Remote mode: auth profiles live on the gateway machine, not your laptop, confirm you're running commands there.

Why did it also try Google Gemini and fail?

If your model config includes Google Gemini as a fallback (or you switched to a Gemini shorthand), OpenClaw tries it during fallback. No Google credentials configured gives No API key found for provider "google". Fix: add Google auth, or remove Google models from agents.defaults.model.fallbacks/aliases.

LLM request rejected: thinking signature required (Google Antigravity)

Cause: session history has thinking blocks without signatures (often from an aborted/partial stream); Google Antigravity requires signatures on thinking blocks. OpenClaw strips unsigned thinking blocks for Google Antigravity Claude; if it still appears, start a new session or set /thinking off for that agent.

Auth profiles: what they are and how to manage them

Related: /concepts/oauth (OAuth flows, token storage, multi-account patterns)

What is an auth profile?

A named credential record (OAuth or API key) tied to a provider, stored at:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Inspect saved profiles without dumping secrets: openclaw models auth list (optionally --provider <id> or --json). See Models CLI.

What are typical profile IDs?

Provider-prefixed: anthropic:default (common when no email identity exists), anthropic:<email> for OAuth identities, or a custom id you choose (e.g. anthropic:work).

Can I control which auth profile is tried first?

Yes. auth.order.<provider> config sets rotation order per provider (metadata only, no secrets stored).

OpenClaw may skip a profile in a short cooldown (rate limits, timeouts, auth failures) or a longer disabled state (billing/insufficient credits). Inspect with openclaw models status --json and check auth.unusableProfiles. Rate-limit cooldowns can be model-scoped, a profile cooling down for one model can still serve a sibling model on the same provider; billing/disabled windows block the whole profile.

Set a per-agent order override (stored in that agent's auth-state.json):

# Defaults to the configured default agent (omit --agent)
openclaw models auth order get --provider anthropic

# Lock rotation to a single profile
openclaw models auth order set --provider anthropic anthropic:default

# Or set an explicit order (fallback within provider)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# Clear override (fall back to config auth.order / round-robin)
openclaw models auth order clear --provider anthropic

# Target a specific agent
openclaw models auth order set --provider anthropic --agent main anthropic:default

Verify what will actually be tried: openclaw models status --probe. A stored profile omitted from an explicit order reports excluded_by_auth_order instead of being tried silently.

OAuth vs API key - what is the difference?

• OAuth / CLI login often uses subscription access where the provider supports it. For Anthropic, OpenClaw's Claude CLI backend uses Claude Code claude -p, which Anthropic currently treats as Agent SDK/programmatic usage drawing from subscription usage limits, see Anthropic for the current billing-pause status and source links.
• API keys use pay-per-token billing.

The wizard supports Anthropic Claude CLI, OpenAI Codex OAuth, and API keys.

Related

• FAQ: the primary FAQ page
• Quick start and first-run setup FAQ
• Choosing a model
• Handling model failover