# How to Configure Azure OpenAI with OpenClaude Using `OPENAI_AZURE_STYLE=1`

> Learn to configure Azure OpenAI with OpenClaude using OPENAI_AZURE_STYLE=1. Set OPENAI_BASE_URL, OPENAI_DEPLOYMENT_ID, and AZURE_OPENAI_API_KEY for seamless Azure OpenAI integration.

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

---

**Set `OPENAI_AZURE_STYLE=1` to enable Azure-style endpoint handling, then configure `OPENAI_BASE_URL`, `OPENAI_DEPLOYMENT_ID`, and `AZURE_OPENAI_API_KEY` to route all requests through Azure OpenAI.**

OpenClaude supports multiple gateway backends, including Azure OpenAI, through environment-based configuration. When you enable Azure mode, the CLI switches from standard OpenAI API handling to Azure's resource-based endpoint pattern, using deployment names instead of model routing. This article explains how to configure OpenClaude with Azure OpenAI using the `OPENAI_AZURE_STYLE=1` environment variable, based on the source code implementation in `Gitlawb/openclaude`.

---

## Understanding Azure Mode in OpenClaude

Setting **`OPENAI_AZURE_STYLE=1`** activates the **instance-style** Azure gateway. This tells OpenClaude's request shim to treat your base URL as an Azure resource endpoint and to use deployment-based routing rather than model-based routing.

The Azure gateway logic lives in [`src/integrations/gateways/azure-openai.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/gateways/azure-openai.ts). When Azure mode is active, this gateway:

- Propagates authentication via the `api-key` header (`supportsAuthHeaders: true`)
- Skips model routing (the deployment name functions as your model identifier)
- Constructs URLs following Azure's `/deployments/{deployment}/completions` pattern

The configuration detection is validated in [`src/services/api/providerConfig.local.test.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/providerConfig.local.test.ts), where `isAzureStyleBaseUrl` confirms URLs containing `/azure-openai` or matching Azure resource patterns (see lines 541–542). Request URL construction is tested in [`src/services/api/openaiShim.test.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/openaiShim.test.ts) (lines 975–1007).

---

## Required Environment Variables

| Variable | Purpose | Example Value |
|----------|---------|---------------|
| `OPENAI_AZURE_STYLE` | Enables Azure-style endpoint handling | `1` |
| `OPENAI_BASE_URL` | Azure resource endpoint (must end with `/openai/v1`) | `https://myresource.openai.azure.com/openai/v1` |
| `OPENAI_DEPLOYMENT_ID` | Name of your Azure deployment | `gpt-35-turbo` |
| `AZURE_OPENAI_API_KEY` | API key for your Azure OpenAI resource | `your-azure-key` |

**Important:** The `OPENAI_BASE_URL` must terminate with `/openai/v1` for the shim to correctly append Azure's deployment path segments.

---

## Step-by-Step Configuration

### 1. Configure Environment Variables

Create a `.env` file in your project root or export the variables directly:

```bash
OPENAI_AZURE_STYLE=1
OPENAI_BASE_URL=https://myresource.openai.azure.com/openai/v1
OPENAI_DEPLOYMENT_ID=gpt-35-turbo
AZURE_OPENAI_API_KEY=your-azure-key

```

For secure credential handling, OpenClaude also supports loading these from your shell environment.

### 2. Verify the Configuration

Run the provider list command to confirm Azure OpenAI is registered:

```bash
openclaude provider list

```

You should see the **Azure OpenAI** gateway listed with your deployment name recognized as an available model.

### 3. Execute Chat Commands

Reference your deployment name as the model:

```bash
openclaude chat --model=gpt-35-turbo "Explain quantum entanglement"

```

The CLI constructs and sends requests to:

```

https://myresource.openai.azure.com/openai/v1/deployments/gpt-35-turbo/completions

```

with the `api-key` header automatically injected.

---

## Programmatic Usage

Instantiate OpenClaude with Azure configuration in Node.js/TypeScript:

```typescript
import { OpenClaude } from 'openclaude';

const client = new OpenClaude({
  env: {
    OPENAI_AZURE_STYLE: '1',
    OPENAI_BASE_URL: 'https://myresource.openai.azure.com/openai/v1',
    OPENAI_DEPLOYMENT_ID: 'gpt-35-turbo',
    AZURE_OPENAI_API_KEY: 'your-azure-key',
  },
});

const response = await client.chat({
  model: 'gpt-35-turbo',
  messages: [{ role: 'user', content: 'What is the capital of France?' }],
});

console.log(response);

```

The client respects the same environment-based configuration used by the CLI.

---

## Key Implementation Files

Understanding the source helps debug configuration issues:

| File | Role |
|------|------|
| [`src/integrations/gateways/azure-openai.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/gateways/azure-openai.ts) | Azure gateway definition, default base URL, and auth requirements |
| [`src/services/api/providerConfig.local.test.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/providerConfig.local.test.ts) | URL validation tests including `isAzureStyleBaseUrl` |
| [`src/services/api/openaiShim.test.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/openaiShim.test.ts) | Request URL construction tests for Azure endpoints |
| [`web/src/data/providers.ts`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/providers.ts) | UI provider definition (`id: 'azure-openai'`) |
| [`src/integrations/generated/integrationManifest.generated.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/generated/integrationManifest.generated.ts) | Generated manifest containing Azure preset |

These files collectively implement the Azure-style routing activated by `OPENAI_AZURE_STYLE=1`.

---

## Summary

- **`OPENAI_AZURE_STYLE=1`** enables Azure instance-style endpoint handling in OpenClaude
- **`OPENAI_BASE_URL`** must end with `/openai/v1` and point to your Azure resource
- **`OPENAI_DEPLOYMENT_ID`** replaces model names—use your Azure deployment name directly
- **`AZURE_OPENAI_API_KEY`** authenticates requests via the `api-key` header
- The Azure gateway in [`src/integrations/gateways/azure-openai.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/integrations/gateways/azure-openai.ts) handles all request transformation automatically

---

## Frequently Asked Questions

### What happens if I omit `OPENAI_AZURE_STYLE`?

OpenClaude defaults to standard OpenAI API handling. Requests will be routed to `api.openai.com` or your custom `OPENAI_BASE_URL` using OpenAI's model-based path structure, which is incompatible with Azure's deployment-based endpoints.

### Can I use `OPENAI_AZURE_STYLE` with other values besides `1`?

The source code treats `OPENAI_AZURE_STYLE=1` as the activation value for instance-style handling. Other values may not trigger Azure mode. Always use `1` to ensure the Azure gateway is selected.

### Why does my deployment name work as the model parameter?

Azure OpenAI uses deployment-specific endpoints rather than model-based routing. OpenClaude's Azure gateway recognizes this pattern—when `OPENAI_AZURE_STYLE=1` is set, the model parameter is passed directly as the deployment identifier in the URL path.

### How do I troubleshoot connection failures?

Verify your `OPENAI_BASE_URL` ends with `/openai/v1`, confirm your `AZURE_OPENAI_API_KEY` has not expired, and ensure your `OPENAI_DEPLOYMENT_ID` exactly matches the deployment name in Azure Portal. Check [`src/services/api/providerConfig.local.test.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/services/api/providerConfig.local.test.ts) for URL pattern validation logic if custom endpoints fail detection.