# How to Switch Between OpenClaude Provider Profiles: 3 Methods Explained

> Learn how to switch OpenClaude provider profiles easily. Discover 3 methods to manage API credentials and endpoint configurations for your sessions. Get started now.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: how-to-guide
- Published: 2026-09-06

---

**OpenClaude stores API credentials and endpoint configurations in JSON-based provider profiles at `~/.openclaude/profile.json`, and switches between them using `applySavedProfileToCurrentSession`, which merges the profile's environment variables, API keys, and default model into the current session.**

OpenClaude (Gitlawb/openclaude) manages multiple AI provider configurations through persistent *provider profiles*. Each profile encapsulates provider-specific settings, allowing you to switch between OpenClaude provider profiles seamlessly during an active CLI session without restarting the application.

## Where Provider Profiles Are Stored

OpenClaude persists profile data on disk using a standard JSON structure.

- **Storage Location**: `~/.openclaude/profile.json`
- **Core Loader**: The `loadProfileFile` function in [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts) reads this file at startup and returns a `ProviderProfile` object.
- **Session Integration**: When activated, profile data is merged into the running session's environment, overriding previous provider settings.

## Method 1: Switch Using the Interactive /provider Command

The primary interface for switching profiles is the `ProviderManager` UI, invoked via the `/provider` command defined in [`src/commands/provider/provider.tsx`](https://github.com/Gitlawb/openclaude/blob/main/src/commands/provider/provider.tsx).

When you activate a profile through this interface:

1. The UI calls `applySharedProfileToCurrentSession` (re-exported from [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts) as `applySavedProfileToCurrentSession`).
2. The function updates the session's environment variables and API keys.
3. `buildProviderManagerCompletion` generates a system reminder confirming the switch.

The system emits a `<system-reminder>` message formatted by `buildProviderManagerCompletion`:

```text
Provider switched mid-session to Anthropic using model claude-3-sonnet-20240229.

```

This reminder ensures the LLM knows to route subsequent requests through the newly selected provider.

```tsx
// Activate interactively
await runCommand('/provider');
// Navigate to desired profile → Select "Activate"

```

## Method 2: Switch via the Model Picker (/model)

You can switch between OpenClaude provider profiles implicitly through the `/model` command. The model picker surfaces models from inactive profiles alongside active ones.

In [`src/utils/model/modelOptions.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/model/modelOptions.ts), profiles are scanned for their custom model lists. When you select a model belonging to a different profile:

1. The UI automatically calls `applySavedProfileToCurrentSession` with the associated `profileId`.
2. The profile activates immediately, updating the session context.

This method is ideal for quick switches when you already know which model you need.

## Method 3: Programmatic Profile Activation

For automation or custom commands, import `applySavedProfileToCurrentSession` directly from [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts) and invoke it with a specific profile identifier.

```typescript
import { applySavedProfileToCurrentSession } from '../../utils/providerProfile.js';

async function switchTo(profileId: string) {
  const result = await applySavedProfileToCurrentSession(profileId);
  console.log(result.message); // "Provider profile updated"
  
  // The result includes action: 'activated' for confirmation
  if (result.action === 'activated') {
    console.log(`Switched to ${profileId}`);
  }
}

// Example usage
switchTo('my-anthropic-profile');

```

The function returns a `ProviderManagerResult` object containing the action type, message, and metadata you can log or inspect.

## Automatic Failover with Provider Fallback Chains

If the active profile encounters a rate limit or quota error, OpenClaude automatically switches to the next available profile without manual intervention.

The [`src/utils/providerFallback.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerFallback.ts) utility implements this logic:

- It walks the `providerFallbackChain` array defined in your configuration.
- On failure, it activates the next profile in the chain by calling the same `applySavedProfileToCurrentSession` function used in manual switching.
- This ensures continuity during high-traffic scenarios or provider outages.

## Key Files Controlling Profile Switching

Understanding these source files helps when debugging or extending profile functionality:

- [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts): Core functions for loading, saving, sanitizing, and applying profiles.
- [`src/commands/provider/provider.tsx`](https://github.com/Gitlawb/openclaude/blob/main/src/commands/provider/provider.tsx): CLI command entry point that launches the ProviderManager UI.
- [`src/components/ProviderManager.tsx`](https://github.com/Gitlawb/openclaude/blob/main/src/components/ProviderManager.tsx): React component handling the interactive profile list, creation, and activation.
- [`src/utils/providerFallback.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerFallback.ts): Implements automatic failover logic when providers error.
- [`src/utils/model/modelOptions.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/model/modelOptions.ts): Controls how models from inactive profiles appear in the picker.

## Summary

- OpenClaude stores provider credentials in `~/.openclaude/profile.json` and loads them via `loadProfileFile` in [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts).
- Switch between OpenClaude provider profiles interactively using `/provider`, implicitly via `/model` selection, or programmatically via `applySavedProfileToCurrentSession`.
- The `buildProviderManagerCompletion` function generates system reminders confirming successful switches.
- [`src/utils/providerFallback.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerFallback.ts) provides automatic failover through the `providerFallbackChain` when rate limits occur.
- All switching methods ultimately invoke `applySavedProfileToCurrentSession` to merge profile data into the active session.

## Frequently Asked Questions

### Where are OpenClaude provider profiles stored on disk?

Provider profiles persist as a JSON object at `~/.openclaude/profile.json`. The `loadProfileFile` function in [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts) handles reading this file, while `applySavedProfileToCurrentSession` applies the loaded configuration to your current CLI session.

### Can I switch provider profiles automatically when one fails?

Yes. OpenClaude includes automatic failover through [`src/utils/providerFallback.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerFallback.ts). When a request encounters a rate limit or quota error, the system walks the `providerFallbackChain` defined in your configuration and automatically activates the next profile using the same underlying switching logic as manual selection.

### How do I switch profiles programmatically in a custom command?

Import `applySavedProfileToCurrentSession` from [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts) and call it with the target `profileId`. The function returns a `ProviderManagerResult` containing the action status and confirmation message, allowing your script to confirm the switch succeeded.

### What happens to the current session when I switch profiles?

When you switch profiles, `applySavedProfileToCurrentSession` immediately merges the new profile's environment variables, API keys, and default model into the current session. The system emits a `<system-reminder>` message via `buildProviderManagerCompletion` to notify the LLM of the provider change, ensuring all subsequent API calls route through the newly activated profile.