Model Providers & Auth Profiles

+15 Mana ✨
OpenClaw Auth Profiles(DOCUMENTATION)

Introduction

OpenClaw supports multiple AI model providers including Anthropic, OpenAI, Bedrock, OpenRouter, Gemini, Moonshot, and Qianfan. Each provider requires authentication credentials stored as auth profiles. This lesson explains how to configure providers, manage API keys and OAuth tokens, and how OpenClaw selects which profile to use.

Key Concepts

  • Model Provider: A service that hosts and serves AI models, such as Anthropic (Claude) or OpenAI (GPT).
  • Auth Profile: A stored credential set for a specific provider, located at ~/.openclaw/agents/<agentId>/agent/auth-profiles.json.
  • API Key Credential: A simple key-based authentication format containing a provider name and a key string.
  • OAuth Token Credential: A token-based authentication format containing a provider, access token, refresh token, and expiration timestamp.
  • Profile Selection Order: The priority chain OpenClaw follows when choosing which auth profile to use.

Real World Context

A development team might have multiple Anthropic API keys — one for each team member's account — and a shared OAuth token from their organization's SSO. OpenClaw's auth profile system lets you store all of these credentials and intelligently rotate between them. If one key hits a rate limit, the system automatically switches to another. OAuth tokens are preferred because they can be refreshed automatically without manual intervention.

Deep Dive

Auth profiles are stored per agent in a JSON file. Here is the structure of auth-profiles.json:

json
{
  "profiles": [
    {
      "id": "team-api-key",
      "type": "api-key",
      "provider": "anthropic",
      "key": "sk-ant-xxxxxxxxxxxxx"
    },
    {
      "id": "org-oauth",
      "type": "oauth",
      "provider": "anthropic",
      "accessToken": "eyJhbGciOiJSUzI1NiIs...",
      "refreshToken": "dGhpcyBpcyBhIHJlZnJl...",
      "expiresAt": "2026-03-01T00:00:00Z"
    },
    {
      "id": "openai-backup",
      "type": "api-key",
      "provider": "openai",
      "key": "sk-xxxxxxxxxxxxxxxx"
    }
  ]
}

The file above contains three auth profiles. The first is an API key credential for Anthropic, identified by the api-key type. It stores the provider name and the raw API key. The second is an OAuth credential for the same provider, containing an access token, a refresh token for automatic renewal, and an expiration timestamp. The third is an API key for a different provider, OpenAI, which could serve as an alternative if Anthropic is unavailable.

OpenClaw follows a specific priority chain when selecting which auth profile to use for a request. The selection order is:

  1. Explicit config: If the agent configuration directly specifies a profile ID, that profile is used.
  2. Configured profiles: Profiles listed in the agent's own configuration file are tried next.
  3. Stored profiles: Any profiles found in the auth-profiles.json file are considered.
  4. Round-robin: If multiple profiles are available at the same priority level, OpenClaw rotates between them, preferring OAuth tokens first, then using least-recently-used (LRU) ordering for API keys.

This selection logic is critical to understand. The round-robin behavior with OAuth preference means the system will always try to use refreshable tokens before consuming API key quota. The LRU strategy for API keys distributes load evenly across all available keys.

Here is how you would configure an agent to explicitly use a specific auth profile:

json
{
  "agentId": "code-reviewer",
  "model": {
    "primary": "anthropic:claude-sonnet-4-20250514",
    "authProfile": "org-oauth"
  }
}

By setting the authProfile field, you bypass the selection chain entirely and always use the specified profile. This is useful when you need guaranteed use of a specific set of credentials, such as an organization's OAuth token for billing purposes.

The supported providers span a wide range of services. Anthropic and OpenAI are the most commonly used, but Bedrock provides AWS-integrated access, OpenRouter offers a unified API across multiple providers, and Gemini gives access to Google's models. Moonshot and Qianfan serve the Chinese market with locally optimized models.

Common Pitfalls

  • Storing credentials in version control: Auth profiles contain sensitive keys and tokens. Never commit auth-profiles.json to a repository.
  • Ignoring OAuth token expiration: If you do not monitor expiresAt, your OAuth tokens may expire silently, causing the agent to fall back to API keys unexpectedly.
  • Mixing providers in a single agent without fallbacks: If your agent is configured for Anthropic but only has OpenAI credentials, it will fail at auth before even trying the model.

Best Practices

  • Prefer OAuth tokens over API keys: OAuth tokens can be refreshed automatically and provide better auditability.
  • Set up multiple profiles per provider: Having at least two credentials per provider ensures continuity if one is rate-limited or revoked.
  • Use explicit auth profile references for production agents: Do not rely on round-robin selection for critical agents. Pin them to a known-good credential.

Summary

  • OpenClaw supports seven model providers: Anthropic, OpenAI, Bedrock, OpenRouter, Gemini, Moonshot, and Qianfan.
  • Auth profiles store either API key credentials or OAuth token credentials in auth-profiles.json.
  • Profile selection follows a priority chain: explicit config, configured profiles, stored profiles, then round-robin.
  • Round-robin selection prefers OAuth tokens over API keys and uses LRU ordering.
  • Always prefer OAuth tokens for production use due to automatic refresh capabilities.
✓ Completed