ZCode 自定义模型接入

ZCode 自定义服务商接入 QCode.cc：桌面版按官方文档填写，ZCode CLI 0.17.1 已实测 Anthropic、OpenAI Chat、Responses。

需要 API Key？ 前往注册 →·端点与 Base URL →

最后核实：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 账号。桌面版步骤依据官方文档。

接入速览¶

走哪个协议¶

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

本文讲第三种。QCode 上 Claude 只走 Anthropic 协议，GPT 只走 OpenAI 协议，GLM / Kimi / DeepSeek / Qwen 走 Anthropic 与 OpenAI Chat 都行（见 接入点与 API 格式）：

接口路径由 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 下载。

添加 QCode 服务商¶

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

1. 打开 ZCode，点对话框里的模型名打开模型选择器，在列表底部点「管理模型」，进入 设置 -> 模型设置 面板。首次启动还没有可用模型时，欢迎页的「使用 API Key」也会进入模型服务商配置。智谱开放平台的 ZCode 页把同一处叫作 模型供应商 页面。
2. 在左侧列表底部点 添加供应商。

3. 第一个服务商：

4. 名称：QCode Claude（名称自己起，官方示例用 claude、deepseek 这类名字）

5. Anthropic 接口地址：https://api.qcode.cc/api（官方写的是「从下拉列表中选择或手动输入 API 基础 URL」，这里手动输入）
6. API Key：你的 QCode Key（以 cr_ 开头）
7. 点「添加模型」，逐个填模型 ID，例如 claude-sonnet-5-5。官方原话：「通过『添加模型』手动填写该服务支持的模型 ID 即可使用」。
8. 打开启用开关（官方：「开启启用开关后即可开始使用」）并保存。
9. 同样再建 QCode OpenAI：OpenAI 接口地址填 https://api.qcode.cc/openai/v1，Key 相同，模型例如 gpt-6.1-sol、deepseek-v4-flash。

模型 ID 以 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 以源码形式发布：官方快速开始从仓库构建，要求「准备 Git、Node.js 24.14.0 和 pnpm 10.33.2；以仓库根目录的 mise.toml 为准」。在仓库根目录执行：

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 写法：

{
  "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 两处）：

官方 CLI 指南里的两点：

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

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

非交互调用检查¶

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，输入你的 QCode Key，确认请求带着该模型出现。
4. 不经过 ZCode 单独测 Key 和路径：

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"}]}'

常见问题¶

官方还写明 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 格式 —— 协议 × 模型家族对照表
• 工具兼容总览 —— 各工具支持哪种协议
• Kimi Code CLI 接入 —— 同样可配 Anthropic、OpenAI Chat 与 Responses 的终端 Agent
• MiniMax Code 接入 —— 桌面版加 mcode CLI，同样支持三种 API 格式
• DeepSeek Harness（dsh） —— 同样带自定义模型表单的 agent harness
• 国产模型接入 —— GLM / Kimi / DeepSeek / Qwen 的模型 ID 与路径

企业团队版 →