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

# ZCode

> 通过 HaiRoute 网关接入 ZCode

ZCode 是智谱推出的 AI 编程助手，支持通过自定义供应商接入兼容 `OpenAI`、`Anthropic` 协议的模型服务。对 HaiRoute 来说，`OpenAI` 模式通常最稳、兼容性最好；如果你明确需要走 Claude / Anthropic 生态，也可以改用 `Anthropic` 模式。

## 先准备好这些信息

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

<Note>
  ZCode 的配置全程通过图形界面完成，Windows、macOS、Linux 的操作步骤基本一致。不同系统下若菜单位置或窗口样式略有差异，请以实际 UI 为准，但 API Key、Base URL 和模型 ID 的填写逻辑不变。
</Note>

## 接入步骤

### 先选哪种协议

在 ZCode 中，常见有两种接法：

* `OpenAI`：更推荐，兼容面更广，当前文档主流程也按这条路径来写
* `Anthropic`：也很常用，适合你希望按 Claude / Messages 生态去接入的场景

如果你没有明确理由，建议优先选 `OpenAI`。

### 步骤 1：打开模型设置

在 ZCode 主界面左侧边栏，点击 **模型设置** 进入模型供应商管理页面。

<img src="https://mintcdn.com/hai-token/ispw4laipa3cbnL7/images/zcode/PixPin_2026-07-10_10-10-24.png?fit=max&auto=format&n=ispw4laipa3cbnL7&q=85&s=b1a5f9ef49efd1eb5bd978a20367fb2e" alt="打开 ZCode 模型设置" width="1200" height="800" data-path="images/zcode/PixPin_2026-07-10_10-10-24.png" />

### 步骤 2：添加自定义供应商

在模型设置页面的 **自定义供应商** 区域，点击 **+ 添加供应商** 按钮，打开供应商配置表单。

### 步骤 3：填写 HaiRoute 配置

在供应商配置表单中，按以下信息填写：

| 字段       | 填写值                                                                                 |
| -------- | ----------------------------------------------------------------------------------- |
| 供应商名称    | `hairoute`（可自定义）                                                                    |
| Base URL | `OpenAI` 模式填 `https://api.hairoute.ai/v1`；`Anthropic` 模式填 `https://api.hairoute.ai` |
| API Key  | 你的 HaiRoute API Key                                                                 |
| API 格式   | 推荐 `OpenAI`；如需 Claude 生态可选 `Anthropic Messages (/v1/messages)`                      |

<Warning>
  HaiRoute 同时支持 OpenAI Chat Completions 和 OpenAI Responses 协议。如果 API 格式选择 OpenAI 后，Base URL 下方出现 `/responses` 后缀，表示 ZCode 将通过 `POST /v1/responses` 请求；该路径现已支持，可直接使用。仅当你明确需要 Chat Completions（`POST /v1/chat/completions`）时，再选择不含 `/responses` 的 OpenAI 选项。
</Warning>

<Note>
  如果你选择的是 `Anthropic` 模式，请不要把 Base URL 写成 `https://api.hairoute.ai/v1`。这一条路径应当填写 Anthropic 风格的网关前缀 `https://api.hairoute.ai`，由客户端去请求 `/v1/messages`。
</Note>

### 步骤 4：添加模型

在 **模型列表** 区域，点击 **+ 添加模型**，输入你要使用的 HaiRoute 模型 ID，例如 `gpt-5.4`。可重复添加多个模型。

### 步骤 5：保存供应商

填写完成后，点击表单底部的 **添加供应商** 按钮保存配置。

### 步骤 6：测试连通性

保存后，在 ZCode 的对话或编码面板中切换到刚配置的 HaiRoute 模型，发送一条简单消息（如 `hello`）验证连通性。

## 补充说明

| 项目          | 说明                                   |
| ----------- | ------------------------------------ |
| 推荐协议        | OpenAI Chat Completions              |
| 常见请求路径      | `POST /v1/chat/completions`          |
| Claude 兼容路径 | `POST /v1/messages`                  |
| 鉴权头         | `Authorization: Bearer YOUR_API_KEY` |
| 模型切换        | 在 ZCode 对话或编码面板通过模型选择器切换             |

如果你还需要配置温度、最大输出长度、系统提示词等高级参数，第一次接入时建议先保留默认值，优先确认连通性。

## 常见问题

| 问题                          | 解决方案                                                                                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Base URL 显示 `/responses` 后缀 | 这表示使用 `POST /v1/responses`，HaiRoute 已支持。Responses 兼容客户端可保持该设置；如需 Chat Completions，再选择不含 `/responses` 的 OpenAI 选项。                                       |
| 提示接口地址错误                    | 确认 Base URL 填写的是 `https://api.hairoute.ai/v1`，不要多加 `/chat/completions` 后缀，ZCode 会自动拼接路径。                                                                |
| 我想走 Claude / Anthropic 模式   | 把 API 格式切到 `Anthropic Messages (/v1/messages)`，并把 Base URL 改成 `https://api.hairoute.ai`，不要再带 `/v1`。这一条路径会按 Anthropic Messages 协议请求 `POST /v1/messages`。 |
| 提示 `401` 或鉴权失败              | 请确认 API Key 有效，并确认 ZCode 当前使用的是 OpenAI 兼容 Bearer 鉴权。                                                                                                    |
| 提示 `model not found`        | 请确认 ZCode 中填写的模型 ID 与 HaiRoute 实际暴露的模型 ID 完全一致。                                                                                                         |
| 添加模型后仍无法使用                  | 保存供应商后请重新选择一次模型，必要时重启 ZCode 后再测试，避免使用缓存配置。                                                                                                              |

## 下一步

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