Configuring Mistral for OpenClaude: Required Environment Variables and Setup

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, the useMistral flag (around line 297) drives provider selection logic. The flag is then consumed by 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 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 (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), 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:

# 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:

# 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, and routes requests to the configured Mistral endpoint with proper field sanitization.

JavaScript SDK Integration

The OpenClaude SDK automatically reads the same environment variables:

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:

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:

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 that invokes hasMistralApiHost and strips problematic fields before request execution. The integration tests in 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 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 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.

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