How to Connect OpenClaw to Azure OpenAI

GitHub issue #6056, a feature request for native Azure OpenAI support in OpenClaw, was closed as "not planned." That leaves every enterprise team running Azure-provisioned GPT models in the same spot: you need a translation layer between OpenClaw and Azure's endpoints.

The root cause is an API format mismatch. OpenAI and Azure OpenAI both serve the same underlying models, but their APIs differ in authentication, URL routing, and required parameters. OpenClaw's built-in OpenAI provider targets the standard OpenAI format, so requests sent to Azure endpoints fail before they reach a model.

The community has converged on three workarounds, each with different trade-offs for complexity, maintenance, and flexibility. A Microsoft Tech Community guide on integrating Azure AI Foundry with OpenClaw walks through the Foundry-side setup, and a detailed Medium walkthrough covers the LiteLLM proxy approach specifically. This guide consolidates all three methods so you can compare them in one place.

LiteLLM sits between OpenClaw and Azure, accepting OpenAI-format requests on one side and translating them into Azure's expected format on the other. This is the most documented approach and the one Microsoft's own community guides reference.

Install LiteLLM:

python3 -m venv ~/litellm-venv
source ~/litellm-venv/bin/activate
pip install 'litellm[proxy]'

Create the proxy config at ~/litellm_config.yaml:

model_list:
  - model_name: gpt-4o-mini
    litellm_params:
      model: azure/gpt4o-mini
      api_base: https://YOUR-RESOURCE.openai.azure.com
      api_key: YOUR_AZURE_API_KEY
      api_version: "2024-10-21"

- model_name: gpt-4o
    litellm_params:
      model: azure/gpt4o
      api_base: https://YOUR-RESOURCE.openai.azure.com
      api_key: YOUR_AZURE_API_KEY
      api_version: "2024-10-21"

general_settings:
  master_key: "sk-litellm-your-secret-key"

litellm_settings:
  drop_params: true

The drop_params setting matters because OpenClaw sends request parameters that Azure does not recognize. Without that flag, you get cryptic 400 errors pointing to unsupported parameter names. Enabling it tells LiteLLM to silently strip anything Azure cannot handle.

Start the proxy:

litellm --config ~/litellm_config.yaml --port 4000

Configure OpenClaw by adding a provider block to ~/.openclaw/openclaw.json:

{
  "models": {
    "mode": "merge",
    "providers": {
      "litellm": {
        "baseUrl": "http://localhost:4000/v1",
        "apiKey": "sk-litellm-your-secret-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-4o-mini",
            "name": "GPT-4o Mini (Azure)",
            "reasoning": false,
            "input": ["text", "image"],
            "contextWindow": 128000,
            "maxTokens": 16384
          }
        ]
      }
    }
  }
}

Two fields trip people up. The api value must be "openai-completions", not "openai" or blank. And mode: "merge" preserves OpenClaw's built-in providers alongside your custom one, so you can fall back to Anthropic or local models without reconfiguring. For a full list of supported provider configuration options, see the OpenClaw providers documentation.

Verify the connection:

curl http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-litellm-your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello"}]}'

If the curl test works but OpenClaw fails, check that OPENAI_BASE_URL in ~/.openclaw/.env points to http://localhost:4000/v1. A stale environment variable pointing to api.openai.com overrides your config file.

Strengths: Supports routing to 100+ providers through one proxy. Cost tracking and automatic failover are built in. Well-documented with both community guides and official LiteLLM tutorials.

Limitations: Adds a process to manage. LiteLLM must be running before OpenClaw starts, or every request fails. In production, you will want a systemd service or container to keep the proxy alive.

The openclaw-aoai extension, maintained on GitHub by kuzhao, adds Azure OpenAI as a first-class provider inside OpenClaw. No proxy process, no port management. You install a plugin and authenticate.

Install the extension:

Download the latest release from the GitHub repository and install it:

openclaw plugins install openclaw-aoai.zip
openclaw plugins enable azure-openai

Authenticate with an API key:

openclaw models auth login \
  --provider azure-openai \
  --method api-key

The CLI prompts for your Azure OpenAI endpoint URL, model deployment name, and API key. Once entered, you activate the model:

openclaw models set azure-openai/gpt-4o

Or authenticate with managed identity (keyless):

