接入 ZCode

一句话结论：ZCode 支持添加任意兼容 Anthropic / OpenAI 协议的服务作为自定义供应商。 走「模型设置 → 添加供应商」，填接口地址 + API Key + 手动添加模型 ID 即可。

项目	值
入口	对话框模型名 → 管理模型 → 设置 → 模型设置 → 底部添加供应商
OpenAI 接口地址	https://api.ziai.lol/v1
Anthropic 接口地址	https://api.ziai.lol
配置文件	~/.zcode/v2/config.json（一般无需手改）
生效方式	开启启用开关，新会话生效

ZiAI 属于「自定义供应商」路径

ZCode 内置的 BigModel（国内）与 Z.ai（海外）供应商页有专属端点规则 —— 例如 GLM Coding Plan 必须用 Coding 专用端点 https://api.z.ai/api/coding/paas/v4，不能替换为通用端点。 这些规则只适用于 Z.ai / 智谱官方账号，与 ZiAI 无关。接 ZiAI 请走下面的「添加供应商」自定义路径。

前提

• 已安装 ZCode（官方文档）
• 已有 ZiAI 密钥与模型 ID

配置步骤

1. 进入模型设置面板

   两种入口任选：

   • 首次启动：欢迎页选择 使用 API Key，直接进入模型供应商配置
   • 已在应用内：点击对话框中的模型名称打开模型选择器 → 列表底部点 管理模型 → 进入 设置 → 模型设置
   

   图片来源：ZCode 官方文档

2. 点击左侧供应商列表底部的「添加供应商」

3. 填写名称

   例如 ZiAI。名称会显示在模型选择器里，建议起得容易辨认。

4. 选择协议并填写接口地址

   OpenAI 协议（推荐）

   OpenAI 接口地址填：

   https://api.ziai.lol/v1

   走 /v1/chat/completions。兼容性最好，绝大多数模型都能用。

   Anthropic 协议

   Anthropic 接口地址填：

   https://api.ziai.lol

   走 /v1/messages。适合 ZiAI 上的 Claude 系模型，需要完整工具调用时优先用它。

   两个地址可以同时填

   ZCode 的自定义供应商允许分别填写 Anthropic 接口地址与 OpenAI 接口地址。 两个都填上，之后按模型选择协议即可，不必建两个供应商。

5. 填写 API Key

   粘贴 sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx。

6. 点击「添加模型」手动填写模型 ID

   模型 ID 必须手填，不会自动拉取

   ZCode 的自定义供应商不会自动获取模型列表，必须点「添加模型」逐个手填。 填错的表现是「供应商添加成功、启用开关也开了，但发消息就报错或没有响应」。

   准确的模型 ID 用这条命令拉取后复制：

   curl -s https://api.ziai.lol/v1/models \
     -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" | jq -r '.data[].id'

7. 开启启用开关

   保存后打开该供应商的启用开关，即可在模型选择器中选到刚添加的模型。

   

   图片来源：ZCode 官方文档（图为自定义供应商示例）

单个模型的高级参数

在 设置 → 模型供应商 里点开某个模型，展开 高级：

参数	说明
最大输出 Token	单次回复长度上限。默认留空跟随模型自身上限，通常保持留空即可
上下文窗口	自定义供应商的模型可以修改，保存后对新会话生效

输出上限与历史对话共用上下文

调大「最大输出 Token」会挤占历史对话空间，自动压缩来得更早。

ZCode 的自动上下文压缩会在接近窗口上限前提前触发，为模型输出预留空间并保留安全缓冲（合计约 3.4 万 token）。 因此压缩点低于窗口标称值属正常现象 —— 例如 128K 窗口约在 9.4 万 token 时触发，1M 窗口约在 96.6 万 token 时触发。 自动压缩目前没有可配置的开关或阈值。

上下文窗口不是越大越好：窗口越大每轮重发的历史越多，Token 消耗成倍增加。详见省 Token 建议。

思考强度档位

ZCode 会按模型实际能力显示可用的思考强度档位。选择档位后，ZCode 按接口类型转换请求参数：

