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

# Open Code

> Connect Open Code to HaiRoute

Open Code can use HaiRoute through an OpenAI-compatible provider. The stable path is a two-part flow: use `/connect` to store the credential, then use `opencode.json` to define the provider, Base URL, and models.

## Protocol Note

Open Code's custom provider integration is based on `@ai-sdk/openai-compatible`, 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`

## Setup Steps

### Step 1: Save the HaiRoute API key with `/connect`

Inside Open Code, run `/connect` and store your HaiRoute API key there.

This step is mainly for credentials. Do not expect a Base URL input in this dialog.

### Step 2: Edit `opencode.json`

Use your Open Code config file to define the provider, Base URL, and models. A common global path is `~/.config/opencode/opencode.json`.

You can read that path like this on different systems:

* Windows: a common equivalent is `%USERPROFILE%\\.config\\opencode\\opencode.json`
* macOS: commonly `~/.config/opencode/opencode.json`
* Linux: commonly `~/.config/opencode/opencode.json`

Here `~` means your user home directory: usually `%USERPROFILE%` on Windows, `/Users/<your-name>` on macOS, and `/home/<your-name>` on Linux.

Example:

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "hairoute": {
      "name": "HaiRoute",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.hairoute.ai/v1",
        "apiKey": "{env:HAIROUTE_API_KEY}"
      },
      "models": {
        "gpt-5.4": {
          "name": "gpt-5.4"
        },
        "gpt-5.4": {
          "name": "gpt-5.4"
        }
      }
    }
  }
}
```

### Step 3: Make sure the environment variable exists

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 4: Restart Open Code and choose the model

After saving `opencode.json`, restart Open Code if the provider list does not refresh automatically.

Then select the HaiRoute provider and switch to the model you registered.

## Request Mapping

| Item                            | Value                                                         |
| ------------------------------- | ------------------------------------------------------------- |
| Base URL in config              | `https://api.hairoute.ai/v1`                                  |
| Chat endpoint used by Open Code | `POST /v1/chat/completions`                                   |
| Model discovery                 | `GET /v1/models` may be used for discovery or troubleshooting |
| Auth header                     | `Authorization: Bearer YOUR_API_KEY`                          |

## Verification

1. Open Open Code.
2. Select the HaiRoute provider and one of your configured models.
3. Send a simple prompt such as `hello`.
4. If a normal response comes back, the integration is working.

## FAQ

| Question                                          | Fix                                                                                                                                  |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| I used `/connect` but never saw a Base URL field  | That is expected. `/connect` mainly stores credentials. The provider definition, Base URL, and model list belong in `opencode.json`. |
| `401` or authentication failed                    | Make sure the key is valid and that `HAIROUTE_API_KEY` is available in the same environment where Open Code is running.              |
| `model not found`                                 | Make sure the model name in `opencode.json` exactly matches a model ID that HaiRoute exposes.                                        |
| The provider was added but still does not show up | Restart Open Code after saving `opencode.json`, then check the provider picker again.                                                |

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