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

> 通过 HaiRoute 网关接入 Open Code

Open Code 可以通过 OpenAI 兼容 Provider 接入 HaiRoute。最稳妥的接法是分成两步：先用 `/connect` 保存凭据，再用 `opencode.json` 定义 provider、Base URL 和模型列表。

## 协议说明

Open Code 的自定义 Provider 接入基于 `@ai-sdk/openai-compatible`，只支持 OpenAI Chat Completions 协议，不支持 Anthropic Messages 协议。因此本文档只覆盖 OpenAI 模式，Base URL 固定为 `https://api.hairoute.ai/v1`。

## 先准备好这些信息

* HaiRoute API Key
* 至少一个可用模型 ID，例如 `gpt-5.4`
* HaiRoute OpenAI 兼容 Base URL：`https://api.hairoute.ai/v1`

## 接入步骤

### 步骤 1：先用 `/connect` 保存 HaiRoute API Key

在 Open Code 中运行 `/connect`，把你的 HaiRoute API Key 先保存进去。

这一步主要是录入凭据，不要期待这里会出现 Base URL 输入框。

### 步骤 2：编辑 `opencode.json`

在 Open Code 配置文件中定义 provider、Base URL 和模型。常见的全局路径是 `~/.config/opencode/opencode.json`。

不同系统下可以这样理解这个路径：

* Windows：常见可写成 `%USERPROFILE%\.config\opencode\opencode.json`
* macOS：常见是 `~/.config/opencode/opencode.json`
* Linux：常见是 `~/.config/opencode/opencode.json`

其中 `~` 表示当前用户主目录：Windows 下通常对应 `%USERPROFILE%`，macOS 下通常是 `/Users/<你的用户名>`，Linux 下通常是 `/home/<你的用户名>`。

参考示例：

```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"
        }
      }
    }
  }
}
```

### 步骤 3：确认环境变量已生效

Windows PowerShell：

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

macOS / Linux：

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

### 步骤 4：重启 Open Code 并选择模型

保存 `opencode.json` 后，如果 Provider 列表没有自动刷新，就重启 Open Code。

然后在界面中选择 HaiRoute Provider，再切换到你注册的模型。

## 请求关系速览

| 项目               | 说明                                   |
| ---------------- | ------------------------------------ |
| 配置中的 Base URL    | `https://api.hairoute.ai/v1`         |
| Open Code 实际聊天请求 | `POST /v1/chat/completions`          |
| 模型发现             | `GET /v1/models` 可用于发现或排障            |
| 鉴权头              | `Authorization: Bearer YOUR_API_KEY` |

## 验证步骤

1. 打开 Open Code。
2. 选择 HaiRoute Provider 和你配置的模型。
3. 发送一条简单提示词，例如 `hello`。
4. 如果能够正常返回内容，说明接入成功。

## 常见问题

| 问题                                | 解决方案                                                                    |
| --------------------------------- | ----------------------------------------------------------------------- |
| 我用了 `/connect`，但没有看到 Base URL 输入框 | 这是正常的。`/connect` 主要负责保存凭据；provider 定义、Base URL 和模型列表属于 `opencode.json`。 |
| 提示 `401` 或鉴权失败                    | 请确认 API Key 有效，并且 `HAIROUTE_API_KEY` 已经在 Open Code 所在的同一运行环境中生效。        |
| 提示 `model not found`              | 请确认 `opencode.json` 中填写的模型名，与 HaiRoute 当前实际暴露的模型 ID 完全一致。               |
| Provider 已配置，但仍然没有显示              | 保存 `opencode.json` 后重启 Open Code，再重新检查 Provider 列表。                     |

## 下一步

* 查看 [获取 API Key](/docs/zh/quickstart/get-api-key)
* 查看 [OpenAI 格式 API 文档](/docs/zh/api-reference/chat/openai-format)
* 查看 [模型列表](/docs/zh/api-reference/models/list-models)