• OpenAI 兼容接口 → 顶层 reasoning_effort
• Anthropic 兼容接口 → thinking / effort

第三方部署的档位可能与官方不同

同名模型的第三方部署，接受的档位可能与官方端点不一致。 例如 DeepSeek V4 系列在 ZCode 中最高档按官方约定发送 max，而部分第三方部署只接受 xhigh 及以下 —— 此时选最高档会返回 400 参数错误，改选 high 档即可正常使用。

对于「其他自定义模型」，ZCode 通常只提供「开启 / 关闭」两档，或不提供档位 —— 这表示 ZCode 还没有该模型的档位映射，不是配置丢失。

供应商私有思考参数的支持情况：Qwen 系列的 enable_thinking、thinking.type=enabled/disabled 形式的开关已适配； GLM 的 clear_thinking、MiniMax 的 adaptive 思考模式当前不支持在 ZCode 内配置。

配置文件：能改什么、不能改什么

ZCode 的供应商配置存放在 ~/.zcode/v2/config.json。

options 只认四个字段，其余静默丢弃

供应商的 options 只识别以下连接参数：

字段	用途
apiKey	API 密钥
baseURL	接口地址
apiKeyRequired	是否必须提供密钥
headers	自定义请求头

手动加入的其他字段不会写入请求体，也不会有任何报错提示。 例如塞进 reasoning_effort、vl_high_resolution_images 是无效的 —— 网上不少教程会让你这么改，照抄必然踩坑。

需要调思考强度请用界面上的档位选择，需要自定义请求头请用 headers。

图片输入的支持判定

ZCode 会综合供应商与模型配置、模型目录能力信息、内置规则与当前接口协议，判断所选模型能否接收图片，结果分三种：

判定	行为
支持	保留图片并随请求发送
不支持	请求发出前移除图片数据，用文字提示替代
能力未知	不提前拦截，由上游决定；若上游不支持可能直接报错

注意：同一个模型通过不同协议接入，判定结果可能不同。例如 GLM 系模型通过官方 Anthropic 兼容接口接入时可保留图片， 通过 OpenAI Chat 兼容接口接入时则按不支持图片处理。带后缀的变体（如 -highspeed）还会结合供应商与显式能力配置判断， 不能只凭模型名称推断是否支持图片。

遇到图片相关报错时：先用 ZiAI 文档中的标准模型 ID，确认该接口本身支持图片输入；无法确认时暂时不要在该模型下发送图片。

HTTP 代理注意事项

ZCode 默认不读系统代理环境变量

ZCode 默认不读取系统的 HTTP_PROXY / HTTPS_PROXY（仅 WebFetch 在未配置代理时会兜底使用），以设置页里填写的代理为准。

设置中的代理不是全局代理：

• 走代理：模型 API 请求、MCP 服务器（stdio / HTTP / SSE）、WebFetch 网页抓取、终端命令子进程、插件市场、应用内页面加载
• 不走代理：桌面端账号登录与后端服务请求、仓库 Wiki 生成、Web 远程控制通道（WebSocket）、SSH 远程连接

修改代理设置后需要重启 ZCode 才会对全部链路生效。

验证

在对话框的模型选择器中选中 ZiAI 的模型，发送一句简单指令测试。确认模型可用、响应稳定即可开始使用。

命令行独立验证：

curl https://api.ziai.lol/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"model":"模型ID","messages":[{"role":"user","content":"你好"}]}'

ZCode 专属常见问题

现象	原因	解决
供应商已启用但发消息报错	模型 ID 填错或未添加	用 /v1/models 拉取准确 ID 重新添加
选最高思考档返回 400	第三方部署不接受该档位	降到 high 或更低
改了 config.json 里的参数没效果	该字段不在 options 识别范围内	改用界面配置，或只用 headers 传自定义头
发图片报错或被忽略	该协议下模型被判为不支持图片	换 Anthropic 协议地址，或改用支持视觉的模型
配了代理但部分请求仍走直连	该链路本就不走代理	见上面的代理作用范围表

下一步

• 其他客户端：配置速查表
• 报错排查：常见报错速查
• 上下文与花费：计费、配额与限速