Models & Providers

Configure OpenClaw model providers, provider-qualified model refs, OAuth and API credentials, fallbacks, usage reporting, and SecretRef-backed auth.

OpenClaw separates the agent runtime from the model provider. One Gateway can use different providers for different agents, tasks, or fallbacks.

Model References

Model refs are usually provider-qualified:

anthropic/claude-opus-4-6
openai/gpt-5
openrouter/moonshotai/kimi-k2
ollama/llama3

Provider-qualified names make routing explicit and reduce ambiguity when several providers expose similarly named models.

Credential Paths

OpenClaw supports multiple credential patterns:

• API keys
• OAuth or subscription-backed profiles where supported
• provider-specific auth profiles
• SecretRefs that point to env vars, files, or commands
• managed plugin/provider auth

Prefer SecretRefs or auth profiles over inline secrets in config files.

openclaw secrets audit
openclaw models status
openclaw models list

Per-Agent Models

Different agents can use different models:

{
  "agents": {
    "list": [
      { "id": "main", "model": "anthropic/claude-opus-4-6" },
      { "id": "quick", "model": "openai/gpt-5-mini" },
      { "id": "local", "model": "ollama/llama3" }
    ]
  }
}

Choose models by task:

• strong reasoning for planning, coding, and recovery
• cheaper models for simple classification
• local models for private or low-stakes work
• provider-backed media models for image, audio, or video tasks

Fallbacks and Routing

Fallbacks are useful when a provider is rate-limited, temporarily down, or missing a capability. They should be explicit and tested.

Good fallback practice:

1. Keep provider IDs normalized.
2. Avoid mixing incompatible tool schemas blindly.
3. Test replay behavior for tool-heavy sessions.
4. Confirm credentials are profile-aware.
5. Watch usage and cost after fallback changes.

Recent OpenClaw releases improved safer model routing, managed SecretRef auth, bounded model browsing, and recovery around provider-specific tool schema issues.

Usage Reporting

Use usage output to understand token and cost behavior:

openclaw status --usage
openclaw sessions list --usage

Slash commands can also control usage detail in chat:

/usage tokens
/usage full
/usage off

Usage numbers depend on provider support and freshness. Treat provider dashboards as the billing source of truth.

Local Models

Local models are useful for private or low-cost tasks:

ollama pull llama3
openclaw models list

Local models may not support every tool shape, context size, or media capability. Keep prompts and expectations small unless you have benchmarked the model.

Provider Selection Checklist

• Does the provider support the tool schema OpenClaw needs?
• Does it support the required context window?
• Are credentials scoped to the correct agent?
• Is there a fallback?
• Can you see usage?
• Are media or web-grounded tools provider-specific?
• Is the provider appropriate for sensitive data?