# Configuring Mistral for OpenClaude: Required Environment Variables and Setup

> Configure Mistral with OpenClaude by setting environment variables CLAUDE_CODE_USE_MISTRAL and MISTRAL_API_KEY. Learn optional overrides for MISTRAL_MODEL and MISTRAL_BASE_URL for seamless integration.

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

---

**To use Mistral with OpenClaude, you must set `CLAUDE_CODE_USE_MISTRAL=true` and provide a `MISTRAL_API_KEY`; optional overrides include `MISTRAL_MODEL` and `MISTRAL_BASE_URL`.**

The OpenClaude project from Gitlawb/openclaude includes specific handling for **Mistral AI** as an OpenAI-compatible provider. Unlike generic OpenAI-compatible backends, Mistral requires a special compatibility mode to handle its unique API constraints and field requirements. This guide covers the exact configuration variables, their source code implementations, and practical setup examples.

## Enable Mistral Mode with the Required Flag

The single most important configuration step is enabling **Mistral mode** through an environment variable.

Set **`CLAUDE_CODE_USE_MISTRAL=true`** before running any OpenClaude commands. This flag activates the Mistral compatibility path throughout the codebase.

In [`src/utils/providerFlag.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerFlag.ts), the `useMistral` flag (around line 297) drives provider selection logic. The flag is then consumed by [`src/services/api/providerConfig.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/providerConfig.ts) via the `isMistralMode` check (around line 946) to determine base URL handling and provider-specific behavior.

Without this flag, OpenClaude treats Mistral as a generic OpenAI-compatible backend, which causes request validation failures.

## Provide a Mistral API Key

Mistral authentication requires a dedicated secret variable.

Set **`MISTRAL_API_KEY`** with your Mistral API key. The key is read and sanitized in [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts) by the `buildMistralProfileEnv` function (around line 1055), which uses `sanitizeApiKey` to strip whitespace and validate format.

The profile construction fails if this variable is missing or malformed. The API key must follow Mistral's format: typically starting with `sk-mistral-` for production keys.

## Optional: Override the Default Model

Mistral supports multiple model variants, and you may want to specify a particular version.

Set **`MISTRAL_MODEL`** or pass `--model <model>` on the CLI. The `buildMistralProfileEnv` function normalizes the value using `normalizeProfileModel`. Common options include:

- `mistral-7b-instruct-v0.2`
- `mistral-large-2`
- `codestral-22b`

If omitted, OpenClaude falls back to `DEFAULT_MISTRAL_MODEL` as defined in the provider configuration.

## Optional: Configure a Custom Endpoint

For proxies, regional deployments, or self-hosted Mistral instances, you can redirect API calls.

Set **`MISTRAL_BASE_URL`** to override the default `https://api.mistral.ai/v1`. The custom endpoint is sanitized in `buildMistralProfileEnv` and later inspected by `hasMistralApiHost` in [`src/services/api/openaiShim/providerCompatibility.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/openaiShim/providerCompatibility.ts) (around line 103).

The `hasMistralApiHost` function recognizes these host patterns:

- `api.mistral.ai`
- `proxy.mistral.ai`
- `eu.mistral.ai`
- `edge.api.mistral.ai`

This detection triggers **Mistral-specific request sanitization** in the OpenAI shim ([`src/services/api/openaiShim.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/openaiShim.ts)), which strips unsupported fields like `store` and `max_completion_tokens` to prevent 422 validation errors.

## Complete .env Configuration Example

The following environment file shows a fully configured Mistral setup for OpenClaude:

```text

# Enable the special Mistral compatibility path

CLAUDE_CODE_USE_MISTRAL=true

# Your Mistral API key (keep secret!)

MISTRAL_API_KEY=sk-mistral-xxxxxxxxxxxxxxxxxxxx

# (Optional) Choose a specific model

MISTRAL_MODEL=mistral-7b-instruct-v0.2

# (Optional) Use a custom endpoint for proxies or regional deployments

MISTRAL_BASE_URL=https://proxy.mistral.ai/v1

```

When these variables are present, `buildMistralProfileEnv` constructs a complete profile and `applyProviderProfileToProcessEnv` injects it into the process environment for the CLI session.

## Running OpenClaude with Mistral

### CLI Usage with Environment File

