> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hairoute.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenClaw

> Connect OpenClaw to HaiRoute

OpenClaw can use HaiRoute through an OpenAI-compatible provider in `openclaw.json`. The stable path is to register HaiRoute under `models.providers`, then point the default agent model to that provider.

## Protocol Note

OpenClaw's custom provider integration uses the `openai-completions` API type, so it only supports the OpenAI Chat Completions protocol; it does not support the Anthropic Messages protocol. This guide therefore only covers the OpenAI mode, with the Base URL fixed to `https://api.hairoute.ai/v1`.

## What you need

* A HaiRoute API key
* At least one available model ID, such as `gpt-5.4`
* HaiRoute OpenAI-compatible base URL: `https://api.hairoute.ai/v1`

<Note>
  If you see `~`, environment variables, or user-directory placeholders in OpenClaw examples, read them as “your current user home directory.” On Windows this is usually `%USERPROFILE%`, on macOS usually `/Users/<your-name>`, and on Linux usually `/home/<your-name>`.
</Note>

## Setup Steps

### Step 1: Edit `openclaw.json`

Add a HaiRoute provider under `models.providers`.

Example:

```json5 theme={null}
{
  models: {
    mode: "merge",
    providers: {
      hairoute: {
        baseUrl: "https://api.hairoute.ai/v1",
        apiKey: "${HAIROUTE_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gpt-5.4", name: "GPT-5.4" },
          { id: "gpt-5.4", name: "GPT-5.4" },
          { id: "gpt-4o", name: "GPT-4o" }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: {
        primary: "hairoute/gpt-5.4",
        fallbacks: ["hairoute/gpt-5.4"]
      },
      models: {
        "hairoute/gpt-5.4": { alias: "flash" }
      }
    }
  }
}
```

### Step 2: Set the environment variable

Windows PowerShell:

```powershell theme={null}
$env:HAIROUTE_API_KEY = "YOUR_API_KEY"
```

macOS / Linux:

```bash theme={null}
export HAIROUTE_API_KEY="YOUR_API_KEY"
```

### Step 3: Reload OpenClaw

After saving the file, first check whether OpenClaw picks up the change automatically.

If the new model does not appear, restart the gateway or reopen OpenClaw and test again.

### Step 4: Pick the HaiRoute-backed model

Use the primary model or one of the aliases you configured and send a simple prompt.

## Notes

| Item              | Value                                |
| ----------------- | ------------------------------------ |
| Provider base URL | `https://api.hairoute.ai/v1`         |
| API type          | `openai-completions`                 |
| Chat endpoint     | `POST /v1/chat/completions`          |
| Auth header       | `Authorization: Bearer YOUR_API_KEY` |

<Note>
  Do not write OpenClaw setup as an install or onboarding guide here. The key part is the provider configuration and model mapping.
</Note>

Model discovery through `GET /v1/models` can help when debugging, but you should not describe it as a guaranteed mandatory step for every OpenClaw flow.

## Verification

1. Open OpenClaw.
2. Select the HaiRoute-backed model or alias.
3. Send a simple prompt.
4. If the response returns normally, the integration is working.

## FAQ

| Question                                                       | Fix                                                                                                                                   |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `401` or authentication failed                                 | Make sure `HAIROUTE_API_KEY` is set in the same environment where OpenClaw is running.                                                |
| `model not found`                                              | Make sure the model IDs in `models.providers.hairoute.models` exactly match the IDs exposed by HaiRoute.                              |
| The configuration was saved but the new model does not show up | OpenClaw may not reload immediately in every setup. Reopen it or restart the related gateway process and test again.                  |
| Do I always need to restart?                                   | No. Check whether the config has been reloaded automatically first. Restart only if the updated provider or models are still missing. |

## Next

* See [Get API Key](/docs/en/quickstart/get-api-key)
* See [OpenAI format API](/docs/en/api-reference/chat/openai-format)
* See [List models](/docs/en/api-reference/models/list-models)