Manage OpenClaw Auth Profiles: Configure API Keys & OAuth

Managing multiple API keys and login methods across different projects is often a headache. It gets messy fast when you are switching between personal and work accounts or trying to keep track of which credential has enough credits left to finish a task.

Understanding how OpenClaw handles these credentials through auth profiles makes your life much easier. Here is a breakdown of how it works and how you can stay in control.

What is an auth profile?

An auth profile is a named credential record tied to a provider. It can be an OAuth token or an API key. These profiles are stored locally on your machine in a specific JSON file:

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

What are typical profile IDs?

OpenClaw uses IDs that start with the provider name to keep things organized. You will usually see IDs like:

• anthropic:default (this is common when no email identity exists)
• anthropic:<email> for OAuth identities
• Custom IDs you choose yourself (like anthropic:work)

Can I control which auth profile is tried first?

You can control this through your configuration. OpenClaw supports an ordering system per provider using auth.order.<provider>.

Sometimes, OpenClaw might skip a profile. This happens if a profile is in a short cooldown due to rate limits or auth failures, or if it is disabled because of billing issues. To see which profiles are currently out of rotation, run openclaw models status --json and check the auth.unusableProfiles field.

Set a per-agent order:

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

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

# Clear override
openclaw models auth order clear --provider anthropic

OAuth vs API key—what’s the difference?

OpenClaw supports both methods, and the choice usually depends on how you want to be billed:

• OAuth often lets you use your existing subscription access.
• API keys typically follow a pay-per-token billing model.

The setup wizard has built-in support for Anthropic setup-tokens and OpenAI Codex OAuth, and it can securely store your API keys for you.

---

Next steps

• Check your current profile status with openclaw models status
• Learn more about provider-specific configurations

Need help setting up your credentials? Check out the AI Setup Assistant.