Load your `.env` file and invoke the chat command:

```bash

# Using dotenv-cli or similar

dotenv -e .env -- claude chat "Explain the benefits of using Mistral-7B for code generation"

```

The CLI detects `CLAUDE_CODE_USE_MISTRAL`, builds the profile through [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts), and routes requests to the configured Mistral endpoint with proper field sanitization.

### JavaScript SDK Integration

The OpenClaude SDK automatically reads the same environment variables:

```typescript
import { createClient } from '@openclaude/sdk';

const client = createClient();

const response = await client.chat({
  messages: [{ 
    role: 'user', 
    content: 'Summarize the latest research on Retrieval-Augmented Generation' 
  }],
});

console.log(response.choices[0].message.content);

```

### Programmatic Profile Construction

For dynamic configuration without environment variables, use the profile utilities directly:

```typescript
import { buildMistralProfileEnv, applyProviderProfileToProcessEnv } from '@openclaude/core/utils';

const mistralEnv = buildMistralProfileEnv({
  apiKey: 'sk-mistral-xxxxxxxxxxxx',
  model: 'mistral-large-2',
  baseUrl: 'https://proxy.mistral.ai/v1',
});

applyProviderProfileToProcessEnv(mistralEnv);

```

### Proxy Endpoint Configuration

Route traffic through a custom proxy while maintaining Mistral compatibility:

```bash
export CLAUDE_CODE_USE_MISTRAL=true
export MISTRAL_API_KEY=sk-mistral-xxxx
export MISTRAL_BASE_URL=https://my-proxy.example.com/v1

claude chat "What is the current state of the art in protein folding?"

```

The shim continues to recognize this as a Mistral host and applies appropriate request transformations.

## Why Special Handling Is Required

According to the Gitlawb/openclaude source code, Mistral diverges from standard OpenAI-compatible behavior in several ways:

- **Stricter field validation**: Mistral rejects unknown request body parameters
- **Different token limit fields**: `max_completion_tokens` handling varies from OpenAI's implementation
- **Missing feature support**: Fields like `store` are not recognized

The `CLAUDE_CODE_USE_MISTRAL` flag activates conditional logic in [`src/services/api/openaiShim.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/openaiShim.ts) that invokes `hasMistralApiHost` and strips problematic fields before request execution. The integration tests in [`src/services/api/openaiShim/requestExecutor.integration.test.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/openaiShim/requestExecutor.integration.test.ts) document these 422-error prevention scenarios.

## Summary

- **`CLAUDE_CODE_USE_MISTRAL=true`** is mandatory to activate Mistral compatibility mode
- **`MISTRAL_API_KEY`** provides authentication and is validated by `buildMistralProfileEnv`
- **`MISTRAL_MODEL`** optionally overrides the default model selection
- **`MISTRAL_BASE_URL`** optionally redirects to custom endpoints while preserving host detection
- The **OpenAI shim** automatically sanitizes requests when Mistral mode is enabled, preventing validation errors

## Frequently Asked Questions

### What happens if I don't set `CLAUDE_CODE_USE_MISTRAL`?

Without this flag, OpenClaude treats Mistral as a generic OpenAI-compatible provider. The request shim skips Mistral-specific sanitization, causing **422 validation errors** when unsupported fields like `store` or `max_completion_tokens` are sent to the Mistral API.

### Can I use Mistral with a self-hosted or regional endpoint?

Yes. Set `MISTRAL_BASE_URL` to your custom endpoint. The `hasMistralApiHost` function in [`src/services/api/openaiShim/providerCompatibility.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/openaiShim/providerCompatibility.ts) detects known Mistral host patterns and applies the same request transformations as the official API.

### Where does OpenClaude read the API key from?

The `buildMistralProfileEnv` function in [`src/utils/providerProfile.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/providerProfile.ts) reads `MISTRAL_API_KEY` from `process.env`, sanitizes it with `sanitizeApiKey`, and injects it into the active profile. The SDK and CLI both rely on this centralized profile construction.

### Is the Mistral model required to be specified?

No. If `MISTRAL_MODEL` is omitted, OpenClaude uses `DEFAULT_MISTRAL_MODEL` from the provider configuration. Explicit specification is only needed when targeting a specific model variant like `codestral-22b` or `mistral-large-2`.