Where Are OpenClaude Provider Profiles Stored? A Complete Guide to Configuration Persistence

OpenClaude provider profiles are stored in a JSON file named .openclaude-profile.json located in the user-specific configuration directory, which resolves to ~/.config/openclaude/ on Linux/macOS and %APPDATA%\openclaude\ on Windows.

The OpenClaude CLI tool persists provider selections—including the default model, base URL, and credential source—to a standardized location on the filesystem. This configuration file enables the CLI to remember your preferred AI provider between sessions without requiring environment variables or command-line flags on every invocation.

File Location and Naming Convention

The profile storage location follows the XDG Base Directory Specification for Unix-like systems and equivalent conventions on Windows.

Cross-Platform Paths

On Linux and macOS, the full path resolves to:

~/.config/openclaude/.openclaude-profile.json

On Windows, the file resides in the application data directory:

%APPDATA%\openclaude\.openclaude-profile.json

This location is determined dynamically at runtime. The constant PROFILE_FILE_NAME is defined in src/utils/providerProfile.ts as the string '.openclaude-profile.json', while the parent directory is resolved by the utility module src/utils/xdg.ts according to platform-specific environment variables.

Core Implementation Files

The persistence layer is implemented across two primary utility modules that handle directory resolution and file I/O.

providerProfile.ts

The file src/utils/providerProfile.ts exports the core functions for reading and writing provider configurations. It defines the constant PROFILE_FILE_NAME and exposes readProviderProfile() to deserialize the JSON contents into a typed object. When the CLI executes a provider recommendation flow, this module handles the atomic write operation to ensure the profile is saved correctly.

xdg.ts

The module src/utils/xdg.ts computes the configuration directory path. It checks the XDG_CONFIG_HOME environment variable on Unix systems, falling back to ~/.config, and maps to %APPDATA% on Windows. This ensures the .openclaude-profile.json file is always stored in an OS-appropriate user-scoped directory rather than the project root or system directories.

How Profiles Are Written and Read

The CLI lifecycle involves two critical scripts that interact with the profile file during provider discovery and launch sequences.

Writing During Provider Recommendations

When you run the provider recommendation wizard, the script scripts/provider-recommend.ts evaluates available AI providers and writes the selected configuration to disk. It constructs a profile object containing the provider identifier, preferred model, and authentication method, then persists it to .openclaude-profile.json via the utilities in src/utils/providerProfile.ts.

Reading at Launch Time

Conversely, scripts/provider-launch.ts invokes readProviderProfile() at startup to retrieve the saved configuration. If hasExplicitProviderSelection() returns true—indicating a valid profile exists on disk—the CLI uses those settings to initialize the provider connection rather than prompting for credentials again.

Programmatic Access to Profile Data

You can interact with the stored profile programmatically using the exported utilities. This is useful for custom integrations or validation scripts that need to verify the current provider configuration.

// Import the profile utilities
import {
  readProviderProfile,
  hasExplicitProviderSelection,
} from '@/utils/providerProfile.js';

// Check for an explicitly saved provider
if (hasExplicitProviderSelection()) {
  const profile = readProviderProfile();
  console.log(`Active provider: ${profile.provider}`);
  console.log(`Default model: ${profile.model}`);
} else {
  console.warn('No provider profile found—using fallback defaults');
}

For higher-level resolution logic, the integration layer in src/integrations/profileResolver.ts consumes these utilities to map a saved profile to a concrete routing identifier. The function resolveActiveRouteIdFromEnv() internally references the profile file to determine which provider route should handle the current request.

Summary

• OpenClaude provider profiles are stored in .openclaude-profile.json within the user's configuration directory.
• The file location follows XDG standards: ~/.config/openclaude/ on Linux/macOS and %APPDATA%\openclaude\ on Windows.
• src/utils/providerProfile.ts defines the filename constant and implements read/write operations.
• src/utils/xdg.ts resolves the OS-specific configuration directory path.
• The profile is written by scripts/provider-recommend.ts and read by scripts/provider-launch.ts during normal CLI operation.
• Use readProviderProfile() and hasExplicitProviderSelection() to access profile data programmatically.

Frequently Asked Questions

What happens if the .openclaude-profile.json file is deleted?

If you delete the profile file, the CLI will behave as if no provider has been selected. On the next invocation, hasExplicitProviderSelection() returns false, and OpenClaude will either prompt you to run the provider recommendation wizard or fall back to environment variable-based configuration.

Can I manually edit the provider profile JSON?

Yes, you can manually edit the file at ~/.config/openclaude/.openclaude-profile.json (or the Windows equivalent). The JSON structure follows the ProviderProfile type defined in the source code, containing fields for provider, model, baseUrl, and credentialSource. Ensure valid JSON syntax, as malformed files will cause readProviderProfile() to throw a parse error on the next CLI launch.

How does OpenClaude handle profile storage on Windows vs macOS?

OpenClaude uses the src/utils/xdg.ts module to abstract platform differences. On macOS and Linux, it respects the XDG_CONFIG_HOME environment variable, defaulting to ~/.config. On Windows, it resolves to the path specified by %APPDATA%. In both cases, the subdirectory openclaude is appended, and the filename .openclaude-profile.json remains consistent across platforms.

Is the provider profile shared between different OpenClaude installations?

The profile is stored in the user-specific configuration directory, not the project directory. This means all OpenClaude CLI instances running under the same user account will read from and write to the same .openclaude-profile.json file, effectively sharing provider preferences system-wide for that user.

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