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

> 通过 HaiRoute 网关接入 OpenClaw

OpenClaw 可以通过 `openclaw.json` 中的 OpenAI 兼容 Provider 接入 HaiRoute。最稳妥的方式是在 `models.providers` 里注册 HaiRoute，再把默认 agent 模型指向这个 Provider。

## 协议说明

OpenClaw 的自定义 Provider 接入使用 `openai-completions` API 类型，只支持 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`

<Note>
  如果你在 OpenClaw 文档或社区示例中看到 `~`、环境变量或用户目录写法，请把它理解成“当前用户主目录”。Windows 下通常对应 `%USERPROFILE%`，macOS 下通常是 `/Users/<你的用户名>`，Linux 下通常是 `/home/<你的用户名>`。
</Note>

## 接入步骤

### 步骤 1：编辑 `openclaw.json`

在 `models.providers` 下新增一个 HaiRoute Provider。

参考示例：

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

### 步骤 2：设置环境变量

Windows PowerShell：

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

macOS / Linux：

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

### 步骤 3：重新加载 OpenClaw

保存配置后，先观察 OpenClaw 是否已经自动读取新配置。

如果新模型没有出现，再重启相关 gateway 或重新打开 OpenClaw 后再测试。

### 步骤 4：选择 HaiRoute 模型并测试

选择你刚配置的主模型或别名，发送一条简单提示词进行验证。

## 补充说明

| 项目                | 说明                                   |
| ----------------- | ------------------------------------ |
| Provider Base URL | `https://api.hairoute.ai/v1`         |
| API 类型            | `openai-completions`                 |
| 实际聊天接口            | `POST /v1/chat/completions`          |
| 鉴权头               | `Authorization: Bearer YOUR_API_KEY` |

<Note>
  这里不要把 OpenClaw 文档写成安装或首次引导教程。对接入文档来说，关键是 Provider 配置和模型映射关系。
</Note>

`GET /v1/models` 可以在排障时辅助确认模型可见性，但不应写成每个 OpenClaw 场景都必须执行的固定步骤。

## 验证步骤

1. 打开 OpenClaw。
2. 选择你配置的 HaiRoute 模型或别名。
3. 发送一条简单提示词。
4. 如果能够正常返回内容，说明接入成功。

## 常见问题

| 问题                   | 解决方案                                                                           |
| -------------------- | ------------------------------------------------------------------------------ |
| 提示 `401` 或鉴权失败       | 请确认 `HAIROUTE_API_KEY` 已经在 OpenClaw 所在的同一运行环境中生效。                              |
| 提示 `model not found` | 请确认 `models.providers.hairoute.models` 中配置的模型 ID，与 HaiRoute 当前实际暴露的模型 ID 完全一致。 |
| 配置已经保存，但新模型没有出现      | OpenClaw 并不一定会立即重载配置。请重新打开应用，或重启相关 gateway 进程后再测试。                             |
| 是否每次都必须重启            | 不是。先看当前版本是否已经自动重载；只有在 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)