FAQ: Models and Auth Profiles for OpenClaw

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

Models: defaults, selection, aliases, switching

What is the "default model"?

Configure with:

agents.defaults.model.primary

Models point to provider/model references (for instance, openai/gpt-5.5 or anthropic/claude-sonnet-4-6). Always specify provider/model explicitly. When the provider is omitted, OpenClaw first attempts an alias lookup, then tries a unique configured provider matching that model id, and finally resorts to the configured default provider (a deprecated fallback). If that provider no longer serves the configured default model, OpenClaw defaults to the first configured provider/model instead of an outdated default.

What model do you recommend?

Choose the most capable latest generation model your provider stack supports, particularly for agents that use tools or handle untrusted input. Weaker or heavily quantized models are more susceptible to prompt injection and unsafe behavior (see Security). Assign less expensive models to routine or low risk chat by agent role.

Assign models per agent and use sub-agents to parallelize lengthy 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?

Modify only the model fields, avoid replacing the entire config.

• /model in chat (per session, see Slash commands)
• openclaw models set ... (updates model config only)
• openclaw configure --section model (interactive)
• edit agents.defaults.model inside ~/.openclaw/openclaw.json directly

For RPC edits, first inspect with config.schema.lookup (normalized path, shallow schema docs, child summaries), then prefer config.patch over config.apply with a partial object. If you overwrote 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 offers the simplest route. Quick setup:

1. Install Ollama from https://ollama.com/download
2. Pull a local model, for example ollama pull gemma4
3. For cloud models as well, run ollama signin
4. Run openclaw onboard, select Ollama, then Local or Cloud + Local

Cloud + Local provides cloud models together with your local Ollama models; cloud models like kimi-k2.5:cloud do not require a local pull. To switch manually: openclaw models list, then openclaw models set ollama/<model>.

Smaller or heavily quantized models are more prone to prompt injection. Use large models for any bot with tool access; if you still use small models, 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> as a standalone message. See Slash commands for the complete command list, including the numbered picker (/model, /model list, /model 3), /model default to clear a session override, and /model status for endpoint or API mode details.

Force a specific auth profile per session using @profile:

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

To remove a pinned profile that was set using @profile, execute /model again without the suffix (for example, /model anthropic/claude-opus-4-6), or choose the default option from /model. Use /model status to verify which auth profile is currently active.

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

/model provider/model targets a specific provider route. For instance, qianfan/deepseek-v4-flash and deepseek/deepseek-v4-flash point to different references even when the model ID is identical, OpenClaw does not automatically change providers based on a matching bare ID.

When a user selects a /model reference, it enforces strict fallback behavior: if that provider or model becomes inaccessible, the request fails with an error rather than reverting to agents.defaults.model.fallbacks. Configured fallback chains still apply to system defaults, scheduled job primaries, and automatically selected fallback states. For runs that are not session overrides and are permitted to use fallback, OpenClaw attempts the requested provider and model first, then any configured fallbacks, followed by the configured primary, so duplicate bare model IDs never skip directly back to the default provider.

Refer to Models and Model failover.

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

Yes, model selection and runtime selection operate independently:

• Native Codex coding agent: assign agents.defaults.model.primary the value openai/gpt-5.5. Authenticate using openclaw models auth login --provider openai for ChatGPT or Codex subscription credentials.
• Direct OpenAI API tasks outside the agent loop: set up OPENAI_API_KEY for images, embeddings, speech, realtime, and other non-agent OpenAI API endpoints.
• OpenAI agent API-key authentication: use /model openai/gpt-5.5 with an ordered openai API-key profile.
• Sub-agents: direct coding tasks to a Codex-focused agent that uses 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 working with openai/gpt-5.5.
• 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 quickly until the cutoff point, then processes later retries, fallbacks, tool results, or continuation calls without fast mode. The cutoff defaults to 60 seconds; 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 preserved, and fast mode does not modify reasoning or text.verbosity. Session-level /fast overrides take precedence over configuration 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 contains a value, it functions as the allowlist for /model, session overrides, and --model. Selecting a model not on that list produces this response instead of a standard reply:

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

To fix this, add the exact model or a provider wildcard like "provider/*" to the named modelPolicy.allow list, remove or clear that list, or choose a model from /model list. If the command also included --runtime codex, update the allowlist first, then reissue the same /model provider/model --runtime codex command.

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

