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

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. 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, 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 (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:

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:

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:

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:

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	Azure gateway definition, default base URL, and auth requirements
src/services/api/providerConfig.local.test.ts	URL validation tests including isAzureStyleBaseUrl
src/services/api/openaiShim.test.ts	Request URL construction tests for Azure endpoints
web/src/data/providers.ts	UI provider definition (id: 'azure-openai')
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 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 for URL pattern validation logic if custom endpoints fail detection.

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