How to Switch Between OpenClaude Provider Profiles: 3 Methods Explained

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 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.

When you activate a profile through this interface:

1. The UI calls applySharedProfileToCurrentSession (re-exported from 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:

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.

// 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, 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 and invoke it with a specific profile identifier.

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 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: Core functions for loading, saving, sanitizing, and applying profiles.
• src/commands/provider/provider.tsx: CLI command entry point that launches the ProviderManager UI.
• src/components/ProviderManager.tsx: React component handling the interactive profile list, creation, and activation.
• src/utils/providerFallback.ts: Implements automatic failover logic when providers error.
• 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.
• 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 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 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}