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

# ZCode

> 通过 HaiToken 网关接入 ZCode

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

## 先准备好这些信息

* HaiToken API Key
* HaiToken OpenAI 兼容地址：`https://api.haitoken.ai/v1`
* HaiToken Claude / Anthropic 兼容地址：`https://api.haitoken.ai`
* 至少一个可用模型 ID，例如 `deepseek-v4-flash`

<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：填写 HaiToken 配置

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

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

<Warning>
  如果 API 格式选择 `OpenAI` 后，Base URL 下方出现 `/responses` 后缀提示，说明当前使用的是 Responses API 路径。HaiToken 兼容的是 Chat Completions 路径（`/v1/chat/completions`），请选择不含 `/responses` 的 `OpenAI` 选项，确保请求路径正确。
</Warning>

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

### 步骤 4：添加模型

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

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

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

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

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

## 补充说明

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

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

## 常见问题

| 问题                        | 解决方案                                                                                                                                                    |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 模型列表拉取成功但调用失败             | 检查 API 格式是否使用了 Responses API（URL 后缀显示 `/responses`）。HaiToken 兼容 Chat Completions，请选择不含 `/responses` 的 `OpenAI` 选项。                                      |
| 提示接口地址错误                  | 确认 Base URL 填写的是 `https://api.haitoken.ai/v1`，不要多加 `/chat/completions` 后缀，ZCode 会自动拼接路径。                                                                |
| 我想走 Claude / Anthropic 模式 | 把 API 格式切到 `Anthropic Messages (/v1/messages)`，并把 Base URL 改成 `https://api.haitoken.ai`，不要再带 `/v1`。这一条路径会按 Anthropic Messages 协议请求 `POST /v1/messages`。 |
| 提示 `401` 或鉴权失败            | 请确认 API Key 有效，并确认 ZCode 当前使用的是 OpenAI 兼容 Bearer 鉴权。                                                                                                    |
| 提示 `model not found`      | 请确认 ZCode 中填写的模型 ID 与 HaiToken 实际暴露的模型 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)