openclaw models auth login \
  --provider azure-openai \
  --method keyless

This uses Azure's DefaultAzureCredential chain, pulling credentials from environment variables, the Azure CLI, or a managed identity attached to your VM. No API keys to rotate or leak. The identity needs the "Cognitive Services OpenAI User" RBAC role on the Azure OpenAI resource.

Strengths: No external proxy. Two authentication options. Feels native once configured.

Limitations: The repository has 3 stars and 6 commits as of this writing. There are no published releases on the GitHub Releases page, so installation requires downloading the zip manually. If the maintainer stops updating, you are stuck on whatever OpenClaw version the plugin last supported.

Give your OpenClaw agents persistent file storage

Free 50GB workspace with MCP access. Agents write to Fastio, humans review in the same workspace. No credit card, no trial expiration.

Start 14-Day Trial

Starting with OpenClaw version 2026.4.22, the built-in OpenAI provider can detect Azure endpoints and adjust its request format automatically. This means you can point baseUrl at your Azure resource without a proxy or plugin, as long as you handle the authentication header difference.

Configure the provider in ~/.openclaw/openclaw.json:

{
  "models": {
    "providers": {
      "openai": {
        "baseUrl": "https://YOUR-RESOURCE.services.ai.azure.com/models",
        "authHeader": false,
        "headers": {
          "api-key": "YOUR_AZURE_API_KEY"
        }
      }
    }
  }
}

Setting authHeader to false tells OpenClaw not to send the standard Authorization: Bearer header. Instead, the custom headers block sends the api-key header that Azure expects.

OpenClaw detects Azure host suffixes (*.openai.azure.com, *.services.ai.azure.com, *.cognitiveservices.azure.com) and automatically switches to deployment-scoped paths and API version parameters.

Strengths: No extra software. No plugin to install. Uses OpenClaw's built-in provider with one config change.

Limitations: Requires OpenClaw 2026.4.22 or later. Limited to models deployed in your Azure resource. You lose LiteLLM's multi-provider failover and cost tracking. The drop_params problem still applies: if OpenClaw sends parameters Azure does not support, requests fail. Community reports suggest this method works reliably for chat completions but can break for image generation or newer API features without additional configuration.

The right choice depends on your constraints.

Use LiteLLM Proxy if you need multiple Azure models, want automatic failover, or plan to route requests to other providers alongside Azure. The proxy adds operational overhead but gives you the most flexibility. Teams already running LiteLLM for other tools can reuse their existing proxy instance.

Use the openclaw-aoai extension if you want the cleanest developer experience and you are comfortable depending on a community-maintained plugin. Managed identity support makes it the strongest option for Azure VMs and container instances where you want keyless auth. Watch the repository for maintenance activity before committing to production use.

Use direct provider configuration if you want zero dependencies and only need one or two Azure models. This works best for simple setups where you control the OpenClaw version and can pin to 2026.4.22 or later.

For production workloads, LiteLLM is the safest bet. It is the only method with documented troubleshooting for common failure modes like drop_params errors, API version mismatches, and authentication header conflicts.

Whichever method you choose, test with a simple chat completion request before pointing your agents at the endpoint. Authentication mismatches surface immediately on the first request, but parameter compatibility issues (the drop_params problem) only show up once OpenClaw sends a request with features Azure does not support.

Connecting OpenClaw to Azure OpenAI solves the model access problem. But the files your agents create still need somewhere to live, especially when multiple agents or team members need to access the results.

Local filesystems work for single-user setups. S3 or Azure Blob Storage work if you want to write custom upload scripts. For teams that need shared access without building infrastructure, Fastio provides workspaces where agents and humans collaborate on the same files.

Fastio's MCP server connects to OpenClaw through Streamable HTTP and exposes tools for uploads, downloads, workspace management, and AI-powered file search. Agents can write generated content to a workspace, and team members see it immediately with version history and audit trails.

The Business Trial includes 50GB of storage, included credits, and 5 workspaces with no credit card required. You can test the full workflow, from Azure OpenAI generation through OpenClaw to persistent storage, without paying for anything beyond your Azure compute.

For teams already using OpenClaw with Azure, adding Fastio as the storage layer means agents can read context files from a shared workspace (using Intelligence Mode for RAG search), generate content through Azure models, and write results back to the same workspace where humans review and approve them.