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

> Discover where OpenClaude provider profiles are stored. Learn about configuration persistence in this complete guide to the .openclaude-profile.json file and its directory.

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

---

**OpenClaude provider profiles are stored in a JSON file named [`.openclaude-profile.json`](https://github.com/Gitlawb/openclaude/blob/main/.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:

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

```

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

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

```

This location is determined dynamically at runtime. The constant `PROFILE_FILE_NAME` is defined in [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts) as the string `'.openclaude-profile.json'`, while the parent directory is resolved by the utility module [`src/utils/xdg.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/.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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/.openclaude-profile.json) via the utilities in [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts).

### Reading at Launch Time

Conversely, [`scripts/provider-launch.ts`](https://github.com/Gitlawb/openclaude/blob/main/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.

```typescript
// 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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/.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`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts)** defines the filename constant and implements read/write operations.
- **[`src/utils/xdg.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/xdg.ts)** resolves the OS-specific configuration directory path.
- The profile is written by [`scripts/provider-recommend.ts`](https://github.com/Gitlawb/openclaude/blob/main/scripts/provider-recommend.ts) and read by [`scripts/provider-launch.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/.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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/.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`](https://github.com/Gitlawb/openclaude/blob/main/.openclaude-profile.json) file, effectively sharing provider preferences system-wide for that user.