OpenClaw Model Providers Guide

Model references use the form provider/model. Adding credentials makes a provider available; it does not automatically change the primary model unless the setup flow explicitly does so.

Inspect the active route

openclaw models status
openclaw models list
openclaw config get agents.defaults.model

Record where each credential comes from. A key stored in OpenClaw configuration behaves differently from a key supplied by the Gateway service environment, especially after a shell-only change or service restart.

Test before selecting

The Control UI Model Providers page can run a real provider probe and categorize authentication, rate-limit, billing, timeout, and response errors. A probe may consume a small number of tokens.

After the connection succeeds, set the chosen model with the current CLI syntax shown by:

openclaw models set --help

Then verify the resolved primary route again. Keep the exact provider prefix; two providers can expose models with similar display names.

Protect credentials

Do not paste keys into public config checkers, screenshots, or issue reports. Prefer the provider’s supported secret or authentication profile. Restart the managed Gateway when you change an environment-provided credential so the service receives the new value.

Expected result

• The provider appears in model status.
• A live connection probe succeeds.
• The primary model resolves to the expected provider/model reference.
• A new direct chat uses that route.

If the provider is healthy but an older agent still fails, check for an agent-specific auth profile or model override. Use Model failover only after the primary route works by itself.