If you are using an older OpenClaw release, upgrade first (or run from source main) and restart the gateway, MiniMax-M3 may not yet appear in your installed release's catalog. Otherwise, the MiniMax provider is not set up (no provider entry or auth profile found), so the model cannot be resolved. Check the Troubleshooting section on the MiniMax provider page for the complete fix checklist, provider and model ID table, and configuration block example.

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

Yes. Set MiniMax as the default and change models per session, fallbacks handle errors, not "hard tasks", so use /model or a separate agent instead.

Option A: switch per session

{
  env: { 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.

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

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

Are opus / sonnet / gpt built-in shortcuts?

Yes, there are built-in aliases that only apply when the target model is present in agents.defaults.models:

If you create a custom alias with an identical name, it overrides the default.

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

Aliases are stored 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" },
      },
    },
  },
}

After that, /model sonnet (or /<alias> where supported) maps to that model ID.

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

OpenRouter (pay-per-token, wide model selection):

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

Z.AI (GLM models):

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

Referencing a provider or model without a corresponding key triggers a runtime authentication error, for instance No API key found for provider "zai".

No API key found for provider after adding a new agent

A freshly created agent starts with an empty authentication store. Auth is per-agent and lives at:

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

To fix this, run openclaw agents add <id> and set up authentication through the wizard, or copy only portable static api_key/token profiles from the original agent's store. For OAuth, sign in from the new agent when it requires its own account. See Multi-Agent Routing for the complete agentDir reuse and credential-sharing rules. Never reuse agentDir across agents.

Model failover and "All models failed"

How does failover work?

Two phases:

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

Failing profiles are subject to cooldowns using exponential backoff, so OpenClaw continues responding even when a provider is rate-limited or experiencing temporary failures.

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

Billing responses are not always 402, and some 402s remain in the transient or rate-limit category rather than the billing lane. Explicit billing text on 401/403 can still be directed to billing. Provider-specific text matchers, such as OpenRouter Key limit exceeded, stay limited to their own provider. A 402 that resembles a retryable usage-window or org/workspace spend limit (daily limit reached, resets tomorrow, organization spending limit exceeded) is handled as rate_limit, not a permanent billing disable.

Context overflow errors are completely excluded from 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 are routed to compaction or retry rather than triggering model fallback.

Generic server error text is more specific than "anything containing unknown or error". Provider specific transient shapes that do qualify as failover signals include: Anthropic bare An unknown error occurred, OpenRouter bare Provider returned error, stop reason errors like Unhandled stop reason: error, JSON api_error payloads carrying transient server text (internal server error, unknown error, 520, upstream error, backend error), and provider busy errors such as ModelNotReadyException when the provider context matches. Generic internal fallback text like LLM request failed with an unknown error. remains cautious and does not independently activate fallback.

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

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

Fix checklist:

• Verify where profiles are stored: current location is ~/.openclaw/agents/<agentId>/agent/auth-profiles.json; legacy location is ~/.openclaw/agent/* (migrated via openclaw doctor).
• Ensure the Gateway loads your environment variable. Setting ANTHROPIC_API_KEY only in your shell will not reach a Gateway running under systemd or launchd. Place it in ~/.openclaw/.env or enable env.shellEnv.
• Confirm you are editing the correct agent. Multi agent setups contain multiple auth-profiles.json files.
• Execute openclaw models status to view configured models and provider authentication status.

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

The run is tied to an Anthropic profile that the Gateway cannot locate.

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

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

  openclaw models auth order clear --provider anthropic
  

• Remote mode: auth profiles reside on the gateway machine, not your laptop. Confirm you are executing commands there.

Why did it also try Google Gemini and fail?

If your model configuration includes Google Gemini as a fallback (or you have switched to a Gemini shorthand), OpenClaw attempts it during fallback. Without Google credentials configured, you get No API key found for provider "google". To fix this, add Google authentication or remove Google models from agents.defaults.model.fallbacks or aliases.

LLM request rejected: thinking signature required (Google Antigravity)

Cause: the session history contains thinking blocks that lack signatures, often from an aborted or partial stream. Google Antigravity requires signatures on thinking blocks. OpenClaw removes unsigned thinking blocks for Google Antigravity Claude. If the error persists, 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) associated with a provider, stored at:

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

Inspect saved profiles without exposing 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. The auth.order.<provider> configuration sets rotation order per provider (metadata only, no secrets stored).

OpenClaw may skip a profile during a short cooldown (rate limits, timeouts, auth failures) or a longer disabled state (billing or 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 or disabled windows block the entire 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 attempted: 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 typically 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 or 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
• FAQ, initial setup and first run
• Choosing a model
• Model fallback behavior