# ZCode 自定义模型接入

> **最后核实**：2026-11-10 · 📄 依据官方文档（ZCode 桌面版 v3.17.2，README 与更新日志标注 2026-11-03）· ✅ QCode 接入按 ZCode CLI 0.17.1 实测（2026-11-10）

ZCode 能用自己的 API Key 和接口地址：桌面版在模型设置里添加服务商，开源的 ZCode CLI 从 `~/.zcode/v2/provider_config.json` 读取。截至 2026-11-10，按 ZCode CLI 0.17.1 实测：QCode 的三种协议（Anthropic Messages、OpenAI Chat Completions、OpenAI Responses）全部可用，而且不需要登录智谱 / Z.ai 账号。桌面版步骤依据官方文档。

## 接入速览

| 项目 | 说明 |
|---|---|
| 它是什么 | 智谱（Z.ai）的开源项目（Apache-2.0），README 原文：「ZCode 是 AI 编程工作台，提供桌面应用、浏览器界面和终端 Agent」；仓库 [zai-org/ZCode](https://github.com/zai-org/ZCode) |
| 可用模型 | Claude ✅ · GPT ✅ · GLM / Kimi / DeepSeek / Qwen ✅ · Gemini ❌（QCode 暂不提供 Gemini 模型） |
| Anthropic Messages | `https://api.qcode.cc/api`（ZCode 自己补 `/v1/messages`）· ✅ CLI 实测 |
| OpenAI Chat Completions | `https://api.qcode.cc/openai/v1` · ✅ CLI 实测 |
| OpenAI Responses | `https://api.qcode.cc/openai/v1` · ✅ CLI 实测；桌面版官方文档没有单列这种协议 |
| 桌面版 | 「管理模型」→ `设置 -> 模型设置` → 左侧列表底部添加服务商；配置文件 `~/.zcode/v2/config.json` |
| ZCode CLI | 从源码构建；配置文件 `~/.zcode/v2/provider_config.json`（`access.apiKey`、`api.type`、`api.baseUrl`） |
| 官方文档 | [连接模型](https://zcode.z.ai/cn/docs/configuration) · [安装](https://zcode.z.ai/cn/docs/install) · [智谱开放平台 ZCode 页](https://docs.bigmodel.cn/cn/coding-plan/tool/zcode) · [CLI 使用指南](https://github.com/zai-org/ZCode/blob/main/apps/zcode-cli/docs/usage/README.md) |

## 走哪个协议

ZCode 取得模型有三种方式，额度来源不同：

| 方式 | 做法 | 用量记在哪 |
|---|---|---|
| 账号登录 | 欢迎页选 Z.ai 或 BigModel | 账号下的套餐：「若账号已开通 GLM Coding Plan 编程套餐，ZCode 会直接使用该账号下的套餐与额度。」 |
| 在 Z.ai / BigModel 页用 API Key | 把该页切到 API Key 模式，出现「OpenAI 接口地址」与「Anthropic 接口地址」两个字段 | 你填的智谱 / Z.ai Key |
| 自定义服务商 | 桌面版添加服务商，或在 CLI 的 `provider_config.json` 里填自己的接口地址和 Key | 你指向的服务，这里是 QCode |

本文讲第三种。QCode 上 Claude 只走 Anthropic 协议，GPT 只走 OpenAI 协议，GLM / Kimi / DeepSeek / Qwen 走 Anthropic 与 OpenAI Chat 都行（见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)）：

| 协议 | QCode Base URL | 可用型号 | CLI 的 `api.type` |
|---|---|---|---|
| Anthropic Messages | `https://api.qcode.cc/api` | Claude、GLM / Kimi / DeepSeek / Qwen | `anthropic-messages` |
| OpenAI Chat Completions | `https://api.qcode.cc/openai/v1` | GPT、GLM / Kimi / DeepSeek / Qwen | `openai-chat-completions` |
| OpenAI Responses | `https://api.qcode.cc/openai/v1` | GPT | `openai-responses` |

接口路径由 ZCode 自己补。CLI 源码里的 `normalizeAnthropicBaseURL`：Anthropic Base URL 不以 `/v1` 结尾就补上 `/v1`，之后 SDK 再补 `/messages`，所以填 `https://api.qcode.cc/api`，请求发到 `/api/v1/messages`。两种 OpenAI 类型是在 Base URL 后直接补 `/chat/completions` 或 `/responses`，所以这两个值都以 `/openai/v1` 结尾。末尾不要加 `/`。同一把 Key 在 `us.qcode.cc`、`asia.qcode.cc` 上也能用，换掉域名、保留路径即可。

## 桌面版（📄 依据官方文档）

以下步骤依据 v3.17.2 的官方文档。同样的 QCode 地址已在 ZCode CLI 实测通过；桌面版以你在应用里发出的第一条测试指令的结果为准。

### 安装

官方安装页写明支持「macOS（Apple Silicon / Intel）、Windows（x64 / ARM64）、Linux（x64 / ARM64，AppImage、DEB、RPM）」，并把 v3.17.2 标为最新版本。

- macOS：打开下载的 `ZCode.dmg`，把 ZCode.app 拖进「应用程序」。若提示应用已损坏，官方给的办法是 `xattr -dr com.apple.quarantine /Applications/ZCode.app`。
- Windows：下载安装包，双击后按向导完成。
- Linux：下载 `.AppImage`、`.deb` 或 `.rpm`；AppImage 先执行 `chmod +x ZCode-*.AppImage`。

安装包请到 [zcode.z.ai](https://zcode.z.ai/cn/docs/install) 下载。

### 添加 QCode 服务商

官方示例里既有只填一种接口的服务商，也有 DeepSeek 示例在同一个服务商里两种都填，但没写同一个服务商填了两个接口时 ZCode 怎么选，所以本文按协议分成两个服务商：

| 服务商名称 | 接口字段 | 填写值 | 模型 ID（示例） |
|---|---|---|---|
| `QCode Claude` | Anthropic 接口地址 | `https://api.qcode.cc/api` | `claude-sonnet-5-5`、`claude-opus-5-5`、`claude-haiku-5-5` |
| `QCode OpenAI` | OpenAI 接口地址 | `https://api.qcode.cc/openai/v1` | `gpt-6.1-sol`、`deepseek-v4-flash`、`glm-5.3`、`kimi-k3`、`qwen3.8-max` |

1. 打开 ZCode，点对话框里的模型名打开模型选择器，在列表底部点「管理模型」，进入 `设置 -> 模型设置` 面板。首次启动还没有可用模型时，欢迎页的「使用 API Key」也会进入模型服务商配置。智谱开放平台的 ZCode 页把同一处叫作 `模型供应商` 页面。
2. 在左侧列表底部点 `添加供应商`。
3. 第一个服务商：
   - 名称：`QCode Claude`（名称自己起，官方示例用 claude、deepseek 这类名字）
   - Anthropic 接口地址：`https://api.qcode.cc/api`（官方写的是「从下拉列表中选择或手动输入 API 基础 URL」，这里手动输入）
   - API Key：你的 QCode Key（以 `cr_` 开头）
4. 点「添加模型」，逐个填模型 ID，例如 `claude-sonnet-5-5`。官方原话：「通过『添加模型』手动填写该服务支持的模型 ID 即可使用」。
5. 打开启用开关（官方：「开启启用开关后即可开始使用」）并保存。
6. 同样再建 `QCode OpenAI`：OpenAI 接口地址填 `https://api.qcode.cc/openai/v1`，Key 相同，模型例如 `gpt-6.1-sol`、`deepseek-v4-flash`。

模型 ID 以 [qcode.cc/models](https://qcode.cc/models) 上的为准、逐字照填，各模型单价也在那里。国产模型在 Anthropic 接口上同样可用，想少建一个服务商也可以全放在 `QCode Claude` 里。桌面版官方文档点名的是 Anthropic 与 OpenAI 两种接口，没有单列 Responses 选项；要用 Responses，请用下文的 CLI。

### 桌面版配置文件

官方 FAQ 把 `~/.zcode/v2/config.json` 列为保存「Model provider setup (API keys, base URLs, model lists)」的文件，所以它含有你的 Key，不要提交到仓库。官方关于它写明了一条规则：`~/.zcode/v2/config.json` 中服务商的 `options` 只识别 `apiKey`、`baseURL`、`apiKeyRequired`、`headers` 等连接参数，手动加入的其他字段（如 `reasoning_effort`、`vl_high_resolution_images`）不会写入请求体，也不会有报错提示。建议在界面里配置，不要手改这个文件。官方 FAQ 还说明：终端里的环境变量与桌面端的模型配置是两个入口，配置不会自动同步。

## ZCode CLI（✅ 2026-11-10 实测）

截至 2026-11-10，按 ZCode CLI 0.17.1 实测：通过 `~/.zcode/v2/provider_config.json` 接 QCode，三种协议全部通过，不需要执行 `zcode login`。

### 从源码构建

CLI 以源码形式发布：官方[快速开始](https://github.com/zai-org/ZCode/blob/main/apps/zcode-cli/docs/usage/01-quickstart.md)从仓库构建，要求「准备 Git、Node.js 24.14.0 和 pnpm 10.33.2；以仓库根目录的 mise.toml 为准」。在仓库根目录执行：

```sh
git clone https://github.com/zai-org/ZCode.git
cd ZCode
pnpm install --frozen-lockfile
pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --version
node apps/zcode-cli/packages/cli/dist/zcode.cjs doctor --json
```

下文的 `zcode` 代表 `node /absolute/path/to/zcode.cjs`，并保留构建生成的相邻文件。

### 写 provider_config.json

把下面内容存为 `~/.zcode/v2/provider_config.json`，把 `cr_xxx` 换成你的 QCode Key。这是实测用的 Anthropic 写法：

```json
{
  "schemaVersion": 1,
  "config": {
    "providerConfigRules": {
      "providerRules": [
        {
          "providerId": "qcode",
          "providerName": "QCode",
          "config": {
            "group": "standard-personal",
            "access": { "type": "api-key", "apiKey": "cr_xxx" },
            "api": {
              "type": "anthropic-messages",
              "baseUrl": "https://api.qcode.cc/api"
            },
            "personalModelIds": ["claude-haiku-5-5"]
          }
        }
      ]
    },
    "modelConfigRules": {
      "providerModelRules": [],
      "manualProviderModelRules": []
    },
    "defaultModelSelection": {
      "providerId": "qcode",
      "modelId": "claude-haiku-5-5"
    }
  }
}
```

换协议时改 `api.type`、`api.baseUrl` 和模型 ID（`personalModelIds` 与 `defaultModelSelection.modelId` 两处）：

| 协议 | `api.type` | `api.baseUrl` | 实测型号 |
|---|---|---|---|
| Anthropic Messages | `anthropic-messages` | `https://api.qcode.cc/api` | `claude-haiku-5-5` ✅ |
| OpenAI Chat Completions | `openai-chat-completions` | `https://api.qcode.cc/openai/v1` | `deepseek-v4-flash` ✅ |
| OpenAI Responses | `openai-responses` | `https://api.qcode.cc/openai/v1` | `gpt-6.1-terra` ✅ |

官方 CLI 指南里的两点：

- 字段是 `api.baseUrl`，官方原文：「`api.baseUrl` 的拼写与旧格式的 `options.baseURL` 不同」；CLI 读的是 `provider_config.json`，不是 `~/.zcode/v2/config.json`。
- 官方原文：「配置读取不承诺对 `apiKey` 字符串做 `${ENV}` 替换」，所以 Key 以明文写在文件里。限制文件权限，并且不要提交到 Git：

```sh
chmod 600 ~/.zcode/v2/provider_config.json
```

### 非交互调用检查

```sh
zcode --prompt "只用一句话回复 ready，不调用工具" \
  --cwd /path/to/project --mode plan --json --no-color
```

`--json` 返回 `sessionId`、`response` 和运行信息，`response` 为 `ready` 即表示服务商可用。一定要写 `--mode`：不写时 `--prompt` 默认以 `yolo` 模式运行，会直接执行命令、修改文件。无参数运行 `zcode` 进入交互式终端界面。

## 验证

1. 桌面版：在对话框的模型选择器里选中新服务商的模型，发一句简单指令测试（官方：「发送一句简单指令测试」）。
2. CLI：运行上面的 `--prompt` 检查。
3. 打开 [probe.qcode.cc](https://probe.qcode.cc)，输入你的 QCode Key，确认请求带着该模型出现。
4. 不经过 ZCode 单独测 Key 和路径：

```bash
KEY="cr_your_key"

# Anthropic Messages
curl -sS https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-5-5","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'

# OpenAI Chat Completions
curl -sS https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"model":"deepseek-v4-flash","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'
```

## 常见问题

| 现象 | 原因 | 处理 |
|---|---|---|
| 桌面版：连接一直 Loading | 官方 FAQ：机器连不上模型服务，或 Key 没有额度 / 没有该模型权限 | 先查网络，再查 Key 与模型 ID |
| `model_not_available_on_endpoint` | 把 `claude-…` 的 ID 加到了 OpenAI 接口或 OpenAI 类型的 `api.type` 下 | Claude 的 ID 放在 Anthropic 接口下（CLI 里是 `anthropic-messages`） |
| 404 | 末尾多了 `/`，或 OpenAI 的 Base URL 少了 `/v1` | 严格照上表填写，并用 curl 命令对照 |
| CLI 没用上你填的 Key 或地址 | CLI 读的是 `provider_config.json` 里的 `api.baseUrl`，不是桌面版的 `config.json` | 改 `~/.zcode/v2/provider_config.json` |
| CLI：把 QCode 地址填进 `ZCODE_BASE_URL` 不起作用 | 官方：`ZCODE_BASE_URL` 与产品服务端点有关，不能代替 `api.baseUrl` | 地址写进 `api.baseUrl` |
| CLI：`apiKey` 里的 `${QCODE_API_KEY}` 没有被替换 | 官方：不承诺对 `apiKey` 做 `${ENV}` 替换 | 直接写 Key，并 `chmod 600` 该文件 |
| CLI 首次运行打印一行「ZCode Built-in」刷新失败的提示 | 0.17.1 实测出现，不影响通过自定义服务商调用，之后的运行显示 skipped | 无需处理 |
| 选最高思考档返回 400 参数错误 | 官方：部分第三方部署只接受 `xhigh` 及以下，而 ZCode 对 DeepSeek V4 最高档发送 `max` | 改选 high 档：「改选 high 档即可正常使用」 |
| 某个模型没有细分思考档位 | 官方：ZCode 还没有该模型的档位映射，「并不是配置丢失」 | 用开启 / 关闭两档 |
| 桌面版：在 `options` 里手写 `reasoning_effort` 没有效果 | 官方：其他字段不会写入请求体，也没有报错提示 | 用界面里的档位 |
| 图片被去掉 | 官方示例：GLM-5.2 通过 OpenAI Chat 兼容接口接入时按不支持图片处理，换接口或协议结果可能不同 | 在模型配置里明确声明图片能力，或不在该模型下发图片 |

官方还写明 ZCode 会按接口转换思考档位：「OpenAI 兼容接口使用顶层 reasoning_effort，Anthropic 兼容接口使用 thinking / effort」。

## 已知限制

- 桌面版部分依据 v3.17.2 的官方文档，菜单名称可能随版本变化；CLI 部分按 0.17.1 实测，每种协议测了一个型号。
- 官方写明目前也不支持为第三方模型追加自定义请求参数。
- 桌面版官方文档点名的是 Anthropic 与 OpenAI 两种接口；Responses 可以通过 CLI 的 `openai-responses` 使用。QCode 暂不提供 Gemini 模型。
- CLI：Key 以明文保存在 `provider_config.json`；`--prompt` 不写 `--mode` 时以 `yolo` 模式运行。

## 相关文档

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) —— 协议 × 模型家族对照表
- [工具兼容总览](/docs/ide/tool-compatibility) —— 各工具支持哪种协议
- [Kimi Code CLI 接入](/docs/ide/kimi-code) —— 同样可配 Anthropic、OpenAI Chat 与 Responses 的终端 Agent
- [MiniMax Code 接入](/docs/ide/minimax-code) —— 桌面版加 `mcode` CLI，同样支持三种 API 格式
- [DeepSeek Harness（dsh）](/docs/ide/deepseek-harness) —— 同样带自定义模型表单的 agent harness
- [国产模型接入](/docs/usage/cn-models) —— GLM / Kimi / DeepSeek / Qwen 的模型 ID 与路径